camoufox-cli 0.1.0__py3-none-any.whl

camoufox_cli/__main__.py

@@ -0,0 +1,32 @@
+"""Entry point: python -m camoufox_cli"""
+
+import argparse
+import sys
+
+from .server import DaemonServer
+
+
+def main():
+    parser = argparse.ArgumentParser(description="camoufox-cli daemon server")
+    parser.add_argument("--session", default="default", help="Session name")
+    parser.add_argument("--headless", action="store_true", default=True, help="Run headless (default)")
+    parser.add_argument("--headed", action="store_true", help="Show browser window")
+    parser.add_argument("--timeout", type=int, default=1800, help="Idle timeout in seconds")
+    parser.add_argument("--persistent", default=None, help="Path for persistent browser profile")
+    args = parser.parse_args()
+
+    headless = not args.headed
+
+    server = DaemonServer(
+        session=args.session,
+        headless=headless,
+        timeout=args.timeout,
+        persistent=args.persistent,
+    )
+
+    print(f"[camoufox-cli] Starting daemon session={args.session} headless={headless}", file=sys.stderr)
+    server.start()
+
+
+if __name__ == "__main__":
+    main()

camoufox_cli/browser.py

@@ -0,0 +1,99 @@
+"""Browser manager: launches and manages Camoufox instance."""
+
+from __future__ import annotations
+
+from camoufox.sync_api import Camoufox
+from playwright.sync_api import BrowserContext, Page
+
+from .refs import RefRegistry
+
+
+class BrowserManager:
+    def __init__(self, persistent: str | None = None):
+        self._camoufox: Camoufox | None = None
+        self._context: BrowserContext | None = None
+        self._page: Page | None = None
+        self.refs = RefRegistry()
+        self._headless: bool = True
+        self._persistent = persistent
+
+    def launch(self, headless: bool = True) -> None:
+        if self._camoufox is not None:
+            return
+        self._headless = headless
+
+        kwargs: dict = {"headless": headless}
+        if self._persistent:
+            kwargs["persistent_context"] = True
+            kwargs["user_data_dir"] = self._persistent
+
+        self._camoufox = Camoufox(**kwargs)
+        result = self._camoufox.__enter__()
+
+        if self._persistent:
+            # persistent_context returns BrowserContext directly
+            self._context = result
+            pages = self._context.pages
+            self._page = pages[0] if pages else self._context.new_page()
+        else:
+            # Normal mode: result is Browser, new_page() creates default context + page
+            self._page = result.new_page()
+            self._context = self._page.context
+
+    def get_page(self) -> Page:
+        if self._page is None:
+            raise RuntimeError("Browser not launched. Send 'open' command first.")
+        return self._page
+
+    def get_context(self) -> BrowserContext:
+        if self._context is None:
+            raise RuntimeError("Browser not launched. Send 'open' command first.")
+        return self._context
+
+    def get_tabs(self) -> list[dict]:
+        ctx = self.get_context()
+        tabs = []
+        for i, p in enumerate(ctx.pages):
+            tabs.append({
+                "index": i,
+                "url": p.url,
+                "title": p.title(),
+                "active": p is self._page,
+            })
+        return tabs
+
+    def switch_to_tab(self, index: int) -> Page:
+        ctx = self.get_context()
+        pages = ctx.pages
+        if index < 0 or index >= len(pages):
+            raise IndexError(f"Tab index {index} out of range (0-{len(pages) - 1})")
+        self._page = pages[index]
+        self._page.bring_to_front()
+        return self._page
+
+    def close_current_tab(self) -> None:
+        ctx = self.get_context()
+        pages = ctx.pages
+        if len(pages) <= 1:
+            raise RuntimeError("Cannot close the last tab. Use 'close' to shut down the browser.")
+        current = self._page
+        # Switch to another tab before closing
+        idx = pages.index(current)
+        new_idx = idx - 1 if idx > 0 else 1
+        self._page = pages[new_idx]
+        self._page.bring_to_front()
+        current.close()
+
+    def close(self) -> None:
+        if self._camoufox is not None:
+            try:
+                self._camoufox.__exit__(None, None, None)
+            except Exception:
+                pass
+            self._camoufox = None
+            self._context = None
+            self._page = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._camoufox is not None

camoufox_cli/cli.py

