browsercontrol 0.1.2__tar.gz → 0.1.4__tar.gz

browsercontrol-0.1.4/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(xargs cat -n)",
+      "Bash(git show-ref *)"
+    ]
+  },
+  "prefersReducedMotion": false
+}

browsercontrol-0.1.4/.github/workflows/ci.yml

@@ -0,0 +1,135 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run pre-commit hooks
+        run: uv run pre-commit run --all-files
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Install Playwright browsers
+        run: uv run playwright install chromium --with-deps
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  # Test on Windows and macOS as well
+  test-windows:
+    runs-on: windows-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Install Playwright browsers
+        run: uv run playwright install chromium
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  test-macos:
+    runs-on: macos-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Install Playwright browsers
+        run: uv run playwright install chromium
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  security:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run bandit security checks
+        run: uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv
+
+  type-check:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run mypy (if type hints are used)
+        run: uv run mypy browsercontrol/ || echo "No mypy configuration found"

browsercontrol-0.1.4/.github/workflows/dependency-review.yml

@@ -0,0 +1,39 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request,
+# surfacing known-vulnerable versions of the packages declared or updated in the PR.
+# Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable
+# packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+name: "Dependency review"
+on:
+  pull_request:
+    branches: ["main"]
+
+# If using a dependency submission action in this workflow this permission will need to be set to:
+#
+# permissions:
+#   contents: write
+#
+# https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api
+permissions:
+  contents: read
+  # Write permissions for pull-requests are required for using the `comment-summary-in-pr` option, comment out if you aren't using this option
+  pull-requests: write
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository"
+        uses: actions/checkout@v4
+      - name: "Dependency Review"
+        uses: actions/dependency-review-action@v4
+        # Commonly enabled options, see https://github.com/actions/dependency-review-action#configuration-options for all available options.
+        with:
+          comment-summary-in-pr: always
+        #   fail-on-severity: moderate
+        #   deny-licenses: GPL-1.0-or-later, LGPL-2.0-or-later
+        #   retry-on-snapshot-warnings: true

{browsercontrol-0.1.2 → browsercontrol-0.1.4}/.gitignore

