browsectl 0.1.1__tar.gz

browsectl-0.1.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright © 2026 Luis Alejandro Bordo Garcia
+
+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.

browsectl-0.1.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: browsectl
+Version: 0.1.1
+Summary: Browser-agnostic automation for AI agents
+License-File: LICENSE
+Author: Luis Bordo
+Requires-Python: >=3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: attrs (>=26.1.0,<27.0.0)
+Requires-Dist: websockets (>=15.0)

browsectl-0.1.1/browsectl/adapters/cdp.py

@@ -0,0 +1,394 @@
+"""Chrome DevTools Protocol adapter."""
+
+import asyncio
+import base64
+import json
+import urllib.request
+from collections.abc import Awaitable, Callable
+
+import attrs
+import websockets.asyncio.client
+
+from browsectl.models import (
+    BrowserEndpoint,
+    EvalResult,
+    PageInfo,
+    Screenshot,
+    Tab,
+)
+
+CDP_TIMEOUT: float = 30.0
+
+
+class CdpError(Exception):
+    """Raised when a CDP command returns an error."""
+
+
+class CdpTimeoutError(CdpError):
+    """Raised when a CDP operation exceeds its timeout."""
+
+
+@attrs.define(slots=True)
+class CdpSession:
+    """Holds a live websocket connection to a CDP target."""
+
+    ws: websockets.asyncio.client.ClientConnection
+    target_id: str
+    endpoint: BrowserEndpoint
+    _msg_id: int = 0
+
+    def next_id(self) -> int:
+        self._msg_id += 1
+        return self._msg_id
+
+
+def _fetch_json(url: str) -> bytes:
+    """Blocking HTTP GET — run via asyncio.to_thread."""
+    with urllib.request.urlopen(url) as resp:
+        return resp.read()  # type: ignore[no-any-return]
+
+
+async def _send_command(
+    session: CdpSession,
+    method: str,
+    params: dict[str, object] | None = None,
+) -> dict[str, object]:
+    """Send a CDP command and return the result."""
+    msg_id = session.next_id()
+    payload: dict[str, object] = {"id": msg_id, "method": method}
+    if params is not None:
+        payload["params"] = params
+    await session.ws.send(json.dumps(payload))
+
+    async def _recv_response() -> dict[str, object]:
+        while True:
+            raw = await session.ws.recv()
+            response = json.loads(raw)
+            if isinstance(response, dict) and response.get("id") == msg_id:
+                if "error" in response:
+                    error = response["error"]
+                    if isinstance(error, dict):
+                        msg = error.get("message", str(error))
+                    else:
+                        msg = str(error)
+                    raise CdpError(msg)
+                result = response.get("result")
+                if isinstance(result, dict):
+                    return result
+                return {}
+
+    try:
+        return await asyncio.wait_for(_recv_response(), timeout=CDP_TIMEOUT)
+    except TimeoutError:
+        raise CdpTimeoutError(
+            f"CDP command {method} timed out after {CDP_TIMEOUT}s"
+        )
+
+
+type TSendCommand = Callable[
+    [CdpSession, str, dict[str, object] | None], Awaitable[dict[str, object]]
+]
+
+send_command: TSendCommand = _send_command
+
+
+async def connect(
+    endpoint: BrowserEndpoint, target_id: str | None = None
+) -> CdpSession:
+    """Connect to a CDP target, preferring target_id if it still exists."""
+    list_url = f"http://{endpoint.host}:{endpoint.port}/json"
+    raw = await asyncio.to_thread(_fetch_json, list_url)
+    targets = json.loads(raw.decode())
+
+    page_targets = [t for t in targets if t.get("type") == "page"]
+    if not page_targets:
+        raise CdpError("No page targets found")
+
+    target = None
+    if target_id is not None:
+        target = next(
+            (t for t in page_targets if t.get("id") == target_id),
+            None,
+        )
+    if target is None:
+        target = page_targets[0]
+
+    ws_url: str = target["webSocketDebuggerUrl"]
+    tid: str = target["id"]
+
+    ws = await websockets.asyncio.client.connect(ws_url)
+    return CdpSession(ws=ws, target_id=tid, endpoint=endpoint)
+
+
+async def disconnect(session: CdpSession) -> None:
+    """Close the websocket connection."""
+    await session.ws.close()
+
+
+async def list_tabs(session: CdpSession) -> tuple[Tab, ...]:
+    """List all page targets via the Target domain."""
+    result = await send_command(session, "Target.getTargets", None)
+    raw_targets = result.get("targetInfos", [])
+    if not isinstance(raw_targets, list):
+        return ()
+    return tuple(
+        Tab(
+            id=t["targetId"],
+            title=t.get("title", ""),
+            url=t.get("url", ""),
+        )
+        for t in raw_targets
+        if isinstance(t, dict) and t.get("type") == "page"
+    )
+
+
+async def page_info(session: CdpSession) -> PageInfo:
+    """Get the current page's URL and title."""
+    result = await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": "JSON.stringify({url: location.href, title: document.title})"},
+    )
+    raw_value = result.get("result")
+    if not isinstance(raw_value, dict):
+        raise CdpError("page_info: unexpected response structure")
+    value_str = raw_value.get("value")
+    if not isinstance(value_str, str):
+        raise CdpError("page_info: missing result value")
+    parsed = json.loads(value_str)
+    return PageInfo(
+        url=parsed.get("url", ""),
+        title=parsed.get("title", ""),
+    )
+
+
+async def navigate(session: CdpSession, url: str) -> PageInfo:
+    """Navigate to a URL and wait for the page to load."""
+    await send_command(session, "Page.enable", None)
+    await send_command(session, "Page.navigate", {"url": url})
+
+    async def _wait_for_load() -> None:
+        while True:
+            raw = await session.ws.recv()
+            msg = json.loads(raw)
+            if isinstance(msg, dict) and msg.get("method") == "Page.loadEventFired":
+                break
+
+    try:
+        await asyncio.wait_for(_wait_for_load(), timeout=CDP_TIMEOUT)
+    except TimeoutError:
+        raise CdpTimeoutError(f"Page load timed out after {CDP_TIMEOUT}s")
+
+    return await page_info(session)
+
+
+async def screenshot(session: CdpSession) -> Screenshot:
+    """Capture a full-page screenshot as PNG."""
+    result = await send_command(
+        session,
+        "Page.captureScreenshot",
+        {"format": "png"},
+    )
+    data_str = result.get("data")
+    if not isinstance(data_str, str) or not data_str:
+        raise CdpError("screenshot: no image data in response")
+    return Screenshot(data=base64.b64decode(data_str), format="png")
+
+
+async def click(session: CdpSession, selector: str) -> None:
+    """Click an element identified by CSS selector."""
+    js = f"""
+    (() => {{
+        const el = document.querySelector({json.dumps(selector)});
+        if (!el) throw new Error("Element not found: " + {json.dumps(selector)});
+        el.scrollIntoView({{block: 'center'}});
+        const rect = el.getBoundingClientRect();
+        return JSON.stringify({{
+            x: rect.x + rect.width / 2,
+            y: rect.y + rect.height / 2
+        }});
+    }})()
+    """
+    result = await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": js, "returnByValue": True},
+    )
+    if "exceptionDetails" in result:
+        desc = result.get("exceptionDetails")
+        if isinstance(desc, dict):
+            exc = desc.get("exception")
+            if isinstance(exc, dict):
+                raise CdpError(str(exc.get("description", "click failed")))
+        raise CdpError("click failed")
+
+    raw_result = result.get("result")
+    if not isinstance(raw_result, dict):
+        raise CdpError("click: unexpected response structure")
+    value_str = raw_result.get("value")
+    if not isinstance(value_str, str):
+        raise CdpError("click: missing coordinate data")
+    coords = json.loads(value_str)
+    x = float(coords.get("x", 0))
+    y = float(coords.get("y", 0))
+
+    for event_type in ("mousePressed", "mouseReleased"):
+        await send_command(
+            session,
+            "Input.dispatchMouseEvent",
+            {
+                "type": event_type,
+                "x": x,
+                "y": y,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+
+
+async def type_text(session: CdpSession, selector: str, text: str) -> None:
+    """Focus an element and type text into it."""
+    focus_js = f"""
+    (() => {{
+        const el = document.querySelector({json.dumps(selector)});
+        if (!el) throw new Error("Element not found: " + {json.dumps(selector)});
+        el.focus();
+    }})()
+    """
+    result = await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": focus_js},
+    )
+    if "exceptionDetails" in result:
+        raise CdpError(f"Focus failed for selector: {selector}")
+
+    for char in text:
+        await send_command(
+            session,
+            "Input.dispatchKeyEvent",
+            {"type": "keyDown", "text": char},
+        )
+        await send_command(
+            session,
+            "Input.dispatchKeyEvent",
+            {"type": "keyUp"},
+        )
+
+
+async def extract_html(session: CdpSession, selector: str) -> str:
+    """Extract the innerHTML of an element by CSS selector."""
+    js = f"""
+    (() => {{
+        const el = document.querySelector({json.dumps(selector)});
+        if (!el) throw new Error("Element not found: " + {json.dumps(selector)});
+        return el.innerHTML;
+    }})()
+    """
+    result = await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": js, "returnByValue": True},
+    )
+    if "exceptionDetails" in result:
+        raise CdpError(f"Element not found: {selector}")
+    raw_result = result.get("result")
+    if not isinstance(raw_result, dict):
+        raise CdpError("extract_html: unexpected response structure")
+    value = raw_result.get("value")
+    if not isinstance(value, str):
+        raise CdpError("extract_html: no string value in result")
+    return value
+
+
+async def eval_js(session: CdpSession, expression: str) -> EvalResult:
+    """Evaluate a JS expression and return the result."""
+    result = await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": expression, "returnByValue": True},
+    )
+    if "exceptionDetails" in result:
+        exc_details = result["exceptionDetails"]
+        if isinstance(exc_details, dict):
+            exc = exc_details.get("exception", {})
+            if isinstance(exc, dict):
+                raise CdpError(str(exc.get("description", "eval failed")))
+        raise CdpError("eval failed")
+    raw_result = result.get("result")
+    if not isinstance(raw_result, dict):
+        raise CdpError("eval_js: unexpected response structure")
+    return EvalResult(value=str(raw_result.get("value", "")))
+
+
+async def new_tab(session: CdpSession, url: str) -> Tab:
+    """Create a new tab and return its info."""
+    result = await send_command(
+        session,
+        "Target.createTarget",
+        {"url": url},
+    )
+    target_id = result.get("targetId", "")
+    if not isinstance(target_id, str) or not target_id:
+        raise CdpError("Failed to create new tab")
+    return Tab(id=target_id, title="", url=url)
+
+
+async def switch_tab(session: CdpSession, target_id: str) -> None:
+    """Switch to a different tab by reconnecting to its websocket."""
+    ep = session.endpoint
+    list_url = f"http://{ep.host}:{ep.port}/json"
+
+    target = None
+    for _ in range(10):
+        raw = await asyncio.to_thread(_fetch_json, list_url)
+        targets = json.loads(raw.decode())
+        target = next(
+            (t for t in targets if t.get("id") == target_id),
+            None,
+        )
+        if target is not None:
+            break
+        await asyncio.sleep(0.2)
+
+    if target is None:
+        raise CdpError(f"Tab not found: {target_id}")
+
+    ws_url: str = target["webSocketDebuggerUrl"]
+    new_ws = await websockets.asyncio.client.connect(ws_url)
+    await session.ws.close()
+    session.ws = new_ws
+    session.target_id = target_id
+
+
+async def scroll(session: CdpSession, pixels: int) -> None:
+    """Scroll the page by N pixels (positive=down, negative=up)."""
+    await send_command(
+        session,
+        "Runtime.evaluate",
+        {"expression": f"window.scrollBy(0, {pixels})"},
+    )
+
+
+async def wait_for(session: CdpSession, selector: str, timeout: float = 30.0) -> None:
+    """Poll for a CSS selector until it exists or timeout."""
+    js = f"document.querySelector({json.dumps(selector)}) !== null"
+
+    async def _poll() -> None:
+        while True:
+            result = await send_command(
+                session,
+                "Runtime.evaluate",
+                {"expression": js, "returnByValue": True},
+            )
+            raw = result.get("result")
+            if isinstance(raw, dict) and raw.get("value") is True:
+                return
+            await asyncio.sleep(0.1)
+
+    try:
+        await asyncio.wait_for(_poll(), timeout=timeout)
+    except TimeoutError:
+        raise CdpTimeoutError(
+            f"Selector {selector!r} not found after {timeout}s"
+        )

