browser-tools 0.1.0__tar.gz

browser_tools-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build
+*.whl

browser_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Browser Tools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

browser_tools-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: browser-tools
+Version: 0.1.0
+Summary: Browser automation, debugging, and anti-detect browsing CLI
+Project-URL: Homepage, https://github.com/dungle-scrubs/browser-tools
+Project-URL: Repository, https://github.com/dungle-scrubs/browser-tools
+Project-URL: Issues, https://github.com/dungle-scrubs/browser-tools/issues
+Project-URL: Changelog, https://github.com/dungle-scrubs/browser-tools/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anti-detect,browser-automation,camoufox,cdp,chrome-devtools,mcp,playwright,web-scraping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.14.1
+Requires-Dist: camoufox[geoip]>=0.4.11
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: websockets>=14.0
+Description-Content-Type: text/markdown
+
+# Browser Tools
+
+[![CI](https://github.com/dungle-scrubs/browser-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/dungle-scrubs/browser-tools/actions/workflows/ci.yml)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
+
+Browser automation, debugging, and anti-detect browsing CLI. Provides:
+
+- **Chrome DevTools MCP wrapper** — Snapshot-based page automation via
+  [chrome-devtools-mcp](https://github.com/anthropics/chrome-devtools-mcp)
+- **Persistent browser sessions** — Long-lived Chrome instances with named profiles,
+  daemon-based MCP reuse, and attach-to-running-browser support
+- **Frame-aware tools** — Iframe/CDP frame tree management, execution context
+  resolution, and storage inspection
+- **Interstitial detection** — Multi-signal heuristic detection for Cloudflare,
+  DataDome, Akamai, PerimeterX, Imperva, AWS WAF, and other challenge pages
+- **Camoufox anti-detect browsing** — Fingerprint-injected Firefox-based
+  browsing for bot-protected sites
+- **CPU profiling** — Direct CDP-based JavaScript CPU profiling with
+  threshold-triggered capture
+
+## Quick Start
+
+### Installation
+
+```bash
+# Using uv (recommended)
+uv tool install browser-tools
+
+# Or with pip
+pip install browser-tools
+```
+
+### Usage
+
+```bash
+# Run the CLI
+browser-tools --help
+
+# Take a snapshot of a page
+browser-tools --headless navigate --url https://example.com
+browser-tools --headless take-snapshot
+
+# Use a persistent profile
+browser-tools --profile dev navigate --url https://example.com
+```
+
+### Development setup
+
+```bash
+# Clone and install in editable mode
+git clone https://github.com/dungle-scrubs/browser-tools.git
+cd browser-tools
+uv sync
+```
+
+Runtime requirements:
+
+- **Chrome** or **Chrome Canary** for DevTools automation
+- **Node.js** (>=18) for `chrome-devtools-mcp`
+- **Camoufox** (`camoufox fetch`) for anti-detect Firefox workflows
+
+## Architecture
+
+```
+browser_tools_session.py     CLI entry point
+        |
+        +-- chrome_config.py          Tool schemas & validation
+        +-- chrome_utils.py           MCP subprocess invocation, formatting
+        +-- persistent_browser.py     Chrome lifecycle, daemon, profiles
+        |       +-- browser_state.py     Persisted state dataclasses
+        |       +-- mcp_session.py       Short-lived MCP session wrapper
+        |       +-- daemon_client.py      Unix socket client
+        |       +-- process_utils.py      Chrome process/port utilities
+        |       +-- mcp_daemon.py         Long-lived MCP daemon
+        |               +-- cdp_handler.py     CDP tool implementations
+        |               +-- cdp_constants.py   CDP toolset definitions
+        |               +-- cdp_client.py      CDP WebSocket client
+        |               +-- frame_manager.py   Frame tree management
+        |               +-- interstitial.py    Challenge detection
+        |               +-- screenshot_utils.py Blank-frame detection
+        +-- camoufox_session.py     Camoufox anti-detect wrapper
+        +-- profiler.py            Standalone CPU profiler
+```
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src/ tests/
+uv run pytest
+```
+
+### Project Configuration
+
+Place a `.browser-tools.json` in your project root:
+
+```json
+{
+  "preferredSession": {
+    "mode": "headed-auth",
+    "profile": "dev"
+  }
+}
+```
+
+This auto-selects a persistent headed browser session using the named profile.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+All contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md) for responsible disclosure.

browser_tools-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Browser Tools
+
+[![CI](https://github.com/dungle-scrubs/browser-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/dungle-scrubs/browser-tools/actions/workflows/ci.yml)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
+
+Browser automation, debugging, and anti-detect browsing CLI. Provides:
+
+- **Chrome DevTools MCP wrapper** — Snapshot-based page automation via
+  [chrome-devtools-mcp](https://github.com/anthropics/chrome-devtools-mcp)
+- **Persistent browser sessions** — Long-lived Chrome instances with named profiles,
+  daemon-based MCP reuse, and attach-to-running-browser support
+- **Frame-aware tools** — Iframe/CDP frame tree management, execution context
+  resolution, and storage inspection
+- **Interstitial detection** — Multi-signal heuristic detection for Cloudflare,
+  DataDome, Akamai, PerimeterX, Imperva, AWS WAF, and other challenge pages
+- **Camoufox anti-detect browsing** — Fingerprint-injected Firefox-based
+  browsing for bot-protected sites
+- **CPU profiling** — Direct CDP-based JavaScript CPU profiling with
+  threshold-triggered capture
+
+## Quick Start
+
+### Installation
+
+```bash
+# Using uv (recommended)
+uv tool install browser-tools
+
+# Or with pip
+pip install browser-tools
+```
+
+### Usage
+
+```bash
+# Run the CLI
+browser-tools --help
+
+# Take a snapshot of a page
+browser-tools --headless navigate --url https://example.com
+browser-tools --headless take-snapshot
+
+# Use a persistent profile
+browser-tools --profile dev navigate --url https://example.com
+```
+
+### Development setup
+
+```bash
+# Clone and install in editable mode
+git clone https://github.com/dungle-scrubs/browser-tools.git
+cd browser-tools
+uv sync
+```
+
+Runtime requirements:
+
+- **Chrome** or **Chrome Canary** for DevTools automation
+- **Node.js** (>=18) for `chrome-devtools-mcp`
+- **Camoufox** (`camoufox fetch`) for anti-detect Firefox workflows
+
+## Architecture
+
+```
+browser_tools_session.py     CLI entry point
+        |
+        +-- chrome_config.py          Tool schemas & validation
+        +-- chrome_utils.py           MCP subprocess invocation, formatting
+        +-- persistent_browser.py     Chrome lifecycle, daemon, profiles
+        |       +-- browser_state.py     Persisted state dataclasses
+        |       +-- mcp_session.py       Short-lived MCP session wrapper
+        |       +-- daemon_client.py      Unix socket client
+        |       +-- process_utils.py      Chrome process/port utilities
+        |       +-- mcp_daemon.py         Long-lived MCP daemon
+        |               +-- cdp_handler.py     CDP tool implementations
+        |               +-- cdp_constants.py   CDP toolset definitions
+        |               +-- cdp_client.py      CDP WebSocket client
+        |               +-- frame_manager.py   Frame tree management
+        |               +-- interstitial.py    Challenge detection
+        |               +-- screenshot_utils.py Blank-frame detection
+        +-- camoufox_session.py     Camoufox anti-detect wrapper
+        +-- profiler.py            Standalone CPU profiler
+```
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src/ tests/
+uv run pytest
+```
+
+### Project Configuration
+
+Place a `.browser-tools.json` in your project root:
+
+```json
+{
+  "preferredSession": {
+    "mode": "headed-auth",
+    "profile": "dev"
+  }
+}
+```
+
+This auto-selects a persistent headed browser session using the named profile.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+All contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md) for responsible disclosure.

browser_tools-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "browser-tools"
+version = "0.1.0"
+description = "Browser automation, debugging, and anti-detect browsing CLI"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+keywords = [
+    "browser-automation",
+    "chrome-devtools",
+    "cdp",
+    "anti-detect",
+    "camoufox",
+    "playwright",
+    "web-scraping",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "camoufox[geoip]>=0.4.11",
+    "pillow>=10.0.0",
+    "websockets>=14.0",
+    # Security overrides for transitive dependencies.
+    # camoufox pulls in aiohttp 3.13.x which has 11 known CVEs (PYSEC-2026-237, etc.).
+    # Force >=3.14.1 until camoufox updates its own pin.
+    "aiohttp>=3.14.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/dungle-scrubs/browser-tools"
+Repository = "https://github.com/dungle-scrubs/browser-tools"
+Issues = "https://github.com/dungle-scrubs/browser-tools/issues"
+Changelog = "https://github.com/dungle-scrubs/browser-tools/blob/main/CHANGELOG.md"
+
+[project.scripts]
+browser-tools = "browser_tools.browser_tools_session:main"
+browser-tools-profiler = "browser_tools.profiler:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/browser_tools"]
+artifacts = [
+    "src/browser_tools/*.js",
+    "src/browser_tools/*.mjs",
+    "src/browser_tools/*.sh",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/browser_tools",
+    "tests",
+    "README.md",
+]
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.8.0",
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.13"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportUnknownParameterType = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I",    # pycodestyle + pyflakes + isort
+    "B",                     # flake8-bugbear
+    "C4",                    # flake8-comprehensions
+    "RUF",                   # ruff-specific rules
+    "SIM",                   # flake8-simplify
+    "TCH",                   # flake8-type-checking
+    "UP",                    # pyupgrade
+]
+ignore = ["E501", "E731", "F841"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["browser_tools"]

browser_tools-0.1.0/src/browser_tools/__init__.py

@@ -0,0 +1,22 @@
+"""Browser Tools automation package."""
+
+from __future__ import annotations
+
+from .browser_state import ActiveAttachConfig, BrowserState, ProjectBrowserConfig
+from .camoufox_session import CamoufoxSession
+from .cdp_client import CDPClient, CDPError
+from .frame_manager import FrameManager
+from .persistent_browser import PersistentChromeController
+
+__all__ = [
+    "ActiveAttachConfig",
+    "BrowserState",
+    "CDPClient",
+    "CDPError",
+    "CamoufoxSession",
+    "FrameManager",
+    "PersistentChromeController",
+    "ProjectBrowserConfig",
+    "__version__",
+]
+__version__ = "0.1.0"

browser_tools-0.1.0/src/browser_tools/attach_chrome.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# attach-chrome.sh — Launch Chrome with remote debugging for browser-tools attach
+#
+# Usage:
+#   ./attach-chrome.sh [--port PORT] [--profile PROFILE] [URL]
+#
+# Examples:
+#   ./attach-chrome.sh                          # Default port 9222
+#   ./attach-chrome.sh --port 9333              # Custom port
+#   ./attach-chrome.sh --profile dev            # Named profile
+#   ./attach-chrome.sh https://myapp.localhost   # Open specific URL
+
+set -euo pipefail
+
+PORT=9222
+PROFILE=""
+URL=""
+CHROME_CANARY="/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
+CHROME_STABLE="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --port)
+            PORT="$2"
+            shift 2
+            ;;
+        --profile)
+            PROFILE="$2"
+            shift 2
+            ;;
+        --help|-h)
+            echo "Usage: $0 [--port PORT] [--profile PROFILE] [URL]"
+            echo ""
+            echo "Launch Chrome with remote debugging enabled for browser-tools."
+            echo ""
+            echo "Options:"
+            echo "  --port PORT      Remote debugging port (default: 9222)"
+            echo "  --profile NAME   Named profile for persistent sessions"
+            echo "  URL              URL to open on launch"
+            echo ""
+            echo "Then in your agent, use:"
+            echo '  attach_browser(endpoint="http://127.0.0.1:PORT")'
+            exit 0
+            ;;
+        *)
+            URL="$1"
+            shift
+            ;;
+    esac
+done
+
+# Find Chrome executable
+CHROME=""
+if [[ -x "$CHROME_CANARY" ]]; then
+    CHROME="$CHROME_CANARY"
+elif [[ -x "$CHROME_STABLE" ]]; then
+    CHROME="$CHROME_STABLE"
+elif command -v google-chrome &>/dev/null; then
+    CHROME="google-chrome"
+elif command -v chromium &>/dev/null; then
+    CHROME="chromium"
+else
+    echo "Error: Chrome not found. Install Chrome or Chrome Canary." >&2
+    exit 1
+fi
+
+# Build user-data-dir path
+CACHE_DIR="$HOME/.cache/tool-proxy/browser-tools"
+if [[ -n "$PROFILE" ]]; then
+    USER_DATA_DIR="$CACHE_DIR/profiles/$PROFILE"
+else
+    USER_DATA_DIR="$CACHE_DIR/profiles/attach-$PORT"
+fi
+
+mkdir -p "$USER_DATA_DIR"
+chmod 700 "$USER_DATA_DIR"
+
+echo "Launching Chrome with remote debugging on port $PORT..."
+echo "  Executable: $CHROME"
+echo "  Profile:    $USER_DATA_DIR"
+
+ARGS=(
+    "--remote-debugging-port=$PORT"
+    "--user-data-dir=$USER_DATA_DIR"
+    "--no-first-run"
+    "--no-default-browser-check"
+    "--disable-sync"
+)
+
+if [[ -n "$URL" ]]; then
+    ARGS+=("$URL")
+fi
+
+# Detach Chrome into a new session so it survives if our parent shell is
+# killed (e.g. an agent's Bash tool call hits its timeout). nohup alone is
+# not enough on macOS: when the shell's process group is signaled, the
+# child dies with it. Python's start_new_session=True calls os.setsid()
+# in the child before exec, putting Chrome in its own session/process group.
+python3 - "$CHROME" "${ARGS[@]}" <<'PY'
+import subprocess, sys
+subprocess.Popen(
+    sys.argv[1:],
+    stdin=subprocess.DEVNULL,
+    stdout=subprocess.DEVNULL,
+    stderr=subprocess.DEVNULL,
+    start_new_session=True,
+)
+PY
+
+# Wait for the remote debugging endpoint to become reachable so the caller
+# can attach immediately on return.
+for _ in $(seq 1 60); do
+    if curl -fsS "http://127.0.0.1:$PORT/json/version" >/dev/null 2>&1; then
+        echo ""
+        echo "Chrome ready on http://127.0.0.1:$PORT"
+        echo "Connect with: attach_browser(endpoint=\"http://127.0.0.1:$PORT\")"
+        exit 0
+    fi
+    sleep 0.5
+done
+
+echo "Error: Chrome did not become ready on port $PORT within 30s." >&2
+echo "If another Chrome is already using $USER_DATA_DIR, kill it first or use --profile NAME." >&2
+exit 1