feat: add browser automation commands (v0.6.0)

Navigation: open-wait (open + block until loaded)
DOM: key, hover, check/uncheck, clear, focus, submit, poll, scroll, select, eval, wait-for
Tabs: pin/unpin, screenshot, watch-url (block until URL matches regex)
New command groups: page info, storage get/set, cookies list/get/set
Extension: add cookies permission

browser_cli/commands/cookies.py

@@ -0,0 +1,86 @@
+import click
+from browser_cli.client import send_command, BrowserNotConnected
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def _handle(command, args=None):
+    try:
+        return send_command(command, args or {})
+    except BrowserNotConnected as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise SystemExit(1)
+    except RuntimeError as e:
+        console.print(f"[red]Browser error:[/red] {e}")
+        raise SystemExit(1)
+
+
+@click.group("cookies")
+def cookies_group():
+    """Manage browser cookies."""
+
+
+@cookies_group.command("list")
+@click.option("--url", default=None, help="Filter by URL")
+@click.option("--domain", default=None, help="Filter by domain")
+@click.option("--name", default=None, help="Filter by cookie name")
+def cookies_list(url, domain, name):
+    """List cookies, optionally filtered by URL, domain, or name."""
+    cookies = _handle("cookies.list", {"url": url, "domain": domain, "name": name}) or []
+    if not cookies:
+        console.print("[yellow]No cookies found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Name")
+    table.add_column("Value")
+    table.add_column("Domain")
+    table.add_column("Path")
+    table.add_column("Secure", width=7)
+    table.add_column("HttpOnly", width=9)
+    for c in cookies:
+        table.add_row(
+            c.get("name", ""),
+            (c.get("value") or "")[:60],
+            c.get("domain", ""),
+            c.get("path", ""),
+            "[green]✓[/green]" if c.get("secure") else "",
+            "[green]✓[/green]" if c.get("httpOnly") else "",
+        )
+    console.print(table)
+
+
+@cookies_group.command("get")
+@click.argument("url")
+@click.argument("name")
+def cookies_get(url, name):
+    """Get the value of a single cookie by URL and NAME."""
+    cookie = _handle("cookies.get", {"url": url, "name": name})
+    if cookie is None:
+        console.print(f"[yellow]Cookie '{name}' not found for {url}[/yellow]")
+        raise SystemExit(1)
+    console.print(cookie.get("value", ""))
+
+
+@cookies_group.command("set")
+@click.argument("url")
+@click.argument("name")
+@click.argument("value")
+@click.option("--domain", default=None)
+@click.option("--path", default=None)
+@click.option("--secure", is_flag=True)
+@click.option("--http-only", "http_only", is_flag=True)
+@click.option("--expires", "expiration_date", type=float, default=None, help="Unix timestamp")
+@click.option("--same-site", type=click.Choice(["no_restriction", "lax", "strict"]), default=None)
+def cookies_set(url, name, value, domain, path, secure, http_only, expiration_date, same_site):
+    """Set a cookie on URL."""
+    _handle("cookies.set", {
+        "url": url, "name": name, "value": value,
+        "domain": domain, "path": path,
+        "secure": secure or None,
+        "httpOnly": http_only or None,
+        "expirationDate": expiration_date,
+        "sameSite": same_site,
+    })
+    console.print(f"[green]Set cookie:[/green] {name}={value!r} on {url}")

browser_cli/commands/dom.py