browsectl-0.1.1/browsectl/core.py

@@ -0,0 +1,157 @@
+"""Command orchestration -- browser-agnostic business logic."""
+
+import fcntl
+import json
+import logging
+from pathlib import Path
+
+from browsectl.gateway import BrowserGateway
+from browsectl.models import BrowserEndpoint, Command
+
+logger = logging.getLogger(__name__)
+
+SESSIONS_DIR = Path.home() / ".browsectl" / "sessions"
+SCREENSHOT_PATH = Path("screenshot.png")
+
+
+def _session_file(name: str) -> Path:
+    return SESSIONS_DIR / f"{name}.json"
+
+
+def load_session(name: str = "default") -> tuple[BrowserEndpoint, str | None]:
+    """Load the saved browser endpoint and target from the session file."""
+    path = _session_file(name)
+    if not path.exists():
+        raise SystemExit(
+            "No active session. Run: browsectl connect <host> <port>"
+        )
+    data = json.loads(path.read_text())
+    target_id = data.get("target_id")
+    return (
+        BrowserEndpoint(host=data["host"], port=data["port"]),
+        target_id if isinstance(target_id, str) else None,
+    )
+
+
+def save_session(
+    endpoint: BrowserEndpoint,
+    target_id: str | None = None,
+    name: str = "default",
+) -> None:
+    """Save the browser endpoint and optional target to the session file."""
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    data: dict[str, object] = {"host": endpoint.host, "port": endpoint.port}
+    if target_id is not None:
+        data["target_id"] = target_id
+    path = _session_file(name)
+    with path.open("w") as f:
+        fcntl.flock(f, fcntl.LOCK_EX)
+        f.write(json.dumps(data))
+
+
+async def dispatch[S](
+    gateway: BrowserGateway[S],
+    command: Command,
+    args: tuple[str, ...],
+    session_name: str = "default",
+) -> str:
+    """Dispatch a CLI command through the gateway. Returns output text."""
+    if command == Command.CONNECT:
+        host = args[0] if args else "localhost"
+        port = int(args[1]) if len(args) > 1 else 9222
+        endpoint = BrowserEndpoint(host=host, port=port)
+        session = await gateway.connect(endpoint, None)
+        await gateway.disconnect(session)
+        save_session(endpoint, name=session_name)
+        return f"Connected to {host}:{port}"
+
+    endpoint, target_id = load_session(session_name)
+    session = await gateway.connect(endpoint, target_id)
+    try:
+        result = await _run_command(gateway, session, command, args)
+        if command == Command.SWITCHTAB and args:
+            save_session(endpoint, target_id=args[0], name=session_name)
+        return result
+    finally:
+        await gateway.disconnect(session)
+
+
+async def _run_command[S](
+    gateway: BrowserGateway[S],
+    session: S,
+    command: Command,
+    args: tuple[str, ...],
+) -> str:
+    """Execute a single command on an active session."""
+    match command:
+        case Command.GOTO:
+            if not args:
+                raise SystemExit("Usage: browsectl goto <url>")
+            info = await gateway.navigate(session, args[0])
+            return f"{info.title}\n{info.url}"
+
+        case Command.SCREENSHOT:
+            shot = await gateway.screenshot(session)
+            out_path = Path(args[0]) if args else SCREENSHOT_PATH
+            out_path.write_bytes(shot.data)
+            return f"Saved to {out_path} ({len(shot.data)} bytes)"
+
+        case Command.CLICK:
+            if not args:
+                raise SystemExit("Usage: browsectl click <selector>")
+            await gateway.click(session, args[0])
+            return f"Clicked: {args[0]}"
+
+        case Command.TYPE:
+            if len(args) < 2:
+                raise SystemExit("Usage: browsectl type <selector> <text>")
+            await gateway.type_text(session, args[0], args[1])
+            return f"Typed into: {args[0]}"
+
+        case Command.HTML:
+            if not args:
+                raise SystemExit("Usage: browsectl html <selector>")
+            return await gateway.extract_html(session, args[0])
+
+        case Command.EVAL:
+            if not args:
+                raise SystemExit("Usage: browsectl eval <expression>")
+            result = await gateway.eval_js(session, args[0])
+            return result.value
+
+        case Command.INFO:
+            info = await gateway.page_info(session)
+            return f"{info.title}\n{info.url}"
+
+        case Command.TABS:
+            tabs = await gateway.list_tabs(session)
+            lines = tuple(f"{t.id}  {t.title}  {t.url}" for t in tabs)
+            return "\n".join(lines) if lines else "(no tabs)"
+
+        case Command.NEWTAB:
+            url = args[0] if args else "about:blank"
+            tab = await gateway.new_tab(session, url)
+            return f"Opened tab: {tab.id}  {tab.url}"
+
+        case Command.SWITCHTAB:
+            if not args:
+                raise SystemExit("Usage: browsectl switchtab <tab-id>")
+            await gateway.switch_tab(session, args[0])
+            info = await gateway.page_info(session)
+            return f"Switched to: {info.title}\n{info.url}"
+
+        case Command.SCROLL:
+            if not args:
+                raise SystemExit("Usage: browsectl scroll <pixels>")
+            await gateway.scroll(session, int(args[0]))
+            return f"Scrolled {args[0]}px"
+
+        case Command.WAIT:
+            if not args:
+                raise SystemExit("Usage: browsectl wait <selector> [timeout]")
+            timeout = float(args[1]) if len(args) > 1 else 30.0
+            await gateway.wait_for(session, args[0], timeout)
+            return f"Found: {args[0]}"
+
+        case Command.CONNECT:
+            return ""

