ai-dev-browser 0.5.3__py3-none-any.whl

ai_dev_browser/core/browser.py

@@ -0,0 +1,323 @@
+"""Browser lifecycle management operations."""
+
+import asyncio
+import os
+import time
+from pathlib import Path
+
+from .chrome import launch_chrome
+from .config import (
+    DEFAULT_REUSE_STRATEGY,
+    ReuseStrategy,
+    get_workspace_profile_dir,
+)
+from .connection import graceful_close_browser
+from .port import (
+    _cleanup_temp_profile,
+    _query_chrome_cmdline,
+    find_debug_chromes,
+    find_workspace_chromes,
+    get_available_port,
+    get_pid_on_port,
+    is_port_in_use,
+)
+from .process import _kill_process_tree
+
+
+def _find_chrome_using_profile(profile_dir: Path) -> tuple[int, int | None] | None:
+    """Find a debugging Chrome using the specified profile via CDP.
+
+    Scans debug port range and queries each Chrome's command line
+    to check if --user-data-dir matches the given profile directory.
+
+    Returns:
+        (port, pid) tuple if found, None otherwise.
+    """
+    profile_str = str(profile_dir)
+    for port, pid, _ws in find_debug_chromes():
+        cmdline = _query_chrome_cmdline(port)
+        if cmdline and any(profile_str in arg for arg in cmdline):
+            return (port, pid)
+    return None
+
+
+def _find_reusable_chrome(profile: str | None = None) -> int | None:
+    """Find a debugging Chrome in the current workspace to reuse.
+
+    When `profile` is given, only reuse a Chrome already using that
+    profile's user-data-dir — otherwise two browser_start calls with
+    different profiles would silently share the same Chrome, defeating
+    per-profile isolation (e.g. a parallel worker pool).
+
+    When `profile` is None the caller has no profile preference, so any
+    idle debugging Chrome in this workspace is reused (legacy behaviour
+    for default invocations).
+
+    Returns:
+        Port number if a suitable Chrome is found, None otherwise.
+    """
+    if profile is not None:
+        user_data_dir = get_workspace_profile_dir(profile)
+        existing = _find_chrome_using_profile(user_data_dir)
+        return existing[0] if existing else None
+
+    for port, _pid in find_workspace_chromes():
+        return port
+    return None
+
+
+def browser_start(
+    port: int | None = None,
+    headless: bool = os.environ.get("AI_DEV_BROWSER_HEADLESS", "").lower()
+    in ("1", "true"),
+    url: str | None = None,
+    profile: str | None = None,
+    temp: bool = False,
+    reuse: ReuseStrategy = DEFAULT_REUSE_STRATEGY,
+) -> dict:
+    """Start or reuse a browser instance.
+
+    Args:
+        port: Debug port (auto-assigned if None)
+        headless: Run in headless mode
+        url: Initial URL to open (default: about:blank)
+        profile: Profile name (default: "default")
+        temp: Use temporary profile instead
+        reuse: "none" (always new) or "any" (reuse idle Chrome, default)
+
+    Returns:
+        dict with port, pid, headless, url, profile, reused, message
+    """
+    # Try to reuse an existing Chrome. Profile-aware: if the caller asked
+    # for a specific profile we must not hand back a Chrome running a
+    # different profile (that would break parallel workers using distinct
+    # profiles for isolation). `temp=True` always wants a fresh session,
+    # so skip reuse entirely for that.
+    if reuse != "none" and not temp:
+        reused_port = _find_reusable_chrome(profile=profile)
+        if reused_port:
+            pid = get_pid_on_port(reused_port)
+            return {
+                "port": reused_port,
+                "pid": pid,
+                "profile": profile or "default",
+                "reused": True,
+                "message": f"Reusing existing Chrome on port {reused_port}",
+            }
+
+    # No reusable Chrome found above (or reuse was skipped for
+    # temp/profile/none). Top-level has already decided reuse semantics, so
+    # ask get_available_port for a fresh port only — otherwise it would
+    # silently hand back the same workspace Chrome we just declined to
+    # reuse.
+    if port is None:
+        port = get_available_port(reuse=False)
+    else:
+        # User specified a port - check if it's available
+        if is_port_in_use(port=port):
+            pid = get_pid_on_port(port)
+            return {
+                "error": f"Port {port} is already in use (PID: {pid}). "
+                f"Use a different port or stop the existing process."
+            }
+
+    # Determine user data directory
+    if temp:
+        user_data_dir = None
+        profile_name = "(temp)"
+    else:
+        profile_name = profile or "default"
+        user_data_dir = get_workspace_profile_dir(profile_name)
+        user_data_dir.mkdir(parents=True, exist_ok=True)
+
+        # Safety: if another Chrome is already using this profile, reuse it
+        # (launching two Chromes with the same user-data-dir causes crashes)
+        existing = _find_chrome_using_profile(user_data_dir)
+        if existing:
+            existing_port, existing_pid = existing
+            return {
+                "port": existing_port,
+                "pid": existing_pid,
+                "profile": profile_name,
+                "reused": True,
+                "message": f"Profile '{profile_name}' already in use. Reusing Chrome on port {existing_port}.",
+            }
+
+    # Launch Chrome
+    start_url = url or "about:blank"
+    process = launch_chrome(
+        port=port,
+        headless=headless,
+        start_url=start_url,
+        user_data_dir=str(user_data_dir) if user_data_dir else None,
+    )
+
+    # Wait for Chrome to start listening on the port
+    max_wait = 10.0
+    poll_interval = 0.2
+    elapsed = 0.0
+    while elapsed < max_wait:
+        if is_port_in_use(port=port):
+            break
+        if process.poll() is not None:
+            stderr = process.stderr.read() if process.stderr else ""
+            # Provide more helpful error message
+            if not stderr:
+                stderr = (
+                    "Chrome exited silently. Possible causes:\n"
+                    "  - Another Chrome is using this profile\n"
+                    "  - Profile directory is corrupted\n"
+                    "  - Insufficient permissions"
+                )
+            return {"error": f"Chrome process exited unexpectedly: {stderr}"}
+        time.sleep(poll_interval)
+        elapsed += poll_interval
+    else:
+        return {
+            "error": f"Chrome started (PID {process.pid}) but port {port} not listening after {max_wait}s",
+            "pid": process.pid,
+        }
+
+    return {
+        "port": port,
+        "pid": process.pid,
+        "headless": headless,
+        "url": start_url,
+        "profile": profile_name,
+        "reused": False,
+        "message": f"Browser started on port {port}",
+    }
+
+
+def _graceful_stop(port: int, pid: int, timeout: float = 5.0) -> dict:
+    """Gracefully stop a Chrome instance via CDP Browser.close().
+
+    Sends Browser.close() which flushes cookies/profile data, then waits
+    for the process to exit. Falls back to force-kill if graceful fails.
+
+    Returns:
+        dict with port, pid, and method used ("graceful" or "force").
+    """
+    # Try graceful shutdown via CDP. Detect whether we're already inside a
+    # running event loop BEFORE constructing the coroutine — otherwise
+    # calling graceful_close_browser(port=port) eagerly creates a coroutine
+    # object, and if asyncio.run rejects it (in-loop), the coroutine is
+    # never awaited and Python emits
+    # "RuntimeWarning: coroutine ... was never awaited".
+    try:
+        asyncio.get_running_loop()
+        in_loop = True
+    except RuntimeError:
+        in_loop = False
+
+    try:
+        if in_loop:
+            # Can't asyncio.run here — offload to a thread with its own loop
+            import concurrent.futures
+
+            def _run_close():
+                return asyncio.run(graceful_close_browser(port=port))
+
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                sent = pool.submit(_run_close).result(timeout=timeout)
+        else:
+            sent = asyncio.run(graceful_close_browser(port=port))
+    except Exception:
+        sent = False
+
+    if sent:
+        # Wait for process to exit
+        elapsed = 0.0
+        poll_interval = 0.2
+        while elapsed < timeout:
+            if not is_port_in_use(port=port):
+                _cleanup_temp_profile(port)
+                return {"port": port, "pid": pid, "method": "graceful"}
+            time.sleep(poll_interval)
+            elapsed += poll_interval
+
+    # Graceful failed or timed out — force kill
+    _kill_process_tree(pid)
+    _cleanup_temp_profile(port)
+    return {"port": port, "pid": pid, "method": "force"}
+
+
+def browser_stop(
+    port: int | None = None,
+    stop_all: bool = False,
+) -> dict:
+    """Stop browser instance(s).
+
+    Uses CDP Browser.close() for graceful shutdown (flushes cookies to
+    profile SQLite). Falls back to force-kill if graceful fails.
+
+    Args:
+        port: Port of browser to stop
+        stop_all: Stop all debugging Chrome instances
+
+    Returns:
+        dict with stopped status, count, browsers list
+    """
+    if not port and not stop_all:
+        return {"error": "Please specify port or stop_all"}
+
+    stopped = []
+
+    if stop_all:
+        for p, pid, _ws in find_debug_chromes():
+            if pid is None:
+                continue
+            try:
+                result = _graceful_stop(p, pid)
+                stopped.append(result)
+            except Exception:
+                pass
+    else:
+        pid = get_pid_on_port(port)
+        if pid:
+            result = _graceful_stop(port, pid)
+            stopped.append(result)
+
+    return {
+        "stopped": True,
+        "count": len(stopped),
+        "browsers": stopped,
+    }
+
+
+def browser_list(all_workspaces: bool = False) -> dict:
+    """List debugging Chrome instances.
+
+    By default, shows only Chromes belonging to the current workspace.
+    Use all_workspaces=True to see all debugging Chromes.
+
+    Args:
+        all_workspaces: Show Chromes from all workspaces (default: current only)
+
+    Returns:
+        dict with browsers list and count
+    """
+    browsers = []
+
+    if all_workspaces:
+        for p, pid, workspace in find_debug_chromes():
+            info: dict = {
+                "port": p,
+                "pid": pid,
+            }
+            if workspace:
+                info["workspace"] = workspace
+            browsers.append(info)
+    else:
+        for p, pid in find_workspace_chromes():
+            browsers.append(
+                {
+                    "port": p,
+                    "pid": pid,
+                }
+            )
+
+    return {
+        "browsers": browsers,
+        "count": len(browsers),
+    }

