webtap-tool 0.11.0__py3-none-any.whl

webtap/commands/connection.py

@@ -0,0 +1,220 @@
+"""Chrome browser connection management commands."""
+
+from replkit2.types import ExecutionContext
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import info_response, table_response, error_response
+from webtap.commands._tips import get_mcp_description, get_tips
+
+_connect_desc = get_mcp_description("connect")
+_disconnect_desc = get_mcp_description("disconnect")
+_clear_desc = get_mcp_description("clear")
+
+# Truncation values for pages() REPL mode (compact display)
+_PAGES_REPL_TRUNCATE = {
+    "Title": {"max": 20, "mode": "end"},
+    "URL": {"max": 30, "mode": "middle"},
+    "ID": {"max": 6, "mode": "end"},
+}
+
+# Truncation values for pages() MCP mode (generous for LLM context)
+_PAGES_MCP_TRUNCATE = {
+    "Title": {"max": 100, "mode": "end"},
+    "URL": {"max": 200, "mode": "middle"},
+    "ID": {"max": 50, "mode": "end"},
+}
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _connect_desc or ""}
+)
+def connect(state, page: int = None, page_id: str = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Connect to Chrome page and enable all required domains.
+
+    Args:
+        page: Connect by page index (0-based)
+        page_id: Connect by page ID
+
+    Note: If neither is specified, connects to first available page.
+          Cannot specify both page and page_id.
+
+    Examples:
+        connect()                    # First page
+        connect(page=2)             # Third page (0-indexed)
+        connect(page_id="xyz")      # Specific page ID
+
+    Returns:
+        Connection status in markdown
+    """
+    try:
+        # Build params - default to page=0 when no params given
+        params = {}
+        if page is not None:
+            params["page"] = page
+        if page_id is not None:
+            params["page_id"] = page_id
+        if not params:
+            params["page"] = 0  # Connect to first page by default
+
+        result = state.client.call("connect", **params)
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Success - return formatted info with full URL
+    return info_response(
+        title="Connection Established",
+        fields={"Page": result.get("title", "Unknown"), "URL": result.get("url", "")},
+    )
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _disconnect_desc or ""}
+)
+def disconnect(state) -> dict:
+    """Disconnect from Chrome."""
+    try:
+        state.client.call("disconnect")
+    except RPCError as e:
+        # INVALID_STATE means not connected
+        if e.code == "INVALID_STATE":
+            return info_response(title="Disconnect Status", fields={"Status": "Not connected"})
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    return info_response(title="Disconnect Status", fields={"Status": "Disconnected"})
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _clear_desc or ""}
+)
+def clear(state, events: bool = True, console: bool = False) -> dict:
+    """Clear various data stores.
+
+    Args:
+        events: Clear CDP events (default: True)
+        console: Clear console messages (default: False)
+
+    Examples:
+        clear()                                    # Clear events only
+        clear(events=True, console=True)          # Clear events and console
+        clear(events=False, console=True)         # Console only
+
+    Returns:
+        Summary of what was cleared
+    """
+    try:
+        result = state.client.call("clear", events=events, console=console)
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Build cleared list from result
+    cleared = result.get("cleared", [])
+
+    if not cleared:
+        return info_response(
+            title="Clear Status",
+            fields={"Result": "Nothing to clear (specify events=True or console=True)"},
+        )
+
+    return info_response(title="Clear Status", fields={"Cleared": ", ".join(cleared)})
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "resource", "mime_type": "text/markdown"},
+)
+def pages(state, _ctx: ExecutionContext = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """List available Chrome pages.
+
+    Returns:
+        Table of available pages in markdown
+    """
+    try:
+        result = state.client.call("pages")
+        pages_list = result.get("pages", [])
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Format rows for table with FULL data
+    rows = [
+        {
+            "Index": str(i),
+            "Title": p.get("title", "Untitled"),  # Full title
+            "URL": p.get("url", ""),  # Full URL
+            "ID": p.get("id", ""),  # Full ID
+            "Connected": "Yes" if p.get("is_connected") else "No",
+        }
+        for i, p in enumerate(pages_list)
+    ]
+
+    # Get contextual tips
+    tips = None
+    if rows:
+        # Find connected page or first page
+        connected_row = next((r for r in rows if r["Connected"] == "Yes"), rows[0])
+        page_index = connected_row["Index"]
+
+        # Get page_id for the example page
+        connected_page = next((p for p in pages_list if str(pages_list.index(p)) == page_index), None)
+        page_id = connected_page.get("id", "")[:6] if connected_page else ""
+
+        tips = get_tips("pages", context={"index": page_index, "page_id": page_id})
+
+    # Build contextual warnings
+    warnings = []
+    if any(r["Connected"] == "Yes" for r in rows):
+        warnings.append("Already connected - call connect(page=N) to switch pages")
+
+    # Use mode-specific truncation
+    is_repl = _ctx and _ctx.is_repl()
+    truncate = _PAGES_REPL_TRUNCATE if is_repl else _PAGES_MCP_TRUNCATE
+
+    # Build markdown response
+    return table_response(
+        title="Chrome Pages",
+        headers=["Index", "Title", "URL", "ID", "Connected"],
+        rows=rows,
+        summary=f"{len(pages_list)} page{'s' if len(pages_list) != 1 else ''} available",
+        warnings=warnings if warnings else None,
+        tips=tips,
+        truncate=truncate,
+    )
+
+
+@app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "text/markdown"})
+def status(state) -> dict:
+    """Get connection status.
+
+    Returns:
+        Status information in markdown
+    """
+    try:
+        status_data = state.client.call("status")
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Check if connected
+    if not status_data.get("connected"):
+        return error_response("Not connected to any page. Use connect() first.")
+
+    # Build formatted response with full URL
+    page = status_data.get("page", {})
+    return info_response(
+        title="Connection Status",
+        fields={
+            "Page": page.get("title", "Unknown"),
+            "URL": page.get("url", ""),
+            "Events": f"{status_data.get('events', {}).get('total', 0)} stored",
+            "Fetch": "Enabled" if status_data.get("fetch", {}).get("enabled") else "Disabled",
+        },
+    )

webtap/commands/console.py

@@ -0,0 +1,87 @@
+"""Browser console message monitoring and display commands."""
+
+from replkit2.types import ExecutionContext
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import table_response, error_response, format_timestamp
+from webtap.commands._tips import get_tips
+
+# Truncation values for REPL mode (compact display)
+_REPL_TRUNCATE = {
+    "Message": {"max": 80, "mode": "end"},
+}
+
+# Truncation values for MCP mode (generous for LLM context)
+_MCP_TRUNCATE = {
+    "Message": {"max": 300, "mode": "end"},
+}
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "resource", "mime_type": "text/markdown"},
+)
+def console(state, limit: int = 50, _ctx: ExecutionContext = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Show console messages with full data.
+
+    Args:
+        limit: Max results (default: 50)
+
+    Examples:
+        console()           # Recent console messages
+        console(limit=100)  # Show more messages
+
+    Returns:
+        Table of console messages with full data
+    """
+    # Get console messages via RPC
+    try:
+        result = state.client.call("console", limit=limit)
+        messages = result.get("messages", [])
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Mode-specific configuration
+    is_repl = _ctx and _ctx.is_repl()
+
+    # Build rows with mode-specific formatting
+    rows = [
+        {
+            "ID": str(m.get("id", i)),
+            "Level": m.get("level", "unknown"),
+            "Source": m.get("source", ""),
+            "Message": m.get("message", ""),
+            # REPL: human-friendly time, MCP: raw timestamp for LLM
+            "Time": format_timestamp(m.get("timestamp")) if is_repl else (m.get("timestamp") or 0),
+        }
+        for i, m in enumerate(messages)
+    ]
+
+    # Build response
+    warnings = []
+    if limit and len(messages) == limit:
+        warnings.append(f"Showing first {limit} messages (use limit parameter to see more)")
+
+    # Get contextual tips from TIPS.md
+    tips = None
+    if rows:
+        # Focus on error/warning messages for debugging
+        error_rows = [r for r in rows if r.get("Level", "").upper() in ["ERROR", "WARN", "WARNING"]]
+        example_id = error_rows[0]["ID"] if error_rows else rows[0]["ID"]
+        tips = get_tips("console", context={"id": example_id})
+
+    # Use mode-specific truncation
+    truncate = _REPL_TRUNCATE if is_repl else _MCP_TRUNCATE
+
+    return table_response(
+        title="Console Messages",
+        headers=["ID", "Level", "Source", "Message", "Time"],
+        rows=rows,
+        summary=f"{len(rows)} messages",
+        warnings=warnings,
+        tips=tips,
+        truncate=truncate,
+    )

webtap/commands/fetch.py

@@ -0,0 +1,310 @@
+"""HTTP fetch request interception and debugging commands."""
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import error_response, info_response
+from webtap.commands._tips import get_mcp_description, get_tips
+
+_fetch_desc = get_mcp_description("fetch")
+_resume_desc = get_mcp_description("resume")
+_fail_desc = get_mcp_description("fail")
+_fulfill_desc = get_mcp_description("fulfill")
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _fetch_desc or ""}
+)
+def fetch(state, action: str, options: dict = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Control fetch interception.
+
+    When enabled, requests pause for inspection.
+    Use requests() to see paused items, resume() or fail() to proceed.
+
+    Args:
+        action: Action to perform
+            - "enable" - Enable interception
+            - "disable" - Disable interception
+            - "status" - Get current status
+        options: Action-specific options
+            - For enable: {"response": true} - Also intercept responses
+
+    Examples:
+        fetch("status")                           # Check status
+        fetch("enable")                           # Enable request stage
+        fetch("enable", {"response": true})       # Both stages
+        fetch("disable")                          # Disable
+
+    Returns:
+        Fetch interception status
+    """
+    try:
+        if action == "disable":
+            state.client.call("fetch.disable")
+            return info_response(title="Fetch Disabled", fields={"Status": "Interception disabled"})
+
+        elif action == "enable":
+            response_stage = (options or {}).get("response", False)
+            result = state.client.call("fetch.enable", request=True, response=response_stage)
+
+            stages = "Request and Response stages" if result.get("response_stage") else "Request stage only"
+            return info_response(
+                title="Fetch Enabled",
+                fields={
+                    "Stages": stages,
+                    "Status": "Requests will pause",
+                },
+            )
+
+        elif action == "status":
+            status = state.client.call("status")
+            fetch_state = status.get("fetch", {})
+            fetch_enabled = fetch_state.get("enabled", False)
+            paused_count = fetch_state.get("paused_count", 0) if fetch_enabled else 0
+
+            return info_response(
+                title=f"Fetch Status: {'Enabled' if fetch_enabled else 'Disabled'}",
+                fields={
+                    "Status": "Enabled" if fetch_enabled else "Disabled",
+                    "Paused": f"{paused_count} requests paused" if fetch_enabled else "None",
+                },
+            )
+
+        else:
+            return error_response(f"Unknown action: {action}")
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+
+@app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "text/markdown"})
+def requests(state, limit: int = 50) -> dict:
+    """Show paused requests. Equivalent to network(req_state="paused").
+
+    Args:
+        limit: Maximum items to show
+
+    Examples:
+        requests()           # Show all paused
+        request(583)         # View request details
+        resume(583)          # Continue request
+
+    Returns:
+        Table of paused requests/responses in markdown
+    """
+    try:
+        # Get status to check if fetch is enabled
+        status = state.client.call("status")
+        if not status.get("fetch", {}).get("enabled", False):
+            return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+        # Delegate to network command with state filter
+        from webtap.commands.network import network
+
+        result = network(state, req_state="paused", limit=limit, show_all=True)
+
+        # Add fetch-specific tips if we have rows
+        if result.get("elements"):
+            # Find table element and extract first ID for tips
+            for element in result["elements"]:
+                if element.get("type") == "table":
+                    rows = element.get("rows", [])
+                    if rows and rows[0]:
+                        example_id = rows[0].get("ID", 0)
+                        tips = get_tips("requests", context={"id": example_id})
+                        if tips:
+                            # Add tips as alerts after table
+                            tip_elements = [{"type": "alert", "content": tip, "level": "info"} for tip in tips]
+                            # Insert after table
+                            table_index = result["elements"].index(element)
+                            result["elements"] = (
+                                result["elements"][: table_index + 1]
+                                + tip_elements
+                                + result["elements"][table_index + 1 :]
+                            )
+                    break
+
+        return result
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _resume_desc or ""}
+)
+def resume(state, request: int, wait: float = 0.5, modifications: dict = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Resume a paused request.
+
+    For Request stage, can modify:
+        url, method, headers, postData
+
+    For Response stage, can modify:
+        responseCode, responseHeaders
+
+    Args:
+        request: Request ID from network() table
+        wait: Wait time for next event in seconds (default: 0.5)
+        modifications: Request/response modifications dict
+            - {"url": "..."} - Change URL
+            - {"method": "POST"} - Change method
+            - {"headers": [{"name": "X-Custom", "value": "test"}]} - Set headers
+            - {"responseCode": 404} - Change response code
+            - {"responseHeaders": [...]} - Modify response headers
+
+    Examples:
+        resume(583)                               # Simple resume
+        resume(583, wait=1.0)                    # Wait for redirect
+        resume(583, modifications={"url": "..."})  # Change URL
+        resume(583, modifications={"method": "POST"})  # Change method
+        resume(583, modifications={"headers": [{"name":"X-Custom","value":"test"}]})
+
+    Returns:
+        Continuation status with any follow-up events detected
+    """
+    try:
+        # Get status to check if fetch is enabled
+        status = state.client.call("status")
+        if not status.get("fetch", {}).get("enabled", False):
+            return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+        # Resume via RPC (now uses HAR ID)
+        result = state.client.call("fetch.resume", id=request, modifications=modifications, wait=wait)
+
+        # Build concise status line
+        har_id = result.get("id", request)
+        outcome = result.get("outcome", "unknown")
+        resumed_from = result.get("resumed_from", "unknown")
+
+        if outcome == "response":
+            status_code = result.get("status", "?")
+            summary = f"ID {har_id} → paused at Response ({status_code})"
+        elif outcome == "redirect":
+            redirect_id = result.get("redirect_id", "?")
+            summary = f"ID {har_id} → redirected to ID {redirect_id}"
+        elif outcome == "complete":
+            summary = f"ID {har_id} → complete"
+        else:
+            summary = f"ID {har_id} → resumed from {resumed_from}"
+
+        fields = {"Result": summary}
+        if result.get("remaining", 0) > 0:
+            fields["Remaining"] = f"{result['remaining']} paused"
+
+        return info_response(title="Resumed", fields=fields)
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _fail_desc or ""}
+)
+def fail(state, request: int, reason: str = "BlockedByClient") -> dict:
+    """Fail a paused request.
+
+    Args:
+        request: Request ID from network() table
+        reason: CDP error reason (default: BlockedByClient)
+                Options: Failed, Aborted, TimedOut, AccessDenied,
+                        ConnectionClosed, ConnectionReset, ConnectionRefused,
+                        ConnectionAborted, ConnectionFailed, NameNotResolved,
+                        InternetDisconnected, AddressUnreachable, BlockedByClient,
+                        BlockedByResponse
+
+    Examples:
+        fail(583)                          # Fail specific request
+        fail(583, reason="AccessDenied")  # Fail with specific reason
+
+    Returns:
+        Failure status
+    """
+    try:
+        # Get status to check if fetch is enabled
+        status = state.client.call("status")
+        if not status.get("fetch", {}).get("enabled", False):
+            return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+        # Fail via RPC (now uses HAR ID)
+        result = state.client.call("fetch.fail", id=request, reason=reason)
+
+        har_id = result.get("id", request)
+        summary = f"ID {har_id} → failed ({reason})"
+
+        fields = {"Result": summary}
+        if result.get("remaining", 0) > 0:
+            fields["Remaining"] = f"{result['remaining']} paused"
+
+        return info_response(title="Failed", fields=fields)
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _fulfill_desc or ""}
+)
+def fulfill(
+    state,
+    request: int,
+    body: str = "",
+    status: int = 200,
+    headers: list = None,  # pyright: ignore[reportArgumentType]
+) -> dict:
+    """Fulfill a paused request with a custom response.
+
+    Returns a mock response without hitting the server. Useful for:
+    - Mock API responses during development
+    - Test error handling with specific status codes
+    - Offline development without backend
+
+    Args:
+        request: Request ID from network() table
+        body: Response body content (default: empty)
+        status: HTTP status code (default: 200)
+        headers: Response headers as list of {"name": "...", "value": "..."} dicts
+
+    Examples:
+        fulfill(583)                                    # Empty 200 response
+        fulfill(583, body='{"ok": true}')              # JSON response
+        fulfill(583, body="Not Found", status=404)     # Error response
+        fulfill(583, headers=[{"name": "Content-Type", "value": "application/json"}])
+
+    Returns:
+        Fulfillment status
+    """
+    try:
+        # Get status to check if fetch is enabled
+        fetch_status = state.client.call("status")
+        if not fetch_status.get("fetch", {}).get("enabled", False):
+            return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+        # Fulfill via RPC (uses HAR ID)
+        result = state.client.call(
+            "fetch.fulfill",
+            id=request,
+            response_code=status,
+            response_headers=headers,
+            body=body,
+        )
+
+        har_id = result.get("id", request)
+        summary = f"ID {har_id} → fulfilled ({status})"
+
+        fields = {"Result": summary}
+        if result.get("remaining", 0) > 0:
+            fields["Remaining"] = f"{result['remaining']} paused"
+
+        return info_response(title="Fulfilled", fields=fields)
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))