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

browser_cli/commands/dom.py

@@ -0,0 +1,191 @@
+import click
+from browser_cli.commands import client_from_ctx, handle_errors, tab_option
+from rich.console import Console
+from rich.table import Table
+import json
+
+console = Console()
+
+@click.group("dom")
+def dom_group():
+    """Query and interact with page DOM elements."""
+
+@dom_group.command("query")
+@click.argument("selector")
+@handle_errors
+def dom_query(selector):
+    """Return elements matching CSS SELECTOR (like mini DevTools)."""
+    elements = client_from_ctx().dom.query(selector)
+    if not elements:
+        console.print("[yellow]No elements found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Tag", width=12)
+    table.add_column("Text", width=40)
+    table.add_column("Attributes")
+    for el in elements:
+        attrs = ", ".join(f"{k}={v!r}" for k, v in (el.get("attrs") or {}).items())
+        table.add_row(el.get("tag", ""), (el.get("text") or "")[:60], attrs[:80])
+    console.print(table)
+
+@dom_group.command("click")
+@click.argument("selector")
+@handle_errors
+def dom_click(selector):
+    """Click the first element matching CSS SELECTOR."""
+    client_from_ctx().dom.click(selector)
+    console.print(f"[green]Clicked:[/green] {selector}")
+
+@dom_group.command("type")
+@click.argument("selector")
+@click.argument("text")
+@handle_errors
+def dom_type(selector, text):
+    """Type TEXT into the element matching CSS SELECTOR."""
+    client_from_ctx().dom.type(selector, text)
+    console.print(f"[green]Typed into:[/green] {selector}")
+
+@dom_group.command("attr")
+@click.argument("selector")
+@click.argument("attr_name")
+@handle_errors
+def dom_attr(selector, attr_name):
+    """Get attribute ATTR_NAME from elements matching CSS SELECTOR."""
+    for v in client_from_ctx().dom.attr(selector, attr_name):
+        console.print(v)
+
+@dom_group.command("text")
+@click.argument("selector")
+@handle_errors
+def dom_text(selector):
+    """Get text content of elements matching CSS SELECTOR."""
+    for v in client_from_ctx().dom.text(selector):
+        console.print(v)
+
+@dom_group.command("exists")
+@click.argument("selector")
+@handle_errors
+def dom_exists(selector):
+    """Check if an element matching CSS SELECTOR exists on the page."""
+    if client_from_ctx().dom.exists(selector):
+        console.print(f"[green]exists[/green]: {selector}")
+    else:
+        console.print(f"[red]not found[/red]: {selector}")
+        raise SystemExit(1)
+
+@dom_group.command("scroll")
+@click.argument("selector", required=False)
+@click.option("--x", type=int, default=None, help="Horizontal scroll position (px)")
+@click.option("--y", type=int, default=None, help="Vertical scroll position (px)")
+@handle_errors
+def dom_scroll(selector, x, y):
+    """Scroll to a CSS SELECTOR or to an X/Y coordinate."""
+    client_from_ctx().dom.scroll(selector, x=x, y=y)
+    target = selector or f"({x or 0}, {y or 0})"
+    console.print(f"[green]Scrolled to:[/green] {target}")
+
+@dom_group.command("select")
+@click.argument("selector")
+@click.argument("value")
+@handle_errors
+def dom_select(selector, value):
+    """Set the VALUE of a <select> dropdown matching CSS SELECTOR."""
+    client_from_ctx().dom.select(selector, value)
+    console.print(f"[green]Selected '{value}' in:[/green] {selector}")
+
+@dom_group.command("eval")
+@click.argument("code")
+@tab_option
+@handle_errors
+def dom_eval(code, tab_id):
+    """Evaluate JavaScript CODE in the page and print the result."""
+    result = client_from_ctx().dom.eval(code, tab_id)
+    if result is None:
+        console.print("[dim]null[/dim]")
+    else:
+        console.print(json.dumps(result, indent=2) if isinstance(result, (dict, list)) else str(result))
+
+@dom_group.command("wait-for")
+@click.argument("selector")
+@click.option("--timeout", type=float, default=10.0, show_default=True, help="Max seconds to wait")
+@click.option("--visible", is_flag=True, help="Wait until element is visible (non-zero size)")
+@click.option("--hidden", is_flag=True, help="Wait until element is absent or hidden")
+@tab_option
+@handle_errors
+def dom_wait_for(selector, timeout, visible, hidden, tab_id):
+    """Wait until CSS SELECTOR appears (or disappears) in the DOM."""
+    client_from_ctx().dom.wait_for(selector, timeout=timeout, visible=visible, hidden=hidden, tab_id=tab_id)
+    state = "hidden" if hidden else ("visible" if visible else "present")
+    console.print(f"[green]Ready ({state}):[/green] {selector}")
+
+@dom_group.command("key")
+@click.argument("key")
+@click.option("--selector", default=None, help="CSS selector to target (default: focused element)")
+@handle_errors
+def dom_key(key, selector):
+    """Dispatch a keyboard KEY event (e.g. Enter, Tab, Escape, ArrowDown)."""
+    client_from_ctx().dom.key(key, selector)
+    target = selector or "active element"
+    console.print(f"[green]Key '{key}' sent to:[/green] {target}")
+
+@dom_group.command("hover")
+@click.argument("selector")
+@handle_errors
+def dom_hover(selector):
+    """Dispatch mouseover/mouseenter on the element matching CSS SELECTOR."""
+    client_from_ctx().dom.hover(selector)
+    console.print(f"[green]Hovered:[/green] {selector}")
+
+@dom_group.command("check")
+@click.argument("selector")
+@handle_errors
+def dom_check(selector):
+    """Check a checkbox matching CSS SELECTOR."""
+    client_from_ctx().dom.check(selector)
+    console.print(f"[green]Checked:[/green] {selector}")
+
+@dom_group.command("uncheck")
+@click.argument("selector")
+@handle_errors
+def dom_uncheck(selector):
+    """Uncheck a checkbox matching CSS SELECTOR."""
+    client_from_ctx().dom.uncheck(selector)
+    console.print(f"[green]Unchecked:[/green] {selector}")
+
+@dom_group.command("clear")
+@click.argument("selector")
+@handle_errors
+def dom_clear(selector):
+    """Clear the value of an input matching CSS SELECTOR."""
+    client_from_ctx().dom.clear(selector)
+    console.print(f"[green]Cleared:[/green] {selector}")
+
+@dom_group.command("focus")
+@click.argument("selector")
+@handle_errors
+def dom_focus(selector):
+    """Focus the element matching CSS SELECTOR."""
+    client_from_ctx().dom.focus(selector)
+    console.print(f"[green]Focused:[/green] {selector}")
+
+@dom_group.command("submit")
+@click.argument("selector")
+@handle_errors
+def dom_submit(selector):
+    """Submit the form that contains the element matching CSS SELECTOR."""
+    client_from_ctx().dom.submit(selector)
+    console.print(f"[green]Submitted form for:[/green] {selector}")
+
+@dom_group.command("poll")
+@click.argument("selector")
+@click.argument("pattern")
+@click.option("--attr", default=None, help="Attribute or property to read (default: textContent/value)")
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait")
+@click.option("--interval", type=float, default=0.5, show_default=True, help="Poll interval in seconds")
+@tab_option
+@handle_errors
+def dom_poll(selector, pattern, attr, timeout, interval, tab_id):
+    """Poll SELECTOR until its text/value matches regex PATTERN."""
+    result = client_from_ctx().dom.poll(selector, pattern, attr=attr, timeout=timeout, interval=interval, tab_id=tab_id)
+    value = result.get("value", "") if isinstance(result, dict) else ""
+    console.print(f"[green]Matched:[/green] {selector!r} = {value!r}")