@@ -0,0 +1,385 @@
+"""CLI client: parses args, starts daemon if needed, sends command via Unix socket."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+
+
+SOCKET_PREFIX = "/tmp/camoufox-cli-"
+
+
+def get_socket_path(session: str) -> str:
+    return f"{SOCKET_PREFIX}{session}.sock"
+
+
+def send_command(sock_path: str, command: dict) -> dict:
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.connect(sock_path)
+    s.sendall(json.dumps(command).encode() + b"\n")
+    s.shutdown(socket.SHUT_WR)
+    data = b""
+    while True:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        data += chunk
+    s.close()
+    return json.loads(data.decode())
+
+
+def spawn_daemon(session: str, headed: bool, timeout: int, persistent: str | None) -> None:
+    cmd = [sys.executable, "-m", "camoufox_cli", "--session", session, "--timeout", str(timeout)]
+    if headed:
+        cmd.append("--headed")
+    if persistent:
+        cmd.extend(["--persistent", persistent])
+
+    subprocess.Popen(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+    sock_path = get_socket_path(session)
+    for _ in range(50):
+        if os.path.exists(sock_path):
+            return
+        time.sleep(0.1)
+
+    print("Error: Daemon did not start within 5 seconds", file=sys.stderr)
+    sys.exit(1)
+
+
+def ensure_daemon(session: str, headed: bool, timeout: int, persistent: str | None) -> None:
+    sock_path = get_socket_path(session)
+    if not os.path.exists(sock_path):
+        spawn_daemon(session, headed, timeout, persistent)
+
+
+def list_sessions() -> list[str]:
+    sessions = []
+    try:
+        for name in os.listdir("/tmp"):
+            if name.startswith("camoufox-cli-") and name.endswith(".sock"):
+                sessions.append(name[len("camoufox-cli-"):-len(".sock")])
+    except OSError:
+        pass
+    sessions.sort()
+    return sessions
+
+
+def parse_args(args: list[str]) -> tuple[dict, dict]:
+    """Parse CLI args into (flags, command). Returns (flags_dict, command_json)."""
+    flags = {"session": "default", "headed": False, "timeout": 1800, "json": False, "persistent": None}
+    rest = []
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--session":
+            i += 1
+            if i >= len(args):
+                print("Error: --session requires a value", file=sys.stderr)
+                sys.exit(1)
+            flags["session"] = args[i]
+        elif args[i] == "--headed":
+            flags["headed"] = True
+        elif args[i] == "--timeout":
+            i += 1
+            if i >= len(args):
+                print("Error: --timeout requires a value", file=sys.stderr)
+                sys.exit(1)
+            flags["timeout"] = int(args[i])
+        elif args[i] == "--json":
+            flags["json"] = True
+        elif args[i] == "--persistent":
+            i += 1
+            if i >= len(args):
+                print("Error: --persistent requires a value", file=sys.stderr)
+                sys.exit(1)
+            flags["persistent"] = args[i]
+        else:
+            rest.append(args[i])
+        i += 1
+
+    if not rest:
+        print(USAGE, file=sys.stderr)
+        sys.exit(1)
+
+    action = rest[0]
+    cmd = build_command(action, rest)
+    return flags, cmd
+
+
+def build_command(action: str, rest: list[str]) -> dict:
+    """Build JSON command from action and remaining args."""
+    match action:
+        # Navigation
+        case "open":
+            url = _require(rest, 1, "Usage: camoufox-cli open <url>")
+            return {"id": "r1", "action": "open", "params": {"url": url}}
+        case "back":
+            return {"id": "r1", "action": "back", "params": {}}
+        case "forward":
+            return {"id": "r1", "action": "forward", "params": {}}
+        case "reload":
+            return {"id": "r1", "action": "reload", "params": {}}
+        case "url":
+            return {"id": "r1", "action": "url", "params": {}}
+        case "title":
+            return {"id": "r1", "action": "title", "params": {}}
+        case "close":
+            all_flag = "--all" in rest
+            return {"id": "r1", "action": "close", "params": {"all": all_flag}}
+
+        # Snapshot
+        case "snapshot":
+            interactive = "-i" in rest
+            selector = None
+            if "-s" in rest:
+                idx = rest.index("-s")
+                selector = _require(rest, idx + 1, "Usage: camoufox-cli snapshot -s <selector>")
+            params = {"interactive": interactive}
+            if selector:
+                params["selector"] = selector
+            return {"id": "r1", "action": "snapshot", "params": params}
+
+        # Interaction
+        case "click":
+            ref = _require(rest, 1, "Usage: camoufox-cli click @e1")
+            return {"id": "r1", "action": "click", "params": {"ref": ref}}
+        case "fill":
+            ref = _require(rest, 1, "Usage: camoufox-cli fill @e1 \"text\"")
+            text = _require(rest, 2, "Usage: camoufox-cli fill @e1 \"text\"")
+            return {"id": "r1", "action": "fill", "params": {"ref": ref, "text": text}}
+        case "type":
+            ref = _require(rest, 1, "Usage: camoufox-cli type @e1 \"text\"")
+            text = _require(rest, 2, "Usage: camoufox-cli type @e1 \"text\"")
+            return {"id": "r1", "action": "type", "params": {"ref": ref, "text": text}}
+        case "select":
+            ref = _require(rest, 1, "Usage: camoufox-cli select @e1 \"option\"")
+            value = _require(rest, 2, "Usage: camoufox-cli select @e1 \"option\"")
+            return {"id": "r1", "action": "select", "params": {"ref": ref, "value": value}}
+        case "check":
+            ref = _require(rest, 1, "Usage: camoufox-cli check @e1")
+            return {"id": "r1", "action": "check", "params": {"ref": ref}}
+        case "hover":
+            ref = _require(rest, 1, "Usage: camoufox-cli hover @e1")
+            return {"id": "r1", "action": "hover", "params": {"ref": ref}}
+        case "press":
+            key = _require(rest, 1, "Usage: camoufox-cli press Enter")
+            return {"id": "r1", "action": "press", "params": {"key": key}}
+
+        # Data extraction
+        case "text":
+            target = _require(rest, 1, "Usage: camoufox-cli text @e1 | camoufox-cli text body")
+            return {"id": "r1", "action": "text", "params": {"target": target}}
+        case "eval":
+            expr = _require(rest, 1, "Usage: camoufox-cli eval \"document.title\"")
+            return {"id": "r1", "action": "eval", "params": {"expression": expr}}
+        case "screenshot":
+            params = {}
+            for arg in rest[1:]:
+                if arg == "--full":
+                    params["full_page"] = True
+                else:
+                    params["path"] = arg
+            return {"id": "r1", "action": "screenshot", "params": params}
+        case "pdf":
+            path = _require(rest, 1, "Usage: camoufox-cli pdf output.pdf")
+            return {"id": "r1", "action": "pdf", "params": {"path": path}}
+
+        # Scroll & Wait
+        case "scroll":
+            direction = _require(rest, 1, "Usage: camoufox-cli scroll down [px]")
+            amount = int(rest[2]) if len(rest) > 2 else 500
+            return {"id": "r1", "action": "scroll", "params": {"direction": direction, "amount": amount}}
+        case "wait":
+            target = _require(rest, 1, "Usage: camoufox-cli wait @e1 | camoufox-cli wait 2000 | camoufox-cli wait --url \"pattern\"")
+            if target == "--url":
+                pattern = _require(rest, 2, "Usage: camoufox-cli wait --url \"*/dashboard\"")
+                return {"id": "r1", "action": "wait", "params": {"url": pattern}}
+            elif target.startswith("@"):
+                return {"id": "r1", "action": "wait", "params": {"ref": target}}
+            elif target[0].isdigit():
+                return {"id": "r1", "action": "wait", "params": {"ms": int(target)}}
+            else:
+                return {"id": "r1", "action": "wait", "params": {"selector": target}}
+
+        # Tab management
+        case "tabs":
+            return {"id": "r1", "action": "tabs", "params": {}}
+        case "switch":
+            index = _require(rest, 1, "Usage: camoufox-cli switch <tab-index>")
+            return {"id": "r1", "action": "switch", "params": {"index": int(index)}}
+        case "close-tab":
+            return {"id": "r1", "action": "close-tab", "params": {}}
+
+        # Session & Cookies
+        case "sessions":
+            return {"id": "r1", "action": "sessions", "params": {}}
+        case "cookies":
+            if len(rest) > 1 and rest[1] == "import":
+                path = _require(rest, 2, "Usage: camoufox-cli cookies import file.json")
+                return {"id": "r1", "action": "cookies", "params": {"op": "import", "path": path}}
+            elif len(rest) > 1 and rest[1] == "export":
+                path = _require(rest, 2, "Usage: camoufox-cli cookies export file.json")
+                return {"id": "r1", "action": "cookies", "params": {"op": "export", "path": path}}
+            else:
+                return {"id": "r1", "action": "cookies", "params": {"op": "list"}}
+
+        case _:
+            print(f"Unknown command: {action}\n{USAGE}", file=sys.stderr)
+            sys.exit(1)
+
+
+def _require(args: list[str], idx: int, usage: str) -> str:
+    if idx >= len(args):
+        print(usage, file=sys.stderr)
+        sys.exit(1)
+    return args[idx]
+
+
+def print_response(response: dict, json_mode: bool) -> None:
+    if json_mode:
+        print(json.dumps(response, indent=2, ensure_ascii=False))
+        return
+
+    if not response.get("success"):
+        print(f"Error: {response.get('error', 'Unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    data = response.get("data")
+    if not data:
+        return
+
+    if "snapshot" in data:
+        print(data["snapshot"])
+    elif "text" in data:
+        print(data["text"])
+    elif "result" in data:
+        v = data["result"]
+        print("null" if v is None else json.dumps(v, ensure_ascii=False) if not isinstance(v, str) else v)
+    elif data.get("closed"):
+        pass  # silent
+    elif "url" in data:
+        if "title" in data:
+            print(data["title"])
+        print(data["url"])
+    elif "title" in data:
+        print(data["title"])
+    elif not data:
+        pass  # silent success
+    else:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def main():
+    args = sys.argv[1:]
+    flags, command = parse_args(args)
+
+    action = command.get("action", "")
+
+    # Client-side: sessions
+    if action == "sessions":
+        sessions = list_sessions()
+        if flags["json"]:
+            print(json.dumps(sessions, indent=2))
+        elif not sessions:
+            print("No active sessions.")
+        else:
+            for s in sessions:
+                print(s)
+        return
+
+    # Client-side: close --all
+    if action == "close" and command.get("params", {}).get("all"):
+        sessions = list_sessions()
+        if not sessions:
+            print("No active sessions.")
+            return
+        close_cmd = {"id": "r1", "action": "close", "params": {}}
+        for session in sessions:
+            sock_path = get_socket_path(session)
+            try:
+                send_command(sock_path, close_cmd)
+            except Exception as e:
+                print(f"Failed to close session {session}: {e}", file=sys.stderr)
+        return
+
+    # Ensure daemon is running
+    ensure_daemon(flags["session"], flags["headed"], flags["timeout"], flags["persistent"])
+
+    sock_path = get_socket_path(flags["session"])
+
+    # Send command with retry
+    last_err = ""
+    for attempt in range(5):
+        try:
+            response = send_command(sock_path, command)
+            print_response(response, flags["json"])
+            return
+        except Exception as e:
+            last_err = str(e)
+            if attempt < 4:
+                time.sleep(0.2 * (attempt + 1))
+
+    print(f"Error: Failed to connect to daemon after 5 attempts: {last_err}", file=sys.stderr)
+    sys.exit(1)
+
+
+USAGE = """\
+Usage: camoufox-cli [flags] <command> [args]
+
+Navigation:
+  open <url>              Navigate to URL
+  back                    Go back
+  forward                 Go forward
+  reload                  Reload page
+  url                     Print current URL
+  title                   Print page title
+  close [--all]           Close browser and daemon (--all: all sessions)
+
+Snapshot:
+  snapshot [-i] [-s sel]  Aria tree (-i interactive, -s scoped)
+
+Interaction:
+  click @ref              Click element
+  fill @ref "text"        Clear + type into input
+  type @ref "text"        Type without clearing
+  select @ref "option"    Select dropdown option
+  check @ref              Toggle checkbox
+  hover @ref              Hover over element
+  press <key>             Press key (e.g. Enter, Control+a)
+
+Data:
+  text @ref|selector      Get text content
+  eval "js expression"    Execute JavaScript
+  screenshot [--full] [f] Screenshot to file or stdout
+  pdf <file>              Save page as PDF
+
+Scroll & Wait:
+  scroll <dir> [px]       Scroll up/down (default 500px)
+  wait <ms|@ref|--url p>  Wait for time/element/URL
+
+Tabs:
+  tabs                    List open tabs
+  switch <index>          Switch to tab
+  close-tab               Close current tab
+
+Session:
+  sessions                List active sessions
+  cookies [import|export] Manage cookies
+
+Flags:
+  --session <name>     Session name (default: "default")
+  --headed             Show browser window
+  --timeout <secs>     Daemon idle timeout (default: 1800)
+  --json               Output as JSON
+  --persistent <path>  Use persistent browser profile"""

camoufox_cli/commands.py

@@ -0,0 +1,343 @@
+"""Command implementations for the daemon."""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from .browser import BrowserManager
+from .protocol import ok_response, error_response
+
+
+def execute(manager: BrowserManager, command: dict) -> dict:
+    """Dispatch and execute a command, return a response dict."""
+    cmd_id = command.get("id", "?")
+    action = command.get("action", "")
+    params = command.get("params", {})
+
+    try:
+        handler = _HANDLERS.get(action)
+        if handler is None:
+            return error_response(cmd_id, f"Unknown action: {action}")
+        return handler(manager, cmd_id, params)
+    except Exception as e:
+        return error_response(cmd_id, str(e))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_ref(manager: BrowserManager, ref_str: str):
+    """Resolve a ref string to a (locator, entry) tuple, or raise."""
+    entry = manager.refs.resolve(ref_str)
+    if entry is None:
+        raise ValueError(f"Ref @{ref_str.lstrip('@')} not found. Run 'camoufox-cli snapshot' to refresh refs.")
+    page = manager.get_page()
+    locator = page.get_by_role(entry.role, name=entry.name)
+    if entry.nth > 0:
+        locator = locator.nth(entry.nth)
+    return locator
+
+
+# ---------------------------------------------------------------------------
+# Navigation
+# ---------------------------------------------------------------------------
+
+def _cmd_open(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    url = params.get("url", "")
+    if not url:
+        return error_response(cmd_id, "Missing 'url' parameter")
+
+    if not manager.is_running:
+        manager.launch(headless=params.get("headless", True))
+
+    page = manager.get_page()
+    page.goto(url, wait_until="domcontentloaded")
+    return ok_response(cmd_id, {"url": page.url, "title": page.title()})
+
+
+def _cmd_back(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    manager.get_page().go_back(wait_until="domcontentloaded")
+    return ok_response(cmd_id)
+
+
+def _cmd_forward(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    manager.get_page().go_forward(wait_until="domcontentloaded")
+    return ok_response(cmd_id)
+
+
+def _cmd_reload(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    page = manager.get_page()
+    page.evaluate("location.reload()")
+    page.wait_for_load_state("domcontentloaded")
+    return ok_response(cmd_id)
+
+
+def _cmd_url(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    return ok_response(cmd_id, {"url": manager.get_page().url})
+
+
+def _cmd_title(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    return ok_response(cmd_id, {"title": manager.get_page().title()})
+
+
+def _cmd_close(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    manager.close()
+    return ok_response(cmd_id, {"closed": True})
+
+
+# ---------------------------------------------------------------------------
+# Snapshot
+# ---------------------------------------------------------------------------
+
+def _cmd_snapshot(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    page = manager.get_page()
+    interactive = params.get("interactive", False)
+    selector = params.get("selector")
+
+    target = page.locator(selector) if selector else page.locator("body")
+    aria_text = target.aria_snapshot()
+    annotated = manager.refs.build_from_snapshot(aria_text, interactive_only=interactive)
+    return ok_response(cmd_id, {"snapshot": annotated})
+
+
+# ---------------------------------------------------------------------------
+# Interaction
+# ---------------------------------------------------------------------------
+
+def _cmd_click(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    _resolve_ref(manager, ref_str).click()
+    return ok_response(cmd_id)
+
+
+def _cmd_fill(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    text = params.get("text", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    _resolve_ref(manager, ref_str).fill(text)
+    return ok_response(cmd_id)
+
+
+def _cmd_type(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    text = params.get("text", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    _resolve_ref(manager, ref_str).press_sequentially(text)
+    return ok_response(cmd_id)
+
+
+def _cmd_select(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    value = params.get("value", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    _resolve_ref(manager, ref_str).select_option(label=value)
+    return ok_response(cmd_id)
+
+
+def _cmd_check(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    locator = _resolve_ref(manager, ref_str)
+    if locator.is_checked():
+        locator.uncheck()
+    else:
+        locator.check()
+    return ok_response(cmd_id)
+
+
+def _cmd_hover(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ref_str = params.get("ref", "")
+    if not ref_str:
+        return error_response(cmd_id, "Missing 'ref' parameter")
+    _resolve_ref(manager, ref_str).hover()
+    return ok_response(cmd_id)
+
+
+def _cmd_press(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    key = params.get("key", "")
+    if not key:
+        return error_response(cmd_id, "Missing 'key' parameter")
+    manager.get_page().keyboard.press(key)
+    return ok_response(cmd_id)
+
+
+# ---------------------------------------------------------------------------
+# Data extraction
+# ---------------------------------------------------------------------------
+
+def _cmd_text(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    target = params.get("target", "")
+    if not target:
+        return error_response(cmd_id, "Missing 'target' parameter")
+
+    if target.startswith("@"):
+        text = _resolve_ref(manager, target).text_content() or ""
+    else:
+        text = manager.get_page().locator(target).text_content() or ""
+
+    return ok_response(cmd_id, {"text": text})
+
+
+def _cmd_eval(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    expression = params.get("expression", "")
+    if not expression:
+        return error_response(cmd_id, "Missing 'expression' parameter")
+    result = manager.get_page().evaluate(expression)
+    return ok_response(cmd_id, {"result": result})
+
+
+def _cmd_screenshot(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    page = manager.get_page()
+    path = params.get("path")
+    full_page = params.get("full_page", False)
+
+    if path:
+        page.screenshot(path=path, full_page=full_page)
+        return ok_response(cmd_id, {"path": path})
+    else:
+        buf = page.screenshot(full_page=full_page)
+        b64 = base64.b64encode(buf).decode("ascii")
+        return ok_response(cmd_id, {"base64": b64})
+
+
+def _cmd_pdf(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    return error_response(
+        cmd_id,
+        "PDF export is not supported with Firefox/Camoufox. Use 'screenshot --full' instead.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Scroll & Wait
+# ---------------------------------------------------------------------------
+
+def _cmd_scroll(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    direction = params.get("direction", "down")
+    amount = int(params.get("amount", 500))
+
+    if direction == "up":
+        amount = -amount
+
+    manager.get_page().evaluate(f"window.scrollBy(0, {amount})")
+    return ok_response(cmd_id)
+
+
+def _cmd_wait(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    page = manager.get_page()
+
+    if "ms" in params:
+        page.wait_for_timeout(int(params["ms"]))
+    elif "ref" in params:
+        _resolve_ref(manager, params["ref"]).wait_for()
+    elif "selector" in params:
+        page.wait_for_selector(params["selector"])
+    elif "url" in params:
+        page.wait_for_url(params["url"])
+    else:
+        return error_response(cmd_id, "wait requires ms, ref, selector, or url parameter")
+
+    return ok_response(cmd_id)
+
+
+# ---------------------------------------------------------------------------
+# Tab management
+# ---------------------------------------------------------------------------
+
+def _cmd_tabs(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    return ok_response(cmd_id, {"tabs": manager.get_tabs()})
+
+
+def _cmd_switch(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    index = params.get("index")
+    if index is None:
+        return error_response(cmd_id, "Missing 'index' parameter")
+    page = manager.switch_to_tab(int(index))
+    return ok_response(cmd_id, {"url": page.url, "title": page.title()})
+
+
+def _cmd_close_tab(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    manager.close_current_tab()
+    page = manager.get_page()
+    return ok_response(cmd_id, {"url": page.url, "title": page.title()})
+
+
+# ---------------------------------------------------------------------------
+# Cookies
+# ---------------------------------------------------------------------------
+
+def _cmd_cookies(manager: BrowserManager, cmd_id: str, params: dict) -> dict:
+    ctx = manager.get_context()
+    op = params.get("op", "list")
+
+    if op == "list":
+        cookies = ctx.cookies()
+        return ok_response(cmd_id, {"cookies": cookies})
+
+    elif op == "export":
+        path = params.get("path", "")
+        if not path:
+            return error_response(cmd_id, "Missing 'path' parameter for export")
+        cookies = ctx.cookies()
+        with open(path, "w") as f:
+            json.dump(cookies, f, indent=2)
+        return ok_response(cmd_id, {"path": path, "count": len(cookies)})
+
+    elif op == "import":
+        path = params.get("path", "")
+        if not path:
+            return error_response(cmd_id, "Missing 'path' parameter for import")
+        with open(path) as f:
+            cookies = json.load(f)
+        ctx.add_cookies(cookies)
+        return ok_response(cmd_id, {"count": len(cookies)})
+
+    else:
+        return error_response(cmd_id, f"Unknown cookies op: {op}")
+
+
+# ---------------------------------------------------------------------------
+# Handler dispatch table
+# ---------------------------------------------------------------------------
+
+_HANDLERS = {
+    # Navigation
+    "open": _cmd_open,
+    "back": _cmd_back,
+    "forward": _cmd_forward,
+    "reload": _cmd_reload,
+    "url": _cmd_url,
+    "title": _cmd_title,
+    "close": _cmd_close,
+    # Snapshot
+    "snapshot": _cmd_snapshot,
+    # Interaction
+    "click": _cmd_click,
+    "fill": _cmd_fill,
+    "type": _cmd_type,
+    "select": _cmd_select,
+    "check": _cmd_check,
+    "hover": _cmd_hover,
+    "press": _cmd_press,
+    # Data extraction
+    "text": _cmd_text,
+    "eval": _cmd_eval,
+    "screenshot": _cmd_screenshot,
+    "pdf": _cmd_pdf,
+    # Scroll & Wait
+    "scroll": _cmd_scroll,
+    "wait": _cmd_wait,
+    # Tab management
+    "tabs": _cmd_tabs,
+    "switch": _cmd_switch,
+    "close-tab": _cmd_close_tab,
+    # Cookies
+    "cookies": _cmd_cookies,
+}

camoufox_cli/protocol.py

@@ -0,0 +1,24 @@
+"""JSON-line protocol for CLI <-> Daemon communication."""
+
+import json
+
+
+def parse_command(line: str) -> dict:
+    """Parse a JSON-line command from the CLI."""
+    return json.loads(line.strip())
+
+
+def serialize_response(response: dict) -> bytes:
+    """Serialize a response dict to JSON-line bytes."""
+    return json.dumps(response, ensure_ascii=False).encode("utf-8") + b"\n"
+
+
+def ok_response(id: str, data: dict | None = None) -> dict:
+    resp = {"id": id, "success": True}
+    if data is not None:
+        resp["data"] = data
+    return resp
+
+
+def error_response(id: str, error: str) -> dict:
+    return {"id": id, "success": False, "error": error}

camoufox_cli/refs.py

@@ -0,0 +1,83 @@
+"""Ref registry: maps @e1, @e2 to aria role+name for Playwright locators."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class RefEntry:
+    ref: str        # e.g. "e1"
+    role: str       # e.g. "link"
+    name: str       # e.g. "About"
+    nth: int = 0    # index for duplicates
+
+
+# Roles considered "interactive" for snapshot -i
+INTERACTIVE_ROLES = frozenset({
+    "link", "button", "combobox", "textbox", "textarea",
+    "checkbox", "radio", "switch", "slider",
+    "tab", "tabpanel", "menuitem", "option",
+    "select", "listbox", "searchbox",
+})
+
+# Pattern to match aria snapshot lines like:  - link "About"
+#   handles nested indentation and optional attributes
+_ARIA_LINE_RE = re.compile(
+    r'^(\s*-\s+)'           # leading indent + dash
+    r'(\w+)'                # role
+    r'(?:\s+"([^"]*)")?'    # optional quoted name
+)
+
+
+class RefRegistry:
+    def __init__(self):
+        self._entries: dict[str, RefEntry] = {}  # ref_str -> RefEntry
+        self._counter = 0
+
+    def build_from_snapshot(self, aria_text: str, interactive_only: bool = False) -> str:
+        """Parse aria snapshot text, assign refs, return annotated text."""
+        self._entries.clear()
+        self._counter = 0
+
+        # Track role+name occurrences for nth disambiguation
+        seen: dict[tuple[str, str], int] = {}
+        lines = aria_text.split("\n")
+        result_lines = []
+
+        for line in lines:
+            m = _ARIA_LINE_RE.match(line)
+            if not m:
+                if not interactive_only:
+                    result_lines.append(line)
+                continue
+
+            role = m.group(2)
+            name = m.group(3) or ""
+
+            if interactive_only and role not in INTERACTIVE_ROLES:
+                continue
+
+            key = (role, name)
+            nth = seen.get(key, 0)
+            seen[key] = nth + 1
+
+            self._counter += 1
+            ref = f"e{self._counter}"
+            entry = RefEntry(ref=ref, role=role, name=name, nth=nth)
+            self._entries[ref] = entry
+
+            # Append [ref=eN] to the line
+            annotated = f"{line.rstrip()} [ref={ref}]"
+            result_lines.append(annotated)
+
+        return "\n".join(result_lines)
+
+    def resolve(self, ref_str: str) -> RefEntry | None:
+        """Resolve a ref string like 'e1' or '@e1' to a RefEntry."""
+        ref = ref_str.lstrip("@")
+        return self._entries.get(ref)
+
+    def __len__(self) -> int:
+        return len(self._entries)

