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

browser_cli/commands/session.py

@@ -0,0 +1,163 @@
+import json
+from pathlib import Path
+import click
+from browser_cli.commands import client_from_ctx, gentle_mode_option, handle_errors
+from rich.console import Console
+
+console = Console()
+
+@click.group("session")
+def session_group():
+    """Save and restore browser sessions."""
+
+@session_group.command("save")
+@click.argument("name")
+@handle_errors
+def session_save(name):
+    """Save all current tabs as session NAME."""
+    result = client_from_ctx().session.save(name)
+    count = result.get("tabs", 0) if isinstance(result, dict) else 0
+    console.print(f"[green]Session '{name}' saved[/green] ({count} tabs)")
+
+@session_group.command("load")
+@click.argument("name")
+@gentle_mode_option("Throttle mode for large restores.")
+@click.option("--discard-background-tabs", is_flag=True, help="Discard restored background tabs after opening to reduce load.")
+@click.option("--lazy", is_flag=True, help="Create lightweight placeholder tabs after --eager-tabs; placeholders load when selected.")
+@click.option("--eager-tabs", type=int, default=10, show_default=True, help="Number of real tabs to open before lazy placeholders.")
+@click.option("--background", "background_job", is_flag=True, help="Start restore as a background job and return immediately.")
+@handle_errors
+def session_load(name, gentle_mode, discard_background_tabs, lazy, eager_tabs, background_job):
+    """Restore session NAME (opens all saved tabs)."""
+    b = client_from_ctx()
+    if background_job:
+        result = b.session.load_background(
+            name, gentle_mode=gentle_mode, discard_background_tabs=discard_background_tabs,
+            lazy=lazy, eager_tabs=eager_tabs,
+        )
+        if isinstance(result, dict) and result.get("jobId"):
+            console.print(f"[green]Session restore started[/green] job={result['jobId']}")
+            return
+    else:
+        result = b.session.load(
+            name, gentle_mode=gentle_mode, discard_background_tabs=discard_background_tabs,
+            lazy=lazy, eager_tabs=eager_tabs,
+        )
+    count = result.get("tabs", 0) if isinstance(result, dict) else 0
+    console.print(f"[green]Session '{name}' loaded[/green] ({count} tabs opened)")
+
+@session_group.command("export")
+@click.argument("name", required=False)
+@click.option("-o", "output", type=click.Path(dir_okay=False, path_type=Path), default=None, help="Write JSON to file instead of stdout")
+@handle_errors
+def session_export(name, output):
+    """Export one saved session, or all sessions as JSON."""
+    data = client_from_ctx().session.export(name)
+    text = json.dumps(data, indent=2, sort_keys=True)
+    if output:
+        output.write_text(text + "\n", encoding="utf-8")
+        console.print(f"[green]Exported session data to {output}[/green]")
+    else:
+        click.echo(text)
+
+@session_group.command("import")
+@click.argument("name")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--overwrite", is_flag=True, help="Replace an existing saved session")
+@handle_errors
+def session_import(name, file, overwrite):
+    """Import a saved session JSON file."""
+    payload = json.loads(file.read_text(encoding="utf-8"))
+    session = payload.get("session", payload) if isinstance(payload, dict) else payload
+    result = client_from_ctx().session.import_(name, session, overwrite=overwrite)
+    count = result.get("tabs", 0) if isinstance(result, dict) else 0
+    console.print(f"[green]Imported session '{name}'[/green] ({count} tabs)")
+
+@session_group.command("diff")
+@click.argument("name_a")
+@click.argument("name_b")
+@handle_errors
+def session_diff(name_a, name_b):
+    """Show tabs added/removed between two saved sessions."""
+    diff = client_from_ctx().session.diff(name_a, name_b)
+    if not diff:
+        console.print("[yellow]No diff data returned[/yellow]")
+        return
+
+    added = diff.get("added") or []
+    removed = diff.get("removed") or []
+
+    if added:
+        console.print(f"[green]Added in '{name_b}':[/green]")
+        for url in added:
+            console.print(f"  + {url}")
+
+    if removed:
+        console.print(f"[red]Removed in '{name_b}':[/red]")
+        for url in removed:
+            console.print(f"  - {url}")
+
+    if not added and not removed:
+        console.print("[green]Sessions are identical[/green]")
+
+@session_group.command("list")
+@handle_errors
+def session_list():
+    """List all saved sessions."""
+    from datetime import datetime
+    from rich.table import Table
+    sessions = client_from_ctx().session.list()
+    if not sessions:
+        console.print("[yellow]No saved sessions[/yellow]")
+        return
+    show_browser = any("browser" in s for s in sessions)
+    table = Table(show_header=True, header_style="bold cyan")
+    if show_browser:
+        table.add_column("Browser")
+    table.add_column("Name")
+    table.add_column("Tabs", width=6)
+    table.add_column("Saved at")
+    for s in sessions:
+        saved = datetime.fromtimestamp(s["savedAt"] / 1000).strftime("%Y-%m-%d %H:%M") if s.get("savedAt") else ""
+        row = [s.get("browser", "")] if show_browser else []
+        row.extend([s["name"], str(s["tabs"]), saved])
+        table.add_row(*row)
+    console.print(table)
+
+@session_group.command("remove")
+@click.argument("name")
+@handle_errors
+def session_remove(name):
+    """Delete a saved session."""
+    client_from_ctx().session.remove(name)
+    console.print(f"[green]Session '{name}' removed[/green]")
+
+@session_group.command("job-status")
+@click.argument("job_id")
+@handle_errors
+def session_job_status(job_id):
+    """Show status for a background session job."""
+    result = client_from_ctx().perf.job_status(job_id)
+    status = result.get("status", "unknown")
+    console.print(f"[bold]{job_id}[/bold]: {status}")
+    if result.get("error"):
+        console.print(f"[red]{result['error']}[/red]")
+    elif result.get("result"):
+        console.print(result["result"])
+
+@session_group.command("job-cancel")
+@click.argument("job_id")
+@handle_errors
+def session_job_cancel(job_id):
+    """Cancel a running background job."""
+    client_from_ctx().perf.job_cancel(job_id)
+    console.print(f"[green]Cancel requested for {job_id}[/green]")
+
+@session_group.command("auto-save")
+@click.argument("state", type=click.Choice(["on", "off"]))
+@handle_errors
+def session_auto_save(state):
+    """Enable or disable automatic session saving."""
+    enabled = state == "on"
+    client_from_ctx().session.auto_save(enabled)
+    console.print(f"[green]Auto-save {state}[/green]")

