init commit

examples/demo.py

@@ -0,0 +1,107 @@
+"""
+browser-cli Python API demo
+----------------------------
+Shows how to manage your running browser from a Python script.
+
+Run with:
+    uv run python examples/demo.py
+"""
+from browser_cli import BrowserCLI
+
+b = BrowserCLI()
+
+
+# ── 1. See what's open ────────────────────────────────────────────────────────
+print("=== Open tabs ===")
+tabs = b.tabs_list()
+for tab in tabs:
+    active = " <-- active" if tab["active"] else ""
+    print(f"  [{tab['id']}] (window {tab['windowId']}) {tab['title'][:50]}{active}")
+
+
+# ── 2. Count tabs per domain ──────────────────────────────────────────────────
+print("\n=== Tabs per domain ===")
+from urllib.parse import urlparse
+from collections import Counter
+
+domains = Counter(
+    urlparse(t["url"]).netloc
+    for t in tabs
+    if t.get("url") and not t["url"].startswith("chrome")
+)
+for domain, count in domains.most_common(5):
+    print(f"  {count:>3}x  {domain}")
+
+
+# ── 3. Open a group and add tabs to it ───────────────────────────────────────
+print("\n=== Creating 'demo' tab group ===")
+group = b.group_open("demo")
+group_id = group["id"]
+print(f"  Created group id: {group_id}")
+
+urls = [
+    "https://example.com",
+    "https://wikipedia.org",
+]
+first_tab_id = None
+for url in urls:
+    b.open(url, background=True)
+    # find the tab we just opened and move it into the group
+    fresh = b.tabs_list()
+    new_tab = next((t for t in reversed(fresh) if t.get("url", "").startswith(url[:20])), None)
+    if new_tab:
+        b.tabs_move(new_tab["id"], group_id=group_id)
+        print(f"  Added {url} → tab {new_tab['id']}")
+        if first_tab_id is None:
+            first_tab_id = new_tab["id"]
+
+# Activate the first opened tab so DOM/extract have a real page to work with
+if first_tab_id:
+    b.tabs_active(first_tab_id)
+    print(f"  Switched to tab {first_tab_id} for DOM demo")
+
+
+# ── 4. Extract links from the active tab ─────────────────────────────────────
+# Re-fetch tabs so we have the current active tab (it may have changed)
+current_tabs = b.tabs_list()
+active_tab = next((t for t in current_tabs if t.get("active")), None)
+active_url = active_tab.get("url", "") if active_tab else ""
+scriptable = active_url.startswith("http://") or active_url.startswith("https://")
+
+print("\n=== Links on active tab ===")
+if not scriptable:
+    print(f"  Skipped — active tab is {active_url!r} (not a web page)")
+else:
+    links = b.extract_links()
+    for link in links[:5]:
+        print(f"  {link['text'][:30]:<32} {link['href'][:60]}")
+    if len(links) > 5:
+        print(f"  ... and {len(links) - 5} more")
+
+
+# ── 5. Check if an element exists, then read its text ────────────────────────
+print("\n=== DOM: page heading ===")
+if not scriptable:
+    print(f"  Skipped — active tab is {active_url!r} (not a web page)")
+elif b.dom_exists("h1"):
+    headings = b.dom_text("h1")
+    for h in headings:
+        print(f"  <h1> {h}")
+else:
+    print("  No <h1> found on active tab")
+
+
+# ── 6. Save current session and show how to restore ──────────────────────────
+print("\n=== Saving session as 'demo-session' ===")
+result = b.session_save("demo-session")
+print(f"  Saved {result['tabs']} tabs")
+print("  Restore later with: b.session_load('demo-session')")
+
+
+# ── 7. Clean up: close inactive tabs ─────────────────────────────────────────
+print("\n=== Closing duplicate tabs ===")
+result = b.tabs_close_duplicates()
+closed = result.get("closed", 0) if isinstance(result, dict) else 0
+print(f"  Closed {closed} duplicate tab(s)")
+
+print("\nDone!")

examples/demo.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# browser-cli Bash demo
+# ----------------------
+# Shows how to drive your running browser from a shell script.
+#
+# Run with:
+#   bash examples/demo.sh
+#
+# Press ENTER to advance each step, or set AUTO=1 to run without pausing:
+#   AUTO=1 bash examples/demo.sh
+
+CLI="uv run browser-cli"
+DELAY=2   # seconds between steps in auto mode
+
+pause() {
+    echo ""
+    if [ "${AUTO:-0}" = "1" ]; then
+        sleep "$DELAY"
+    else
+        read -rp "  [press ENTER to continue] "
+    fi
+    echo ""
+}
+
+header() {
+    echo ""
+    echo "────────────────────────────────────"
+    echo "  $1"
+    echo "────────────────────────────────────"
+}
+
+
+header "1/8 · Open tabs"
+$CLI tabs list
+pause
+
+header "2/8 · Tab count & windows"
+$CLI tabs count
+echo ""
+$CLI windows list
+pause
+
+header "3/8 · Create 'research' group and open URLs into it"
+$CLI group create research
+echo ""
+$CLI open https://example.com   --group research --bg
+$CLI open https://wikipedia.org --group research --bg
+echo ""
+echo "  Tabs are now open inside the 'research' group in your browser."
+pause
+
+header "4/8 · Tab hygiene — close duplicates, sort by domain"
+$CLI tabs close --duplicates
+echo ""
+$CLI tabs sort --by domain
+pause
+
+header "5/8 · Find tabs by URL pattern or title"
+$CLI tabs filter wikipedia
+echo ""
+$CLI tabs query "example"
+pause
+
+header "6/8 · DOM and content extraction (active tab)"
+echo "  Switching to the example.com tab first..."
+$CLI focus example.com
+echo ""
+echo "  Page headings:"
+$CLI dom text h1
+echo ""
+echo "  Links on the page:"
+$CLI extract links
+pause
+
+header "7/8 · Session management"
+$CLI session save before-meeting
+echo ""
+echo "  Restore later with:"
+echo "    $CLI session load before-meeting"
+echo ""
+echo "  Compare two sessions with:"
+echo "    $CLI session diff before-meeting after-meeting"
+pause
+
+header "8/8 · Merge all windows into one"
+$CLI tabs merge-windows
+echo ""
+echo "Done!"