real-browser-cli 0.14.2__py3-none-any.whl

browser_cli/commands/workspace.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from browser_cli.commands import client_from_ctx, handle_errors
+from browser_cli.constants import CONFIG_DIR
+
+console = Console()
+WORKSPACES_PATH = CONFIG_DIR / "workspaces.json"
+
+def _load() -> dict:
+    try:
+        return json.loads(WORKSPACES_PATH.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+
+def _save(data: dict) -> None:
+    WORKSPACES_PATH.parent.mkdir(parents=True, exist_ok=True)
+    WORKSPACES_PATH.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+@click.group("workspace")
+def workspace_group():
+    """Named browser workspaces built on top of sessions."""
+
+@workspace_group.command("save")
+@click.argument("name")
+@click.option("--session", "session_name", default=None, help="Session name to save/use (default: workspace name)")
+@click.option("--profile", default=None, help="Performance profile to remember")
+@handle_errors
+def workspace_save(name, session_name, profile):
+    session_name = session_name or name
+    result = client_from_ctx().session.save(session_name)
+    data = _load()
+    data[name] = {"session": session_name, "profile": profile}
+    _save(data)
+    console.print(f"[green]Workspace '{name}' saved[/green] ({result.get('tabs', 0) if isinstance(result, dict) else 0} tabs)")
+
+@workspace_group.command("load")
+@click.argument("name")
+@click.option("--lazy", is_flag=True, help="Lazy-restore tabs")
+@click.option("--eager-tabs", type=int, default=10, show_default=True)
+@handle_errors
+def workspace_load(name, lazy, eager_tabs):
+    data = _load()
+    ws = data.get(name)
+    if not ws:
+        raise click.ClickException(f"Workspace '{name}' not found")
+    client = client_from_ctx()
+    if ws.get("profile"):
+        client.perf.set_profile(ws["profile"])
+    result = client.session.load(ws["session"], lazy=lazy, eager_tabs=eager_tabs)
+    console.print(f"[green]Workspace '{name}' loaded[/green] ({result.get('tabs', 0) if isinstance(result, dict) else 0} tabs)")
+
+@workspace_group.command("switch")
+@click.argument("name")
+@click.option("--lazy", is_flag=True)
+@handle_errors
+def workspace_switch(name, lazy):
+    """Load a workspace. Alias for workspace load."""
+    ctx = click.get_current_context()
+    ctx.invoke(workspace_load, name=name, lazy=lazy, eager_tabs=10)
+
+@workspace_group.command("list")
+def workspace_list():
+    """List configured workspaces."""
+    data = _load()
+    if not data:
+        console.print("[yellow]No workspaces[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Name")
+    table.add_column("Session")
+    table.add_column("Profile")
+    for name, ws in sorted(data.items()):
+        table.add_row(name, ws.get("session", ""), ws.get("profile") or "")
+    console.print(table)
+
+@workspace_group.command("remove")
+@click.argument("name")
+def workspace_remove(name):
+    data = _load()
+    if name not in data:
+        raise click.ClickException(f"Workspace '{name}' not found")
+    del data[name]
+    _save(data)
+    console.print(f"[green]Workspace '{name}' removed[/green]")

browser_cli/compat/__init__.py

@@ -0,0 +1,4 @@
+from browser_cli.compat.commands import adapt_request, adapt_response
+from browser_cli.compat.auth import adapt_auth
+
+__all__ = ["adapt_auth", "adapt_request", "adapt_response"]

browser_cli/compat/auth.py

@@ -0,0 +1,44 @@
+"""
+Auth-field normalizers — applied to the raw incoming message *before* the
+auth check runs.  Protocol fields (pubkey, sig, …) are still present here.
+
+Add one entry per breaking auth-field change:
+    ("X.Y.Z", transformer_fn)
+
+Entries must stay in ascending version order.
+"""
+from __future__ import annotations
+from typing import Callable
+from browser_cli.version_manager import parse_version
+
+
+# ── v0.9.3 ────────────────────────────────────────────────────────────────────
+
+def _auth_0_9_3(msg: dict) -> dict:
+    """pubkey validation tightened to lowercase hex; normalize for older clients."""
+    changed: dict = {}
+    pk = msg.get("pubkey")
+    if isinstance(pk, str) and pk:
+        changed["pubkey"] = pk.lower()
+    if msg.get("command") == "browser-cli.auth.trust":
+        args = msg.get("args") or {}
+        trust_pk = args.get("pubkey")
+        if isinstance(trust_pk, str) and trust_pk:
+            changed["args"] = {**args, "pubkey": trust_pk.lower()}
+    return {**msg, **changed} if changed else msg
+
+
+# ── registry ──────────────────────────────────────────────────────────────────
+
+_AUTH_COMPAT: list[tuple[str, Callable[[dict], dict]]] = [
+    ("0.9.3", _auth_0_9_3),
+]
+
+
+def adapt_auth(msg: dict, client_version: str) -> dict:
+    """Apply all auth normalizers needed to bring msg up to the current format."""
+    cv = parse_version(client_version)
+    for version, fn in _AUTH_COMPAT:
+        if cv < parse_version(version):
+            msg = fn(msg)
+    return msg

browser_cli/compat/commands.py

@@ -0,0 +1,43 @@
+"""
+Command-format shims — applied to clean_msg (protocol fields already stripped)
+before forwarding to the native host, and to responses before sending back.
+
+Add one entry per breaking command-format change:
+    ("X.Y.Z", request_fn, response_fn)
+
+- request_fn(msg: dict) -> dict   or None
+- response_fn(resp: bytes, command: str) -> bytes   or None
+
+Entries must stay in ascending version order.
+adapt_request walks forward (oldest first); adapt_response walks backward.
+
+Current baseline: 0.9.3 — no command-format shims needed yet.
+"""
+from __future__ import annotations
+from typing import Callable
+from browser_cli.version_manager import parse_version
+
+
+# ── registry ──────────────────────────────────────────────────────────────────
+
+_COMPAT: list[tuple[str, Callable[[dict], dict] | None, Callable[[bytes, str], bytes] | None]] = [
+    # ("1.0.0", _req_1_0_0, _resp_1_0_0),
+]
+
+
+def adapt_request(msg: dict, client_version: str) -> dict:
+    """Upgrade a client message to the current browser command format."""
+    cv = parse_version(client_version)
+    for version, req_fn, _ in _COMPAT:
+        if cv < parse_version(version) and req_fn is not None:
+            msg = req_fn(msg)
+    return msg
+
+
+def adapt_response(resp: bytes, command: str, client_version: str) -> bytes:
+    """Downgrade a native-host response to the format the client expects."""
+    cv = parse_version(client_version)
+    for version, _, resp_fn in reversed(_COMPAT):
+        if cv < parse_version(version) and resp_fn is not None:
+            resp = resp_fn(resp, command)
+    return resp

browser_cli/constants.py

@@ -0,0 +1,95 @@
+"""Project-wide constants for browser-cli.
+
+Only static values live here. Runtime-derived state (e.g. installed version,
+open sockets, locks) stays in the owning module.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP_NAME = "browser-cli"
+RUNTIME_DIRNAME = ".browser_cli"
+DEFAULT_ALIAS = "default"
+
+NATIVE_HOST_NAME = "com.browsercli.host"
+EXTENSION_ID = "bfpmkhngkjnfhabmfckgeohlilokodkg"
+WEBSTORE_EXTENSION_ID = "hekaebjhbhhdbmakimmaklbblbmccahp"
+ALLOWED_EXTENSION_IDS = [EXTENSION_ID, WEBSTORE_EXTENSION_ID]
+SUPPORTED_BROWSERS = ["chrome", "chromium", "brave", "edge", "vivaldi"]
+
+PROTOCOL_MIN_CLIENT = "0.9.0"
+MAX_MSG_BYTES = 32 * 1024 * 1024
+DEFAULT_REMOTE_PORT = 443
+DEFAULT_PAGE_SIZE = 100
+DEFAULT_TRANSPORT_THRESHOLD = 512
+
+NO_ROUTE_COMMANDS = {"browser-cli.targets", "browser-cli.auth.keys", "browser-cli.auth.trust"}
+GENTLE_MODES = ["auto", "normal", "gentle", "ultra"]
+
+PAGEABLE_COMMANDS = {
+  "tabs.list",
+  "tabs.filter",
+  "tabs.query",
+  "group.list",
+  "group.tabs",
+  "group.query",
+  "windows.list",
+  "dom.query",
+  "dom.text",
+  "dom.attr",
+  "extract.links",
+  "extract.images",
+  "extract.json",
+  "session.list",
+}
+
+NATIVE_HOST_DIRS = {
+  "chrome": {
+    "linux":  [Path.home() / ".config/google-chrome/NativeMessagingHosts"],
+    "darwin": [Path.home() / "Library/Application Support/Google/Chrome/NativeMessagingHosts"],
+  },
+  "chromium": {
+    "linux":  [Path.home() / ".config/chromium/NativeMessagingHosts"],
+    "darwin": [Path.home() / "Library/Application Support/Chromium/NativeMessagingHosts"],
+  },
+  "brave": {
+    "linux":  [Path.home() / ".config/BraveSoftware/Brave-Browser/NativeMessagingHosts"],
+    "darwin": [Path.home() / "Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts"],
+  },
+  "edge": {
+    "linux":  [Path.home() / ".config/microsoft-edge/NativeMessagingHosts"],
+    "darwin": [Path.home() / "Library/Application Support/Microsoft Edge/NativeMessagingHosts"],
+  },
+  "vivaldi": {
+    "linux":  [Path.home() / ".config/vivaldi/NativeMessagingHosts"],
+    "darwin": [Path.home() / "Library/Application Support/Vivaldi/NativeMessagingHosts"],
+  },
+}
+
+WINDOWS_NATIVE_HOST_REGISTRY_KEYS = {
+  "chrome": [r"Software\Google\Chrome\NativeMessagingHosts"],
+  "chromium": [r"Software\Chromium\NativeMessagingHosts"],
+  "brave": [r"Software\BraveSoftware\Brave-Browser\NativeMessagingHosts"],
+  "edge": [r"Software\Microsoft\Edge\NativeMessagingHosts"],
+  "vivaldi": [r"Software\Vivaldi\NativeMessagingHosts"],
+}
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))) / APP_NAME
+DEFAULT_KEY_PATH = CONFIG_DIR / "client.key.pem"
+DEFAULT_AUTHORIZED_KEYS_PATH = CONFIG_DIR / "authorized_keys"
+
+SSH_AGENTC_REQUEST_IDENTITIES = 11
+SSH_AGENT_IDENTITIES_ANSWER = 12
+SSH_AGENTC_SIGN_REQUEST = 13
+SSH_AGENT_SIGN_RESPONSE = 14
+
+PQ_KEX_ALG = "ML-KEM-768"
+PQ_TRANSPORT_ALG = "ML-KEM-768+ChaCha20Poly1305"
+
+SER_JSON = 0
+SER_MSGPACK = 1
+COMP_NONE = 0
+COMP_ZLIB = 1
+COMP_GZIP = 2
+COMP_ZSTD = 3

browser_cli/endpoints.py

@@ -0,0 +1,55 @@
+"""Remote endpoint string handling — parsing, normalization, display.
+
+Pure helpers (no sockets, no I/O) for turning user-facing ``host[:port]``
+strings into the canonical forms the rest of the client uses, and back into the
+short forms shown to humans.
+"""
+from __future__ import annotations
+
+import re
+
+from browser_cli.constants import DEFAULT_REMOTE_PORT
+from browser_cli.errors import BrowserNotConnected
+
+def _looks_like_domain(host: str) -> bool:
+    """True if host looks like a domain name rather than an IP address or localhost."""
+    if host in {"localhost", "127.0.0.1", "::1"}:
+        return False
+    if re.match(r'^\d{1,3}(\.\d{1,3}){3}$', host):
+        return False
+    return '.' in host and any(c.isalpha() for c in host)
+
+def _normalize_endpoint(endpoint: str) -> str:
+    """Strip :443 from domain-like endpoints so they are stored without the default port."""
+    if not endpoint:
+        return endpoint
+    host, sep, port = endpoint.rpartition(":")
+    if sep and port == "443" and _looks_like_domain(host):
+        return host
+    return endpoint
+
+def _resolve_connect_endpoint(endpoint: str) -> str:
+    """Return host:port for TCP connection; domain without port defaults to :443."""
+    _, sep, _ = endpoint.rpartition(":")
+    if not sep:
+        if _looks_like_domain(endpoint):
+            return f"{endpoint}:{DEFAULT_REMOTE_PORT}"
+        raise BrowserNotConnected(
+            f"Invalid remote endpoint '{endpoint}': expected host:port"
+        )
+    return endpoint
+
+def display_browser_name(profile_name: str, sock_path: str) -> str:
+    from pathlib import Path
+
+    if profile_name != "default":
+        return profile_name
+    return Path(sock_path).stem or profile_name
+
+def _remote_display_name(endpoint: str, profile_name: str, display_name: str) -> str:
+    host, sep, port = endpoint.rpartition(":")
+    if sep and (port == "8765" or (port == "443" and _looks_like_domain(host))):
+        display_endpoint = host
+    else:
+        display_endpoint = endpoint  # normalized domain (no port) or non-default port
+    return f"{display_endpoint}:{display_name or profile_name}"

browser_cli/errors.py

@@ -0,0 +1,9 @@
+"""Shared exception types for the browser-cli client stack.
+
+Kept dependency-free so the transport, endpoint, and client modules can import
+it without creating an import cycle.
+"""
+from __future__ import annotations
+
+class BrowserNotConnected(Exception):
+    """Raised when the native host socket is not available."""

browser_cli/framing.py

@@ -0,0 +1,83 @@
+"""Length-prefixed byte framing used by browser-cli transports.
+
+Frame format is shared by local IPC and remote TCP: 4-byte little-endian payload
+length followed by raw payload bytes. Native Messaging stdio has the same length
+prefix but JSON helpers stay in ``browser_cli.native.host`` because they operate
+on file streams, not sockets/asyncio streams.
+"""
+from __future__ import annotations
+
+import asyncio
+import struct
+from typing import Protocol
+
+from browser_cli.version_manager import MAX_MSG_BYTES
+
+class RecvSocket(Protocol):
+    def recv(self, n: int) -> bytes: ...
+
+class SendSocket(Protocol):
+    def sendall(self, data: bytes) -> None: ...
+
+def frame(data: bytes) -> bytes:
+    """Return *data* with the browser-cli 4-byte little-endian length prefix."""
+    return struct.pack("<I", len(data)) + data
+
+def _message_length(raw_len: bytes, *, label: str) -> int:
+    msg_len = struct.unpack("<I", raw_len)[0]
+    if msg_len > MAX_MSG_BYTES:
+        raise ConnectionError(f"{label} too large ({msg_len} bytes)")
+    return msg_len
+
+def recv_exact(sock: RecvSocket, n: int, *, allow_eof: bool = False) -> bytes | None:
+    """Read exactly *n* bytes from a blocking socket-like object.
+
+    Returns ``None`` on EOF when ``allow_eof=True``; otherwise raises
+    ``ConnectionError``.
+    """
+    buf = b""
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            if allow_eof:
+                return None
+            raise ConnectionError("Socket closed before full message received")
+        buf += chunk
+    return buf
+
+def recv_frame(sock: RecvSocket, *, allow_eof: bool = False, label: str = "Message") -> bytes | None:
+    """Read one framed payload from a blocking socket-like object."""
+    raw_len = recv_exact(sock, 4, allow_eof=allow_eof)
+    if raw_len is None:
+        return None
+    return recv_exact(sock, _message_length(raw_len, label=label), allow_eof=allow_eof)
+
+def send_frame(sock: SendSocket, data: bytes) -> None:
+    """Send one framed payload through a blocking socket-like object."""
+    sock.sendall(frame(data))
+
+async def async_recv_exact(reader: asyncio.StreamReader, n: int, *, allow_eof: bool = False) -> bytes | None:
+    """Read exactly *n* bytes from an asyncio StreamReader."""
+    try:
+        return await reader.readexactly(n)
+    except asyncio.IncompleteReadError as exc:
+        if allow_eof:
+            return None
+        raise ConnectionError("Socket closed before full message received") from exc
+
+async def async_recv_frame(
+    reader: asyncio.StreamReader,
+    *,
+    allow_eof: bool = False,
+    label: str = "Message",
+) -> bytes | None:
+    """Read one framed payload from an asyncio StreamReader."""
+    raw_len = await async_recv_exact(reader, 4, allow_eof=allow_eof)
+    if raw_len is None:
+        return None
+    return await async_recv_exact(reader, _message_length(raw_len, label=label), allow_eof=allow_eof)
+
+async def async_send_frame(writer: asyncio.StreamWriter, data: bytes) -> None:
+    """Send one framed payload through an asyncio StreamWriter."""
+    writer.write(frame(data))
+    await writer.drain()

browser_cli/local_transport.py

@@ -0,0 +1,64 @@
+"""Local IPC transport for browser-cli client commands."""
+from __future__ import annotations
+
+import asyncio
+import socket
+from collections.abc import Callable
+from multiprocessing.connection import Client as PipeClient
+
+from browser_cli.framing import async_recv_exact as framing_async_recv_exact
+from browser_cli.framing import async_recv_frame, async_send_frame, frame
+from browser_cli.platform import is_windows
+from browser_cli.remote.transport import _recv_all
+
+async def async_recv_exact(reader: asyncio.StreamReader, n: int) -> bytes | None:
+  try:
+    return await framing_async_recv_exact(reader, n, allow_eof=True)
+  except ConnectionError:
+    return None
+
+async def async_recv_all(reader: asyncio.StreamReader) -> bytes | None:
+  try:
+    return await async_recv_frame(reader, allow_eof=True)
+  except ConnectionError:
+    return None
+
+async def async_send_all(writer: asyncio.StreamWriter, data: bytes) -> None:
+  await async_send_frame(writer, data)
+
+def send_local_sync(profile: str | None, payload: bytes, resolve_socket: Callable[[str | None], str]) -> bytes | None:
+  sock_path = resolve_socket(profile)
+  if is_windows():
+    with PipeClient(sock_path, family="AF_PIPE") as conn:
+      conn.send_bytes(payload)
+      return conn.recv_bytes()
+
+  with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+    sock.connect(sock_path)
+    sock.sendall(frame(payload))
+    return _recv_all(sock)
+
+async def send_local_async(profile: str | None, payload: bytes, resolve_socket: Callable[[str | None], str]) -> bytes | None:
+  sock_path = await asyncio.to_thread(resolve_socket, profile)
+  if is_windows():
+    return await _send_windows_pipe_async(sock_path, payload)
+  return await _send_local_unix_async(sock_path, payload)
+
+async def _send_local_unix_async(sock_path: str, payload: bytes) -> bytes | None:
+  reader, writer = await asyncio.open_unix_connection(sock_path)
+  try:
+    await async_send_all(writer, payload)
+    return await async_recv_all(reader)
+  finally:
+    writer.close()
+    try:
+      await writer.wait_closed()
+    except Exception:
+      pass
+
+async def _send_windows_pipe_async(sock_path: str, payload: bytes) -> bytes:
+  def _roundtrip():
+    with PipeClient(sock_path, family="AF_PIPE") as conn:
+      conn.send_bytes(payload)
+      return conn.recv_bytes()
+  return await asyncio.to_thread(_roundtrip)

browser_cli/markdown/__init__.py

@@ -0,0 +1,8 @@
+"""Markdown rendering and HTML-to-Markdown conversion helpers."""
+from browser_cli.markdown.render import (
+  _clean_markdown_output,
+  _convert_html_to_markdown,
+  render_markdown,
+)
+
+__all__ = ["_clean_markdown_output", "_convert_html_to_markdown", "render_markdown"]