ai_dev_browser/core/cdp.py

@@ -0,0 +1,66 @@
+"""CDP (Chrome DevTools Protocol) command operations."""
+
+import json
+
+from ai_dev_browser import cdp as cdp_module
+
+from ._case import camel_to_snake
+from ._tab import Tab
+
+
+def _get_cdp_command(method: str, params: dict):
+    """Dynamically create a CDP command generator.
+
+    Args:
+        method: CDP method like "Browser.getVersion" or "DOM.getDocument"
+        params: Parameters dict
+
+    Returns:
+        CDP command generator
+    """
+    domain, cmd = method.split(".")
+    domain_snake = camel_to_snake(domain)
+    cmd_snake = camel_to_snake(cmd)
+
+    # Get the domain module (e.g., cdp.browser)
+    domain_mod = getattr(cdp_module, domain_snake)
+
+    # Get the command function (e.g., cdp.browser.get_version)
+    cmd_func = getattr(domain_mod, cmd_snake)
+
+    # Call with params
+    return cmd_func(**params) if params else cmd_func()
+
+
+async def cdp_send(
+    tab: Tab,
+    method: str,
+    params: str | None = None,
+) -> dict:
+    """Send a CDP (Chrome DevTools Protocol) command.
+
+    Args:
+        tab: Tab instance
+        method: CDP method name (e.g., "Browser.getVersion", "DOM.getDocument")
+        params: JSON string of parameters
+
+    Returns:
+        dict with result or error
+    """
+    # Parse params if provided
+    parsed_params = {}
+    if params:
+        parsed_params = json.loads(params)
+
+    # Create CDP command generator
+    cdp_cmd = _get_cdp_command(method, parsed_params)
+
+    # Send CDP command
+    result = await tab.send(cdp_cmd)
+
+    # Try to serialize result
+    try:
+        json.dumps(result)
+        return {"result": result}
+    except (TypeError, ValueError):
+        return {"result": str(result)}