browsectl-0.1.1/browsectl/gateway.py

@@ -0,0 +1,40 @@
+"""Browser gateway bundle -- the single injection point for core."""
+
+import attrs
+
+from browsectl.ports import (
+    TClick,
+    TConnect,
+    TDisconnect,
+    TEvalJs,
+    TExtractHtml,
+    TListTabs,
+    TNavigate,
+    TNewTab,
+    TPageInfo,
+    TScreenshot,
+    TScroll,
+    TSwitchTab,
+    TTypeText,
+    TWaitFor,
+)
+
+
+@attrs.define(frozen=True, slots=True)
+class BrowserGateway[S]:
+    """Bundles all browser port functions into a single injectable unit."""
+
+    connect: TConnect[S]
+    disconnect: TDisconnect[S]
+    navigate: TNavigate[S]
+    screenshot: TScreenshot[S]
+    click: TClick[S]
+    type_text: TTypeText[S]
+    extract_html: TExtractHtml[S]
+    eval_js: TEvalJs[S]
+    page_info: TPageInfo[S]
+    list_tabs: TListTabs[S]
+    new_tab: TNewTab[S]
+    switch_tab: TSwitchTab[S]
+    scroll: TScroll[S]
+    wait_for: TWaitFor[S]

browsectl-0.1.1/browsectl/main.py