camoufox_cli/server.py

@@ -0,0 +1,145 @@
+"""Unix socket server for the camoufox-cli daemon."""
+
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import sys
+import threading
+import time
+
+from .browser import BrowserManager
+from .commands import execute
+from .protocol import parse_command, serialize_response
+
+
+class DaemonServer:
+    def __init__(self, session: str = "default", headless: bool = True, timeout: int = 1800, persistent: str | None = None):
+        self.session = session
+        self.headless = headless
+        self.timeout = timeout  # idle timeout in seconds
+        self.socket_path = f"/tmp/camoufox-cli-{session}.sock"
+        self.pid_path = f"/tmp/camoufox-cli-{session}.pid"
+        self.manager = BrowserManager(persistent=persistent)
+        self._server_socket: socket.socket | None = None
+        self._last_activity = time.time()
+        self._running = False
+
+    def start(self) -> None:
+        self._cleanup_stale()
+        self._write_pid()
+        self._running = True
+
+        # Start idle timeout watchdog
+        watchdog = threading.Thread(target=self._idle_watchdog, daemon=True)
+        watchdog.start()
+
+        # Set up signal handlers
+        signal.signal(signal.SIGTERM, self._handle_signal)
+        signal.signal(signal.SIGINT, self._handle_signal)
+
+        self._server_socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            self._server_socket.bind(self.socket_path)
+            self._server_socket.listen(5)
+            self._server_socket.settimeout(1.0)  # allow periodic checks
+
+            while self._running:
+                try:
+                    conn, _ = self._server_socket.accept()
+                except socket.timeout:
+                    continue
+                except OSError:
+                    break
+
+                self._last_activity = time.time()
+                try:
+                    self._handle_connection(conn)
+                except Exception as e:
+                    print(f"[camoufox-cli] Connection error: {e}", file=sys.stderr)
+                finally:
+                    conn.close()
+        finally:
+            self._shutdown()
+
+    def _handle_connection(self, conn: socket.socket) -> None:
+        data = b""
+        while True:
+            chunk = conn.recv(4096)
+            if not chunk:
+                break
+            data += chunk
+            if b"\n" in data:
+                break
+
+        line = data.decode("utf-8").strip()
+        if not line:
+            return
+
+        command = parse_command(line)
+
+        # Pass headless preference to open commands
+        if command.get("action") == "open":
+            command.setdefault("params", {}).setdefault("headless", self.headless)
+
+        response = execute(self.manager, command)
+        conn.sendall(serialize_response(response))
+
+        # If close command, shut down the daemon
+        if command.get("action") == "close":
+            self._running = False
+
+    def _idle_watchdog(self) -> None:
+        while self._running:
+            time.sleep(10)
+            if time.time() - self._last_activity > self.timeout:
+                print(f"[camoufox-cli] Idle timeout ({self.timeout}s), shutting down", file=sys.stderr)
+                self._running = False
+                # Nudge the accept() loop
+                try:
+                    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                    s.connect(self.socket_path)
+                    s.close()
+                except Exception:
+                    pass
+                break
+
+    def _handle_signal(self, signum, frame):
+        self._running = False
+
+    def _shutdown(self) -> None:
+        self.manager.close()
+        if self._server_socket:
+            try:
+                self._server_socket.close()
+            except Exception:
+                pass
+        self._cleanup_files()
+
+    def _cleanup_stale(self) -> None:
+        """Remove stale socket file if no daemon is running."""
+        if os.path.exists(self.socket_path):
+            # Check if another daemon is using it
+            if os.path.exists(self.pid_path):
+                try:
+                    with open(self.pid_path) as f:
+                        pid = int(f.read().strip())
+                    os.kill(pid, 0)
+                    # Process exists — abort
+                    print(f"[camoufox-cli] Daemon already running (pid {pid})", file=sys.stderr)
+                    sys.exit(1)
+                except (ProcessLookupError, ValueError):
+                    pass  # stale pid, clean up
+            os.unlink(self.socket_path)
+
+    def _write_pid(self) -> None:
+        with open(self.pid_path, "w") as f:
+            f.write(str(os.getpid()))
+
+    def _cleanup_files(self) -> None:
+        for path in (self.socket_path, self.pid_path):
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass

