patchright-cli 0.4.0__tar.gz → 0.5.0__tar.gz

patchright_cli-0.5.0/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "patchright-cli",
+  "owner": {
+    "name": "Han Zhu"
+  },
+  "metadata": {
+    "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
+    "version": "0.5.0"
+  },
+  "plugins": [
+    {
+      "name": "patchright-cli",
+      "description": "Anti-detect browser automation skill using Patchright (undetected Playwright fork)",
+      "source": "./",
+      "skills": [
+        "./skills/patchright-cli"
+      ]
+    }
+  ]
+}

patchright_cli-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ">=0.7,<0.8"
+          python-version: "3.12"
+      - run: uv venv && uv pip install -e ".[dev]"
+      - run: uv run pre-commit run --all-files
+
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ">=0.7,<0.8"
+          python-version: ${{ matrix.python-version }}
+      - run: uv venv && uv pip install -e ".[dev]"
+      - run: uv run pytest tests/ -v --ignore=tests/test_e2e.py

{patchright_cli-0.4.0 → patchright_cli-0.5.0}/.gitignore

@@ -6,3 +6,4 @@ __pycache__/
 dist/
 build/
 docs/reddit-post.md
+.worktrees/

{patchright_cli-0.4.0 → patchright_cli-0.5.0}/CLAUDE.md

@@ -26,7 +26,18 @@ python -m patchright_cli <command> [args...]
 patchright-cli <command> [args...]
 ```
 
-There are no automated tests yet — changes are tested manually via the CLI.
+## Testing
+
+```bash
+# Unit tests (no browser required)
+pytest tests/ -v --ignore=tests/test_e2e.py
+
+# E2E tests (requires Chrome)
+pytest tests/test_e2e.py -v
+
+# Lint
+pre-commit run --all-files
+```
 
 ## Architecture
 
@@ -38,9 +49,9 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 
 - **CLI (`src/patchright_cli/cli.py`)**: Stateless thin client. Parses argv manually (not click subcommands), builds a JSON `{command, args, options, cwd}` message, sends it over a length-prefixed TCP socket to the daemon, prints the response, and exits. All commands are defined in the `COMMANDS_HELP` dict and `ALL_COMMANDS` list.
 
-- **Daemon (`src/patchright_cli/daemon.py`)**: Long-running async process managing browser sessions. Auto-spawned on `open` via `ensure_daemon_running()` which launches a subprocess. Uses `DaemonState` → multiple `Session` objects, each owning a Patchright persistent browser context. Command dispatch is a large `handle_command()` function with if/elif branches. Console capture uses CDP sessions (not Playwright's `page.on('console')`) because Patchright suppresses it.
+- **Daemon (`src/patchright_cli/daemon.py`)**: Long-running async process managing browser sessions. Auto-spawned on `open` via `ensure_daemon_running()` which launches a subprocess. Uses `DaemonState` → multiple `Session` objects, each owning a Patchright persistent browser context. Command dispatch uses `@register()` decorated handlers in `COMMAND_HANDLERS` dict, dispatched by `handle_command()`. Console capture uses CDP sessions (not Playwright's `page.on('console')`) because Patchright suppresses it.
 
-- **Snapshot (`src/patchright_cli/snapshot.py`)**: Two-pass DOM scanner injected as JavaScript: Pass 1 uses TreeWalker to assign `data-patchright-ref` attributes (`e1`, `e2`, ...) in document order; Pass 2 builds a nested tree. Python side converts to flat YAML. Snapshots are saved to `.patchright-cli/` in the caller's cwd.
+- **Snapshot (`src/patchright_cli/snapshot.py`)**: Uses Playwright's native `aria_snapshot()` to get the accessibility tree. `RefRegistry` annotates each node with sequential refs (`e1`, `e2`, ...). Snapshots are saved as YAML to `.patchright-cli/` in the caller's cwd.
 
 ## Key Design Decisions
 

patchright_cli-0.5.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: install-dev lint test-unit test-e2e test build
+
+install-dev:
+	uv venv && uv pip install -e ".[dev]" && pre-commit install
+
+lint:
+	pre-commit run --all-files
+
+test-unit:
+	pytest tests/ -v --ignore=tests/test_e2e.py
+
+test-e2e:
+	pytest tests/test_e2e.py -v
+
+test: lint test-unit
+
+build:
+	uv build

{patchright_cli-0.4.0 → patchright_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchright-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -21,9 +21,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
 Requires-Dist: click
 Requires-Dist: patchright
 Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # patchright-cli
@@ -173,6 +178,8 @@ patchright-cli check <ref>             # Check checkbox
 patchright-cli uncheck <ref>           # Uncheck checkbox
 patchright-cli drag <from> <to>        # Drag and drop
 patchright-cli snapshot                # Accessibility snapshot
+patchright-cli snapshot -i             # Interactive elements only (recommended)
+patchright-cli snapshot --depth=3      # Limit depth
 patchright-cli snapshot <ref>          # Snapshot element subtree
 patchright-cli snapshot --filename=f   # Save to custom path
 patchright-cli eval <expr>             # Run JavaScript
@@ -297,6 +304,17 @@ patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+### Output
+```bash
+patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)
+patchright-cli --raw snapshot > p.yml  # Pipe raw snapshot to file
+```
+
+### Setup
+```bash
+patchright-cli install --skills        # Auto-install skills for detected AI agents
+```
+
 ### Sessions
 ```bash
 patchright-cli -s=mysession open https://example.com --persistent