@@ -0,0 +1,116 @@
+"""CLI entry point and wiring."""
+
+import asyncio
+import sys
+from enum import StrEnum
+
+from browsectl.adapters import cdp
+from browsectl.core import dispatch
+from browsectl.gateway import BrowserGateway
+from browsectl.models import Command
+
+USAGE = """\
+Usage: browsectl [-b <backend>] [-s <session>] <command> [args...]
+
+Options:
+  -b, --backend <name>    Browser backend (default: cdp)
+                          Available: cdp
+  -s, --session <name>    Named session (default: default)
+                          Allows multiple independent browser sessions
+
+Commands:
+  connect [host] [port]   Connect to browser (default: localhost:9222)
+  goto <url>              Navigate to URL
+  screenshot [path]       Save screenshot (default: screenshot.png)
+  click <selector>        Click element by CSS selector
+  type <selector> <text>  Type text into element
+  html <selector>         Extract innerHTML of element
+  eval <expression>       Evaluate JavaScript expression
+  info                    Show current page URL and title
+  tabs                    List open tabs
+  newtab [url]            Open a new tab (default: about:blank)
+  switchtab <tab-id>      Switch to a tab by ID (from 'tabs' output)
+  scroll <pixels>         Scroll page (positive=down, negative=up)
+  wait <selector> [timeout]  Wait for element to appear (default: 30s)
+"""
+
+
+class Backend(StrEnum):
+    CDP = "cdp"
+
+
+def _build_cdp_gateway() -> BrowserGateway[cdp.CdpSession]:
+    return BrowserGateway(
+        connect=cdp.connect,
+        disconnect=cdp.disconnect,
+        navigate=cdp.navigate,
+        screenshot=cdp.screenshot,
+        click=cdp.click,
+        type_text=cdp.type_text,
+        extract_html=cdp.extract_html,
+        eval_js=cdp.eval_js,
+        page_info=cdp.page_info,
+        list_tabs=cdp.list_tabs,
+        new_tab=cdp.new_tab,
+        switch_tab=cdp.switch_tab,
+        scroll=cdp.scroll,
+        wait_for=cdp.wait_for,
+    )
+
+
+def _parse_args(
+    argv: list[str],
+) -> tuple[Backend, str, Command, tuple[str, ...]]:
+    backend = Backend.CDP
+    session_name = "default"
+    args = list(argv)
+
+    while args and args[0].startswith("-"):
+        flag = args.pop(0)
+        if flag in ("-b", "--backend"):
+            if not args:
+                raise SystemExit("--backend requires a value")
+            try:
+                backend = Backend(args.pop(0))
+            except ValueError as e:
+                raise SystemExit(
+                    f"Unknown backend: {e}. "
+                    f"Available: {', '.join(Backend)}"
+                )
+        elif flag in ("-s", "--session"):
+            if not args:
+                raise SystemExit("--session requires a value")
+            session_name = args.pop(0)
+        elif flag in ("-h", "--help"):
+            print(USAGE)
+            raise SystemExit(0)
+        else:
+            print(f"Unknown flag: {flag}", file=sys.stderr)
+            print(USAGE, file=sys.stderr)
+            raise SystemExit(1)
+
+    if not args:
+        print(USAGE)
+        raise SystemExit(0)
+
+    try:
+        command = Command(args[0])
+    except ValueError:
+        print(f"Unknown command: {args[0]}", file=sys.stderr)
+        print(USAGE, file=sys.stderr)
+        raise SystemExit(1)
+
+    return backend, session_name, command, tuple(args[1:])
+
+
+def main() -> None:
+    """Entry point for the browsectl CLI."""
+    backend, session_name, command, args = _parse_args(sys.argv[1:])
+    match backend:
+        case Backend.CDP:
+            gateway = _build_cdp_gateway()
+        case _:
+            raise SystemExit(f"Unsupported backend: {backend}")
+    output = asyncio.run(dispatch(gateway, command, args, session_name))
+    if output:
+        print(output)