camoufox_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: camoufox-cli
+Version: 0.1.0
+Summary: Anti-detect browser CLI for AI agents, powered by Camoufox
+Project-URL: Homepage, https://github.com/Bin-Huang/camoufox-cli
+Project-URL: Repository, https://github.com/Bin-Huang/camoufox-cli
+Project-URL: Issues, https://github.com/Bin-Huang/camoufox-cli/issues
+Author: Bin Huang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,anti-detect,automation,browser,camoufox,headless
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: camoufox[geoip]
+Requires-Dist: playwright
+Description-Content-Type: text/markdown
+
+# camoufox-cli
+
+Anti-detect browser CLI for AI agents, powered by [Camoufox](https://github.com/daijro/camoufox).
+
+Camoufox has C++-level fingerprint spoofing (`navigator.webdriver=false`, randomized canvas/WebGL/audio, real plugins) but only exposes a Python API. This CLI wraps it into a simple command interface optimized for AI agent tool calls — snapshot the accessibility tree, interact by ref, repeat.
+
+## Install
+
+```bash
+pipx install camoufox-cli
+```
+
+Or with pip:
+
+```bash
+pip install camoufox-cli
+```
+
+## Quick Start
+
+```bash
+camoufox-cli open https://example.com    # Launch browser & navigate
+camoufox-cli snapshot -i                  # Interactive elements only
+# - link "More information..." [ref=e1]
+camoufox-cli click @e1                    # Click by ref
+camoufox-cli close                        # Done
+```
+
+## Commands
+
+### Navigation
+
+```bash
+camoufox-cli open <url>                   # Navigate to URL (starts daemon if needed)
+camoufox-cli back                         # Go back
+camoufox-cli forward                      # Go forward
+camoufox-cli reload                       # Reload page
+camoufox-cli url                          # Print current URL
+camoufox-cli title                        # Print page title
+camoufox-cli close                        # Close browser and stop daemon
+```
+
+### Snapshot
+
+```bash
+camoufox-cli snapshot                     # Full accessibility tree
+camoufox-cli snapshot -i                  # Interactive elements only
+camoufox-cli snapshot -s "css-selector"   # Scoped to CSS selector
+```
+
+Output format:
+
+```
+- heading "Example Domain" [level=1] [ref=e1]
+- paragraph [ref=e2]
+  - link "More information..." [ref=e3]
+```
+
+### Interaction
+
+```bash
+camoufox-cli click @e1                    # Click element
+camoufox-cli fill @e3 "search query"      # Clear + type into input
+camoufox-cli type @e3 "append text"       # Type without clearing
+camoufox-cli select @e5 "option text"     # Select dropdown option
+camoufox-cli check @e6                    # Toggle checkbox
+camoufox-cli hover @e2                    # Hover over element
+camoufox-cli press Enter                  # Press keyboard key
+camoufox-cli press "Control+a"            # Key combination
+```
+
+### Data Extraction
+
+```bash
+camoufox-cli text @e1                     # Get text content of element
+camoufox-cli text body                    # Get all page text
+camoufox-cli eval "document.title"        # Execute JavaScript
+camoufox-cli screenshot                   # Screenshot (base64 to stdout)
+camoufox-cli screenshot page.png          # Screenshot to file
+camoufox-cli screenshot --full page.png   # Full page screenshot
+```
+
+### Scroll & Wait
+
+```bash
+camoufox-cli scroll down                  # Scroll down 500px
+camoufox-cli scroll up 1000               # Scroll up 1000px
+camoufox-cli wait 2000                    # Wait milliseconds
+camoufox-cli wait @e1                     # Wait for element to appear
+camoufox-cli wait --url "*/dashboard"     # Wait for URL pattern
+```
+
+### Tabs
+
+```bash
+camoufox-cli tabs                         # List open tabs
+camoufox-cli switch 2                     # Switch to tab by index
+camoufox-cli close-tab                    # Close current tab
+```
+
+### Sessions
+
+```bash
+camoufox-cli sessions                     # List active sessions
+camoufox-cli --session work open <url>    # Use named session
+camoufox-cli close --all                  # Close all sessions
+```
+
+### Cookies
+
+```bash
+camoufox-cli cookies                      # Dump cookies as JSON
+camoufox-cli cookies import file.json     # Import cookies
+camoufox-cli cookies export file.json     # Export cookies
+```
+
+## Flags
+
+```
+--session <name>       Named session (default: "default")
+--headed               Show browser window (default: headless)
+--timeout <seconds>    Daemon idle timeout (default: 1800)
+--json                 Output as JSON
+--persistent <path>    Use persistent browser profile directory
+```
+
+## Architecture
+
+```
+CLI (camoufox-cli)  ──Unix socket──▶  Daemon (Python)  ──Playwright──▶  Camoufox (Firefox)
+```
+
+The CLI sends JSON commands to a long-running daemon process via Unix socket. The daemon manages the Camoufox browser instance and maintains the ref registry between commands. The daemon auto-starts on the first command and auto-stops after 30 minutes of inactivity.
+
+## License
+
+MIT

camoufox_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+camoufox_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+camoufox_cli/__main__.py,sha256=LW3Uey5g-nZ09cxETsLRs13KMxxWmTmhzEu0BInHeZA,1039
+camoufox_cli/browser.py,sha256=Urol-couWtcg4BxtlsPuqg-fnYByPRkvW1uEAtcMLoM,3289
+camoufox_cli/cli.py,sha256=Qu5BDTDTRsHDCEIC7qkU7ipMw0kfz1TkiTFIqkwS4ro,13777
+camoufox_cli/commands.py,sha256=UxdAbGDu0KOYZIdCc511-3_Otl4PykSHhHH66b1eLpo,11556
+camoufox_cli/protocol.py,sha256=vRpQPLxS4s5chA57bqdM9MgrP-wTlRGmiZm2V-QMtuI,658
+camoufox_cli/refs.py,sha256=2qldrUQe3LWXvEAGvF40VjomTWui8EzfUg_GTaGeR_M,2509
+camoufox_cli/server.py,sha256=p4rL-ha83RnRf8CnLJ7kjEB32ocMAxInSEgJ8G6kWak,4888
+camoufox_cli-0.1.0.dist-info/METADATA,sha256=dLwSD9MgcddbClVMldRDsZhEN22r9L04h9R-PmKAAgo,5171
+camoufox_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+camoufox_cli-0.1.0.dist-info/entry_points.txt,sha256=xB8yicErztODnNm6aPmBX00JC46jh4HvwtppdoG0op0,55
+camoufox_cli-0.1.0.dist-info/licenses/LICENSE,sha256=oW4W62E_nL4Ybo4equL-rDJ-7R6zX-e4shGYeIWj86I,1066
+camoufox_cli-0.1.0.dist-info/RECORD,,

camoufox_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

camoufox_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+camoufox-cli = camoufox_cli.cli:main

camoufox_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bin Huang
+
+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.