drissionpage-cli 0.2.0__tar.gz → 0.4.1__tar.gz

{drissionpage_cli-0.2.0 → drissionpage_cli-0.4.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: drissionpage-cli
-Version: 0.2.0
+Version: 0.4.1
 Summary: DrissionPage CLI - Token-efficient browser automation for coding agents
 Author: DrissionPage-MCP Contributors
 License: Apache-2.0
-Project-URL: Homepage, https://github.com/nicekate/DrissionPage-MCP
-Project-URL: Repository, https://github.com/nicekate/DrissionPage-MCP
+Project-URL: Homepage, https://github.com/M4rque2/DrissionPage-cli
+Project-URL: Repository, https://github.com/M4rque2/DrissionPage-cli
 Keywords: browser,automation,cli,drissionpage,web,scraping
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -21,7 +21,8 @@ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: DrissionPage>=4.0.0
+Requires-Dist: DrissionPage<6,>=5.0.0b1
+Requires-Dist: packaging>=21.0
 Dynamic: license-file
 
 # DrissionPage-cli
@@ -58,6 +59,19 @@ Modern coding agents (Claude Code, GitHub Copilot, etc.) increasingly favour CLI
 
 - Python 3.8+
 - Chrome / Chromium browser installed
+- DrissionPage 5 (`>=5.0.0b1,<6`, installed automatically)
+
+### Upgrading from DrissionPage 4
+
+This CLI only supports DrissionPage 5. Commands fail before connecting to or launching a browser if an older, unsupported, or unknown version is detected, and print an upgrade command:
+
+```bash
+python -m pip install --upgrade --pre "DrissionPage>=5.0.0b1,<6"
+```
+
+The check applies regardless of Chrome's version and cannot be disabled with `DRISSIONPAGE_CLI_NO_VERSION_WARN`. Help, version information, and `install --skills` remain available for recovery.
+
+DrissionPage 5 removes `ChromiumPage` and `WebPage`. The CLI uses `Chromium` for browser management and `ChromiumTab` for page operations. See the [official 5.0 changes](https://drissionpage.cn/features/5/) and [Chrome target investigation](docs/chrome146_compatibility_fix.md).
 
 ## Installation
 
@@ -70,8 +84,8 @@ pip install drissionpage-cli
 ### From source (development)
 
 ```bash
-git clone https://github.com/nicekate/DrissionPage-MCP.git
-cd DrissionPage-MCP/DrissionPage-cli
+git clone https://github.com/M4rque2/DrissionPage-cli.git
+cd DrissionPage-cli
 pip install -e .
 ```
 
@@ -172,17 +186,28 @@ For a fully isolated throwaway session (no persistent state):
 drissionpage-cli open --sandbox
 ```
 
-### Capture mode (full page archive)
+### Capture mode (network traffic recording)
+
+Append `--capture` to any interaction command to record all network traffic triggered by that action:
 
 ```bash
+# Capture during navigation
 drissionpage-cli open https://example.com --capture
+drissionpage-cli goto https://example.com --capture
+
+# Capture traffic triggered by a click (e.g. form submit, XHR, SPA navigation)
+drissionpage-cli click "#submit" --capture
+
+# Also supported on: dblclick, right-click, type, fill, hover, drag, select, check, uncheck
+drissionpage-cli fill "css:input[name=q]" "search term" --submit --capture
+drissionpage-cli hover "@id=lazy-load-trigger" --capture
 ```
 
 Creates a timestamped folder `capture-<ts>/` in the current directory containing:
 
 | File | Contents |
 |------|----------|
-| `snapshot.html` | Page HTML at load-complete time |
+| `snapshot.html` | Page HTML after the action completes |
 | `traffic.json` | Manifest of all requests (url, method, status, content_type, file) |
 | `0001_*.{ext}` … | Every response body saved as an individual file |
 
@@ -213,6 +238,8 @@ Captured file types include: HTML, CSS, JS, JSON, images (jpg, png, webp, gif, s
 | `select <ref> <value>` | Select dropdown option |
 | `check <ref>` / `uncheck <ref>` | Check / uncheck a checkbox |
 | `upload <ref> <file>` | Upload a file |
+
+All commands above (except `upload`) accept `--capture` to record network traffic triggered by the action.
 | `snapshot [ref] [--filename=f]` | Capture page or element snapshot |
 | `eval <expr> [ref]` | Evaluate JavaScript on page or element |
 | `run-code <code> [--filename=f]` | Run arbitrary DrissionPage Python code |
@@ -321,9 +348,40 @@ Or set a default session via environment variable:
 DRISSIONPAGE_CLI_SESSION=myproject drissionpage-cli open https://example.com
 ```
 
+## Browser Connection Lifecycle
+
+### How `open` connects
+
+`open` uses a lazy, connection-first strategy — it never kills a browser it didn't launch:
+
+1. **Reconnect to previous session** — if a session record exists in `~/.drissionpage-cli/sessions.json` and the browser is still alive, `open` reconnects to it. It does not kill and relaunch. Calling `open <url>` on a running session simply navigates to the new URL.
+2. **Launch a new browser** — if no session record exists and port 9222 is free, `open` starts a fresh Chrome instance with the CLI-managed profile.
+3. **Adopt an existing browser** — if port 9222 is already occupied (e.g. by an orphaned Chrome from a crashed session, or a manually launched `chrome --remote-debugging-port=9222`), `open` attempts a CDP connection. If it succeeds, the browser is adopted as the current session — no restart needed.
+4. **Report an error** — if the port is occupied by something that isn't a controllable Chrome (e.g. another server), `open` reports a clear error with options (`--port=<other>`, `kill-all`). It never auto-kills the process.
+
+### How `close` works
+
+`close` only shuts down browsers that have a session record. If you run `close` and there is no matching session in the registry, it prints `"Session 'X' not found. Nothing to close."` — it does not probe the port or kill unknown processes. To forcefully clean up all Chrome instances (including orphans), use `kill-all`.
+
+### Two processes controlling the same Chrome
+
+Chrome DevTools Protocol (CDP) allows multiple clients to connect simultaneously. If two dp-cli processes (or any two CDP clients) attach to the same Chrome on port 9222:
+
+- **Both send commands independently.** Chrome executes them in arrival order with no coordination — navigation, clicks, and JS evaluation from one client can interleave unpredictably with the other.
+- **Both receive all events.** DOM changes, navigations, and network events triggered by one client appear to the other as spontaneous activity.
+- **`close` from either side kills Chrome for both.** CDP's `Browser.close` terminates the entire browser process; the other client's WebSocket disconnects immediately.
+- **Neither client can detect the other.** CDP has no API to list connected clients or receive "another client connected" events.
+
+**Recommendation:** avoid sharing a single Chrome instance between concurrent automations. Use named sessions on different ports instead:
+
+```bash
+dp-cli -s=task1 open --port=9222 https://site-a.com
+dp-cli -s=task2 open --port=9223 https://site-b.com
+```
+
 ## Running Custom Code
 
-Execute arbitrary DrissionPage Python code with `run-code`. The `page` variable is the active `ChromiumPage` instance. Set `result` to output a return value.
+Execute arbitrary DrissionPage Python code with `run-code`. The `page` variable is the active DrissionPage 5 `ChromiumTab`; `browser` is its `Chromium` instance. Set `result` to output a return value.
 
 ```bash
 drissionpage-cli run-code "result = page.title"
@@ -379,7 +437,7 @@ DrissionPage-cli/
         network-listening.md
         dual-mode.md
   pyproject.toml                     # Python packaging
-  requirements.txt                   # DrissionPage>=4.0.0
+  requirements.txt                   # DrissionPage>=5.0.0b1,<6
   pytest.ini                         # Test configuration
   README.md
   LICENSE

{drissionpage_cli-0.2.0 → drissionpage_cli-0.4.1}/README.md

@@ -32,6 +32,19 @@ Modern coding agents (Claude Code, GitHub Copilot, etc.) increasingly favour CLI
 
 - Python 3.8+
 - Chrome / Chromium browser installed
+- DrissionPage 5 (`>=5.0.0b1,<6`, installed automatically)
+
+### Upgrading from DrissionPage 4
+
+This CLI only supports DrissionPage 5. Commands fail before connecting to or launching a browser if an older, unsupported, or unknown version is detected, and print an upgrade command:
+
+```bash
+python -m pip install --upgrade --pre "DrissionPage>=5.0.0b1,<6"
+```
+
+The check applies regardless of Chrome's version and cannot be disabled with `DRISSIONPAGE_CLI_NO_VERSION_WARN`. Help, version information, and `install --skills` remain available for recovery.
+
+DrissionPage 5 removes `ChromiumPage` and `WebPage`. The CLI uses `Chromium` for browser management and `ChromiumTab` for page operations. See the [official 5.0 changes](https://drissionpage.cn/features/5/) and [Chrome target investigation](docs/chrome146_compatibility_fix.md).
 
 ## Installation
 
@@ -44,8 +57,8 @@ pip install drissionpage-cli
 ### From source (development)
 
 ```bash
-git clone https://github.com/nicekate/DrissionPage-MCP.git
-cd DrissionPage-MCP/DrissionPage-cli
+git clone https://github.com/M4rque2/DrissionPage-cli.git
+cd DrissionPage-cli
 pip install -e .
 ```
 
@@ -146,17 +159,28 @@ For a fully isolated throwaway session (no persistent state):
 drissionpage-cli open --sandbox
 ```
 
-### Capture mode (full page archive)
+### Capture mode (network traffic recording)
+
+Append `--capture` to any interaction command to record all network traffic triggered by that action:
 
 ```bash
+# Capture during navigation
 drissionpage-cli open https://example.com --capture
+drissionpage-cli goto https://example.com --capture
+
+# Capture traffic triggered by a click (e.g. form submit, XHR, SPA navigation)
+drissionpage-cli click "#submit" --capture
+
+# Also supported on: dblclick, right-click, type, fill, hover, drag, select, check, uncheck
+drissionpage-cli fill "css:input[name=q]" "search term" --submit --capture
+drissionpage-cli hover "@id=lazy-load-trigger" --capture
 ```
 
 Creates a timestamped folder `capture-<ts>/` in the current directory containing:
 
 | File | Contents |
 |------|----------|
-| `snapshot.html` | Page HTML at load-complete time |
+| `snapshot.html` | Page HTML after the action completes |
 | `traffic.json` | Manifest of all requests (url, method, status, content_type, file) |
 | `0001_*.{ext}` … | Every response body saved as an individual file |
 
@@ -187,6 +211,8 @@ Captured file types include: HTML, CSS, JS, JSON, images (jpg, png, webp, gif, s
 | `select <ref> <value>` | Select dropdown option |
 | `check <ref>` / `uncheck <ref>` | Check / uncheck a checkbox |
 | `upload <ref> <file>` | Upload a file |
+
+All commands above (except `upload`) accept `--capture` to record network traffic triggered by the action.
 | `snapshot [ref] [--filename=f]` | Capture page or element snapshot |
 | `eval <expr> [ref]` | Evaluate JavaScript on page or element |
 | `run-code <code> [--filename=f]` | Run arbitrary DrissionPage Python code |
@@ -295,9 +321,40 @@ Or set a default session via environment variable:
 DRISSIONPAGE_CLI_SESSION=myproject drissionpage-cli open https://example.com
 ```
 
+## Browser Connection Lifecycle
+
+### How `open` connects
+
+`open` uses a lazy, connection-first strategy — it never kills a browser it didn't launch:
+
+1. **Reconnect to previous session** — if a session record exists in `~/.drissionpage-cli/sessions.json` and the browser is still alive, `open` reconnects to it. It does not kill and relaunch. Calling `open <url>` on a running session simply navigates to the new URL.
+2. **Launch a new browser** — if no session record exists and port 9222 is free, `open` starts a fresh Chrome instance with the CLI-managed profile.
+3. **Adopt an existing browser** — if port 9222 is already occupied (e.g. by an orphaned Chrome from a crashed session, or a manually launched `chrome --remote-debugging-port=9222`), `open` attempts a CDP connection. If it succeeds, the browser is adopted as the current session — no restart needed.
+4. **Report an error** — if the port is occupied by something that isn't a controllable Chrome (e.g. another server), `open` reports a clear error with options (`--port=<other>`, `kill-all`). It never auto-kills the process.
+
+### How `close` works
+
+`close` only shuts down browsers that have a session record. If you run `close` and there is no matching session in the registry, it prints `"Session 'X' not found. Nothing to close."` — it does not probe the port or kill unknown processes. To forcefully clean up all Chrome instances (including orphans), use `kill-all`.
+
+### Two processes controlling the same Chrome
+
+Chrome DevTools Protocol (CDP) allows multiple clients to connect simultaneously. If two dp-cli processes (or any two CDP clients) attach to the same Chrome on port 9222:
+
+- **Both send commands independently.** Chrome executes them in arrival order with no coordination — navigation, clicks, and JS evaluation from one client can interleave unpredictably with the other.
+- **Both receive all events.** DOM changes, navigations, and network events triggered by one client appear to the other as spontaneous activity.
+- **`close` from either side kills Chrome for both.** CDP's `Browser.close` terminates the entire browser process; the other client's WebSocket disconnects immediately.
+- **Neither client can detect the other.** CDP has no API to list connected clients or receive "another client connected" events.
+
+**Recommendation:** avoid sharing a single Chrome instance between concurrent automations. Use named sessions on different ports instead:
+
+```bash
+dp-cli -s=task1 open --port=9222 https://site-a.com
+dp-cli -s=task2 open --port=9223 https://site-b.com
+```
+
 ## Running Custom Code
 
-Execute arbitrary DrissionPage Python code with `run-code`. The `page` variable is the active `ChromiumPage` instance. Set `result` to output a return value.
+Execute arbitrary DrissionPage Python code with `run-code`. The `page` variable is the active DrissionPage 5 `ChromiumTab`; `browser` is its `Chromium` instance. Set `result` to output a return value.
 
 ```bash
 drissionpage-cli run-code "result = page.title"
@@ -353,7 +410,7 @@ DrissionPage-cli/
         network-listening.md
         dual-mode.md
   pyproject.toml                     # Python packaging
-  requirements.txt                   # DrissionPage>=4.0.0
+  requirements.txt                   # DrissionPage>=5.0.0b1,<6
   pytest.ini                         # Test configuration
   README.md
   LICENSE