@@ -371,6 +389,13 @@ Works with any AI coding agent that supports SKILL.md skills:
 | **Windsurf** | Copy SKILL.md to `.windsurf/skills/patchright-cli/` in your project |
 | **Aider** | Copy SKILL.md to `.aider/skills/patchright-cli/` in your project |
 
+Or auto-install for all detected agents:
+
+```bash
+pip install patchright-cli
+patchright-cli install --skills
+```
+
 Or just tell your agent:
 
 > Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
@@ -397,9 +422,7 @@ patchright-cli aims for full command parity with [Microsoft's playwright-cli](ht
 | Feature | Reason |
 |---------|--------|
 | `--browser=firefox/webkit/msedge` | Patchright only supports Chromium/Chrome. Anti-detect patches are Chrome-specific. |
-| `--config=<file>` | No config file system. Options are passed as CLI flags. |
 | `--extension` | Browser extension connection not supported. Patchright uses CDP directly. |
-| `show` / `devtools-start` | DevTools are available natively in headed mode (default). |
 | `install` / `install-browser` | Use `python -m patchright install chromium` instead. |
 
 All other commands and options are fully supported.
@@ -415,6 +438,16 @@ All other commands and options are fully supported.
 
 ---
 
+## Credits
+
+This project builds on the work of:
+
+- **[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)** by [@Kaliiiiiiiiii-Vinyzu](https://github.com/Kaliiiiiiiiii-Vinyzu) — the undetected Playwright fork that makes this possible. All anti-detect capabilities come from Patchright.
+- **[playwright-cli](https://github.com/microsoft/playwright-cli)** by Microsoft — the original CLI that patchright-cli's command interface is modeled after.
+- **[camoufox-cli](https://github.com/Bin-Huang/camoufox-cli)** by [@Bin-Huang](https://github.com/Bin-Huang) — inspiration for the CLI-first approach to anti-detect browser automation and the SKILL.md agent integration pattern.
+
+---
+
 ## License
 
 Apache 2.0 — same as [playwright-cli](https://github.com/microsoft/playwright-cli)

{patchright_cli-0.4.0 → patchright_cli-0.5.0}/README.md

@@ -145,6 +145,8 @@ patchright-cli check <ref>             # Check checkbox
 patchright-cli uncheck <ref>           # Uncheck checkbox
 patchright-cli drag <from> <to>        # Drag and drop
 patchright-cli snapshot                # Accessibility snapshot
+patchright-cli snapshot -i             # Interactive elements only (recommended)
+patchright-cli snapshot --depth=3      # Limit depth
 patchright-cli snapshot <ref>          # Snapshot element subtree
 patchright-cli snapshot --filename=f   # Save to custom path
 patchright-cli eval <expr>             # Run JavaScript
@@ -269,6 +271,17 @@ patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+### Output
+```bash
+patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)
+patchright-cli --raw snapshot > p.yml  # Pipe raw snapshot to file
+```
+
+### Setup
+```bash
+patchright-cli install --skills        # Auto-install skills for detected AI agents
+```
+
 ### Sessions
 ```bash
 patchright-cli -s=mysession open https://example.com --persistent
@@ -343,6 +356,13 @@ Works with any AI coding agent that supports SKILL.md skills:
 | **Windsurf** | Copy SKILL.md to `.windsurf/skills/patchright-cli/` in your project |
 | **Aider** | Copy SKILL.md to `.aider/skills/patchright-cli/` in your project |
 
+Or auto-install for all detected agents:
+
+```bash
+pip install patchright-cli
+patchright-cli install --skills
+```
+
 Or just tell your agent:
 
 > Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
@@ -369,9 +389,7 @@ patchright-cli aims for full command parity with [Microsoft's playwright-cli](ht
 | Feature | Reason |
 |---------|--------|
 | `--browser=firefox/webkit/msedge` | Patchright only supports Chromium/Chrome. Anti-detect patches are Chrome-specific. |
-| `--config=<file>` | No config file system. Options are passed as CLI flags. |
 | `--extension` | Browser extension connection not supported. Patchright uses CDP directly. |
-| `show` / `devtools-start` | DevTools are available natively in headed mode (default). |
 | `install` / `install-browser` | Use `python -m patchright install chromium` instead. |
 
 All other commands and options are fully supported.
@@ -387,6 +405,16 @@ All other commands and options are fully supported.
 
 ---
 
+## Credits
+
+This project builds on the work of:
+
+- **[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)** by [@Kaliiiiiiiiii-Vinyzu](https://github.com/Kaliiiiiiiiii-Vinyzu) — the undetected Playwright fork that makes this possible. All anti-detect capabilities come from Patchright.
+- **[playwright-cli](https://github.com/microsoft/playwright-cli)** by Microsoft — the original CLI that patchright-cli's command interface is modeled after.
+- **[camoufox-cli](https://github.com/Bin-Huang/camoufox-cli)** by [@Bin-Huang](https://github.com/Bin-Huang) — inspiration for the CLI-first approach to anti-detect browser automation and the SKILL.md agent integration pattern.
+
+---
+
 ## License
 
 Apache 2.0 — same as [playwright-cli](https://github.com/microsoft/playwright-cli)

patchright_cli-0.5.0/docs/superpowers/plans/2026-04-14-cdp-attach.md

@@ -0,0 +1,297 @@
+# CDP Attach Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add `attach --cdp=<url>` support so patchright-cli can connect to an already-running Chrome/Edge instance via the Chrome DevTools Protocol.
+
+**Architecture:** Add a new `attach` CLI command and corresponding daemon handler. When a `cdp_endpoint` is provided, the daemon uses `chromium.connect_over_cdp()` instead of `launch_persistent_context()`, then creates a fresh browser context and page from the connected `Browser` object.
+
+**Tech Stack:** Python 3.10+, Patchright (Playwright)
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|------|----------------|
+| `src/patchright_cli/cli.py` | Add `attach` command help and map `--cdp` flag. |
+| `src/patchright_cli/daemon.py` | Handle `attach` command, update `get_or_create_session` to support `cdp_endpoint`, `cdp_headers`, `cdp_timeout`. |
+| `tests/test_daemon_handlers.py` | Async test for `attach` handler. |
+
+---
+
+### Task 1: CLI command definition
+
+**Files:**
+- Modify: `src/patchright_cli/cli.py`
+
+- [ ] **Step 1: Add `attach` to command help**
+
+In `COMMANDS_HELP`, add:
+
+```python
+    "attach": "attach --cdp=<url>   Attach to running Chrome via CDP",
+```
+
+In `_print_help()`, under Browser lifecycle (near `open`), change the category to include `attach`:
+
+```python
+        (
+            "Core",
+            [
+                "open",
+                "attach",
+                "goto",
+                ...
+            ],
+        ),
+```
+
+- [ ] **Step 2: Add `--cdp` global option parsing**
+
+In `main()`, inside the option-parsing loop, add:
+
+```python
+        elif arg.startswith("--cdp="):
+            extra_opts["cdp"] = arg.split("=", 1)[1]
+        elif arg == "--cdp" and i + 1 < len(argv):
+            i += 1
+            extra_opts["cdp"] = argv[i]
+```
+
+And in `_print_help()`:
+
+```python
+    click.echo("  --cdp=<url>         Attach to Chrome via CDP endpoint")
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/patchright_cli/cli.py
+git commit -m "feat: add attach command and --cdp flag to CLI"
+```
+
+---
+
+### Task 2: Daemon handler and session creation
+
+**Files:**
+- Modify: `src/patchright_cli/daemon.py`
+- Test: `tests/test_daemon_handlers.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+@pytest.mark.asyncio
+async def test_attach_cdp(mock_state, mock_session):
+    mock_state.sessions = {}
+    mock_browser = MagicMock()
+    mock_context = MagicMock()
+    mock_page = MagicMock()
+    mock_page.url = "about:blank"
+    mock_page.title = AsyncMock(return_value="Attached")
+    mock_browser.new_context = AsyncMock(return_value=mock_context)
+    mock_context.new_page = AsyncMock(return_value=mock_page)
+    mock_context.pages = [mock_page]
+    mock_state.playwright.chromium.connect_over_cdp = AsyncMock(return_value=mock_browser)
+
+    with patch("patchright_cli.daemon.take_snapshot", new_callable=AsyncMock) as mock_snap:
+        mock_snap.return_value = ("snapshot-text", MagicMock())
+        with patch("patchright_cli.daemon.save_snapshot", return_value="/tmp/snap.yml"):
+            response = await handle_command(
+                mock_state,
+                {"command": "attach", "args": [], "options": {"cdp": "http://localhost:9222"}}
+            )
+    assert response["success"] is True
+    mock_state.playwright.chromium.connect_over_cdp.assert_awaited_once_with(
+        "http://localhost:9222", headers=None, timeout=30000
+    )
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/test_daemon_handlers.py::test_attach_cdp -v`
+Expected: FAIL — command unknown or `connect_over_cdp` not called.
+
+- [ ] **Step 3: Update `get_or_create_session` for CDP**
+
+In `DaemonState.get_or_create_session` signature, add:
+
+```python
+        cdp_endpoint: str | None = None,
+        cdp_headers: dict | None = None,
+        cdp_timeout: int = 30000,
+```
+
+Then replace the `launch_kwargs` and `launch_persistent_context` block with branching logic:
+
+```python
+        if cdp_endpoint:
+            browser = await self.playwright.chromium.connect_over_cdp(
+                cdp_endpoint, headers=cdp_headers, timeout=cdp_timeout
+            )
+            context = await browser.new_context()
+            pages = context.pages or []
+            if not pages:
+                page = await context.new_page()
+                pages = [page]
+        else:
+            launch_kwargs = {
+                "channel": "chrome",
+                "headless": use_headless,
+                "no_viewport": True,
+                "args": ["--disable-blink-features=AutomationControlled"],
+            }
+            if proxy:
+                parsed = urlparse(proxy)
+                if parsed.username or parsed.password:
+                    import base64
+                    creds = base64.b64encode(f"{parsed.username or ''}:{parsed.password or ''}".encode()).decode()
+                    launch_kwargs["extra_http_headers"] = {"Proxy-Authorization": f"Basic {creds}"}
+                    netloc = parsed.hostname or ""
+                    if parsed.port:
+                        netloc += f":{parsed.port}"
+                    cleaned = parsed._replace(netloc=netloc).geturl()
+                    launch_kwargs["proxy"] = {"server": cleaned}
+                else:
+                    launch_kwargs["proxy"] = {"server": proxy}
+            launch_kwargs.update(context_options)
+            context = await self.playwright.chromium.launch_persistent_context(
+                profile_dir,
+                **launch_kwargs,
+            )
+            pages = context.pages or []
+            if not pages:
+                page = await context.new_page()
+                pages = [page]
+```
+
+Wait, we need to make sure `context_options` is still built for the non-CDP path. And for CDP, device/viewport options should also be applied. Actually, when using `browser.new_context()` after CDP connect, we can pass context options directly to `new_context()`:
+
+```python
+        context_options = {}
+        if device and self.playwright is not None:
+            device_descriptor = self.playwright.devices.get(device)
+            if device_descriptor:
+                context_options.update(device_descriptor)
+        if viewport:
+            context_options["viewport"] = {"width": int(viewport["width"]), "height": int(viewport["height"])}
+        if locale:
+            context_options["locale"] = locale
+        if timezone:
+            context_options["timezone_id"] = timezone
+        if geolocation:
+            context_options["geolocation"] = {
+                "latitude": float(geolocation["lat"]),
+                "longitude": float(geolocation["lon"]),
+            }
+            context_options["permissions"] = context_options.get("permissions", []) + ["geolocation"]
+        if user_agent:
+            context_options["user_agent"] = user_agent
+        if grant_permissions:
+            perms = [p.strip() for p in grant_permissions.split(",") if p.strip()]
+            context_options["permissions"] = list(set(context_options.get("permissions", []) + perms))
+
+        if cdp_endpoint:
+            browser = await self.playwright.chromium.connect_over_cdp(
+                cdp_endpoint, headers=cdp_headers, timeout=cdp_timeout
+            )
+            context = await browser.new_context(**context_options)
+            pages = context.pages or []
+            if not pages:
+                page = await context.new_page()
+                pages = [page]
+        else:
+            launch_kwargs = {
+                "channel": "chrome",
+                "headless": use_headless,
+                "no_viewport": True,
+                "args": ["--disable-blink-features=AutomationControlled"],
+            }
+            if proxy:
+                parsed = urlparse(proxy)
+                if parsed.username or parsed.password:
+                    import base64
+                    creds = base64.b64encode(f"{parsed.username or ''}:{parsed.password or ''}".encode()).decode()
+                    launch_kwargs["extra_http_headers"] = {"Proxy-Authorization": f"Basic {creds}"}
+                    netloc = parsed.hostname or ""
+                    if parsed.port:
+                        netloc += f":{parsed.port}"
+                    cleaned = parsed._replace(netloc=netloc).geturl()
+                    launch_kwargs["proxy"] = {"server": cleaned}
+                else:
+                    launch_kwargs["proxy"] = {"server": proxy}
+            launch_kwargs.update(context_options)
+            context = await self.playwright.chromium.launch_persistent_context(
+                profile_dir,
+                **launch_kwargs,
+            )
+            pages = context.pages or []
+            if not pages:
+                page = await context.new_page()
+                pages = [page]
+```
+
+- [ ] **Step 4: Add `attach` handler and update `open` handler**
+
+In `handle_command`, add the `attach` branch right after the `open` branch:
+
+```python
+        if cmd == "attach":
+            cdp = options.get("cdp")
+            if not cdp:
+                return {"success": False, "output": "Usage: attach --cdp=<url>"}
+            headless = options.get("headless", False)
+            session = await state.get_or_create_session(
+                session_name,
+                headless=headless,
+                cdp_endpoint=cdp,
+                cdp_headers=options.get("cdp-headers"),
+                cdp_timeout=int(options.get("cdp-timeout", 30000)),
+                device=options.get("device"),
+                viewport=options.get("viewport"),
+                locale=options.get("locale"),
+                timezone=options.get("timezone"),
+                geolocation=options.get("geolocation"),
+                user_agent=options.get("user-agent") or options.get("userAgent"),
+                grant_permissions=options.get("grant-permissions") or options.get("grantPermissions"),
+            )
+            if session.page:
+                session.push_history(session.page.url)
+            return await _page_info(session, cwd)
+```
+
+- [ ] **Step 5: Run test**
+
+Run: `pytest tests/test_daemon_handlers.py::test_attach_cdp -v`
+Expected: PASS
+
+- [ ] **Step 6: Run full handler test suite**
+
+Run: `pytest tests/test_daemon_handlers.py -v`
+Expected: All PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add tests/test_daemon_handlers.py src/patchright_cli/daemon.py
+git commit -m "feat: attach to running Chrome via CDP endpoint"
+```
+
+---
+
+## Self-Review
+
+**1. Spec coverage:**
+- `attach --cdp=<url>` → Task 1 + Task 2
+- CDP headers/timeout support → Task 2 via `get_or_create_session`
+- All requirements covered.
+
+**2. Placeholder scan:**
+- No TBDs or vague steps.
+- Exact code provided for every change.
+
+**3. Type consistency:**
+- `cdp_endpoint` is consistently `str | None`.
+- `cdp_timeout` defaults to `30000` (int) throughout.