ai_dev_browser/core/chrome.py

@@ -0,0 +1,253 @@
+"""Chrome executable detection and launching.
+
+This module provides cross-platform Chrome management:
+- find_chrome: Detect Chrome installation path
+- launch_chrome: Start Chrome with remote debugging
+
+Example:
+    chrome_path = find_chrome()
+    if chrome_path:
+        process = launch_chrome()
+"""
+
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .config import DEFAULT_DEBUG_PORT, DEFAULT_PROFILE_PREFIX
+
+
+logger = logging.getLogger(__name__)
+
+
+def find_chrome() -> str | None:
+    """
+    Find Chrome executable path based on platform.
+
+    Automatically detects Chrome installation on Windows, macOS, and Linux.
+    Checks common installation paths and falls back to PATH search on Unix.
+
+    Returns:
+        Path to Chrome executable, or None if not found.
+
+    Example:
+        chrome = find_chrome()
+        if chrome:
+            print(f"Chrome at: {chrome}")
+        else:
+            print("Chrome not found")
+    """
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        candidates = [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            str(
+                Path.home()
+                / "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+            ),
+        ]
+    elif system == "Windows":
+        candidates = [
+            r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+            r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+            str(Path.home() / r"AppData\Local\Google\Chrome\Application\chrome.exe"),
+        ]
+    else:  # Linux
+        candidates = [
+            "/usr/bin/google-chrome",
+            "/usr/bin/google-chrome-stable",
+            "/usr/bin/chromium",
+            "/usr/bin/chromium-browser",
+            "/snap/bin/chromium",
+        ]
+
+    # Check known paths
+    for candidate in candidates:
+        if Path(candidate).exists():
+            return candidate
+
+    # Try to find via 'which' on Unix-like systems
+    if system != "Windows":
+        for cmd in [
+            "google-chrome",
+            "google-chrome-stable",
+            "chromium",
+            "chromium-browser",
+        ]:
+            result = shutil.which(cmd)
+            if result:
+                return result
+
+    return None
+
+
+def _ensure_no_session_restore(user_data_dir: Path) -> None:
+    """Ensure Chrome won't restore previous session on startup.
+
+    Sets restore_on_startup=5 in Preferences file, which tells Chrome
+    to open a new tab page instead of restoring previous tabs.
+
+    Args:
+        user_data_dir: Chrome user data directory path
+    """
+    import json
+
+    default_dir = user_data_dir / "Default"
+    default_dir.mkdir(parents=True, exist_ok=True)
+
+    prefs_file = default_dir / "Preferences"
+
+    # Load existing preferences or start fresh
+    prefs = {}
+    if prefs_file.exists():
+        try:
+            prefs = json.loads(prefs_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            prefs = {}
+
+    # Set restore_on_startup to 5 (open new tab page)
+    if "session" not in prefs:
+        prefs["session"] = {}
+    prefs["session"]["restore_on_startup"] = 5
+
+    # Write back
+    try:
+        prefs_file.write_text(json.dumps(prefs), encoding="utf-8")
+        logger.debug(f"Set restore_on_startup=5 in {prefs_file}")
+    except OSError as e:
+        logger.warning(f"Failed to write Preferences: {e}")
+
+
+def launch_chrome(
+    port: int = DEFAULT_DEBUG_PORT,
+    headless: bool = False,
+    user_data_dir: str | Path | None = None,
+    profile_prefix: str = DEFAULT_PROFILE_PREFIX,
+    extra_args: list[str] | None = None,
+    start_url: str = "about:blank",
+    disable_session_restore: bool = True,
+    disable_session_crashed_bubble: bool = True,
+    hide_crash_restore_bubble: bool = True,
+) -> subprocess.Popen:
+    """
+    Launch Chrome with remote debugging enabled.
+
+    Creates an isolated Chrome instance with its own profile directory,
+    suitable for browser automation without affecting user's Chrome.
+
+    Args:
+        port: Remote debugging port (default: DEFAULT_DEBUG_PORT)
+        headless: Run in headless mode (default: False)
+        user_data_dir: Custom user data directory. If None, creates a temp directory.
+        profile_prefix: Prefix for temp profile directory name
+        extra_args: Additional Chrome command-line arguments
+        start_url: Initial URL to open (default: "about:blank" for clean state)
+        disable_session_restore: Prevent Chrome from restoring previous tabs (default: True).
+                                Sets restore_on_startup=5 in Preferences file.
+        disable_session_crashed_bubble: Chrome flag --disable-session-crashed-bubble (default: True)
+        hide_crash_restore_bubble: Chrome flag --hide-crash-restore-bubble (default: True)
+
+    Returns:
+        Popen process handle for the Chrome instance.
+
+    Raises:
+        FileNotFoundError: If Chrome executable not found.
+        RuntimeError: If Chrome fails to start.
+
+    Example:
+        process = launch_chrome()
+        # ... connect via CDP ...
+        process.terminate()
+    """
+    chrome_path = find_chrome()
+    if not chrome_path:
+        raise FileNotFoundError(
+            "Chrome executable not found. Please install Google Chrome or set the path manually."
+        )
+
+    # Create isolated user data directory if not provided
+    # Use port number in name so browser_stop can find and clean it up
+    if user_data_dir is None:
+        temp_dir = Path(tempfile.gettempdir()) / f"{profile_prefix}{port}"
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        user_data_dir = str(temp_dir)
+
+    # Disable session restore by setting Preferences
+    # This prevents Chrome from restoring previous tabs on startup
+    if disable_session_restore:
+        _ensure_no_session_restore(Path(user_data_dir))
+
+    # Build Chrome arguments (cross-platform)
+    args = [
+        chrome_path,
+        f"--remote-debugging-port={port}",
+        f"--user-data-dir={user_data_dir}",
+        "--remote-allow-origins=*",  # Allow CDP connections for in-use detection
+        "--enable-automation",  # Required for CDP Browser.getBrowserCommandLine()
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-background-networking",
+        "--disable-client-side-phishing-detection",
+        "--disable-default-apps",
+        "--disable-extensions",
+        "--disable-hang-monitor",
+        "--disable-popup-blocking",
+        "--disable-prompt-on-repost",
+        "--disable-sync",
+        "--disable-translate",
+        "--metrics-recording-only",
+        "--safebrowsing-disable-auto-update",
+    ]
+
+    # Workspace tag: identifies which working directory owns this Chrome.
+    # Read back via CDP Browser.getBrowserCommandLine() in port.py.
+    args.append(f"--ai-dev-browser-workspace={os.getcwd()}")
+
+    # Session restore behavior (default: suppress for clean automation state)
+    if disable_session_crashed_bubble:
+        args.append("--disable-session-crashed-bubble")
+    if hide_crash_restore_bubble:
+        args.append("--hide-crash-restore-bubble")
+
+    if headless:
+        args.append("--headless=new")
+
+    if extra_args:
+        args.extend(extra_args)
+
+    # Start URL goes last - use start_url parameter to control initial page
+    if start_url:
+        args.append(start_url)
+
+    # Start Chrome process
+    try:
+        # Use subprocess.Popen on all platforms
+        # On Unix, use start_new_session to detach from parent
+        # On Windows, CREATE_NEW_PROCESS_GROUP for similar isolation
+        if platform.system() == "Windows":
+            popen_kwargs = {
+                "stdout": subprocess.DEVNULL,
+                "stderr": subprocess.PIPE,
+                "creationflags": subprocess.CREATE_NEW_PROCESS_GROUP,
+            }
+        else:
+            popen_kwargs = {
+                "stdout": subprocess.DEVNULL,
+                "stderr": subprocess.PIPE,
+                "start_new_session": True,
+            }
+
+        logger.debug(f"Launching Chrome on port {port}")
+        process = subprocess.Popen(args, **popen_kwargs)  # type: ignore[call-overload]
+
+        logger.debug(f"Chrome process created, PID: {process.pid}")
+    except Exception as e:
+        raise RuntimeError(f"Failed to launch Chrome: {e}") from e
+
+    return process