browser-ctl 0.1.0__py3-none-any.whl

browser_ctl/SKILL.md

@@ -0,0 +1,170 @@
+# browser-ctl
+
+CLI tool for browser automation. Control Chrome from the terminal via `bctl` commands.
+All commands communicate through a Chrome extension + WebSocket bridge and return JSON.
+
+## When to Use
+
+Use browser-ctl when you need to:
+- Navigate web pages, click elements, type text, press keys
+- Query the DOM: get text, HTML, attributes, or count elements
+- Take screenshots or download files (preserves browser auth/cookies)
+- Execute arbitrary JavaScript in the page context
+- Manage browser tabs (list, switch, open, close)
+- Automate browser workflows for testing or data extraction
+
+## Prerequisites
+
+- Chrome with the Browser-Ctl extension loaded
+- Bridge server (auto-starts with any `bctl` command)
+
+## Commands
+
+### Navigation
+```
+bctl navigate <url>       Navigate to URL (aliases: nav, go)
+bctl back                 Go back
+bctl forward              Go forward (alias: fwd)
+bctl reload               Reload page
+```
+
+### Interaction
+```
+bctl click <sel> [-i N]   Click element (CSS selector, optional index)
+bctl hover <sel> [-i N]   Hover over element
+bctl type <sel> <text>    Type text into element
+bctl press <key>          Press key (Enter, Escape, Tab, etc.)
+bctl scroll <dir|sel> [n] Scroll page: up/down/top/bottom or element into view
+bctl select-option <sel> <val> [--text]  Select <select> dropdown option (alias: sopt)
+bctl drag <src> [target]  Drag element to target [--dx N --dy N for offset]
+```
+
+### Query
+```
+bctl text [sel]           Get text content (default: body)
+bctl html [sel]           Get innerHTML
+bctl attr <sel> [name]    Get attribute(s) [-i N for Nth element]
+bctl select <sel> [-l N]  List matching elements (alias: sel, limit default: 20)
+bctl count <sel>          Count matching elements
+bctl status               Current page URL and title
+```
+
+### JavaScript
+```
+bctl eval <code>          Execute JS in page context
+```
+
+### Tabs
+```
+bctl tabs                 List all tabs
+bctl tab <id>             Switch to tab
+bctl new-tab [url]        Open new tab
+bctl close-tab [id]       Close tab (default: active)
+```
+
+### Screenshot & Download
+```
+bctl screenshot [path]    Capture screenshot (alias: ss)
+bctl download <target>    Download file/image (alias: dl) [-o file] [-i N]
+bctl upload <sel> <files> Upload file(s) to <input type="file">
+```
+
+### Wait
+```
+bctl wait <sel|seconds>   Wait for element or sleep [timeout]
+```
+
+### Dialog
+```
+bctl dialog [accept|dismiss] [--text <val>]  Handle next alert/confirm/prompt
+```
+
+### Server
+```
+bctl ping                 Check server and extension status
+bctl serve                Start server (foreground)
+bctl stop                 Stop server
+```
+
+## Output Format
+
+All commands return JSON:
+- Success: `{"success": true, "data": {...}}`
+- Error: `{"success": false, "error": "..."}`
+
+## Tips & Best Practices
+
+### Data Extraction
+- **Prefer `bctl select` over `bctl eval`** for extracting structured DOM data — it's
+  more reliable across all sites, returns text/href/id/class/aria-label automatically,
+  and doesn't require complex JS strings.
+- Use `bctl text <sel>` for simple text extraction and `bctl attr <sel> [name]` for
+  specific attributes. Chain with `-i N` for Nth element.
+- Reserve `bctl eval` for cases that truly need complex JS logic (e.g. mapping/filtering,
+  accessing page-defined variables, or computing derived values).
+
+### Search & Scrape Workflow
+A typical pattern for searching a site and extracting results:
+```bash
+bctl go "https://site.com/search?q=keyword"      # Navigate
+bctl wait ".results" 10                           # Wait for results
+bctl select ".result-item a" -l 10                # Extract links
+bctl attr ".result-item a" href -i 0              # Get specific attribute
+```
+
+### Waiting Strategy
+- Always `bctl wait <selector> [timeout]` or `bctl wait <seconds>` after navigation
+  before querying — SPAs like YouTube take time to render content.
+- Prefer waiting for a specific element over a fixed delay when possible.
+
+### Shell Quoting
+- Wrap CSS selectors in double quotes: `bctl click "button.submit"`
+- For `bctl eval`, use double quotes for the outer string and single quotes inside:
+  `bctl eval "document.querySelector('h1').textContent"`
+
+## Examples
+
+```bash
+# Navigate and inspect
+bctl go https://example.com
+bctl status
+bctl text h1
+
+# Click and type
+bctl click "button.login"
+bctl type "input[name=q]" "search query"
+bctl press Enter
+
+# Scroll a long page
+bctl scroll down              # Scroll down ~80% viewport
+bctl scroll down 500          # Scroll down 500px
+bctl scroll up                # Scroll up
+bctl scroll top               # Scroll to top
+bctl scroll bottom            # Scroll to bottom
+bctl scroll "#section-3"      # Scroll element into view
+
+# Form interaction
+bctl select-option "select#country" "US"           # Select by value
+bctl select-option "select#lang" "English" --text  # Select by visible text
+bctl upload "input[type=file]" ./photo.jpg          # Upload file
+
+# Handle dialogs (call BEFORE triggering action)
+bctl dialog accept               # Auto-accept next alert/confirm
+bctl dialog dismiss              # Dismiss next confirm
+bctl dialog accept --text "yes"  # Answer next prompt with "yes"
+
+# Drag and drop
+bctl drag ".card-1" ".column-done"          # Drag to target element
+bctl drag ".slider-handle" --dx 100 --dy 0  # Drag by pixel offset
+
+# Wait then screenshot
+bctl wait ".loaded" 10
+bctl ss page.png
+
+# Download with browser auth
+bctl download "https://site.com/file.pdf" -o file.pdf
+
+# Extract structured data (prefer select over eval)
+bctl select "a.video-link" -l 10
+bctl eval "JSON.stringify(Array.from(document.querySelectorAll('a')).slice(0,5).map(a=>({text:a.textContent.trim(),href:a.href})))"
+```

