webtap-tool 0.1.1__py3-none-any.whl

webtap/commands/events.py

@@ -0,0 +1,109 @@
+"""CDP event querying with dynamic field discovery."""
+
+from webtap.app import app
+from webtap.cdp import build_query
+from webtap.commands._errors import check_connection
+from webtap.commands._builders import table_response
+from webtap.commands._tips import get_tips, get_mcp_description
+
+
+mcp_desc = get_mcp_description("events")
+
+
+@app.command(
+    display="markdown",
+    truncate={
+        "Value": {"max": 80, "mode": "end"}  # Only truncate values for display
+    },
+    fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"},
+)
+def events(state, filters: dict = None, limit: int = 20) -> dict:  # pyright: ignore[reportArgumentType]
+    """
+    Query CDP events by field values with automatic discovery.
+
+    Searches across ALL event types - network, console, page, etc.
+    Field names are discovered automatically and case-insensitive.
+
+    Args:
+        filters: Field filters to apply
+            - {"method": "Network.*"} - Events matching pattern
+            - {"status": 200, "method": "Network.responseReceived"}
+            - {"url": "*"} - Extract field without filtering
+        limit: Maximum results (default: 20)
+
+    Examples:
+        events()                                    # Recent 20 events
+        events({"method": "Runtime.*"})            # Runtime events
+        events({"requestId": "123"}, limit=100)    # Specific request
+        events({"url": "*api*"})                   # Find all API calls
+        events({"status": 200})                    # Find successful responses
+        events({"method": "POST", "url": "*login*"}) # POST requests to login
+        events({"level": "error"})                # Console errors
+        events({"type": "Document"})              # Page navigations
+        events({"headers": "*"})                  # Extract all header fields
+
+    Returns:
+        Table showing rowid and extracted field values in markdown
+    """
+    # Check connection - return error dict if not connected
+    if error := check_connection(state):
+        return error
+
+    # Use filters dict, default to empty
+    fields = filters or {}
+
+    # Build query using the query module with fuzzy field discovery
+    sql, discovered_fields = build_query(state.cdp, fields, limit=limit)
+
+    # If no fields discovered, return empty
+    if not discovered_fields or not any(discovered_fields.values()):
+        return table_response(
+            title="Event Query Results", headers=["ID", "Field", "Value"], rows=[], summary="No matching fields found"
+        )
+
+    # Execute query
+    results = state.cdp.query(sql)
+
+    # Process results into rows with FULL data
+    rows = []
+    for result_row in results:
+        rowid = result_row[0]
+        col_index = 1  # Skip rowid column
+
+        for field_name, field_paths in discovered_fields.items():
+            for field_path in field_paths:
+                if col_index < len(result_row):
+                    value = result_row[col_index]
+                    if value is not None:
+                        rows.append(
+                            {
+                                "ID": str(rowid),
+                                "Field": field_path,
+                                "Value": str(value),  # Full value, no truncation
+                            }
+                        )
+                    col_index += 1
+
+    # Build warnings if needed
+    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
+    tips = None
+    if rows:
+        # Get unique event IDs for examples
+        event_ids = list(set(row["ID"] for row in rows))[:1]
+        if event_ids:
+            example_id = event_ids[0]
+            tips = get_tips("events", context={"id": example_id})
+
+    # Build markdown response
+    return table_response(
+        title="Event Query Results",
+        headers=["ID", "Field", "Value"],
+        rows=rows,
+        summary=f"{len(rows)} field values from {len(results)} events",
+        warnings=warnings,
+        tips=tips,
+    )

webtap/commands/fetch.py