@@ -6,13 +6,10 @@
 # Python
 */__pycache__/*
 *.py[cod]
-*$py.class
-*.so
-.Python
-*.egg-info/
 dist/
-build/
+.pytest_cache/
 
 # Virtual environments
 .venv/
-
+.ruff_cache/
+.pytest_cache/

browsercontrol-0.1.4/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+repos:
+  # Ruff - Fast Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+      # Run the formatter
+      - id: ruff-format
+
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  # Python security checks
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.0
+    hooks:
+      - id: bandit
+        args: [-c, pyproject.toml]
+        additional_dependencies: ["bandit[toml]"]
+        exclude: ^tests/
+
+# CI configuration
+ci:
+  autofix_commit_msg: |
+    [pre-commit.ci] auto fixes from pre-commit hooks
+
+    for more information, see https://pre-commit.ci
+  autofix_prs: true
+  autoupdate_branch: ""
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit autoupdate"
+  autoupdate_schedule: weekly
+  skip: []
+  submodules: false

browsercontrol-0.1.4/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+BrowserControl is an MCP (Model Context Protocol) server that gives AI agents
+vision-first browser automation via Playwright. Its defining idea is **Set of
+Marks (SoM)**: every action returns an annotated screenshot where interactive
+elements are overlaid with numbered red boxes, so the agent acts by referring to
+an element's number (`click(7)`) instead of CSS selectors or XPath.
+
+## Commands
+
+This project uses `uv` for all dependency and task management.
+
+```bash
+uv sync                                    # Install deps (use --all-extras in CI to include dev group)
+uv run playwright install chromium         # One-time: install the browser engine
+
+uv run pytest                              # Run all tests
+uv run pytest tests/test_navigation.py     # Run a single test file
+uv run pytest tests/test_navigation.py::TestScroll::test_scroll_down_medium   # Single test
+uv run pytest --cov=browsercontrol         # With coverage
+
+uv run ruff check .                        # Lint
+uv run ruff check . --fix                  # Lint + autofix
+uv run ruff format .                       # Format (line length 100, double quotes)
+uv run mypy browsercontrol/                # Type-check (strict mode)
+uv run bandit -c pyproject.toml -r . --exclude ./tests,./.venv   # Security scan
+uv run pre-commit run --all-files          # Run every hook (mirrors the CI lint job)
+
+uv run fastmcp dev browsercontrol/server.py   # Run the server in dev mode with inspector
+browsercontrol                                # Run the installed server (also: python -m browsercontrol)
+```
+
+CI (`.github/workflows/ci.yml`) gates on the lint job first, then runs tests on
+Linux/Windows/macOS plus bandit and mypy. Run `ruff check`, `ruff format`, and
+`pytest` locally before pushing.
+
+## Architecture
+
+The flow is: agent calls an MCP tool → tool drives the Playwright page → a fresh
+annotated screenshot + element map is captured → both are returned to the agent.
+
+**`browser.py` — the heart of the system.** Exposes a single module-global
+`browser = BrowserManager()` instance and a module-global `element_map` dict.
+Key behaviors to understand before touching anything:
+
+- `screenshot_with_som()` is called at the end of nearly every tool. It takes a
+  screenshot, runs `get_interactive_elements()` (injected JS that collects
+  visible, on-screen interactive elements and their bounding boxes), draws the
+  numbered boxes, and **overwrites the global `element_map`** with 1-indexed IDs.
+- **Element IDs are ephemeral.** They are only valid against the most recent
+  screenshot. Any navigation, click, scroll, or screenshot regenerates the map
+  and renumbers everything. Tools look up the target via `get_element_map()` and
+  return an error listing valid IDs when the ID is missing.
+- The browser uses `launch_persistent_context` against a profile directory
+  (`~/.browsercontrol/user_data` by default), so cookies, localStorage, and login
+  state persist across server restarts. Launch args include localhost proxy
+  bypass to avoid `ERR_CONNECTION_REFUSED`.
+- DevTools data (console logs, network requests, page errors) is captured by
+  event listeners attached in `_setup_page_listeners`, auto-wired to every new
+  page/popup, and stored in capped in-memory ring buffers on the manager.
+
+**`server.py` — composition root.** Creates the `FastMCP` instance, attaches a
+`lifespan` context manager that starts/stops the browser, and calls each
+`register_*_tools(mcp)`. The server-level `instructions` string is the prompt the
+agent sees describing available tools — keep it in sync when adding tools.
+
+**`tools/` — one module per category** (navigation, interaction, forms, content,
+devtools, recording, tabs). Each exports a single `register_<category>_tools(mcp)`
+function that defines inner `async` functions decorated with `@mcp.tool()`.
+Conventions every tool follows:
+
+- Signature returns `tuple[str, Image]`: a human-readable status string plus the
+  annotated screenshot.
+- Starts with `await browser.ensure_started()` (lazily boots the browser if the
+  lifespan hasn't, e.g. in some test paths).
+- Ends by building the result via a local `_get_screenshot_with_summary()`
+  helper. **This helper is duplicated verbatim in several tool modules** — if you
+  change the summary format, update every copy.
+
+**`config.py`** — a `Config` dataclass loaded once at import via
+`Config.from_env()` into a global `config`. All settings come from `BROWSER_*`
+and `LOG_LEVEL` env vars (see README for the full table). Because it is read at
+import time, env changes require a server restart.
+
+## Testing conventions
+
+Tests **do not launch a real browser** — everything is mocked. The pattern:
+
+- `tests/conftest.py` provides `mock_browser_manager` (a fully stubbed
+  `BrowserManager`), `mock_page`, `mock_context`, and `sample_element_map`.
+- A test registers the tools onto a throwaway `FastMCP("test")`, then patches the
+  module-level `browser` symbol **in that specific tool module** (e.g.
+  `patch("browsercontrol.tools.navigation.browser", mock_browser_manager)`) —
+  because each tool module does `from browsercontrol.browser import browser`, it
+  holds its own reference that must be patched independently.
+- The tool callable is reached through FastMCP internals:
+  `mcp_server._tool_manager._tools["navigate_to"].fn(...)`.
+- `asyncio_mode = "auto"` is set, so `async def test_*` runs without an explicit
+  marker (though existing tests also add `@pytest.mark.asyncio`).
+
+When adding a tool, add a test covering both the happy path and graceful error
+handling, following the existing per-module test files.
+
+## Conventions
+
+- Python 3.11+. Type hints are required and checked by mypy in **strict** mode
+  (`disallow_untyped_defs`, etc.) — annotate fully.
+- Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`).
+- Pre-commit hooks (ruff, prettier for md/yaml/json, bandit) run on commit;
+  `git commit --no-verify` bypasses them but CI will still enforce them.

browsercontrol-0.1.4/CODE_QUALITY.md

@@ -0,0 +1,81 @@
+# Code Formatting and Quality
+
+This project uses automated code formatting and linting tools to maintain code quality.
+
+## Tools
+
+- **[Ruff](https://github.com/astral-sh/ruff)** - Fast Python linter and formatter
+- **[Pre-commit](https://pre-commit.com/)** - Git hooks for automated checks
+- **[Prettier](https://prettier.io/)** - Markdown/YAML/JSON formatting
+- **[Bandit](https://bandit.readthedocs.io/)** - Security vulnerability scanner
+
+## Setup
+
+The tools are already configured. To install the pre-commit hooks:
+
+```bash
+uv sync
+uv run pre-commit install
+```
+
+## Usage
+
+### Manual Formatting
+
+```bash
+# Check for linting issues
+uv run ruff check .
+
+# Auto-fix linting issues
+uv run ruff check . --fix
+
+# Format code
+uv run ruff format .
+
+# Run all pre-commit hooks manually
+uv run pre-commit run --all-files
+```
+
+### Automatic Formatting
+
+Pre-commit hooks run automatically on `git commit`. They will:
+
+1. Run ruff linter and formatter
+2. Trim trailing whitespace
+3. Fix end-of-file issues
+4. Format markdown/YAML/JSON with prettier
+5. Check for security issues with bandit
+
+If any hook fails, the commit will be aborted and files will be auto-fixed. Review the changes and commit again.
+
+## Configuration
+
+### Ruff
+
+Configuration in `pyproject.toml`:
+
+- **Line length**: 100 characters
+- **Target Python**: 3.11+
+- **Enabled rules**: pycodestyle, pyflakes, isort, pep8-naming, pyupgrade, bugbear, comprehensions, simplify, type-checking, Ruff-specific
+- **Ignored rules**: E501 (line too long), B008 (function call in defaults), N805 (first arg naming), SIM117 (nested with), B904 (exception chaining)
+
+### Pre-commit
+
+Configuration in `.pre-commit-config.yaml`:
+
+- Ruff linter and formatter
+- General file checks (trailing whitespace, EOF, YAML/TOML/JSON validation, large files, merge conflicts)
+- Prettier for markdown formatting
+- Bandit for security checks (excludes tests, allows subprocess for Playwright)
+
+## Bypassing Hooks
+
+If you need to bypass pre-commit hooks (not recommended):
+
+```bash
+git commit --no-verify
+```
+
+## CI Integration
+
+Pre-commit.ci is configured to run automatically on pull requests and can auto-fix issues.

{browsercontrol-0.1.2 → browsercontrol-0.1.4}/CONTRIBUTING.md

@@ -23,7 +23,11 @@ We love your input! We want to make contributing to BrowserControl as easy and t
    ```bash
    uv run playwright install chromium
    ```
-5. **Run the server in dev mode**:
+5. **Install pre-commit hooks**:
+   ```bash
+   uv run pre-commit install
+   ```
+6. **Run the server in dev mode**:
    ```bash
    uv run fastmcp dev browsercontrol/server.py
    ```
@@ -33,11 +37,13 @@ We love your input! We want to make contributing to BrowserControl as easy and t
 We use [uv](https://github.com/astral-sh/uv) for dependency management and packaging. It's fast and reliable.
 
 ### Project Structure
+
 - `browsercontrol/server.py`: Main MCP server definition
 - `browsercontrol/browser.py`: Core logic (Playwright + Set of Marks)
 - `browsercontrol/tools/`: Tool implementations split by category
 
 ### Making Changes
+
 1. Create a branch for your feature: `git checkout -b feature/amazing-feature`
 2. Implement your changes
 3. Run tests (see below)
@@ -48,17 +54,33 @@ We use [uv](https://github.com/astral-sh/uv) for dependency management and packa
 
 ## 🧪 Testing
 
-We use `pytest`. Please ensure all tests pass before submitting a PR.
+We use `pytest` for testing and `ruff` for code quality. Please ensure all checks pass before submitting a PR.
 
 ```bash
 # Run all tests
 uv run pytest
 
+# Run tests with coverage
+uv run pytest --cov=browsercontrol
+
+# Check code formatting and linting
+uv run ruff check .
+uv run ruff format .
+
+# Run all pre-commit hooks
+uv run pre-commit run --all-files
+```
+
+See [CODE_QUALITY.md](CODE_QUALITY.md) for more details on code formatting and quality tools.
+
 # Run specific test file
+
 uv run pytest tests/test_navigation.py
+
 ```
 
 If you add a new tool or feature, please add a corresponding test case covering:
+
 - Happy path (it works)
 - Error handling (it fails gracefully)
 
@@ -82,3 +104,4 @@ Bugs are tracked as GitHub issues. When filing an issue, please explain the prob
 ## 📄 License
 
 By contributing, you agree that your contributions will be licensed under its MIT License.
+```