@@ -87,3 +87,133 @@ def dom_exists(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)")
+def dom_scroll(selector, x, y):
+    """Scroll to a CSS SELECTOR or to an X/Y coordinate."""
+    _handle("dom.scroll", {"selector": 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")
+def dom_select(selector, value):
+    """Set the VALUE of a <select> dropdown matching CSS SELECTOR."""
+    _handle("dom.select", {"selector": selector, "value": value})
+    console.print(f"[green]Selected '{value}' in:[/green] {selector}")
+
+
+@dom_group.command("eval")
+@click.argument("code")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+def dom_eval(code, tab_id):
+    """Evaluate JavaScript CODE in the page and print the result."""
+    result = _handle("dom.eval", {"code": code, "tabId": 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")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+def dom_wait_for(selector, timeout, visible, hidden, tab_id):
+    """Wait until CSS SELECTOR appears (or disappears) in the DOM."""
+    _handle("dom.wait_for", {
+        "selector": selector,
+        "timeout": int(timeout * 1000),
+        "visible": visible,
+        "hidden": hidden,
+        "tabId": 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)")
+def dom_key(key, selector):
+    """Dispatch a keyboard KEY event (e.g. Enter, Tab, Escape, ArrowDown)."""
+    _handle("dom.key", {"key": key, "selector": selector})
+    target = selector or "active element"
+    console.print(f"[green]Key '{key}' sent to:[/green] {target}")
+
+
+@dom_group.command("hover")
+@click.argument("selector")
+def dom_hover(selector):
+    """Dispatch mouseover/mouseenter on the element matching CSS SELECTOR."""
+    _handle("dom.hover", {"selector": selector})
+    console.print(f"[green]Hovered:[/green] {selector}")
+
+
+@dom_group.command("check")
+@click.argument("selector")
+def dom_check(selector):
+    """Check a checkbox matching CSS SELECTOR."""
+    _handle("dom.check", {"selector": selector})
+    console.print(f"[green]Checked:[/green] {selector}")
+
+
+@dom_group.command("uncheck")
+@click.argument("selector")
+def dom_uncheck(selector):
+    """Uncheck a checkbox matching CSS SELECTOR."""
+    _handle("dom.uncheck", {"selector": selector})
+    console.print(f"[green]Unchecked:[/green] {selector}")
+
+
+@dom_group.command("clear")
+@click.argument("selector")
+def dom_clear(selector):
+    """Clear the value of an input matching CSS SELECTOR."""
+    _handle("dom.clear", {"selector": selector})
+    console.print(f"[green]Cleared:[/green] {selector}")
+
+
+@dom_group.command("focus")
+@click.argument("selector")
+def dom_focus(selector):
+    """Focus the element matching CSS SELECTOR."""
+    _handle("dom.focus", {"selector": selector})
+    console.print(f"[green]Focused:[/green] {selector}")
+
+
+@dom_group.command("submit")
+@click.argument("selector")
+def dom_submit(selector):
+    """Submit the form that contains the element matching CSS SELECTOR."""
+    _handle("dom.submit", {"selector": 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")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+def dom_poll(selector, pattern, attr, timeout, interval, tab_id):
+    """Poll SELECTOR until its text/value matches regex PATTERN."""
+    result = _handle("dom.poll", {
+        "selector": selector,
+        "pattern": pattern,
+        "attr": attr,
+        "timeout": int(timeout * 1000),
+        "interval": int(interval * 1000),
+        "tabId": tab_id,
+    })
+    value = result.get("value", "") if isinstance(result, dict) else ""
+    console.print(f"[green]Matched:[/green] {selector!r} = {value!r}")

browser_cli/commands/navigate.py

@@ -78,3 +78,29 @@ def cmd_focus(pattern):
         console.print(f"[green]Focused:[/green] {result.get('url', result)}")
     else:
         console.print(f"[yellow]No tab found matching:[/yellow] {pattern}")
+
+
+@nav_group.command("open-wait")
+@click.argument("url")
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait for load")
+@click.option("--bg", is_flag=True, help="Open in background (no focus)")
+@click.option("--window", "window_name", default=None, help="Open in named window")
+@click.option("--group", "group_name", default=None, help="Open in tab group")
+def cmd_open_wait(url, timeout, bg, window_name, group_name):
+    """Open URL in a new tab and wait until fully loaded."""
+    result = _handle("navigate.open_wait", {
+        "url": url, "timeout": int(timeout * 1000),
+        "background": bg, "window": window_name, "group": group_name,
+    })
+    title = result.get("title", "") if isinstance(result, dict) else ""
+    console.print(f"[green]Loaded:[/green] {url}" + (f" — {title}" if title else ""))
+
+
+@nav_group.command("wait")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait")
+@click.option("--ready-state", type=click.Choice(["complete", "interactive"]), default="complete", show_default=True, help="Target ready state")
+def cmd_wait(tab_id, timeout, ready_state):
+    """Wait until tab finishes loading."""
+    result = _handle("navigate.wait", {"tabId": tab_id, "timeout": int(timeout * 1000), "readyState": ready_state})
+    console.print(f"[green]Ready:[/green] {result.get('url', '')} — {result.get('title', '')}")

browser_cli/commands/page.py

@@ -0,0 +1,38 @@
+import click
+from browser_cli.client import send_command, BrowserNotConnected
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def _handle(command, args=None):
+    try:
+        return send_command(command, args or {})
+    except BrowserNotConnected as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise SystemExit(1)
+    except RuntimeError as e:
+        console.print(f"[red]Browser error:[/red] {e}")
+        raise SystemExit(1)
+
+
+@click.group("page")
+def page_group():
+    """Inspect current page metadata."""
+
+
+@page_group.command("info")
+def page_info():
+    """Show title, URL, readyState, language, and meta tags of the active tab."""
+    info = _handle("page.info") or {}
+    table = Table(show_header=False)
+    table.add_column("Field", style="bold cyan", no_wrap=True)
+    table.add_column("Value")
+    table.add_row("Title",      info.get("title") or "")
+    table.add_row("URL",        info.get("url") or "")
+    table.add_row("Ready",      info.get("readyState") or "")
+    table.add_row("Lang",       info.get("lang") or "")
+    for key, val in (info.get("meta") or {}).items():
+        table.add_row(f"meta:{key}", val)
+    console.print(table)

browser_cli/commands/storage.py

@@ -0,0 +1,48 @@
+import json
+import click
+from browser_cli.client import send_command, BrowserNotConnected
+from rich.console import Console
+
+console = Console()
+
+
+def _handle(command, args=None):
+    try:
+        return send_command(command, args or {})
+    except BrowserNotConnected as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise SystemExit(1)
+    except RuntimeError as e:
+        console.print(f"[red]Browser error:[/red] {e}")
+        raise SystemExit(1)
+
+
+@click.group("storage")
+def storage_group():
+    """Read and write the page's localStorage / sessionStorage."""
+
+
+@storage_group.command("get")
+@click.argument("key", required=False)
+@click.option("--type", "store_type", type=click.Choice(["local", "session"]), default="local", show_default=True)
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+def storage_get(key, store_type, tab_id):
+    """Get a localStorage KEY (or dump all keys if omitted)."""
+    result = _handle("storage.get", {"key": key, "type": store_type, "tabId": tab_id})
+    if result is None:
+        console.print("[dim]null[/dim]")
+    elif isinstance(result, dict):
+        console.print(json.dumps(result, indent=2))
+    else:
+        console.print(str(result))
+
+
+@storage_group.command("set")
+@click.argument("key")
+@click.argument("value")
+@click.option("--type", "store_type", type=click.Choice(["local", "session"]), default="local", show_default=True)
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+def storage_set(key, value, store_type, tab_id):
+    """Set localStorage KEY to VALUE."""
+    _handle("storage.set", {"key": key, "value": value, "type": store_type, "tabId": tab_id})
+    console.print(f"[green]Set[/green] {store_type}[{key!r}] = {value!r}")

browser_cli/commands/tabs.py

@@ -1,3 +1,4 @@
+import base64
 import click
 from browser_cli.client import BrowserNotConnected, active_browser_targets, send_command
 from rich.console import Console
@@ -236,3 +237,54 @@ def tabs_unmute(tab_id):
     result = _handle("tabs.unmute", {"tabId": tab_id})
     target = result.get("tabId", tab_id) if isinstance(result, dict) else tab_id
     console.print(f"[green]Unmuted tab {target}[/green]")
+
+
+@tabs_group.command("pin")
+@click.argument("tab_id", type=int, required=False)
+def tabs_pin(tab_id):
+    """Pin the active tab or a specific tab."""
+    result = _handle("tabs.pin", {"tabId": tab_id})
+    target = result.get("tabId", tab_id) if isinstance(result, dict) else tab_id
+    console.print(f"[green]Pinned tab {target}[/green]")
+
+
+@tabs_group.command("unpin")
+@click.argument("tab_id", type=int, required=False)
+def tabs_unpin(tab_id):
+    """Unpin the active tab or a specific tab."""
+    result = _handle("tabs.unpin", {"tabId": tab_id})
+    target = result.get("tabId", tab_id) if isinstance(result, dict) else tab_id
+    console.print(f"[green]Unpinned tab {target}[/green]")
+
+
+@tabs_group.command("watch-url")
+@click.argument("pattern")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait")
+def tabs_watch_url(pattern, tab_id, timeout):
+    """Wait until the active (or specified) tab URL matches regex PATTERN."""
+    result = _handle("tabs.watch_url", {"pattern": pattern, "tabId": tab_id, "timeout": int(timeout * 1000)})
+    url = result.get("url", "") if isinstance(result, dict) else ""
+    console.print(f"[green]URL matched:[/green] {url}")
+
+
+@tabs_group.command("screenshot")
+@click.argument("output", required=False, metavar="FILE")
+@click.option("--tab", "tab_id", type=int, default=None, help="Tab ID (default: active tab)")
+@click.option("--format", "fmt", type=click.Choice(["png", "jpeg"]), default="png", show_default=True)
+@click.option("--quality", type=int, default=None, help="JPEG quality 0-100")
+def tabs_screenshot(output, tab_id, fmt, quality):
+    """Capture a screenshot of the active (or specified) tab.
+
+    Saves to FILE if given, otherwise prints the base64 data URL.
+    """
+    result = _handle("tabs.screenshot", {"tabId": tab_id, "format": fmt, "quality": quality})
+    data_url = result.get("dataUrl", "") if isinstance(result, dict) else ""
+    if output:
+        header = f"data:image/{fmt};base64,"
+        raw = base64.b64decode(data_url[len(header):])
+        with open(output, "wb") as f:
+            f.write(raw)
+        console.print(f"[green]Screenshot saved:[/green] {output}")
+    else:
+        console.print(data_url)