@@ -0,0 +1,219 @@
+"""HTTP fetch request interception and debugging commands."""
+
+from webtap.app import app
+from webtap.commands._errors import check_connection
+from webtap.commands._builders import error_response, info_response, table_response
+from webtap.commands._tips import get_tips
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+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
+    """
+    fetch_service = state.service.fetch
+
+    if action == "disable":
+        result = fetch_service.disable()
+        if "error" in result:
+            return error_response(result["error"])
+        return info_response(title="Fetch Disabled", fields={"Status": "Interception disabled"})
+
+    elif action == "enable":
+        # Check connection first
+        if error := check_connection(state):
+            return error
+
+        opts = options or {}
+        response_stage = opts.get("response", False)
+
+        result = fetch_service.enable(state.cdp, response_stage=response_stage)
+        if "error" in result:
+            return error_response(result["error"])
+        return info_response(
+            title="Fetch Enabled",
+            fields={
+                "Stages": result.get("stages", "Request stage only"),
+                "Status": "Requests will pause",
+            },
+        )
+
+    elif action == "status":
+        # Show status
+        return info_response(
+            title=f"Fetch Status: {'Enabled' if fetch_service.enabled else 'Disabled'}",
+            fields={
+                "Status": "Enabled" if fetch_service.enabled else "Disabled",
+                "Paused": f"{fetch_service.paused_count} requests paused" if fetch_service.enabled else "None",
+            },
+        )
+
+    else:
+        return error_response(f"Unknown action: {action}")
+
+
+@app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "application/json"})
+def requests(state, limit: int = 50) -> dict:
+    """Show paused requests and responses.
+
+    Lists all paused HTTP traffic. Use the ID with inspect() to examine
+    details or resume() / fail() to proceed.
+
+    Args:
+        limit: Maximum items to show
+
+    Examples:
+        requests()           # Show all paused
+        inspect(event=47)    # Examine request with rowid 47
+        resume(47)           # Continue request 47
+
+    Returns:
+        Table of paused requests/responses in markdown
+    """
+    # Check connection first
+    if error := check_connection(state):
+        return error
+
+    fetch_service = state.service.fetch
+
+    if not fetch_service.enabled:
+        return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+    rows = fetch_service.get_paused_list()
+
+    # Apply limit
+    if limit and len(rows) > limit:
+        rows = rows[:limit]
+
+    # Build warnings if needed
+    warnings = []
+    if limit and len(rows) == limit:
+        warnings.append(f"Showing first {limit} paused requests (use limit parameter to see more)")
+
+    # Get tips from TIPS.md
+    tips = None
+    if rows:
+        example_id = rows[0]["ID"]
+        tips = get_tips("requests", context={"id": example_id})
+
+    # Build markdown response
+    return table_response(
+        title="Paused Requests",
+        headers=["ID", "Stage", "Method", "Status", "URL"],
+        rows=rows,
+        summary=f"{len(rows)} requests paused",
+        warnings=warnings,
+        tips=tips,
+    )
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+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 row ID from requests() 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(123)                               # Simple resume
+        resume(123, wait=1.0)                    # Wait for redirect
+        resume(123, modifications={"url": "..."})  # Change URL
+        resume(123, modifications={"method": "POST"})  # Change method
+        resume(123, modifications={"headers": [{"name":"X-Custom","value":"test"}]})
+
+    Returns:
+        Continuation status with any follow-up events detected
+    """
+    fetch_service = state.service.fetch
+
+    if not fetch_service.enabled:
+        return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+    mods = modifications or {}
+    result = fetch_service.continue_request(request, mods, wait_for_next=wait)
+
+    if "error" in result:
+        return error_response(result["error"])
+
+    fields = {"Stage": result["stage"], "Continued": f"Row {result['continued']}"}
+
+    # Report follow-up if detected
+    if next_event := result.get("next_event"):
+        fields["Next Event"] = next_event["description"]
+        fields["Next ID"] = str(next_event["rowid"])
+        if next_event.get("status"):
+            fields["Status"] = next_event["status"]
+
+    if result.get("remaining"):
+        fields["Remaining"] = f"{result['remaining']} requests paused"
+
+    return info_response(title="Request Resumed", fields=fields)
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def fail(state, request: int, reason: str = "BlockedByClient") -> dict:
+    """Fail a paused request.
+
+    Args:
+        request: Row ID from requests() table
+        reason: CDP error reason (default: BlockedByClient)
+                Options: Failed, Aborted, TimedOut, AccessDenied,
+                        ConnectionClosed, ConnectionReset, ConnectionRefused,
+                        ConnectionAborted, ConnectionFailed, NameNotResolved,
+                        InternetDisconnected, AddressUnreachable, BlockedByClient,
+                        BlockedByResponse
+
+    Examples:
+        fail(47)                          # Fail specific request
+        fail(47, reason="AccessDenied")  # Fail with specific reason
+
+    Returns:
+        Failure status
+    """
+    fetch_service = state.service.fetch
+
+    if not fetch_service.enabled:
+        return error_response("Fetch interception is disabled. Use fetch('enable') first.")
+
+    result = fetch_service.fail_request(request, reason)
+
+    if "error" in result:
+        return error_response(result["error"])
+
+    fields = {"Failed": f"Row {result['failed']}", "Reason": result["reason"]}
+    if result.get("remaining") is not None:
+        fields["Remaining"] = f"{result['remaining']} requests paused"
+
+    return info_response(title="Request Failed", fields=fields)