browsectl-0.1.1/browsectl/models.py

@@ -0,0 +1,63 @@
+"""Domain types for browsectl."""
+
+from enum import StrEnum
+
+import attrs
+
+
+@attrs.define(frozen=True, slots=True)
+class BrowserEndpoint:
+    """Where to connect to a browser's automation interface."""
+
+    host: str
+    port: int
+
+
+@attrs.define(frozen=True, slots=True)
+class Tab:
+    """A single browser tab."""
+
+    id: str
+    title: str
+    url: str
+
+
+@attrs.define(frozen=True, slots=True)
+class PageInfo:
+    """Current state of a page."""
+
+    url: str
+    title: str
+
+
+@attrs.define(frozen=True, slots=True)
+class Screenshot:
+    """Captured page image."""
+
+    data: bytes
+    format: str
+
+
+@attrs.define(frozen=True, slots=True)
+class EvalResult:
+    """Result of evaluating a JS expression."""
+
+    value: str
+
+
+class Command(StrEnum):
+    """CLI commands."""
+
+    CONNECT = "connect"
+    GOTO = "goto"
+    SCREENSHOT = "screenshot"
+    CLICK = "click"
+    TYPE = "type"
+    HTML = "html"
+    EVAL = "eval"
+    INFO = "info"
+    TABS = "tabs"
+    NEWTAB = "newtab"
+    SWITCHTAB = "switchtab"
+    SCROLL = "scroll"
+    WAIT = "wait"