browser_ctl/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running the package with: python -m browser_ctl"""
+from browser_ctl.cli import main
+
+main()

browser_ctl/cli.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""browser-ctl CLI — control your browser from the terminal.
+
+Zero external dependencies (stdlib only). Communicates with the bridge server
+via HTTP POST to localhost:19876/command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import platform
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+
+DEFAULT_PORT = 19876
+SERVER_URL = f"http://127.0.0.1:{DEFAULT_PORT}"
+PID_FILE = os.path.join(tempfile.gettempdir(), f"bctl-{DEFAULT_PORT}.pid")
+
+BCTL_HOME = os.path.join(os.path.expanduser("~"), ".browser-ctl")
+
+SKILL_TARGETS = {
+	"cursor": os.path.join(os.path.expanduser("~"), ".cursor", "skills-cursor"),
+	"opencode": os.path.join(os.path.expanduser("~"), ".config", "opencode", "skills"),
+}
+
+# ---------------------------------------------------------------------------
+# Server management
+# ---------------------------------------------------------------------------
+
+
+def is_server_running() -> bool:
+	"""Check if bridge server is running."""
+	if not os.path.exists(PID_FILE):
+		return False
+	try:
+		with open(PID_FILE) as f:
+			pid = int(f.read().strip())
+		os.kill(pid, 0)
+		return True
+	except (OSError, ValueError):
+		return False
+
+
+def start_server() -> bool:
+	"""Start bridge server as daemon. Returns True if started."""
+	if is_server_running():
+		return False
+
+	cmd = [sys.executable, "-m", "browser_ctl.server", "--port", str(DEFAULT_PORT), "--daemon"]
+	subprocess.Popen(
+		cmd,
+		start_new_session=True,
+		stdout=subprocess.DEVNULL,
+		stderr=subprocess.DEVNULL,
+	)
+
+	# Wait for server to become responsive
+	for _ in range(60):  # 3 seconds max
+		time.sleep(0.05)
+		try:
+			req = urllib.request.Request(f"{SERVER_URL}/health")
+			resp = urllib.request.urlopen(req, timeout=0.5)
+			if resp.status == 200:
+				return True
+		except Exception:
+			pass
+
+	print(json.dumps({"success": False, "error": "Failed to start bridge server"}))
+	sys.exit(1)
+
+
+def stop_server():
+	"""Stop bridge server."""
+	send_raw("shutdown", {})
+
+
+def ensure_server():
+	"""Make sure server is running, start if needed."""
+	if not is_server_running():
+		start_server()
+
+
+# ---------------------------------------------------------------------------
+# Command sending
+# ---------------------------------------------------------------------------
+
+
+def send_raw(action: str, params: dict) -> dict:
+	"""Send command to bridge server, return parsed response."""
+	body = json.dumps({"action": action, "params": params}).encode("utf-8")
+	req = urllib.request.Request(
+		f"{SERVER_URL}/command",
+		data=body,
+		headers={"Content-Type": "application/json"},
+	)
+	try:
+		resp = urllib.request.urlopen(req, timeout=35)
+		return json.loads(resp.read().decode("utf-8"))
+	except urllib.error.URLError as e:
+		return {"success": False, "error": f"Cannot connect to server: {e}"}
+	except json.JSONDecodeError:
+		return {"success": False, "error": "Invalid response from server"}
+
+
+def send_command(action: str, params: dict):
+	"""Ensure server, send command, print JSON result."""
+	ensure_server()
+	result = send_raw(action, params)
+	print(json.dumps(result, ensure_ascii=False))
+	if not result.get("success"):
+		sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# CLI definition
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser(
+		prog="bctl",
+		description="Control your browser from the command line",
+	)
+	sub = parser.add_subparsers(dest="command", help="Available commands")
+
+	# -- Navigation --
+	p = sub.add_parser("navigate", aliases=["nav", "go"], help="Navigate to URL")
+	p.add_argument("url", help="URL to navigate to")
+
+	sub.add_parser("back", help="Go back in history")
+	sub.add_parser("forward", aliases=["fwd"], help="Go forward in history")
+	sub.add_parser("reload", help="Reload current page")
+
+	# -- Interaction --
+	p = sub.add_parser("click", help="Click an element")
+	p.add_argument("selector", help="CSS selector")
+	p.add_argument("-i", "--index", type=int, default=None, help="Click Nth matching element (0-based, negative from end)")
+
+	p = sub.add_parser("hover", help="Hover over an element (trigger mouseover)")
+	p.add_argument("selector", help="CSS selector")
+	p.add_argument("-i", "--index", type=int, default=None, help="Hover Nth matching element (0-based)")
+
+	p = sub.add_parser("type", help="Type text into an element")
+	p.add_argument("selector", help="CSS selector")
+	p.add_argument("text", help="Text to type")
+
+	p = sub.add_parser("press", help="Press a keyboard key")
+	p.add_argument("key", help="Key name (Enter, Escape, Tab, etc.)")
+
+	# -- Query --
+	p = sub.add_parser("text", help="Get text content of an element")
+	p.add_argument("selector", nargs="?", default=None, help="CSS selector (default: body)")
+
+	p = sub.add_parser("html", help="Get innerHTML of an element")
+	p.add_argument("selector", nargs="?", default=None, help="CSS selector (default: body)")
+
+	p = sub.add_parser("attr", help="Get attribute(s) of an element")
+	p.add_argument("selector", help="CSS selector")
+	p.add_argument("name", nargs="?", default=None, help="Attribute name (omit for all)")
+	p.add_argument("-i", "--index", type=int, default=None, help="Get Nth matching element (0-based)")
+
+	p = sub.add_parser("select", aliases=["sel"], help="Query all matching elements (returns summary of each)")
+	p.add_argument("selector", help="CSS selector")
+	p.add_argument("-l", "--limit", type=int, default=20, help="Max items to return (default: 20)")
+
+	p = sub.add_parser("count", help="Count matching elements")
+	p.add_argument("selector", help="CSS selector")
+
+	sub.add_parser("status", help="Get current page URL and title")
+
+	# -- JavaScript --
+	p = sub.add_parser("eval", help="Execute JavaScript in page context")
+	p.add_argument("code", help="JavaScript code to execute")
+
+	# -- Tabs --
+	sub.add_parser("tabs", help="List all open tabs")
+
+	p = sub.add_parser("tab", help="Switch to a tab by ID")
+	p.add_argument("id", type=int, help="Tab ID")
+
+	p = sub.add_parser("new-tab", help="Open a new tab")
+	p.add_argument("url", nargs="?", default=None, help="URL to open")
+
+	p = sub.add_parser("close-tab", help="Close a tab")
+	p.add_argument("id", nargs="?", type=int, default=None, help="Tab ID (default: active)")
+
+	# -- Screenshot / Download --
+	p = sub.add_parser("screenshot", aliases=["ss"], help="Capture screenshot")
+	p.add_argument("path", nargs="?", default=None, help="Save to file path (default: print base64)")
+
+	p = sub.add_parser("download", aliases=["dl"], help="Download a file/image using browser's auth session")
+	p.add_argument("target", help="URL or CSS selector of an element (img, a, etc.)")
+	p.add_argument("-o", "--output", default=None, help="Output filename (default: auto)")
+	p.add_argument("-i", "--index", type=int, default=None, help="Download Nth matching element (0-based, negative from end)")
+
+	# -- Scroll --
+	p = sub.add_parser("scroll", help="Scroll the page")
+	p.add_argument("target", help="Direction (up/down/top/bottom) or CSS selector to scroll into view")
+	p.add_argument("amount", nargs="?", type=int, default=None, help="Pixels to scroll (for up/down)")
+
+	# -- Form interaction --
+	p = sub.add_parser("select-option", aliases=["sopt"], help="Select option in <select> dropdown")
+	p.add_argument("selector", help="CSS selector for <select> element")
+	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")
+
+	# -- File upload --
+	p = sub.add_parser("upload", help="Upload file(s) to file input")
+	p.add_argument("selector", help="CSS selector for file input")
+	p.add_argument("files", nargs="+", help="File path(s) to upload")
+
+	# -- Dialog --
+	p = sub.add_parser("dialog", help="Set handler for next browser dialog (alert/confirm/prompt)")
+	p.add_argument("action", nargs="?", default="accept", choices=["accept", "dismiss"], help="Accept or dismiss (default: accept)")
+	p.add_argument("--text", default=None, help="Response text for prompt dialog")
+
+	# -- Drag --
+	p = sub.add_parser("drag", help="Drag element to another element or offset")
+	p.add_argument("source", help="CSS selector of element to drag")
+	p.add_argument("target", nargs="?", default=None, help="CSS selector of drop target")
+	p.add_argument("--dx", type=int, default=None, help="Horizontal pixel offset (when no target)")
+	p.add_argument("--dy", type=int, default=None, help="Vertical pixel offset (when no target)")
+
+	# -- Wait --
+	p = sub.add_parser("wait", help="Wait for element or sleep")
+	p.add_argument("target", help="CSS selector or seconds to wait")
+	p.add_argument("timeout", nargs="?", type=float, default=5, help="Timeout in seconds (default: 5)")
+
+	# -- Server management --
+	sub.add_parser("serve", help="Start bridge server (foreground)")
+	sub.add_parser("ping", help="Check server and extension status")
+	sub.add_parser("stop", help="Stop bridge server")
+
+	# -- Setup --
+	p = sub.add_parser("setup", help="Install Chrome extension and AI coding skill")
+	p.add_argument(
+		"target",
+		nargs="?",
+		default=None,
+		help="Skill target: cursor, opencode, or a custom directory path",
+	)
+
+	return parser
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+
+def handle_screenshot(args):
+	"""Screenshot needs special handling for file save."""
+	ensure_server()
+	result = send_raw("screenshot", {})
+	if not result.get("success"):
+		print(json.dumps(result, ensure_ascii=False))
+		sys.exit(1)
+
+	if args.path:
+		# Save to file
+		b64 = result["data"]["base64"]
+		img_bytes = base64.b64decode(b64)
+		with open(args.path, "wb") as f:
+			f.write(img_bytes)
+		print(json.dumps({"success": True, "data": {"saved": args.path, "bytes": len(img_bytes)}}))
+	else:
+		print(json.dumps(result, ensure_ascii=False))
+
+
+def handle_serve(args):
+	"""Run server in foreground."""
+	os.execvp(sys.executable, [sys.executable, "-m", "browser_ctl.server", "--port", str(DEFAULT_PORT)])
+
+
+def _get_extension_source_dir() -> str | None:
+	"""Locate the extension source directory (from project root)."""
+	pkg_dir = os.path.dirname(os.path.abspath(__file__))
+	project_root = os.path.dirname(pkg_dir)
+	ext_dir = os.path.join(project_root, "extension")
+	if os.path.isdir(ext_dir) and os.path.exists(os.path.join(ext_dir, "manifest.json")):
+		return ext_dir
+	return None
+
+
+def _install_extension() -> str | None:
+	"""Copy extension to ~/.browser-ctl/extension/ and try to open Chrome extensions page."""
+	src = _get_extension_source_dir()
+	if not src:
+		return None
+
+	dest = os.path.join(BCTL_HOME, "extension")
+	if os.path.exists(dest):
+		shutil.rmtree(dest)
+	shutil.copytree(src, dest)
+
+	# Try to open Chrome extensions page
+	system = platform.system()
+	try:
+		if system == "Darwin":
+			subprocess.Popen(
+				["open", "-a", "Google Chrome", "chrome://extensions"],
+				stdout=subprocess.DEVNULL,
+				stderr=subprocess.DEVNULL,
+			)
+		elif system == "Linux":
+			for cmd in ["google-chrome", "chromium", "chromium-browser"]:
+				try:
+					subprocess.Popen(
+						[cmd, "chrome://extensions"],
+						stdout=subprocess.DEVNULL,
+						stderr=subprocess.DEVNULL,
+					)
+					break
+				except FileNotFoundError:
+					continue
+	except Exception:
+		pass
+
+	return dest
+
+
+def _install_skill(target_dir: str) -> str:
+	"""Copy SKILL.md into <target_dir>/browser-ctl/."""
+	src = os.path.join(os.path.dirname(os.path.abspath(__file__)), "SKILL.md")
+	if not os.path.isfile(src):
+		raise FileNotFoundError("SKILL.md not found in browser_ctl package.")
+
+	skill_dir = os.path.join(target_dir, "browser-ctl")
+	os.makedirs(skill_dir, exist_ok=True)
+	skill_path = os.path.join(skill_dir, "SKILL.md")
+	# Remove existing file/symlink before copying
+	if os.path.lexists(skill_path):
+		os.remove(skill_path)
+	shutil.copy2(src, skill_path)
+	return skill_path
+
+
+def handle_setup(args):
+	"""Install Chrome extension and/or AI coding skill."""
+	print("browser-ctl setup")
+	print("=" * 40)
+
+	# --- Extension ---
+	ext_dir = _install_extension()
+	if ext_dir:
+		print(f"\n[extension] installed -> {ext_dir}")
+		print()
+		print("  Load in Chrome:")
+		print("    1. Open chrome://extensions")
+		print("    2. Enable 'Developer mode' (top right)")
+		print("    3. Click 'Load unpacked'")
+		print(f"    4. Select: {ext_dir}")
+	else:
+		print("\n[extension] source not found")
+		print("  Make sure you are running from a source checkout or dev install.")
+
+	# --- Skill ---
+	if args.target:
+		target = args.target
+		if target in SKILL_TARGETS:
+			target_dir = SKILL_TARGETS[target]
+			label = target
+		else:
+			target_dir = os.path.expanduser(target)
+			label = target_dir
+
+		try:
+			skill_path = _install_skill(target_dir)
+			print(f"\n[skill] installed ({label}) -> {skill_path}")
+		except FileNotFoundError as e:
+			print(f"\n[skill] error: {e}")
+	else:
+		print("\n[skill] skipped (no target specified)")
+		print()
+		print("  Available targets:")
+		for name, path in SKILL_TARGETS.items():
+			print(f"    bctl setup {name:10s}  ->  {path}/browser-ctl/SKILL.md")
+		print(f"    bctl setup <path>       ->  <path>/browser-ctl/SKILL.md")
+
+	print()
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main():
+	parser = build_parser()
+	args = parser.parse_args()
+
+	if not args.command:
+		parser.print_help()
+		sys.exit(0)
+
+	cmd = args.command
+
+	# Aliases
+	if cmd in ("nav", "go"):
+		cmd = "navigate"
+	if cmd == "fwd":
+		cmd = "forward"
+	if cmd in ("ss",):
+		cmd = "screenshot"
+	if cmd in ("sel",):
+		cmd = "select"
+	if cmd in ("dl",):
+		cmd = "download"
+	if cmd in ("sopt",):
+		cmd = "select-option"
+
+	# Local-only commands (no server needed)
+	if cmd == "setup":
+		handle_setup(args)
+		return
+	if cmd == "serve":
+		handle_serve(args)
+		return
+	if cmd == "stop":
+		stop_server()
+		return
+
+	# Screenshot (special handling)
+	if cmd == "screenshot":
+		handle_screenshot(args)
+		return
+
+	# Map CLI args to command params
+	params = {}
+	if cmd == "navigate":
+		params = {"url": args.url}
+	elif cmd == "click":
+		params = {"selector": args.selector, "index": args.index}
+	elif cmd == "hover":
+		params = {"selector": args.selector, "index": args.index}
+	elif cmd == "type":
+		params = {"selector": args.selector, "text": args.text}
+	elif cmd == "press":
+		params = {"key": args.key}
+	elif cmd == "text":
+		params = {"selector": args.selector}
+	elif cmd == "html":
+		params = {"selector": args.selector}
+	elif cmd == "attr":
+		params = {"selector": args.selector, "name": args.name, "index": args.index}
+	elif cmd == "select":
+		params = {"selector": args.selector, "limit": args.limit}
+	elif cmd == "count":
+		params = {"selector": args.selector}
+	elif cmd == "eval":
+		params = {"code": args.code}
+	elif cmd == "tab":
+		params = {"id": args.id}
+	elif cmd == "new-tab":
+		params = {"url": args.url}
+	elif cmd == "close-tab":
+		params = {"id": args.id}
+	elif cmd == "download":
+		target = args.target
+		if target.startswith("http://") or target.startswith("https://"):
+			params = {"url": target, "filename": args.output}
+		else:
+			params = {"selector": target, "filename": args.output, "index": args.index}
+	elif cmd == "scroll":
+		params = {"target": args.target, "amount": args.amount}
+	elif cmd == "select-option":
+		params = {"selector": args.selector, "value": args.value, "byText": args.text}
+	elif cmd == "upload":
+		files = [os.path.abspath(f) for f in args.files]
+		params = {"selector": args.selector, "files": files}
+	elif cmd == "dialog":
+		params = {"accept": args.action == "accept", "text": args.text}
+	elif cmd == "drag":
+		params = {"source": args.source, "target": args.target, "dx": args.dx, "dy": args.dy}
+	elif cmd == "wait":
+		# Determine if target is a number (sleep) or selector
+		try:
+			seconds = float(args.target)
+			params = {"seconds": seconds}
+		except ValueError:
+			params = {"selector": args.target, "timeout": args.timeout}
+
+	send_command(cmd, params)
+
+
+if __name__ == "__main__":
+	main()

browser_ctl/server.py

@@ -0,0 +1,275 @@
+"""Bridge server: relays commands between CLI (HTTP) and Chrome extension (WebSocket).
+
+Single port serves both protocols:
+  - POST /command  — CLI sends commands here
+  - GET  /ws       — Chrome extension connects here
+  - GET  /health   — Health check
+
+Commands are matched to responses via request IDs using asyncio.Future.
+"""
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import signal
+import sys
+import time
+import uuid
+
+from aiohttp import web, WSMsgType
+
+logging.basicConfig(
+	level=logging.INFO,
+	format="%(asctime)s [%(levelname)s] %(message)s",
+)
+log = logging.getLogger("bctl.server")
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+# Currently connected extension WebSocket (only one at a time)
+_ext_ws: web.WebSocketResponse | None = None
+
+# Pending command futures: request_id -> Future[dict]
+_pending: dict[str, asyncio.Future] = {}
+
+DEFAULT_PORT = 19876
+COMMAND_TIMEOUT = 30  # seconds
+
+# ---------------------------------------------------------------------------
+# WebSocket handler (Chrome extension)
+# ---------------------------------------------------------------------------
+
+async def ws_handler(request: web.Request) -> web.WebSocketResponse:
+	global _ext_ws
+
+	ws = web.WebSocketResponse(heartbeat=20)
+	await ws.prepare(request)
+	log.info("Extension connected")
+
+	# Replace any stale connection
+	if _ext_ws is not None and not _ext_ws.closed:
+		await _ext_ws.close()
+	_ext_ws = ws
+
+	try:
+		async for msg in ws:
+			if msg.type == WSMsgType.TEXT:
+				try:
+					data = json.loads(msg.data)
+					req_id = data.get("id", "")
+					if req_id in _pending:
+						_pending[req_id].set_result(data)
+					else:
+						log.warning("Response for unknown request id: %s", req_id)
+				except json.JSONDecodeError:
+					log.warning("Invalid JSON from extension: %s", msg.data[:200])
+			elif msg.type in (WSMsgType.ERROR, WSMsgType.CLOSE):
+				break
+	finally:
+		log.info("Extension disconnected")
+		if _ext_ws is ws:
+			_ext_ws = None
+
+	return ws
+
+
+# ---------------------------------------------------------------------------
+# HTTP handler (CLI)
+# ---------------------------------------------------------------------------
+
+async def command_handler(request: web.Request) -> web.Response:
+	"""Receive a command from CLI, relay to extension, return response."""
+	try:
+		body = await request.json()
+	except json.JSONDecodeError:
+		return _json_error("Invalid JSON in request body", status=400)
+
+	action = body.get("action", "")
+	params = body.get("params", {})
+
+	# Server-local commands
+	if action == "ping":
+		return _json_ok({
+			"server": True,
+			"extension": _ext_ws is not None and not _ext_ws.closed,
+		})
+
+	if action == "shutdown":
+		log.info("Shutdown requested")
+		asyncio.get_event_loop().call_later(0.1, _shutdown)
+		return _json_ok({"shutdown": True})
+
+	# Relay to extension
+	if _ext_ws is None or _ext_ws.closed:
+		return _json_error("Chrome extension not connected. Open Chrome and check the extension is loaded.")
+
+	req_id = f"r-{uuid.uuid4().hex[:12]}"
+	future: asyncio.Future = asyncio.get_event_loop().create_future()
+	_pending[req_id] = future
+
+	try:
+		await _ext_ws.send_json({
+			"id": req_id,
+			"action": action,
+			"params": params,
+		})
+
+		# Wait for extension response
+		result = await asyncio.wait_for(future, timeout=COMMAND_TIMEOUT)
+		return web.json_response(result)
+	except asyncio.TimeoutError:
+		return _json_error(f"Extension did not respond within {COMMAND_TIMEOUT}s")
+	except ConnectionResetError:
+		return _json_error("Extension connection lost during command")
+	finally:
+		_pending.pop(req_id, None)
+
+
+async def health_handler(request: web.Request) -> web.Response:
+	return _json_ok({
+		"server": True,
+		"extension": _ext_ws is not None and not _ext_ws.closed,
+		"pending_commands": len(_pending),
+	})
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _json_ok(data: dict, status: int = 200) -> web.Response:
+	return web.json_response({"success": True, "data": data}, status=status)
+
+
+def _json_error(error: str, status: int = 200) -> web.Response:
+	return web.json_response({"success": False, "error": error}, status=status)
+
+
+_app_runner: web.AppRunner | None = None
+
+def _shutdown():
+	"""Graceful shutdown."""
+	loop = asyncio.get_event_loop()
+	loop.call_soon(loop.stop)
+
+
+# ---------------------------------------------------------------------------
+# App factory & entry point
+# ---------------------------------------------------------------------------
+
+def create_app() -> web.Application:
+	app = web.Application()
+	app.router.add_get("/ws", ws_handler)
+	app.router.add_post("/command", command_handler)
+	app.router.add_get("/health", health_handler)
+	return app
+
+
+def write_pid_file(port: int) -> str:
+	"""Write PID file so CLI can check if server is running."""
+	import tempfile
+	pid_path = os.path.join(tempfile.gettempdir(), f"bctl-{port}.pid")
+	with open(pid_path, "w") as f:
+		f.write(str(os.getpid()))
+	return pid_path
+
+
+def main():
+	parser = argparse.ArgumentParser(description="browser-ctl bridge server")
+	parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="Port to listen on")
+	parser.add_argument("--daemon", action="store_true", help="Run as background daemon")
+	args = parser.parse_args()
+
+	if args.daemon:
+		_daemonize(args.port)
+		return
+
+	pid_path = write_pid_file(args.port)
+	log.info("PID file: %s", pid_path)
+	log.info("Starting bridge server on http://localhost:%d", args.port)
+
+	def cleanup():
+		try:
+			os.unlink(pid_path)
+		except OSError:
+			pass
+
+	import atexit
+	atexit.register(cleanup)
+
+	# Handle signals
+	def handle_signal(sig, frame):
+		log.info("Received signal %s, shutting down", sig)
+		cleanup()
+		sys.exit(0)
+
+	signal.signal(signal.SIGTERM, handle_signal)
+	signal.signal(signal.SIGINT, handle_signal)
+
+	app = create_app()
+	web.run_app(app, host="127.0.0.1", port=args.port, print=lambda msg: log.info(msg))
+
+
+def _daemonize(port: int):
+	"""Fork into background daemon (Unix only)."""
+	if sys.platform == "win32":
+		# Windows: just run directly (no fork)
+		main_args = [sys.executable, "-m", "browser_ctl.server", "--port", str(port)]
+		import subprocess
+		subprocess.Popen(
+			main_args,
+			creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS,
+			stdout=subprocess.DEVNULL,
+			stderr=subprocess.DEVNULL,
+		)
+		return
+
+	# Unix double-fork
+	pid = os.fork()
+	if pid > 0:
+		# Parent: wait briefly then exit
+		return
+
+	# Child: new session
+	os.setsid()
+
+	pid = os.fork()
+	if pid > 0:
+		os._exit(0)
+
+	# Grandchild: redirect stdio
+	sys.stdin.close()
+	devnull = os.open(os.devnull, os.O_RDWR)
+	os.dup2(devnull, 0)
+
+	# Redirect stdout/stderr to log file
+	import tempfile
+	log_path = os.path.join(tempfile.gettempdir(), f"bctl-{port}.log")
+	log_fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+	os.dup2(log_fd, 1)
+	os.dup2(log_fd, 2)
+
+	# Now run the server
+	pid_path = write_pid_file(port)
+	log.info("Daemon started (pid=%d), log: %s", os.getpid(), log_path)
+
+	import atexit
+	atexit.register(lambda: _cleanup_pid(pid_path))
+
+	app = create_app()
+	web.run_app(app, host="127.0.0.1", port=port, print=lambda msg: log.info(msg))
+
+
+def _cleanup_pid(pid_path: str):
+	try:
+		os.unlink(pid_path)
+	except OSError:
+		pass
+
+
+if __name__ == "__main__":
+	main()

browser_ctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: browser-ctl
+Version: 0.1.0
+Summary: Control your browser from the command line via a Chrome extension + WebSocket bridge
+Author-email: geb <853934146@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mikuh/browser-ctl
+Project-URL: Repository, https://github.com/mikuh/browser-ctl
+Project-URL: Issues, https://github.com/mikuh/browser-ctl/issues
+Keywords: browser,automation,chrome,cli,websocket,devtools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Dynamic: license-file
+
+# browser-ctl
+
+**Control Chrome from your terminal.** A lightweight CLI tool for browser automation — navigate, click, type, scroll, screenshot, and more, all through simple commands.
+
+```bash
+pip install browser-ctl
+
+bctl go https://github.com
+bctl click "a.search-button"
+bctl type "input[name=q]" "browser-ctl"
+bctl press Enter
+bctl screenshot results.png
+```
+
+## Why browser-ctl?
+
+- **Zero-config CLI** — single `bctl` command, JSON output, works in any shell or script
+- **No browser binary management** — uses your existing Chrome with a lightweight extension
+- **Stdlib-only CLI** — the CLI itself has zero external Python dependencies
+- **AI-agent friendly** — ships with an AI coding skill file (`SKILL.md`) for Cursor / OpenCode integration
+- **Local & private** — all communication stays on `localhost`, no data leaves your machine
+
+## How It Works
+
+```
+Terminal (bctl)  ──HTTP──▶  Bridge Server  ◀──WebSocket──  Chrome Extension
+```
+
+1. The **CLI** (`bctl`) sends commands via HTTP to a local bridge server
+2. The **bridge server** relays them over WebSocket to the Chrome extension
+3. The **extension** executes commands using Chrome APIs and content scripts
+4. Results flow back the same path as JSON
+
+The bridge server auto-starts on first command — no manual setup needed.
+
+## Installation
+
+### 1. Install the Python package
+
+```bash
+pip install browser-ctl
+```
+
+### 2. Load the Chrome extension
+
+```bash
+bctl setup
+```
+
+This copies the extension to `~/.browser-ctl/extension/` and opens Chrome's extension page. Then:
+
+1. Open `chrome://extensions`
+2. Enable **Developer mode** (top right)
+3. Click **Load unpacked**
+4. Select the `~/.browser-ctl/extension/` directory
+
+### 3. Verify
+
+```bash
+bctl ping
+```
+
+You should see `{"success": true, "data": {"server": true, "extension": true}}`.
+
+## Commands
+
+### Navigation
+
+```bash
+bctl navigate <url>       # Navigate to URL (aliases: nav, go)
+bctl back                 # Go back in history
+bctl forward              # Go forward (alias: fwd)
+bctl reload               # Reload current page
+```
+
+### Interaction
+
+```bash
+bctl click <sel> [-i N]           # Click element (CSS selector, optional Nth match)
+bctl hover <sel> [-i N]           # Hover over element
+bctl type <sel> <text>            # Type text into input/textarea
+bctl press <key>                  # Press key (Enter, Escape, Tab, etc.)
+bctl scroll <dir|sel> [pixels]    # Scroll: up/down/top/bottom or element into view
+bctl select-option <sel> <val>    # Select dropdown option (alias: sopt) [--text]
+bctl drag <src> [target]          # Drag to element or offset [--dx N --dy N]
+```
+
+### DOM Query
+
+```bash
+bctl text [sel]           # Get text content (default: body)
+bctl html [sel]           # Get innerHTML
+bctl attr <sel> [name]    # Get attribute(s) [-i N for Nth element]
+bctl select <sel> [-l N]  # List matching elements (alias: sel, limit default: 20)
+bctl count <sel>          # Count matching elements
+bctl status               # Current page URL and title
+```
+
+### JavaScript
+
+```bash
+bctl eval <code>          # Execute JS in page context (auto-bypasses CSP)
+```
+
+### Tabs
+
+```bash
+bctl tabs                 # List all tabs
+bctl tab <id>             # Switch to tab by ID
+bctl new-tab [url]        # Open new tab
+bctl close-tab [id]       # Close tab (default: active)
+```
+
+### Screenshot & Files
+
+```bash
+bctl screenshot [path]    # Capture screenshot (alias: ss)
+bctl download <target>    # Download file/image (alias: dl) [-o file] [-i N]
+bctl upload <sel> <files> # Upload file(s) to <input type="file">
+```
+
+### Wait & Dialog
+
+```bash
+bctl wait <sel|seconds>   # Wait for element or sleep [timeout]
+bctl dialog [accept|dismiss] [--text <val>]  # Handle next alert/confirm/prompt
+```
+
+### Server
+
+```bash
+bctl ping                 # Check server & extension status
+bctl serve                # Start server in foreground
+bctl stop                 # Stop server
+```
+
+## Examples
+
+### Search and extract
+
+```bash
+bctl go "https://news.ycombinator.com"
+bctl select "a.titlelink" -l 5       # Top 5 links with text, href, etc.
+```
+
+### Fill a form
+
+```bash
+bctl type "input[name=email]" "user@example.com"
+bctl type "input[name=password]" "hunter2"
+bctl select-option "select#country" "US"
+bctl upload "input[type=file]" ./resume.pdf
+bctl click "button[type=submit]"
+```
+
+### Scroll and screenshot
+
+```bash
+bctl go "https://en.wikipedia.org/wiki/Web_browser"
+bctl scroll down 1000
+bctl ss page.png
+```
+
+### Handle dialogs
+
+```bash
+bctl dialog accept              # Set up handler BEFORE triggering
+bctl click "#delete-button"     # This triggers a confirm() dialog
+```
+
+### Drag and drop
+
+```bash
+bctl drag ".task-card" ".done-column"
+bctl drag ".range-slider" --dx 50 --dy 0
+```
+
+### Use in shell scripts
+
+```bash
+# Extract all image URLs from a page
+bctl go "https://example.com"
+bctl eval "JSON.stringify(Array.from(document.images).map(i=>i.src))"
+
+# Wait for SPA content to load
+bctl go "https://app.example.com/dashboard"
+bctl wait ".dashboard-loaded" 15
+bctl text ".metric-value"
+```
+
+## AI Agent Integration
+
+browser-ctl ships with a `SKILL.md` file designed for AI coding assistants. Install it for your tool:
+
+```bash
+bctl setup cursor       # Install skill for Cursor IDE
+bctl setup opencode     # Install skill for OpenCode
+bctl setup /path/to/dir # Install to custom directory
+```
+
+Once installed, AI agents can use `bctl` commands to automate browser tasks on your behalf.
+
+## Output Format
+
+All commands return JSON to stdout:
+
+```json
+// Success
+{"success": true, "data": {"url": "https://example.com", "title": "Example"}}
+
+// Error
+{"success": false, "error": "Element not found: .missing"}
+```
+
+Non-zero exit code on errors — works naturally with `set -e` and `&&` chains.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Terminal                                       │
+│  $ bctl click "button.submit"                   │
+│       │                                         │
+│       ▼ HTTP POST localhost:19876/command        │
+│  ┌─────────────────────┐                        │
+│  │   Bridge Server     │ (Python, aiohttp)      │
+│  │   :19876            │                        │
+│  └────────┬────────────┘                        │
+│           │ WebSocket                           │
+│           ▼                                     │
+│  ┌─────────────────────┐                        │
+│  │  Chrome Extension   │ (Manifest V3)          │
+│  │  Service Worker     │                        │
+│  └────────┬────────────┘                        │
+│           │ chrome.scripting / chrome.debugger   │
+│           ▼                                     │
+│  ┌─────────────────────┐                        │
+│  │  Web Page           │                        │
+│  └─────────────────────┘                        │
+└─────────────────────────────────────────────────┘
+```
+
+- **CLI** → stdlib only, communicates via HTTP
+- **Bridge Server** → async relay (aiohttp), auto-daemonizes
+- **Extension** → MV3 service worker, auto-reconnects via `chrome.alarms`
+- **Eval** → dual strategy: MAIN-world injection (fast) with CDP fallback (CSP-safe)
+
+## Requirements
+
+- Python >= 3.11
+- Chrome / Chromium with the extension loaded
+- macOS, Linux, or Windows
+
+## Privacy
+
+All communication is local (`127.0.0.1`). No analytics, no telemetry, no external servers. See [PRIVACY.md](PRIVACY.md) for the full privacy policy.
+
+## License
+
+[MIT](LICENSE)

browser_ctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+browser_ctl/SKILL.md,sha256=4HdyBgMWDolCFm18E3RSMzPHK21X3kc7fhdDpmFwO_U,5711
+browser_ctl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+browser_ctl/__main__.py,sha256=J9HCyuMk9MmFWS5hp7v5DR0Y83hw3_ud6ZkF3F8361s,101
+browser_ctl/cli.py,sha256=H7k_uovteB_-iWJ2u8ij7XOGZthfNWoYIu93I-HKOvY,16189
+browser_ctl/server.py,sha256=uEZIC-VV10YikF0-SV46d27qsQXVBqkCkOhM9Fk0V8A,7463
+browser_ctl-0.1.0.dist-info/licenses/LICENSE,sha256=MW4OAPawybk4g1YbwDgivl5BVBJRZe3sPC0qtxgn5Xc,1060
+browser_ctl-0.1.0.dist-info/METADATA,sha256=EpGU4XeSlJ23SndHcx-eCfDlA6Rc2m-4iCmUMgGYljg,9120
+browser_ctl-0.1.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+browser_ctl-0.1.0.dist-info/entry_points.txt,sha256=AwixT7GGghhdwc0qPawXHr-OiAP1cvbV-8m0WUEv70Q,84
+browser_ctl-0.1.0.dist-info/top_level.txt,sha256=cvJDSm1xtuiPz2R8-M1cHsc_E7U0jYjYXgn07pG6xsY,12
+browser_ctl-0.1.0.dist-info/RECORD,,

browser_ctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

browser_ctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bctl = browser_ctl.cli:main
+bctl-server = browser_ctl.server:main

browser_ctl-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geb
+
+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_ctl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+browser_ctl