browser_cli/commands/events.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, is_dataclass
+
+import click
+from rich.console import Console
+
+from browser_cli.commands import client_from_ctx, handle_errors
+
+console = Console()
+
+def _snapshot(client):
+    tabs = client.tabs.list()
+    return {str(t.id): asdict(t) if is_dataclass(t) else dict(t) for t in tabs}
+
+def _emit(event, json_output: bool):
+    if json_output:
+        click.echo(json.dumps(event, default=str), flush=True)
+    else:
+        kind = event.get("type")
+        tab = event.get("tab") or {}
+        console.print(f"[cyan]{kind}[/cyan] {tab.get('id', '')} {tab.get('title') or ''} [dim]{tab.get('url') or ''}[/dim]")
+
+@click.command("events")
+@click.option("--interval", type=float, default=1.0, show_default=True, help="Polling interval in seconds")
+@click.option("--once", is_flag=True, help="Emit initial snapshot and exit")
+@click.option("--json", "json_output", is_flag=True, default=True, help="Emit JSON Lines (default)")
+@click.option("--pretty", is_flag=True, help="Render human-readable events instead of JSON")
+@handle_errors
+def cmd_events(interval: float, once: bool, json_output: bool, pretty: bool):
+    """Stream tab events as JSON Lines using a lightweight polling watcher."""
+    json_output = json_output and not pretty
+    client = client_from_ctx()
+    previous = _snapshot(client)
+    for tab in previous.values():
+        _emit({"type": "tabs.snapshot", "tab": tab}, json_output)
+    if once:
+        return
+    while True:
+        time.sleep(interval)
+        current = _snapshot(client)
+        for tab_id, tab in current.items():
+            if tab_id not in previous:
+                _emit({"type": "tabs.created", "tab": tab}, json_output)
+            elif tab != previous[tab_id]:
+                _emit({"type": "tabs.updated", "tab": tab, "previous": previous[tab_id]}, json_output)
+        for tab_id, tab in previous.items():
+            if tab_id not in current:
+                _emit({"type": "tabs.closed", "tab": tab}, json_output)
+        previous = current