browser_cli/commands/storage.py

@@ -0,0 +1,36 @@
+import json
+import click
+from browser_cli.commands import client_from_ctx, handle_errors, tab_option
+from rich.console import Console
+
+console = Console()
+
+@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)
+@tab_option
+@handle_errors
+def storage_get(key, store_type, tab_id):
+    """Get a localStorage KEY (or dump all keys if omitted)."""
+    result = client_from_ctx().storage.get(key, type=store_type, tab_id=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)
+@tab_option
+@handle_errors
+def storage_set(key, value, store_type, tab_id):
+    """Set localStorage KEY to VALUE."""
+    client_from_ctx().storage.set(key, value, type=store_type, tab_id=tab_id)
+    console.print(f"[green]Set[/green] {store_type}[{key!r}] = {value!r}")

browser_cli/commands/tabs.py

@@ -0,0 +1,252 @@
+import base64
+import binascii
+import click
+from browser_cli.commands import client_from_ctx, gentle_mode_option, handle_errors, print_counts, tab_option
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+
+console = Console()
+
+def _print_tabs(tabs, *, show_browser: bool = False) -> None:
+    if not tabs:
+        console.print("[yellow]No tabs found[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    if show_browser:
+        table.add_column("Browser", no_wrap=True)
+    table.add_column("ID", style="dim", no_wrap=True)
+    table.add_column("Window", no_wrap=True)
+    table.add_column("Active", width=7)
+    table.add_column("Muted", width=7)
+    table.add_column("Title")
+    table.add_column("URL")
+    for t in tabs:
+        active = "[green]✓[/green]" if t.active else ""
+        muted = "[yellow]✓[/yellow]" if t.muted else ""
+        row = [
+            (t.browser or "") if show_browser else None,
+            str(t.id),
+            str(t.window_id),
+            active,
+            muted,
+            (t.title or "")[:60],
+            (t.url or "")[:80],
+        ]
+        table.add_row(*[value for value in row if value is not None])
+    console.print(table)
+
+@click.group("tabs")
+def tabs_group():
+    """Manage browser tabs."""
+
+@tabs_group.command("list")
+@handle_errors
+def tabs_list():
+    """List all open tabs across all windows."""
+    tabs = client_from_ctx().tabs.list()
+    _print_tabs(tabs, show_browser=any(t.browser for t in tabs))
+
+@tabs_group.command("tree")
+@handle_errors
+def tabs_tree():
+    """Show tabs grouped as a window/group tree."""
+    tabs = sorted(client_from_ctx().tabs.list(), key=lambda t: ((t.browser or ""), t.window_id, t.group_id if t.group_id is not None else -1, t.index))
+    root = Tree("[bold]Tabs[/bold]")
+    browsers = {}
+    windows = {}
+    groups = {}
+    show_browser = any(t.browser for t in tabs)
+    for tab in tabs:
+        browser_key = tab.browser or "local"
+        browser_node = browsers.setdefault(browser_key, root.add(f"[bold cyan]{browser_key}[/bold cyan]") if show_browser else root)
+        win_key = (browser_key, tab.window_id)
+        win_node = windows.get(win_key)
+        if win_node is None:
+            win_node = browser_node.add(f"Window {tab.window_id}")
+            windows[win_key] = win_node
+        group_label = f"Group {tab.group_id}" if tab.group_id is not None else "Ungrouped"
+        group_key = (browser_key, tab.window_id, group_label)
+        group_node = groups.get(group_key)
+        if group_node is None:
+            group_node = win_node.add(group_label)
+            groups[group_key] = group_node
+        active = " [green]*[/green]" if tab.active else ""
+        group_node.add(f"[{tab.id}] {tab.title or '(untitled)'}{active} — [dim]{tab.url or ''}[/dim]")
+    console.print(root)
+
+@tabs_group.command("close")
+@click.argument("tab_id", type=int, required=False)
+@click.option("--inactive", is_flag=True, help="Close all inactive tabs")
+@click.option("--duplicates", is_flag=True, help="Close duplicate tabs (keep first)")
+@gentle_mode_option("Throttle mode for large close operations.")
+@handle_errors
+def tabs_close(tab_id, inactive, duplicates, gentle_mode):
+    """Close a tab, all inactive tabs, or all duplicate tabs."""
+    count = client_from_ctx().tabs.close(tab_id, inactive=inactive, duplicates=duplicates, gentle_mode=gentle_mode)
+    console.print(f"[green]Closed {count} tab(s)[/green]")
+
+@tabs_group.command("move")
+@click.argument("tab_id", type=int)
+@click.option("-f", "--forward", "forward", is_flag=True, help="Move one position to the right")
+@click.option("-b", "--backward", "backward", is_flag=True, help="Move one position to the left")
+@click.option("-r", "--right", "forward", is_flag=True, help="Move one position to the right")
+@click.option("-l", "--left", "backward", is_flag=True, help="Move one position to the left")
+@click.option("--group", "group_id", type=int, default=None, help="Move to tab group ID")
+@click.option("--window", "window_id", type=int, default=None, help="Move to window ID")
+@click.option("--index", type=int, default=None, help="Absolute position index in target")
+@handle_errors
+def tabs_move(tab_id, forward, backward, group_id, window_id, index):
+    """Move a tab. Use --forward/--backward or --right/--left for relative movement."""
+    client_from_ctx().tabs.move(
+        tab_id, forward=forward, backward=backward,
+        group_id=group_id, window_id=window_id, index=index,
+    )
+    console.print("[green]Tab moved[/green]")
+
+@tabs_group.command("active")
+@click.argument("tab_id", type=int)
+@handle_errors
+def tabs_active(tab_id):
+    """Switch browser focus to a tab."""
+    client_from_ctx().tabs.activate(tab_id)
+    console.print(f"[green]Switched to tab {tab_id}[/green]")
+
+@tabs_group.command("status")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_status(tab_id):
+    """Show status for the active tab or a specific tab."""
+    tab = client_from_ctx().tabs.status(tab_id)
+    table = Table(show_header=False)
+    table.add_column("Field", style="bold cyan")
+    table.add_column("Value")
+    table.add_row("ID", str(tab.id))
+    table.add_row("Window", str(tab.window_id))
+    table.add_row("Active", "yes" if tab.active else "no")
+    table.add_row("Muted", "yes" if tab.muted else "no")
+    table.add_row("Title", tab.title or "")
+    table.add_row("URL", tab.url or "")
+    console.print(table)
+
+@tabs_group.command("filter")
+@click.argument("pattern")
+@handle_errors
+def tabs_filter(pattern):
+    """List tabs whose URL contains PATTERN."""
+    _print_tabs(client_from_ctx().tabs.filter(pattern))
+
+@tabs_group.command("count")
+@click.argument("pattern", required=False)
+@handle_errors
+def tabs_count(pattern):
+    """Count open tabs, optionally filtered by URL PATTERN."""
+    label = f" matching '{pattern}'" if pattern else ""
+    print_counts(client_from_ctx().tabs.count(pattern), "tab", single_suffix=label)
+
+@tabs_group.command("query")
+@click.argument("search")
+@handle_errors
+def tabs_query(search):
+    """Search tabs by URL or title."""
+    _print_tabs(client_from_ctx().tabs.query(search))
+
+@tabs_group.command("html")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_html(tab_id):
+    """Print the full HTML of a tab."""
+    console.print(client_from_ctx().tabs.html(tab_id))
+
+@tabs_group.command("dedupe")
+@gentle_mode_option("Throttle mode for large dedupe operations.")
+@handle_errors
+def tabs_dedupe(gentle_mode):
+    """Close duplicate tabs (keep the first occurrence of each URL)."""
+    count = client_from_ctx().tabs.dedupe(gentle_mode=gentle_mode)
+    console.print(f"[green]Closed {count} duplicate tab(s)[/green]")
+
+@tabs_group.command("sort")
+@click.option("--by", type=click.Choice(["domain", "title", "time"]), default="domain", show_default=True)
+@gentle_mode_option("Throttle mode for large sort operations.")
+@handle_errors
+def tabs_sort(by, gentle_mode):
+    """Sort tabs within each window."""
+    client_from_ctx().tabs.sort(by=by, gentle_mode=gentle_mode)
+    console.print(f"[green]Tabs sorted by {by}[/green]")
+
+@tabs_group.command("merge-windows")
+@gentle_mode_option("Throttle mode for large merge operations.")
+@handle_errors
+def tabs_merge_windows(gentle_mode):
+    """Move all tabs into the focused window."""
+    count = client_from_ctx().tabs.merge_windows(gentle_mode=gentle_mode)
+    console.print(f"[green]Merged — moved {count} tab(s) into current window[/green]")
+
+@tabs_group.command("mute")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_mute(tab_id):
+    """Mute the active tab or a specific tab."""
+    target = client_from_ctx().tabs.mute(tab_id)
+    console.print(f"[green]Muted tab {target}[/green]")
+
+@tabs_group.command("unmute")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_unmute(tab_id):
+    """Unmute the active tab or a specific tab."""
+    target = client_from_ctx().tabs.unmute(tab_id)
+    console.print(f"[green]Unmuted tab {target}[/green]")
+
+@tabs_group.command("pin")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_pin(tab_id):
+    """Pin the active tab or a specific tab."""
+    target = client_from_ctx().tabs.pin(tab_id)
+    console.print(f"[green]Pinned tab {target}[/green]")
+
+@tabs_group.command("unpin")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def tabs_unpin(tab_id):
+    """Unpin the active tab or a specific tab."""
+    target = client_from_ctx().tabs.unpin(tab_id)
+    console.print(f"[green]Unpinned tab {target}[/green]")
+
+@tabs_group.command("watch-url")
+@click.argument("pattern")
+@tab_option
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait")
+@handle_errors
+def tabs_watch_url(pattern, tab_id, timeout):
+    """Wait until the active (or specified) tab URL matches regex PATTERN."""
+    tab = client_from_ctx().tabs.watch_url(pattern, tab_id=tab_id, timeout=timeout)
+    console.print(f"[green]URL matched:[/green] {tab.url}")
+
+@tabs_group.command("screenshot")
+@click.argument("output", required=False, metavar="FILE")
+@tab_option
+@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")
+@handle_errors
+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.
+    """
+    data_url = client_from_ctx().tabs.screenshot(tab_id, format=fmt, quality=quality)
+    if output:
+        header = f"data:image/{fmt};base64,"
+        if not data_url.startswith(header):
+            raise click.ClickException("Empty or unexpected screenshot response (incognito/protected tab?)")
+        try:
+            raw = base64.b64decode(data_url[len(header):])
+        except binascii.Error as e:
+            raise click.ClickException(f"Failed to decode screenshot data: {e}")
+        with open(output, "wb") as f:
+            f.write(raw)
+        console.print(f"[green]Screenshot saved:[/green] {output}")
+    else:
+        console.print(data_url)

browser_cli/commands/watch.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import time
+
+import click
+
+from browser_cli.commands import client_from_ctx, handle_errors
+
+@click.group("watch")
+def watch_group():
+    """Watch browser state and print changes."""
+
+@watch_group.command("tabs")
+@click.option("--interval", type=float, default=1.0, show_default=True)
+@click.option("--once", is_flag=True)
+@handle_errors
+def watch_tabs(interval, once):
+    """Watch the tab list as JSON snapshots."""
+    client = client_from_ctx()
+    previous = None
+    while True:
+        current = [t.__dict__ for t in client.tabs.list()]
+        if current != previous:
+            click.echo(json.dumps({"type": "tabs", "tabs": current}, default=str), flush=True)
+            previous = current
+        if once:
+            return
+        time.sleep(interval)
+
+@watch_group.command("page")
+@click.option("--field", default=None, help="Only print a single page.info field")
+@click.option("--interval", type=float, default=1.0, show_default=True)
+@handle_errors
+def watch_page(field, interval):
+    """Watch page.info for the active tab."""
+    client = client_from_ctx()
+    previous = object()
+    while True:
+        info = client.page.info()
+        current = info.get(field) if field else info
+        if current != previous:
+            click.echo(json.dumps({"type": "page", "field": field, "value": current}, default=str), flush=True)
+            previous = current
+        time.sleep(interval)
+
+@watch_group.command("dom")
+@click.argument("selector")
+@click.option("--interval", type=float, default=1.0, show_default=True)
+@handle_errors
+def watch_dom(selector, interval):
+    """Watch textContent for a selector."""
+    client = client_from_ctx()
+    previous = object()
+    while True:
+        current = client.dom.text(selector)
+        if current != previous:
+            click.echo(json.dumps({"type": "dom", "selector": selector, "text": current}, default=str), flush=True)
+            previous = current
+        time.sleep(interval)

browser_cli/commands/windows.py

@@ -0,0 +1,87 @@
+import click
+from browser_cli.commands import client_from_ctx, handle_errors
+from rich.console import Console
+from rich.table import Table
+from rich.tree import Tree
+
+console = Console()
+
+def _print_windows(windows: list[dict], *, show_browser: bool = False) -> None:
+    if not windows:
+        console.print("[yellow]No windows 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("Alias", width=20)
+    table.add_column("Tabs", width=6)
+    table.add_column("State", width=12)
+    for w in windows:
+        row = [
+            w.get("browser", "") if show_browser else None,
+            str(w.get("id", "")),
+            w.get("alias") or "",
+            str(w.get("tabCount", "")),
+            w.get("state") or "",
+        ]
+        table.add_row(*[value for value in row if value is not None])
+    console.print(table)
+
+@click.group("windows")
+def windows_group():
+    """Manage browser windows."""
+
+@windows_group.command("list")
+@handle_errors
+def windows_list():
+    """List all browser windows."""
+    windows = client_from_ctx().windows.list()
+    _print_windows(windows, show_browser=any("browser" in w for w in windows))
+
+@windows_group.command("tree")
+@handle_errors
+def windows_tree():
+    """Show windows and their tabs as a tree."""
+    client = client_from_ctx()
+    windows = client.windows.list()
+    tabs = client.tabs.list()
+    root = Tree("[bold]Windows[/bold]")
+    for w in sorted(windows, key=lambda item: (item.get("browser", ""), item.get("id", 0))):
+        wid = w.get("id")
+        label = f"Window {wid}"
+        if w.get("alias"):
+            label += f" ({w['alias']})"
+        if w.get("browser"):
+            label = f"{w['browser']}: " + label
+        node = root.add(label)
+        for tab in sorted([t for t in tabs if t.window_id == wid and (not w.get("browser") or t.browser == w.get("browser"))], key=lambda t: t.index):
+            active = " [green]*[/green]" if tab.active else ""
+            node.add(f"[{tab.id}] {tab.title or '(untitled)'}{active} — [dim]{tab.url or ''}[/dim]")
+    console.print(root)
+
+@windows_group.command("rename")
+@click.argument("window_id", type=int)
+@click.argument("name")
+@handle_errors
+def windows_rename(window_id, name):
+    """Give a window a local alias NAME (stored in native host)."""
+    client_from_ctx().windows.rename(window_id, name)
+    console.print(f"[green]Window {window_id} aliased as '{name}'[/green]")
+
+@windows_group.command("close")
+@click.argument("window_id", type=int)
+@handle_errors
+def windows_close(window_id):
+    """Close a browser window."""
+    client_from_ctx().windows.close(window_id)
+    console.print(f"[green]Window {window_id} closed[/green]")
+
+@windows_group.command("open")
+@click.argument("url", required=False)
+@handle_errors
+def windows_open(url):
+    """Open a new browser window."""
+    result = client_from_ctx().windows.open(url)
+    wid = result.get("id") if isinstance(result, dict) else result
+    console.print(f"[green]Opened new window[/green] (id: {wid})" + (f" with {url}" if url else ""))