webtap-tool 0.1.1__py3-none-any.whl

webtap/commands/inspect.py

@@ -0,0 +1,146 @@
+"""CDP event data inspection and analysis commands."""
+
+import json
+
+from webtap.app import app
+from webtap.commands._utils import evaluate_expression, format_expression_result
+from webtap.commands._errors import check_connection
+from webtap.commands._builders import error_response
+from webtap.commands._tips import get_mcp_description
+
+
+mcp_desc = get_mcp_description("inspect")
+
+
+@app.command(display="markdown", fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"})
+def inspect(state, event: int = None, expr: str = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Inspect CDP event or evaluate expression.
+
+    Args:
+        event: Event row ID to inspect (optional)
+        expr: Python expression to evaluate (optional)
+
+    Returns:
+        Evaluation result or full CDP event
+    """
+    if event is None and expr is None:
+        return error_response("Must provide at least one of: event (int) or expr (str)")
+
+    if error := check_connection(state):
+        return error
+
+    # Handle pure expression evaluation (no event)
+    if expr and event is None:
+        try:
+            # Create namespace with cdp and state
+            namespace = {"cdp": state.cdp, "state": state}
+
+            # Execute and get result + output
+            result, output = evaluate_expression(expr, namespace)
+            formatted_result = format_expression_result(result, output)
+
+            # Build markdown response
+            return {
+                "elements": [
+                    {"type": "heading", "content": "Expression Evaluation", "level": 2},
+                    {"type": "text", "content": "**Expression:**"},
+                    {"type": "code_block", "content": expr, "language": "python"},
+                    {"type": "text", "content": "**Result:**"},
+                    {"type": "code_block", "content": formatted_result, "language": ""},
+                ]
+            }
+        except Exception as e:
+            return error_response(
+                f"{type(e).__name__}: {e}", suggestions=["cdp and state objects are available in namespace"]
+            )
+
+    # Handle event inspection (with optional expression)
+    # Fetch event directly from DuckDB
+    result = state.cdp.query("SELECT event FROM events WHERE rowid = ?", [event])
+
+    if not result:
+        return error_response(f"Event with rowid {event} not found")
+
+    # Parse the CDP event
+    data = json.loads(result[0][0])
+
+    # No expression: show the raw data
+    if not expr:
+        # Pretty print the full CDP event as JSON
+        elements = [{"type": "heading", "content": f"Event {event}", "level": 2}]
+
+        # Add event method if available
+        if isinstance(data, dict) and "method" in data:
+            elements.append({"type": "text", "content": f"**Method:** `{data['method']}`"})
+
+        # Add the full data as JSON code block
+        # DATA-LEVEL TRUNCATION for memory/performance (similar to body.py)
+        MAX_EVENT_SIZE = 2000
+        if isinstance(data, dict):
+            formatted = json.dumps(data, indent=2)
+            if len(formatted) > MAX_EVENT_SIZE:
+                elements.append({"type": "code_block", "content": formatted[:MAX_EVENT_SIZE], "language": "json"})
+                elements.append(
+                    {"type": "text", "content": f"_[truncated at {MAX_EVENT_SIZE} chars, {len(formatted)} total]_"}
+                )
+            else:
+                elements.append({"type": "code_block", "content": formatted, "language": "json"})
+        else:
+            elements.append({"type": "code_block", "content": str(data), "language": ""})
+
+        return {"elements": elements}
+
+    # Execute code with data available (Jupyter-style)
+    try:
+        # Create namespace with data
+        namespace = {"data": data}
+
+        # Execute and get result + output
+        result, output = evaluate_expression(expr, namespace)
+        formatted_result = format_expression_result(result, output)
+
+        # Build markdown response
+        elements = [{"type": "heading", "content": f"Inspect Event {event}", "level": 2}]
+
+        # Add event method if available
+        if isinstance(data, dict) and "method" in data:
+            elements.append({"type": "text", "content": f"**Method:** `{data['method']}`"})
+
+        elements.extend(
+            [
+                {"type": "text", "content": "**Expression:**"},
+                {"type": "code_block", "content": expr, "language": "python"},
+                {"type": "text", "content": "**Result:**"},
+                {"type": "code_block", "content": formatted_result, "language": ""},
+            ]
+        )
+
+        return {"elements": elements}
+
+    except Exception as e:
+        # Provide helpful suggestions based on the error type
+        suggestions = ["The event data is available as 'data' dict"]
+
+        if "NameError" in str(type(e).__name__):
+            suggestions.extend(
+                [
+                    "Common libraries are pre-imported: re, json, bs4, jwt, base64",
+                    "Example: re.findall(r'pattern', str(data))",
+                ]
+            )
+        elif "KeyError" in str(e):
+            suggestions.extend(
+                [
+                    "Key not found. Try: list(data.keys()) to see available keys",
+                    "CDP events are nested. Try: data.get('params', {}).get('response', {})",
+                ]
+            )
+        elif "TypeError" in str(e):
+            suggestions.extend(
+                [
+                    "Check data type: type(data)",
+                    "For nested access, use: data.get('params', {}).get('field')",
+                ]
+            )
+
+        return error_response(f"{type(e).__name__}: {e}", suggestions=suggestions)

webtap/commands/javascript.py

@@ -0,0 +1,87 @@
+"""JavaScript code execution in browser context."""
+
+import json
+from webtap.app import app
+from webtap.commands._errors import check_connection
+from webtap.commands._builders import info_response, error_response
+from webtap.commands._tips import get_mcp_description
+
+
+mcp_desc = get_mcp_description("js")
+
+
+@app.command(
+    display="markdown",
+    truncate={
+        "Expression": {"max": 50, "mode": "end"}  # Only truncate for display in info response
+    },
+    fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"},
+)
+def js(state, code: str, wait_return: bool = True, await_promise: bool = False) -> dict:
+    """Execute JavaScript in the browser.
+
+    Args:
+        code: JavaScript code to execute
+        wait_return: Wait for and return result (default: True)
+        await_promise: Await promises before returning (default: False)
+
+    Examples:
+        js("document.title")                           # Get page title
+        js("document.body.innerText.length")           # Get text length
+        js("console.log('test')", wait_return=False)   # Fire and forget
+        js("[...document.links].map(a => a.href)")    # Get all links
+
+        # Async operations
+        js("fetch('/api').then(r => r.json())", await_promise=True)
+
+        # DOM manipulation (no return needed)
+        js("document.querySelectorAll('.ad').forEach(e => e.remove())", wait_return=False)
+
+        # Install interceptors
+        js("window.fetch = new Proxy(window.fetch, {get: (t, p) => console.log(p)})", wait_return=False)
+
+    Returns:
+        The evaluated result if wait_return=True, otherwise execution status
+    """
+    if error := check_connection(state):
+        return error
+
+    result = state.cdp.execute(
+        "Runtime.evaluate", {"expression": code, "returnByValue": wait_return, "awaitPromise": await_promise}
+    )
+
+    # Check for exceptions
+    if result.get("exceptionDetails"):
+        exception = result["exceptionDetails"]
+        error_text = exception.get("exception", {}).get("description", str(exception))
+
+        return error_response(f"JavaScript error: {error_text}")
+
+    # Return based on wait_return flag
+    if wait_return:
+        value = result.get("result", {}).get("value")
+
+        # Format the result in markdown
+        elements = [
+            {"type": "heading", "content": "JavaScript Result", "level": 2},
+            {"type": "code_block", "content": code, "language": "javascript"},  # Full code
+        ]
+
+        # Add the result
+        if value is not None:
+            if isinstance(value, (dict, list)):
+                elements.append({"type": "code_block", "content": json.dumps(value, indent=2), "language": "json"})
+            else:
+                elements.append({"type": "text", "content": f"**Result:** `{value}`"})
+        else:
+            elements.append({"type": "text", "content": "**Result:** _(no return value)_"})
+
+        return {"elements": elements}
+    else:
+        return info_response(
+            title="JavaScript Execution",
+            fields={
+                "Status": "Executed",
+                "Expression": code,  # Full expression, truncation in decorator
+            },
+        )

webtap/commands/launch.py

@@ -0,0 +1,86 @@
+"""Chrome launch commands for WebTap."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from webtap.app import app
+from webtap.commands._builders import success_response, error_response
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "run-chrome", "help": "Launch Chrome with debugging enabled"},
+    fastmcp={"enabled": False},
+)
+def run_chrome(state, detach: bool = True, port: int = 9222) -> dict:
+    """Launch Chrome with debugging enabled for WebTap.
+
+    Args:
+        detach: Run Chrome in background (default: True)
+        port: Debugging port (default: 9222)
+
+    Returns:
+        Status message
+    """
+    # Find Chrome executable
+    chrome_paths = [
+        "google-chrome-stable",
+        "google-chrome",
+        "chromium-browser",
+        "chromium",
+    ]
+
+    chrome_exe = None
+    for path in chrome_paths:
+        if shutil.which(path):
+            chrome_exe = path
+            break
+
+    if not chrome_exe:
+        return error_response(
+            "Chrome not found",
+            suggestions=[
+                "Install google-chrome-stable: sudo apt install google-chrome-stable",
+                "Or install chromium: sudo apt install chromium-browser",
+            ],
+        )
+
+    # Setup temp profile with symlinks to real profile
+    temp_config = Path("/tmp/webtap-chrome-debug")
+    real_config = Path.home() / ".config" / "google-chrome"
+
+    if not temp_config.exists():
+        temp_config.mkdir(parents=True)
+
+        # Symlink Default profile
+        default_profile = real_config / "Default"
+        if default_profile.exists():
+            (temp_config / "Default").symlink_to(default_profile)
+
+        # Copy essential files
+        for file in ["Local State", "First Run"]:
+            src = real_config / file
+            if src.exists():
+                (temp_config / file).write_text(src.read_text())
+
+    # Launch Chrome
+    cmd = [chrome_exe, f"--remote-debugging-port={port}", "--remote-allow-origins=*", f"--user-data-dir={temp_config}"]
+
+    if detach:
+        subprocess.Popen(cmd, start_new_session=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return success_response(
+            f"Launched {chrome_exe}",
+            details={
+                "Port": str(port),
+                "Mode": "Background (detached)",
+                "Profile": str(temp_config),
+                "Next step": "Run connect() to attach WebTap",
+            },
+        )
+    else:
+        result = subprocess.run(cmd)
+        if result.returncode == 0:
+            return success_response("Chrome closed normally")
+        else:
+            return error_response(f"Chrome exited with code {result.returncode}")

webtap/commands/navigation.py

@@ -0,0 +1,199 @@
+"""Browser page navigation and history commands."""
+
+from webtap.app import app
+from webtap.commands._errors import check_connection
+from webtap.commands._builders import info_response, table_response, error_response
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def navigate(state, url: str) -> dict:
+    """Navigate to URL.
+
+    Args:
+        url: URL to navigate to
+
+    Returns:
+        Navigation result in markdown
+    """
+    if error := check_connection(state):
+        return error
+
+    result = state.cdp.execute("Page.navigate", {"url": url})
+
+    return info_response(
+        title="Navigation",
+        fields={
+            "URL": url,
+            "Frame ID": result.get("frameId", "None"),
+            "Loader ID": result.get("loaderId", "None"),
+        },
+    )
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def reload(state, ignore_cache: bool = False) -> dict:
+    """Reload the current page.
+
+    Args:
+        ignore_cache: Force reload ignoring cache
+
+    Returns:
+        Reload status in markdown
+    """
+    if error := check_connection(state):
+        return error
+
+    state.cdp.execute("Page.reload", {"ignoreCache": ignore_cache})
+
+    return info_response(
+        title="Page Reload", fields={"Status": "Page reloaded", "Cache": "Ignored" if ignore_cache else "Used"}
+    )
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def back(state) -> dict:
+    """Navigate back in history.
+
+    Returns:
+        Navigation result in markdown
+    """
+    if error := check_connection(state):
+        return error
+
+    # Get history
+    history = state.cdp.execute("Page.getNavigationHistory")
+    entries = history.get("entries", [])
+    current_index = history.get("currentIndex", 0)
+
+    if current_index > 0:
+        # Navigate to previous entry
+        target_id = entries[current_index - 1]["id"]
+        state.cdp.execute("Page.navigateToHistoryEntry", {"entryId": target_id})
+
+        prev_entry = entries[current_index - 1]
+        return info_response(
+            title="Navigation Back",
+            fields={
+                "Status": "Navigated back",
+                "Page": prev_entry.get("title", "Untitled"),
+                "URL": prev_entry.get("url", ""),  # Full URL, no truncation
+                "Index": f"{current_index - 1} of {len(entries) - 1}",
+            },
+        )
+
+    return error_response("No history to go back")
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def forward(state) -> dict:
+    """Navigate forward in history.
+
+    Returns:
+        Navigation result in markdown
+    """
+    if error := check_connection(state):
+        return error
+
+    # Get history
+    history = state.cdp.execute("Page.getNavigationHistory")
+    entries = history.get("entries", [])
+    current_index = history.get("currentIndex", 0)
+
+    if current_index < len(entries) - 1:
+        # Navigate to next entry
+        target_id = entries[current_index + 1]["id"]
+        state.cdp.execute("Page.navigateToHistoryEntry", {"entryId": target_id})
+
+        next_entry = entries[current_index + 1]
+        return info_response(
+            title="Navigation Forward",
+            fields={
+                "Status": "Navigated forward",
+                "Page": next_entry.get("title", "Untitled"),
+                "URL": next_entry.get("url", ""),  # Full URL, no truncation
+                "Index": f"{current_index + 1} of {len(entries) - 1}",
+            },
+        )
+
+    return error_response("No history to go forward")
+
+
+@app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "application/json"})
+def page(state) -> dict:
+    """Get current page information.
+
+    Returns:
+        Current page information in markdown
+    """
+    # Check connection - return error dict if not connected
+    if error := check_connection(state):
+        return error
+
+    # Get from navigation history
+    history = state.cdp.execute("Page.getNavigationHistory")
+    entries = history.get("entries", [])
+    current_index = history.get("currentIndex", 0)
+
+    if entries and current_index < len(entries):
+        current = entries[current_index]
+
+        # Also get title from Runtime
+        try:
+            title = (
+                state.cdp.execute("Runtime.evaluate", {"expression": "document.title", "returnByValue": True})
+                .get("result", {})
+                .get("value", current.get("title", ""))
+            )
+        except Exception:
+            title = current.get("title", "")
+
+        # Build formatted response
+        return info_response(
+            title=title or "Untitled Page",
+            fields={
+                "URL": current.get("url", ""),  # Full URL
+                "ID": current.get("id", ""),
+                "Type": current.get("transitionType", ""),
+            },
+        )
+
+    return error_response("No navigation history available")
+
+
+@app.command(
+    display="markdown",
+    truncate={"Title": {"max": 40, "mode": "end"}, "URL": {"max": 50, "mode": "middle"}},
+    fastmcp={"type": "resource", "mime_type": "application/json"},
+)
+def history(state) -> dict:
+    """Get navigation history.
+
+    Returns:
+        Table of history entries with current marked
+    """
+    # Check connection - return error dict if not connected
+    if error := check_connection(state):
+        return error
+
+    history = state.cdp.execute("Page.getNavigationHistory")
+    entries = history.get("entries", [])
+    current_index = history.get("currentIndex", 0)
+
+    # Format rows for table with FULL data
+    rows = [
+        {
+            "Index": str(i),
+            "Current": "Yes" if i == current_index else "",
+            "Title": entry.get("title", ""),  # Full title
+            "URL": entry.get("url", ""),  # Full URL
+        }
+        for i, entry in enumerate(entries)
+    ]
+
+    # Build markdown response
+    return table_response(
+        title="Navigation History",
+        headers=["Index", "Current", "Title", "URL"],
+        rows=rows,
+        summary=f"{len(entries)} entries, current index: {current_index}",
+    )