browser_cli/commands/extension.py

@@ -0,0 +1,42 @@
+import click
+from rich.console import Console
+from browser_cli.commands import client_from_ctx, handle_errors
+
+console = Console()
+
+@click.group("extension")
+def extension_group():
+    """Manage the browser-cli browser extension."""
+
+@extension_group.command("info")
+@handle_errors
+def extension_info():
+    """Show extension version and advertised capabilities."""
+    info = client_from_ctx().extension.info()
+    for key in ("name", "version", "id", "platform"):
+        if key in info:
+            console.print(f"[bold]{key}:[/bold] {info[key]}")
+    caps = info.get("capabilities") or []
+    if caps:
+        console.print("[bold]capabilities:[/bold]")
+        for cap in caps:
+            console.print(f"  - {cap}")
+
+@extension_group.command("capabilities")
+@handle_errors
+def extension_capabilities():
+    """Print extension feature capability strings."""
+    for cap in client_from_ctx().extension.capabilities():
+        console.print(cap)
+
+@extension_group.command("reload")
+@handle_errors
+def extension_reload():
+    """Reload the browser-cli extension service worker.
+
+    Useful after updating background.js without restarting the browser.
+    The command returns immediately; the extension restarts ~200 ms later.
+    Re-connects automatically via the keepalive alarm within ~25 seconds.
+    """
+    client_from_ctx().extension.reload()
+    console.print("[green]Extension reloading…[/green] reconnects automatically")

browser_cli/commands/extract.py

@@ -0,0 +1,70 @@
+import json
+
+import click
+from browser_cli.commands import client_from_ctx, handle_errors
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+@click.group("extract")
+def extract_group():
+    """Extract content from the active tab."""
+
+@extract_group.command("links")
+@handle_errors
+def extract_links():
+    """Extract all links from the active tab."""
+    links = client_from_ctx().extract.links()
+    if not links:
+        console.print("[yellow]No links found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Text", width=40)
+    table.add_column("URL")
+    for lnk in links:
+        table.add_row((lnk.get("text") or "")[:60], lnk.get("href") or "")
+    console.print(table)
+
+@extract_group.command("images")
+@handle_errors
+def extract_images():
+    """Extract all images from the active tab."""
+    images = client_from_ctx().extract.images()
+    if not images:
+        console.print("[yellow]No images found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Alt", width=30)
+    table.add_column("Src")
+    for img in images:
+        table.add_row((img.get("alt") or "")[:40], img.get("src") or "")
+    console.print(table)
+
+@extract_group.command("text")
+@handle_errors
+def extract_text():
+    """Extract all visible text from the active tab."""
+    console.print(client_from_ctx().extract.text())
+
+@extract_group.command("json")
+@click.argument("selector")
+@handle_errors
+def extract_json(selector):
+    """Parse and pretty-print JSON content inside SELECTOR."""
+    data = client_from_ctx().extract.json(selector)
+    console.print_json(json.dumps(data))
+
+@extract_group.command("html")
+@handle_errors
+def extract_html():
+    """Print the full HTML of the active tab to stdout."""
+    click.echo(client_from_ctx().extract.html())
+
+@extract_group.command("markdown")
+@click.option("--selector", help="Extract only the DOM subtree matching this CSS selector.")
+@handle_errors
+def extract_markdown(selector):
+    """Extract the page's main content as Markdown."""
+    markdown = client_from_ctx().extract.markdown(selector)
+    click.echo(markdown or "", nl=not (markdown or "").endswith("\n"))

browser_cli/commands/groups.py