browsectl-0.1.1/browsectl/ports.py

@@ -0,0 +1,26 @@
+"""Function signature contracts for browser operations."""
+
+from collections.abc import Awaitable, Callable
+
+from browsectl.models import (
+    BrowserEndpoint,
+    EvalResult,
+    PageInfo,
+    Screenshot,
+    Tab,
+)
+
+type TConnect[S] = Callable[[BrowserEndpoint, str | None], Awaitable[S]]
+type TDisconnect[S] = Callable[[S], Awaitable[None]]
+type TNavigate[S] = Callable[[S, str], Awaitable[PageInfo]]
+type TScreenshot[S] = Callable[[S], Awaitable[Screenshot]]
+type TClick[S] = Callable[[S, str], Awaitable[None]]
+type TTypeText[S] = Callable[[S, str, str], Awaitable[None]]
+type TExtractHtml[S] = Callable[[S, str], Awaitable[str]]
+type TEvalJs[S] = Callable[[S, str], Awaitable[EvalResult]]
+type TPageInfo[S] = Callable[[S], Awaitable[PageInfo]]
+type TListTabs[S] = Callable[[S], Awaitable[tuple[Tab, ...]]]
+type TNewTab[S] = Callable[[S, str], Awaitable[Tab]]
+type TSwitchTab[S] = Callable[[S, str], Awaitable[None]]
+type TScroll[S] = Callable[[S, int], Awaitable[None]]
+type TWaitFor[S] = Callable[[S, str, float], Awaitable[None]]

browsectl-0.1.1/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "browsectl"
+version = "0.1.1"
+description = "Browser-agnostic automation for AI agents"
+authors = [
+    {name = "Luis Bordo"},
+]
+requires-python = ">=3.14"
+dependencies = [
+    "websockets>=15.0",
+    "attrs (>=26.1.0,<27.0.0)",
+]
+
+[project.scripts]
+browsectl = "browsectl.main:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.16"
+pytest = "^8.0"
+ruff = "^0.12"
+pytest-asyncio = "^1.4.0"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+explicit_package_bases = true
+warn_unreachable = true
+disallow_any_explicit = true
+disallow_any_unimported = true
+disallow_any_decorated = true
+enable_error_code = [
+    "possibly-undefined",
+    "redundant-expr",
+    "truthy-bool",
+    "truthy-iterable",
+    "exhaustive-match",
+]
+mypy_path = "."
+
+[[tool.mypy.overrides]]
+module = [
+    "websockets",
+]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]