webtap/commands/network.py

@@ -0,0 +1,85 @@
+"""Network request monitoring and display commands."""
+
+from typing import List
+
+from webtap.app import app
+from webtap.commands._builders import table_response
+from webtap.commands._errors import check_connection
+from webtap.commands._tips import get_tips
+
+
+@app.command(
+    display="markdown",
+    truncate={"ReqID": {"max": 12, "mode": "end"}, "URL": {"max": 60, "mode": "middle"}},
+    transforms={"Size": "format_size"},
+    fastmcp=[{"type": "resource", "mime_type": "application/json"}, {"type": "tool"}],
+)
+def network(state, limit: int = 20, filters: List[str] = None, no_filters: bool = False) -> dict:  # pyright: ignore[reportArgumentType]
+    """Show network requests with full data.
+
+    As Resource (no parameters):
+        network             # Returns last 20 requests with enabled filters
+
+    As Tool (with parameters):
+        network(limit=50)                    # More results
+        network(filters=["ads"])            # Specific filter only
+        network(no_filters=True, limit=50)  # Everything unfiltered
+
+    Args:
+        limit: Maximum results to show (default: 20)
+        filters: Specific filter categories to apply
+        no_filters: Show everything unfiltered (default: False)
+
+    Returns:
+        Table of network requests with full data
+    """
+    # Check connection
+    if error := check_connection(state):
+        return error
+
+    # Get filter SQL from service
+    if no_filters:
+        filter_sql = ""
+    elif filters:
+        filter_sql = state.service.filters.get_filter_sql(use_all=False, categories=filters)
+    else:
+        filter_sql = state.service.filters.get_filter_sql(use_all=True)
+
+    # Get data from service
+    results = state.service.network.get_recent_requests(limit=limit, filter_sql=filter_sql)
+
+    # Build rows with FULL data
+    rows = []
+    for row in results:
+        rowid, request_id, method, status, url, type_val, size = row
+        rows.append(
+            {
+                "ID": str(rowid),
+                "ReqID": request_id or "",  # Full request ID
+                "Method": method or "GET",
+                "Status": str(status) if status else "-",
+                "URL": url or "",  # Full URL
+                "Type": type_val or "-",
+                "Size": size or 0,  # Raw bytes
+            }
+        )
+
+    # Build response with developer guidance
+    warnings = []
+    if limit and len(results) == limit:
+        warnings.append(f"Showing first {limit} results (use limit parameter to see more)")
+
+    # Get tips from TIPS.md with context
+    tips = None
+    if rows:
+        example_id = rows[0]["ID"]
+        tips = get_tips("network", context={"id": example_id})
+
+    return table_response(
+        title="Network Requests",
+        headers=["ID", "ReqID", "Method", "Status", "URL", "Type", "Size"],
+        rows=rows,
+        summary=f"{len(rows)} requests",
+        warnings=warnings,
+        tips=tips,
+    )