webtap/commands/filters.py

@@ -0,0 +1,224 @@
+"""Network request filtering and categorization management commands."""
+
+from webtap.app import app
+from webtap.commands._builders import info_response, error_response
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def filters(state, action: str = "list", config: dict = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """
+    Manage network request filters.
+
+    Filters are managed by the service and can be persisted to .webtap/filters.json.
+
+    Args:
+        action: Filter operation
+            - "list" - List all filter categories (default)
+            - "show" - Show specific category details
+            - "add" - Add patterns to category
+            - "remove" - Remove patterns from category
+            - "update" - Update entire category
+            - "delete" - Delete entire category
+            - "enable" - Enable category
+            - "disable" - Disable category
+            - "save" - Save filters to disk
+            - "load" - Load filters from disk
+        config: Action-specific configuration
+            - For show: {"category": "ads"}
+            - For add: {"category": "ads", "patterns": ["*ad*"], "type": "domain"}
+            - For remove: {"patterns": ["*ad*"], "type": "domain"}
+            - For update: {"category": "ads", "domains": [...], "types": [...]}
+            - For delete/enable/disable: {"category": "ads"}
+
+    Examples:
+        filters()                                          # List all categories
+        filters("list")                                    # Same as above
+        filters("show", {"category": "ads"})              # Show ads category details
+        filters("add", {"category": "ads",
+                "patterns": ["*doubleclick*"]})           # Add domain pattern
+        filters("add", {"category": "tracking",
+                "patterns": ["Ping"], "type": "type"})    # Add type pattern
+        filters("remove", {"patterns": ["*doubleclick*"]}) # Remove pattern
+        filters("update", {"category": "ads",
+                "domains": ["*google*", "*facebook*"]})   # Replace patterns
+        filters("delete", {"category": "ads"})            # Delete category
+        filters("save")                                   # Persist to disk
+        filters("load")                                   # Load from disk
+
+    Returns:
+        Current filter configuration or operation result
+    """
+    fm = state.service.filters
+    cfg = config or {}
+
+    # Handle load operation
+    if action == "load":
+        if fm.load():
+            # Convert display info to markdown
+            display_info = fm.get_display_info()
+            return {
+                "elements": [
+                    {"type": "heading", "content": "Filters Loaded", "level": 2},
+                    {"type": "code_block", "content": display_info, "language": ""},
+                ]
+            }
+        else:
+            return error_response(f"No filters found at {fm.filter_path}")
+
+    # Handle save operation
+    elif action == "save":
+        if fm.save():
+            return info_response(
+                title="Filters Saved", fields={"Categories": f"{len(fm.filters)}", "Path": str(fm.filter_path)}
+            )
+        else:
+            return error_response("Failed to save filters")
+
+    # Handle add operation
+    elif action == "add":
+        if not cfg:
+            return error_response("Config required for add action")
+
+        category = cfg.get("category", "custom")
+        patterns = cfg.get("patterns", [])
+        pattern_type = cfg.get("type", "domain")
+
+        if not patterns:
+            # Legacy single pattern support
+            if pattern_type == "domain" and "domain" in cfg:
+                patterns = [cfg["domain"]]
+            elif pattern_type == "type" and "type" in cfg:
+                patterns = [cfg["type"]]
+            else:
+                return error_response("Patterns required for add action")
+
+        added = []
+        failed = []
+        for pattern in patterns:
+            if fm.add_pattern(pattern, category, pattern_type):
+                added.append(pattern)
+            else:
+                failed.append(pattern)
+
+        if added and not failed:
+            return info_response(
+                title="Filter(s) Added",
+                fields={
+                    "Type": "Domain pattern" if pattern_type == "domain" else "Resource type",
+                    "Patterns": ", ".join(added),
+                    "Category": category,
+                },
+            )
+        elif failed:
+            return error_response(f"Pattern(s) already exist in category '{category}': {', '.join(failed)}")
+        else:
+            # This shouldn't happen unless patterns list was empty after all
+            return error_response("No valid patterns provided")
+
+    # Handle remove operation
+    elif action == "remove":
+        if not cfg:
+            return error_response("Config required for remove action")
+
+        patterns = cfg.get("patterns", [])
+        pattern_type = cfg.get("type", "domain")
+
+        if not patterns:
+            return error_response("Patterns required for remove action")
+
+        removed = []
+        for pattern in patterns:
+            category = fm.remove_pattern(pattern, pattern_type)
+            if category:
+                removed.append((pattern, category))
+
+        if removed:
+            return info_response(
+                title="Filter(s) Removed",
+                fields={
+                    "Type": "Domain pattern" if pattern_type == "domain" else "Resource type",
+                    "Removed": ", ".join(f"{p} from {c}" for p, c in removed),
+                },
+            )
+        else:
+            return error_response("Pattern(s) not found")
+
+    # Handle update operation
+    elif action == "update":
+        if not cfg or "category" not in cfg:
+            return error_response("'category' required for update action")
+
+        category = cfg["category"]
+        fm.update_category(category, domains=cfg.get("domains"), types=cfg.get("types"))
+        return info_response(title="Category Updated", fields={"Category": category})
+
+    # Handle delete operation
+    elif action == "delete":
+        if not cfg or "category" not in cfg:
+            return error_response("'category' required for delete action")
+
+        category = cfg["category"]
+        if fm.delete_category(category):
+            return info_response(title="Category Deleted", fields={"Category": category})
+        return error_response(f"Category '{category}' not found")
+
+    # Handle enable operation
+    elif action == "enable":
+        if not cfg or "category" not in cfg:
+            return error_response("'category' required for enable action")
+
+        category = cfg["category"]
+        if category in fm.filters:
+            fm.enabled_categories.add(category)
+            return info_response(title="Category Enabled", fields={"Category": category})
+        return error_response(f"Category '{category}' not found")
+
+    # Handle disable operation
+    elif action == "disable":
+        if not cfg or "category" not in cfg:
+            return error_response("'category' required for disable action")
+
+        category = cfg["category"]
+        if category in fm.filters:
+            fm.enabled_categories.discard(category)
+            return info_response(title="Category Disabled", fields={"Category": category})
+        return error_response(f"Category '{category}' not found")
+
+    # Handle show operation (specific category)
+    elif action == "show":
+        if not cfg or "category" not in cfg:
+            return error_response("'category' required for show action")
+
+        category = cfg["category"]
+        if category in fm.filters:
+            filters = fm.filters[category]
+            enabled = "Enabled" if category in fm.enabled_categories else "Disabled"
+
+            elements = [
+                {"type": "heading", "content": f"Category: {category}", "level": 2},
+                {"type": "text", "content": f"**Status:** {enabled}"},
+            ]
+
+            if filters.get("domains"):
+                elements.append({"type": "text", "content": "**Domain Patterns:**"})
+                elements.append({"type": "list", "items": filters["domains"]})
+
+            if filters.get("types"):
+                elements.append({"type": "text", "content": "**Resource Types:**"})
+                elements.append({"type": "list", "items": filters["types"]})
+
+            return {"elements": elements}
+        return error_response(f"Category '{category}' not found")
+
+    # Default list action: show all filters
+    elif action == "list" or action == "":
+        display_info = fm.get_display_info()
+        return {
+            "elements": [
+                {"type": "heading", "content": "Filter Configuration", "level": 2},
+                {"type": "code_block", "content": display_info, "language": ""},
+            ]
+        }
+
+    else:
+        return error_response(f"Unknown action: {action}")