@@ -0,0 +1,108 @@
+import click
+from browser_cli.commands import client_from_ctx, gentle_mode_option, handle_errors, print_counts
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+def _print_groups(groups, *, show_browser: bool = False) -> None:
+    if not groups:
+        console.print("[yellow]No groups found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    if show_browser:
+        table.add_column("Browser")
+    table.add_column("ID", style="dim", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Color", width=10)
+    table.add_column("Collapsed", width=10)
+    table.add_column("Tabs", width=6)
+    for g in groups:
+        row = [
+            (g.browser or "") if show_browser else None,
+            str(g.id),
+            g.title or "",
+            g.color or "",
+            "yes" if g.collapsed else "no",
+            str(g.tab_count),
+        ]
+        table.add_row(*[value for value in row if value is not None])
+    console.print(table)
+
+@click.group("groups")
+def group_group():
+    """Manage tab groups."""
+
+@group_group.command("list")
+@handle_errors
+def group_list():
+    """List all tab groups."""
+    groups = client_from_ctx().groups.list()
+    _print_groups(groups, show_browser=any(g.browser for g in groups))
+
+@group_group.command("tabs")
+@click.argument("group_id", type=int)
+@handle_errors
+def group_tabs(group_id):
+    """List tabs inside a group."""
+    from browser_cli.commands.tabs import _print_tabs
+    _print_tabs(client_from_ctx().groups.tabs(group_id))
+
+@group_group.command("count")
+@handle_errors
+def group_count():
+    """Count all tab groups."""
+    print_counts(client_from_ctx().groups.count(), "group")
+
+@group_group.command("query")
+@click.argument("search")
+@handle_errors
+def group_query(search):
+    """Search groups by name."""
+    _print_groups(client_from_ctx().groups.query(search))
+
+@group_group.command("close")
+@click.argument("group_id", type=int)
+@gentle_mode_option("Throttle mode for large group operations.")
+@handle_errors
+def group_close(group_id, gentle_mode):
+    """Close (ungroup and optionally close) a tab group."""
+    client_from_ctx().groups.close(group_id, gentle_mode=gentle_mode)
+    console.print(f"[green]Group {group_id} closed[/green]")
+
+@group_group.command("create")
+@click.argument("name")
+@handle_errors
+def group_create(name):
+    """Create a new tab group with NAME."""
+    group = client_from_ctx().groups.create(name)
+    console.print(f"[green]Created group '{name}'[/green] (id: {group.id})")
+
+@group_group.command("add-tab")
+@click.argument("group")
+@click.argument("url", required=False)
+@handle_errors
+def group_add_tab(group, url):
+    """Open a new tab (optionally at URL) inside GROUP (name or ID)."""
+    tab_id = client_from_ctx().groups.add_tab(group, url)
+    label = url or "new tab"
+    console.print(f"[green]Opened {label}[/green] in group '{group}' (tab id: {tab_id})")
+
+@group_group.command("move")
+@click.argument("group")
+@click.option("-f", "--forward", "forward", is_flag=True, help="Move group one position to the right")
+@click.option("-b", "--backward", "backward", is_flag=True, help="Move group one position to the left")
+@click.option("-r", "--right", "forward", is_flag=True, help="Move group one position to the right")
+@click.option("-l", "--left", "backward", is_flag=True, help="Move group one position to the left")
+@handle_errors
+def group_move(group, forward, backward):
+    """Move a tab group forward/backward or right/left (name or ID)."""
+    if not forward and not backward:
+        console.print("[red]Specify --forward/--right or --backward/--left[/red]")
+        raise SystemExit(1)
+    result = client_from_ctx().groups.move(group, forward=forward, backward=backward)
+    if isinstance(result, dict) and not result.get("moved"):
+        console.print(f"[yellow]Group '{group}' is already at the {'end' if forward else 'start'}[/yellow]")
+    else:
+        direction = "forward" if forward else "backward"
+        console.print(f"[green]Group '{group}' moved {direction}[/green]")

browser_cli/commands/install.py

@@ -0,0 +1,121 @@
+"""Native Messaging host installation command."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from browser_cli.constants import (
+  ALLOWED_EXTENSION_IDS,
+  EXTENSION_ID,
+  NATIVE_HOST_DIRS,
+  NATIVE_HOST_NAME,
+  SUPPORTED_BROWSERS,
+  WEBSTORE_EXTENSION_ID,
+  WINDOWS_NATIVE_HOST_REGISTRY_KEYS,
+)
+from browser_cli.platform import install_base_dir, is_windows
+
+console = Console()
+
+def native_host_exe() -> Path:
+  base = install_base_dir()
+  if is_windows():
+    return base / "libexec" / "browser-cli-native-host.cmd"
+  return base / "libexec" / "browser-cli-native-host"
+
+def write_native_host_exe(path: Path) -> None:
+  path.parent.mkdir(parents=True, exist_ok=True)
+  if is_windows():
+    path.write_text(
+      f'@echo off\r\n"{sys.executable}" -c "from browser_cli.native.host import main; main()" %*\r\n',
+      encoding="utf-8",
+    )
+  else:
+    path.write_text(f'#!{sys.executable}\nfrom browser_cli.native.host import main\nmain()\n')
+    path.chmod(path.stat().st_mode | 0o111)
+
+def _windows_registry_views():
+  import winreg
+  return [0, getattr(winreg, "KEY_WOW64_32KEY", 0), getattr(winreg, "KEY_WOW64_64KEY", 0)]
+
+def _register_windows_native_host(browser: str, manifest_path: Path) -> list[str]:
+  import winreg
+
+  installed = []
+  for key_path in WINDOWS_NATIVE_HOST_REGISTRY_KEYS[browser]:
+    full_key = f"{key_path}\\{NATIVE_HOST_NAME}"
+    for view in _windows_registry_views():
+      try:
+        access = winreg.KEY_WRITE | view
+        key = winreg.CreateKeyEx(winreg.HKEY_CURRENT_USER, full_key, 0, access)
+        with key:
+          winreg.SetValueEx(key, "", 0, winreg.REG_SZ, str(manifest_path))
+        installed.append(f"HKCU\\{full_key}")
+      except OSError as e:
+        console.print(f"[yellow]Could not write registry key {full_key}: {e}[/yellow]")
+  return installed
+
+@click.command("install")
+@click.argument("browser", type=click.Choice(SUPPORTED_BROWSERS), default="chrome")
+def cmd_install(browser):
+  """Register the native messaging host and print extension load instructions."""
+  host_exe = native_host_exe()
+  write_native_host_exe(host_exe)
+
+  ext_url = {
+    "chrome": "chrome://extensions",
+    "chromium": "chrome://extensions",
+    "brave": "brave://extensions",
+    "edge": "edge://extensions",
+    "vivaldi": "vivaldi://extensions",
+  }[browser]
+  console.print("\n[bold]Step 1:[/bold] Load the extension in your browser")
+  console.print(f"  1. Open [cyan]{ext_url}[/cyan]")
+  console.print("  2. Enable [bold]Developer mode[/bold] (top-right toggle)")
+  console.print(f"  3. Click [bold]Load unpacked[/bold] → select: [cyan]{Path(__file__).parent.parent.parent / 'extension'}[/cyan]")
+  console.print(f"  4. Testing extension ID will be [cyan]{EXTENSION_ID}[/cyan] (fixed by built-in key)")
+  console.print(f"     Chrome Web Store extension ID is [cyan]{WEBSTORE_EXTENSION_ID}[/cyan]\n")
+
+  manifest = {
+    "name": NATIVE_HOST_NAME,
+    "description": "browser-cli native messaging host",
+    "path": str(host_exe),
+    "type": "stdio",
+    "allowed_origins": [f"chrome-extension://{extension_id}/" for extension_id in ALLOWED_EXTENSION_IDS],
+  }
+  installed = _install_manifest(browser, host_exe, manifest)
+  if not installed:
+    console.print("[red]Failed to install native host manifest[/red]")
+    sys.exit(1)
+
+  for p in installed:
+    label = "Registered native host" if is_windows() else "Wrote native host manifest"
+    console.print(f"[green]✓[/green] {label}: {p}")
+  console.print(f"[green]✓[/green] Installed native host: {host_exe}")
+  console.print(f"\n[bold]Step 2:[/bold] Restart {browser.capitalize()} completely (quit app, then reopen)")
+  console.print("\n[green bold]✓ Installation complete![/green bold]")
+  console.print("  After restarting the browser, try: [cyan]browser-cli tabs list[/cyan]")
+
+def _install_manifest(browser: str, host_exe: Path, manifest: dict) -> list:
+  if is_windows():
+    manifest_dir = host_exe.parent
+    manifest_dir.mkdir(parents=True, exist_ok=True)
+    manifest_path = manifest_dir / f"{NATIVE_HOST_NAME}.json"
+    manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return _register_windows_native_host(browser, manifest_path)
+
+  platform = "darwin" if sys.platform == "darwin" else "linux"
+  installed = []
+  for directory in NATIVE_HOST_DIRS[browser][platform]:
+    try:
+      directory.mkdir(parents=True, exist_ok=True)
+      manifest_path = directory / f"{NATIVE_HOST_NAME}.json"
+      manifest_path.write_text(json.dumps(manifest, indent=2))
+      installed.append(manifest_path)
+    except Exception as e:
+      console.print(f"[yellow]Could not write to {directory}: {e}[/yellow]")
+  return installed