browser-ctl 0.2.8__tar.gz → 0.2.10__tar.gz

{browser_ctl-0.2.8 → browser_ctl-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browser-ctl
-Version: 0.2.8
+Version: 0.2.10
 Summary: Control your browser from the command line via a Chrome extension + WebSocket bridge
 Author-email: geb <853934146@qq.com>
 License-Expression: MIT
@@ -125,7 +125,7 @@ Then in Chrome: `chrome://extensions` → Enable **Developer mode** → **Load u
 **Step 3** — Verify:
 
 ```bash
-bctl ping
+bctl ensure-ready
 # {"success": true, "data": {"server": true, "extension": true}}
 ```
 
@@ -216,7 +216,10 @@ All `<sel>` arguments accept CSS selectors **or** element refs from `snapshot` (
 
 | Command | Description |
 |---------|-------------|
+| `bctl ensure-ready` | Ensure server + extension are ready (auto-starts server, auto-launches Chrome if needed) |
 | `bctl ping` | Check server & extension status |
+| `bctl capabilities` | Show actions supported by the connected extension |
+| `bctl self-test` | Run generic end-to-end smoke tests for core skill actions |
 | `bctl serve` | Start server in foreground |
 | `bctl stop` | Stop server |
 | `bctl setup` | Install extension to `~/.browser-ctl/extension/` + open Chrome extensions page |

{browser_ctl-0.2.8 → browser_ctl-0.2.10}/README.md

@@ -99,7 +99,7 @@ Then in Chrome: `chrome://extensions` → Enable **Developer mode** → **Load u
 **Step 3** — Verify:
 
 ```bash
-bctl ping
+bctl ensure-ready
 # {"success": true, "data": {"server": true, "extension": true}}
 ```
 
@@ -190,7 +190,10 @@ All `<sel>` arguments accept CSS selectors **or** element refs from `snapshot` (
 
 | Command | Description |
 |---------|-------------|
+| `bctl ensure-ready` | Ensure server + extension are ready (auto-starts server, auto-launches Chrome if needed) |
 | `bctl ping` | Check server & extension status |
+| `bctl capabilities` | Show actions supported by the connected extension |
+| `bctl self-test` | Run generic end-to-end smoke tests for core skill actions |
 | `bctl serve` | Start server in foreground |
 | `bctl stop` | Stop server |
 | `bctl setup` | Install extension to `~/.browser-ctl/extension/` + open Chrome extensions page |

{browser_ctl-0.2.8 → browser_ctl-0.2.10}/browser_ctl/SKILL.md

@@ -14,11 +14,20 @@ Control Chrome via CLI. All commands return JSON to stdout.
 
 ## Always Start With
 
+```bash
+bctl ensure-ready
+```
+
+`ensure-ready` auto-starts the local bridge server and will try to launch Chrome
+if the extension is not connected yet.
+
+Fallback diagnostics:
+
 ```bash
 bctl ping
 ```
 
-If extension is not connected, tell the user to check Chrome and the extension.
+If it still shows `"extension": false`, tell the user to check Chrome and the extension.
 
 ## Core Principle: Text-First Page Perception
 
@@ -58,6 +67,8 @@ bctl uncheck <sel> [-i N] [-t text]  Uncheck checkbox
 bctl scroll <dir|sel> [n]            Scroll: up/down/top/bottom/<selector> [pixels]
 bctl select-option <sel> <val> [--text]  Select dropdown option (alias: sopt)
 bctl drag <src> [target] [--dx N --dy N] Drag element to target or by offset
+bctl set-field <sel> <value> [--no-clear] [--text]            Generic field setter
+bctl submit-and-assert [sel] [--assert-selector CSS] [--assert-url EXP] [--mode ...] [--timeout s]
 ```
 
 ### Query
@@ -71,6 +82,8 @@ bctl count <sel>          Count matching elements
 bctl status               Current page URL and title
 bctl is-visible <sel>     Check if element is visible (returns rect)
 bctl get-value <sel>      Get form element value (input/select/textarea)
+bctl assert-url <exp> [--mode equals|includes|regex]          Assert current URL
+bctl assert-field-value <sel> <exp> [--mode ...] [--by-text]  Assert field value/text
 ```
 
 ### JavaScript
@@ -117,7 +130,10 @@ browser call, reducing overhead by ~90%.
 
 ### Server
 ```
+bctl ensure-ready         Ensure server + extension are ready (auto-launch Chrome)
 bctl ping                 Check server and extension status
+bctl capabilities         Show extension-supported actions
+bctl self-test            Run generic end-to-end smoke checks
 bctl serve                Start server (foreground)
 bctl stop                 Stop server
 ```
@@ -147,19 +163,13 @@ Use `-t` to filter by visible text — ideal for SPAs where class names are dyna
 bctl click "button" -t "Submit"   # click button containing "Submit"
 ```
 
-### SPA Video Sites (Tencent Video, Bilibili, etc.)
-`bctl click` intercepts `window.open()` calls from SPA frameworks and opens the
-target URL via `chrome.tabs.create`. Just click like a normal user:
+### Generic Submit + Assertion Flow
+Prefer assertions after every important state change:
 ```bash
-bctl go "https://v.qq.com" && bctl wait 2
-bctl type "input" "西游记" && bctl press Enter && bctl wait 3
-bctl click ".root.list-item .poster-view" -i 0   # opens video in new tab
-```
-
-Fallback — extract content ID and navigate directly:
-```bash
-bctl attr ".root.list-item [dt-eid='poster']" "dt-params" | grep -o 'cid=[^&]*'
-bctl go "https://v.qq.com/x/cover/<cid>.html"
+bctl click "button" -t "Open settings"
+bctl set-field "input[name='displayName']" "Alice"
+bctl submit-and-assert "button[type='submit']" --assert-selector ".toast-success" --timeout 8
+bctl assert-field-value "input[name='displayName']" "Alice"
 ```
 
 ### Waiting Strategy
@@ -169,13 +179,13 @@ bctl go "https://v.qq.com/x/cover/<cid>.html"
 - Pure sleep (`bctl wait N`) runs locally in Python — no extension round-trip, so it
   never times out even on heavy pages.
 
-### Heavy SPA Pages (YouTube, Gmail, etc.)
-Heavy SPA pages can cause the extension service worker to become unresponsive during
+### Heavy SPA Pages
+Heavy pages can cause the extension service worker to become unresponsive during
 page load. To avoid timeouts:
 - **Don't chain `bctl wait` with navigation via `&&`** — if the page is loading, the
   wait command may timeout because the extension is busy. Instead, run them separately:
   ```bash
-  bctl go "https://www.youtube.com"
+  bctl go "https://example.com"
   bctl wait 3
   bctl status
   ```
@@ -245,10 +255,22 @@ and returns text/href/id/class/aria-label automatically.
 7. **Prefer `bctl go` over `bctl new-tab`** for simple navigation — fewer failure modes.
 8. **Never use `eval` to set input values or click buttons on SPA sites** — use `type`/`input-text`/`click`.
 9. **Verify after complex UI interactions** — `snapshot` or `text` to confirm state changed.
+10. **Use assertion primitives** — `assert-url`, `assert-field-value`, `submit-and-assert`.
+
+## Universal Interaction Template
+
+Use this sequence on any site:
+
+1. `bctl ensure-ready`
+2. `bctl status` and `bctl snapshot`
+3. Prefer `eN` refs from snapshot when possible
+4. Execute (`click`/`set-field`/`type`)
+5. Assert (`assert-url` / `assert-field-value` / `count`)
+6. Retry only when error is retriable; otherwise refresh snapshot and re-select
 
 ## Known Limitations
 
-- `eval` blocked by Trusted Types on some sites (Gemini, YouTube) — use `attr`/`select` instead
+- `eval` may be blocked by Trusted Types/CSP on some pages — use `attr`/`select` instead
 - `eval` with `input.value = ...` or `.click()` bypasses SPA framework state — use `type`/`click` instead
 - `screenshot` captures visible viewport only — scroll for full-page capture
 - Without `-i`, `click` always hits the FIRST match — use `count` to check first

{browser_ctl-0.2.8 → browser_ctl-0.2.10}/browser_ctl/cli.py

@@ -62,6 +62,7 @@ CONTENT_SCRIPT_OPS = frozenset({
 	"text", "html", "attr", "select", "count", "snapshot",
 	"is-visible", "get-value",
 	"scroll", "select-option", "drag", "wait",
+	"assert-url", "assert-field-value", "set-field", "submit-and-assert",
 })
 
 
@@ -175,6 +176,29 @@ def build_parser() -> argparse.ArgumentParser:
 		prog="bctl",
 		description="Control your browser from the command line",
 	)
+	parser.add_argument(
+		"--session",
+		default=None,
+		help="Execution session id (default: default)",
+	)
+	parser.add_argument(
+		"--tab",
+		type=int,
+		default=None,
+		help="Target tab id for command execution",
+	)
+	parser.add_argument(
+		"--window",
+		type=int,
+		default=None,
+		help="Target window id (uses active tab in that window)",
+	)
+	parser.add_argument(
+		"--world",
+		choices=["ISOLATED", "MAIN"],
+		default=None,
+		help="Script execution world override for DOM operations",
+	)
 	sub = parser.add_subparsers(dest="command", help="Available commands")
 
 	# -- Navigation --
@@ -261,6 +285,28 @@ def build_parser() -> argparse.ArgumentParser:
 	p.add_argument("selector", help="CSS selector or element ref")
 	p.add_argument("-i", "--index", type=int, default=None, help="Nth matching element (0-based)")
 
+	p = sub.add_parser("assert-url", help="Assert current URL matches expectation")
+	p.add_argument("expected", help="Expected URL value/pattern")
+	p.add_argument(
+		"--mode",
+		choices=["equals", "includes", "regex"],
+		default="includes",
+		help="Assertion mode (default: includes)",
+	)
+
+	p = sub.add_parser("assert-field-value", help="Assert form field value/text")
+	p.add_argument("selector", help="CSS selector or element ref")
+	p.add_argument("expected", help="Expected field value/text")
+	p.add_argument(
+		"--mode",
+		choices=["equals", "includes", "regex"],
+		default="equals",
+		help="Assertion mode (default: equals)",
+	)
+	p.add_argument("--by-text", action="store_true", help="Assert selected option text instead of value")
+	p.add_argument("-i", "--index", type=int, default=None, help="Nth matching element (0-based)")
+	p.add_argument("-t", "--text", default=None, help="Filter by visible text content")
+
 	# -- JavaScript --
 	p = sub.add_parser("eval", help="Execute JavaScript in page context")
 	p.add_argument("code", help="JavaScript code to execute")
@@ -297,6 +343,27 @@ def build_parser() -> argparse.ArgumentParser:
 	p.add_argument("value", help="Option value or text to select")
 	p.add_argument("--text", action="store_true", help="Match by visible text instead of value")
 
+	p = sub.add_parser("set-field", help="Set field value in a generic way")
+	p.add_argument("selector", help="CSS selector or element ref")
+	p.add_argument("value", help="Field value to set")
+	p.add_argument("--no-clear", action="store_true", help="Do not clear before setting value")
+	p.add_argument("-i", "--index", type=int, default=None, help="Nth matching element (0-based)")
+	p.add_argument("-t", "--text", default=None, help="Filter by visible text content")
+
+	p = sub.add_parser("submit-and-assert", help="Submit and assert URL/selector outcome")
+	p.add_argument("selector", nargs="?", default=None, help="Submit target selector (form/button)")
+	p.add_argument("--assert-selector", default=None, help="Selector that should appear after submit")
+	p.add_argument("--assert-url", default=None, help="URL value/pattern expected after submit")
+	p.add_argument(
+		"--mode",
+		choices=["equals", "includes", "regex"],
+		default="includes",
+		help="URL assertion mode (default: includes)",
+	)
+	p.add_argument("--timeout", type=float, default=5, help="Max wait seconds for assertion")
+	p.add_argument("-i", "--index", type=int, default=None, help="Nth matching element (0-based)")
+	p.add_argument("-t", "--text", default=None, help="Filter by visible text content")
+
 	# -- File upload --
 	p = sub.add_parser("upload", help="Upload file(s) to file input")
 	p.add_argument("selector", help="CSS selector for file input")
@@ -322,8 +389,15 @@ def build_parser() -> argparse.ArgumentParser:
 	# -- Server management --
 	sub.add_parser("serve", help="Start bridge server (foreground)")
 	sub.add_parser("ping", help="Check server and extension status")
+	sub.add_parser("capabilities", help="Show extension-supported actions")
+	p = sub.add_parser("ensure-ready", help="Ensure server + extension are ready (auto-launch Chrome)")
+	p.add_argument("--timeout", type=float, default=20, help="Max seconds to wait for extension connection")
+	p.add_argument("--no-launch", action="store_true", help="Do not auto-launch Chrome")
 	sub.add_parser("stop", help="Stop bridge server")
 
+	p = sub.add_parser("self-test", help="Run generic skill smoke tests")
+	p.add_argument("--timeout", type=float, default=20, help="ensure-ready timeout in seconds")
+
 	# -- Batch / Pipe --
 	p = sub.add_parser("pipe", help="Read commands from stdin (one per line, JSONL output)")
 	p.add_argument("--continue-on-error", action="store_true", help="Don't stop on first error")
@@ -422,6 +496,101 @@ def handle_serve(args):
 	os.execvp(sys.executable, [sys.executable, "-m", "browser_ctl.server", "--port", str(DEFAULT_PORT)])
 
 
+def handle_ensure_ready(args):
+	"""Ensure bridge server and extension are connected."""
+	result = _client().ensure_ready(timeout=args.timeout, launch_browser=not args.no_launch)
+	print(json.dumps(result, ensure_ascii=False))
+	if not result.get("success"):
+		sys.exit(1)
+
+
+def handle_capabilities(_args):
+	"""Query extension capabilities."""
+	_client().ensure_server_optimistic()
+	result = _client().send_raw("capabilities", {})
+	print(json.dumps(result, ensure_ascii=False))
+	if not result.get("success"):
+		sys.exit(1)
+
+
+def handle_self_test(args):
+	"""Run generic, site-agnostic smoke tests."""
+	def fail(msg: str):
+		print(json.dumps({"success": False, "error": msg}, ensure_ascii=False))
+		sys.exit(1)
+
+	ready = _client().ensure_ready(timeout=args.timeout, launch_browser=True)
+	if not ready.get("success"):
+		print(json.dumps(ready, ensure_ascii=False))
+		sys.exit(1)
+
+	caps = _client().send_raw("capabilities", {})
+	if not caps.get("success"):
+		err = str(caps.get("error", ""))
+		if "Unknown action: capabilities" in err:
+			fail("Connected extension is outdated. Please run `bctl setup` and reload extension from ~/.browser-ctl/extension.")
+		fail(f"capabilities check failed: {err}")
+
+	actions = set(caps.get("data", {}).get("actions", []))
+	required = {"assert-url", "assert-field-value", "set-field", "submit-and-assert"}
+	missing = sorted(required - actions)
+	if missing:
+		fail(f"Extension missing required actions: {missing}. Reload extension from ~/.browser-ctl/extension.")
+
+	html = (
+		"<html><body>"
+		"<h1 id='title'>Skill Smoke</h1>"
+		"<input id='name' />"
+		"<button id='save' onclick=\"document.getElementById('out').textContent=document.getElementById('name').value\">Save</button>"
+		"<div id='out'></div>"
+		"<form id='f' onsubmit=\"event.preventDefault(); location.hash='submitted';\">"
+		"<input id='email' />"
+		"<button id='submit' type='submit'>Submit</button>"
+		"</form>"
+		"</body></html>"
+	)
+	import urllib.parse
+	url = "https://example.com"
+	status_result = _client().send_raw("status", {})
+	if not status_result.get("success"):
+		fail(f"self-test failed at status: {status_result.get('error')}")
+	tab_id = status_result.get("data", {}).get("id")
+	if tab_id is None:
+		fail("self-test failed: status returned no tab id")
+
+	steps = [
+		("navigate", {"url": url}),
+		("assert-url", {"expected": "example.com", "mode": "includes"}),
+		("eval", {"code": f"document.body.innerHTML = {json.dumps(html)}; 'ok'"}),
+		("snapshot", {"interactive": True}),
+		("set-field", {"selector": "#name", "value": "Alice", "clear": True}),
+		("assert-field-value", {"selector": "#name", "expected": "Alice", "mode": "equals"}),
+		("click", {"selector": "#save"}),
+		("text", {"selector": "#out"}),
+		("submit-and-assert", {"selector": "#submit", "assertUrl": "#submitted", "mode": "includes", "timeout": 5}),
+		("assert-url", {"expected": "#submitted", "mode": "includes"}),
+	]
+
+	for action, params in steps:
+		p = dict(params)
+		p["tabId"] = tab_id
+		result = _client().send_raw(action, p)
+		if not result.get("success"):
+			fail(f"self-test failed at {action}: {result.get('error')}")
+		if action == "text":
+			text = str(result.get("data", {}).get("text", "")).strip()
+			if text != "Alice":
+				fail(f"self-test failed: expected #out text 'Alice', got '{text}'")
+
+	print(json.dumps({
+		"success": True,
+		"data": {
+			"selfTest": "passed",
+			"checks": [s[0] for s in steps],
+		},
+	}, ensure_ascii=False))
+
+
 def _get_extension_source_dir() -> str | None:
 	"""Locate the extension source directory.
 
@@ -593,6 +762,8 @@ _ALIASES = {
 	"dl": "download",
 	"sopt": "select-option",
 	"snap": "snapshot",
+	"ready": "ensure-ready",
+	"caps": "capabilities",
 }
 
 
@@ -645,6 +816,17 @@ def args_to_action_params(cmd: str, args) -> tuple[str, dict]:
 		params = {"selector": args.selector, "index": args.index}
 	elif cmd == "get-value":
 		params = {"selector": args.selector, "index": args.index}
+	elif cmd == "assert-url":
+		params = {"expected": args.expected, "mode": args.mode}
+	elif cmd == "assert-field-value":
+		params = {
+			"selector": args.selector,
+			"expected": args.expected,
+			"mode": args.mode,
+			"byText": args.by_text,
+			"index": args.index,
+			"text": args.text,
+		}
 	elif cmd == "eval":
 		params = {"code": args.code}
 	elif cmd == "tab":
@@ -657,6 +839,24 @@ def args_to_action_params(cmd: str, args) -> tuple[str, dict]:
 		params = {"target": args.target, "amount": args.amount}
 	elif cmd == "select-option":
 		params = {"selector": args.selector, "value": args.value, "byText": args.text}
+	elif cmd == "set-field":
+		params = {
+			"selector": args.selector,
+			"value": args.value,
+			"clear": not args.no_clear,
+			"index": args.index,
+			"text": args.text,
+		}
+	elif cmd == "submit-and-assert":
+		params = {
+			"selector": args.selector,
+			"assertSelector": args.assert_selector,
+			"assertUrl": args.assert_url,
+			"mode": args.mode,
+			"timeout": args.timeout,
+			"index": args.index,
+			"text": args.text,
+		}
 	elif cmd == "upload":
 		files = [os.path.abspath(f) for f in args.files]
 		params = {"selector": args.selector, "files": files}
@@ -670,6 +870,16 @@ def args_to_action_params(cmd: str, args) -> tuple[str, dict]:
 			params = {"seconds": seconds}
 		except ValueError:
 			params = {"selector": args.target, "timeout": args.timeout}
+
+	# Optional execution context (applies to all server-side actions)
+	if getattr(args, "session", None):
+		params["sessionId"] = args.session
+	if getattr(args, "tab", None) is not None:
+		params["tabId"] = args.tab
+	if getattr(args, "window", None) is not None:
+		params["windowId"] = args.window
+	if getattr(args, "world", None):
+		params["world"] = args.world
 	return cmd, params
 
 
@@ -713,6 +923,15 @@ def main():
 	if cmd == "serve":
 		handle_serve(args)
 		return
+	if cmd == "capabilities":
+		handle_capabilities(args)
+		return
+	if cmd == "ensure-ready":
+		handle_ensure_ready(args)
+		return
+	if cmd == "self-test":
+		handle_self_test(args)
+		return
 	if cmd == "stop":
 		_client().stop_server()
 		return

{browser_ctl-0.2.8 → browser_ctl-0.2.10}/browser_ctl/client.py

@@ -9,8 +9,12 @@ from __future__ import annotations
 
 import json
 import os
+import platform
+import shutil
 import socket
+import subprocess
 import sys
+import time
 
 DEFAULT_PORT = 19876
 _HOST = "127.0.0.1"
@@ -192,3 +196,119 @@ def ensure_server_optimistic() -> None:
 	result = send_raw("ping", {})
 	if not result.get("success") and "Cannot connect" in result.get("error", ""):
 		start_server()
+
+
+def _launch_chrome() -> tuple[bool, str]:
+	"""Try to launch Chrome/Chromium and return (started, method)."""
+	system = platform.system()
+
+	if system == "Darwin":
+		try:
+			subprocess.Popen(
+				["open", "-a", "Google Chrome"],
+				stdout=subprocess.DEVNULL,
+				stderr=subprocess.DEVNULL,
+			)
+			return True, "open -a Google Chrome"
+		except Exception:
+			return False, "open -a Google Chrome"
+
+	if system == "Windows":
+		candidates = [
+			"chrome",
+			r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+			r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+		]
+		for cmd in candidates:
+			try:
+				subprocess.Popen(
+					[cmd],
+					stdout=subprocess.DEVNULL,
+					stderr=subprocess.DEVNULL,
+					creationflags=getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),
+				)
+				return True, cmd
+			except Exception:
+				continue
+		return False, "chrome"
+
+	# Linux / other unix-like: try common Chrome/Chromium binaries
+	for cmd in ("google-chrome", "chromium", "chromium-browser"):
+		if shutil.which(cmd) is None:
+			continue
+		try:
+			subprocess.Popen(
+				[cmd],
+				stdout=subprocess.DEVNULL,
+				stderr=subprocess.DEVNULL,
+			)
+			return True, cmd
+		except Exception:
+			continue
+	return False, "google-chrome/chromium"
+
+
+def ensure_ready(timeout: float = 20.0, launch_browser: bool = True) -> dict:
+	"""Ensure bridge server + extension are ready.
+
+	Flow:
+	1) Start server if needed
+	2) Check ping
+	3) If extension disconnected and launch enabled, attempt to launch Chrome
+	4) Poll until timeout for extension connection
+	"""
+	ensure_server_optimistic()
+	result = send_raw("ping", {})
+	if result.get("success") and result.get("data", {}).get("extension"):
+		return {
+			"success": True,
+			"data": {
+				"server": True,
+				"extension": True,
+				"launchedBrowser": False,
+				"waitedSeconds": 0.0,
+			},
+		}
+
+	if not launch_browser:
+		return result
+
+	started, method = _launch_chrome()
+	if not started:
+		return {
+			"success": False,
+			"error": (
+				"Chrome extension not connected and failed to launch browser. "
+				f"Tried: {method}. Run `bctl setup` and ensure extension is loaded."
+			),
+		}
+
+	deadline = time.time() + max(timeout, 1.0)
+	last = result
+	while time.time() < deadline:
+		time.sleep(0.5)
+		last = send_raw("ping", {})
+		if last.get("success") and last.get("data", {}).get("extension"):
+			return {
+				"success": True,
+				"data": {
+					"server": True,
+					"extension": True,
+					"launchedBrowser": True,
+					"launchMethod": method,
+					"waitedSeconds": round(max(0.0, timeout - max(0.0, deadline - time.time())), 1),
+				},
+			}
+
+	return {
+		"success": False,
+		"error": (
+			"Chrome launched but extension is still not connected. "
+			"Open chrome://extensions and ensure Browser-Ctl extension is loaded."
+		),
+		"data": {
+			"launchedBrowser": True,
+			"launchMethod": method,
+			"lastPing": last,
+		},
+	}