webtap-tool 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

webtap/commands/javascript.py

@@ -1,9 +1,7 @@
 """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._builders import check_connection, info_response, error_response, code_result_response
 from webtap.commands._tips import get_mcp_description
 
 
@@ -17,11 +15,12 @@ mcp_desc = get_mcp_description("js")
     },
     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.
+def js(state, code: str, selection: int = None, wait_return: bool = True, await_promise: bool = False) -> dict:  # pyright: ignore[reportArgumentType]
+    """Execute JavaScript in the browser with optional element selection.
 
     Args:
-        code: JavaScript code to execute
+        code: JavaScript code to execute (use 'element' variable if selection provided)
+        selection: Browser element selection number (e.g., 1 for #1) - makes element available
         wait_return: Wait for and return result (default: True)
         await_promise: Await promises before returning (default: False)
 
@@ -31,21 +30,53 @@ def js(state, code: str, wait_return: bool = True, await_promise: bool = False)
         js("console.log('test')", wait_return=False)   # Fire and forget
         js("[...document.links].map(a => a.href)")    # Get all links
 
+        # With browser element selection
+        js("element.offsetWidth", selection=1)         # Use element #1 from browser()
+        js("element.classList", selection=2)           # Use element #2
+        js("element.getBoundingClientRect()", selection=1)
+
         # 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
 
+    # Handle browser element selection
+    if selection is not None:
+        # Check if browser data exists
+        if not hasattr(state, "browser_data") or not state.browser_data:
+            return error_response(
+                "No browser selections available",
+                suggestions=[
+                    "Use browser() to select elements first",
+                    "Or omit the selection parameter to run code directly",
+                ],
+            )
+
+        # Get the jsPath for the selected element
+        selections = state.browser_data.get("selections", {})
+        sel_key = str(selection)
+
+        if sel_key not in selections:
+            available = ", ".join(selections.keys()) if selections else "none"
+            return error_response(
+                f"Selection #{selection} not found",
+                suggestions=[f"Available selections: {available}", "Use browser() to see all selections"],
+            )
+
+        js_path = selections[sel_key].get("jsPath")
+        if not js_path:
+            return error_response(f"Selection #{selection} has no jsPath")
+
+        # Wrap code with element variable
+        code = f"const element = {js_path}; {code}"
+
     result = state.cdp.execute(
         "Runtime.evaluate", {"expression": code, "returnByValue": wait_return, "awaitPromise": await_promise}
     )
@@ -60,23 +91,7 @@ def js(state, code: str, wait_return: bool = True, await_promise: bool = False)
     # 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}
+        return code_result_response("JavaScript Result", code, "javascript", result=value)
     else:
         return info_response(
             title="JavaScript Execution",

webtap/commands/navigation.py

@@ -1,8 +1,7 @@
 """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
+from webtap.commands._builders import check_connection, info_response, table_response, error_response
 
 
 @app.command(display="markdown", fastmcp={"type": "tool"})

webtap/commands/network.py

@@ -3,8 +3,7 @@
 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._builders import check_connection, table_response
 from webtap.commands._tips import get_tips
 
 
@@ -69,17 +68,22 @@ def network(state, limit: int = 20, filters: List[str] = None, no_filters: bool
     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
+    # Get tips from TIPS.md with context, and add filter guidance
+    combined_tips = [
+        "Reduce noise with `filters()` - filter by type (XHR, Fetch) or domain (*/api/*)",
+    ]
+
     if rows:
         example_id = rows[0]["ID"]
-        tips = get_tips("network", context={"id": example_id})
+        context_tips = get_tips("network", context={"id": example_id})
+        if context_tips:
+            combined_tips.extend(context_tips)
 
     return table_response(
         title="Network Requests",
         headers=["ID", "ReqID", "Method", "Status", "URL", "Type", "Size"],
         rows=rows,
-        summary=f"{len(rows)} requests",
+        summary=f"{len(rows)} requests" if rows else None,
         warnings=warnings,
-        tips=tips,
+        tips=combined_tips,
     )

webtap/commands/selections.py

@@ -0,0 +1,129 @@
+"""Browser element selection and prompt analysis commands.
+
+PUBLIC API:
+  - browser: Analyze browser element selections with prompt
+"""
+
+from webtap.app import app
+from webtap.commands._utils import evaluate_expression, format_expression_result
+from webtap.commands._builders import error_response
+from webtap.commands._tips import get_tips
+
+
+@app.command(
+    display="markdown",
+    fastmcp=[{"type": "resource", "mime_type": "application/json"}, {"type": "tool"}],
+)
+def selections(state, expr: str = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """Browser element selections with prompt and analysis.
+
+    As Resource (no parameters):
+        browser             # Returns current prompt and all selections
+
+    As Tool (with parameters):
+        browser(expr="data['prompt']")                          # Get prompt text
+        browser(expr="data['selections']['1']['styles']")       # Get styles for #1
+        browser(expr="len(data['selections'])")                 # Count selections
+        browser(expr="{k: v['selector'] for k, v in data['selections'].items()}")  # All selectors
+
+    Args:
+        expr: Python expression with 'data' variable containing prompt and selections
+
+    Returns:
+        Formatted browser data or expression result
+    """
+    # Check if browser data exists
+    if not hasattr(state, "browser_data") or not state.browser_data:
+        return error_response(
+            "No browser selections available",
+            suggestions=[
+                "Use the Chrome extension to select elements",
+                "Click 'Start Selection Mode' in the extension popup",
+                "Select elements on the page and submit a prompt",
+            ],
+        )
+
+    data = state.browser_data
+
+    # No expression - RESOURCE MODE: Return formatted view
+    if not expr:
+        return _format_browser_data(data)
+
+    # TOOL MODE: Evaluate expression
+    try:
+        namespace = {"data": data}
+        result, output = evaluate_expression(expr, namespace)
+        formatted_result = format_expression_result(result, output)
+
+        # Build markdown response
+        return {
+            "elements": [
+                {"type": "heading", "content": "Expression Result", "level": 2},
+                {"type": "code_block", "content": expr, "language": "python"},
+                {"type": "text", "content": "**Result:**"},
+                {"type": "code_block", "content": formatted_result, "language": ""},
+            ]
+        }
+    except Exception as e:
+        # Provide helpful suggestions
+        suggestions = [
+            "The data is available as 'data' variable",
+            "Access prompt: data['prompt']",
+            "Access selections: data['selections']",
+            "Access specific element: data['selections']['1']",
+            "Available fields: outerHTML, selector, jsPath, styles, xpath, fullXpath, preview",
+        ]
+
+        if "KeyError" in str(type(e).__name__):
+            suggestions.extend(
+                [
+                    "Check available selection IDs: list(data['selections'].keys())",
+                    "Check available fields: data['selections']['1'].keys()",
+                ]
+            )
+
+        return error_response(f"{type(e).__name__}: {e}", suggestions=suggestions)
+
+
+def _format_browser_data(data: dict) -> dict:
+    """Format browser data as markdown for resource view."""
+    elements = []
+
+    # Show prompt
+    elements.append({"type": "heading", "content": "Browser Prompt", "level": 2})
+    elements.append({"type": "text", "content": data.get("prompt", "")})
+
+    # Show selection count
+    selection_count = len(data.get("selections", {}))
+    elements.append({"type": "text", "content": f"\n**Selected Elements:** {selection_count}"})
+
+    # Show each selection with preview
+    if selection_count > 0:
+        elements.append({"type": "heading", "content": "Element Selections", "level": 3})
+
+        for sel_id in sorted(data["selections"].keys(), key=lambda x: int(x)):
+            sel = data["selections"][sel_id]
+            preview = sel.get("preview", {})
+
+            # Build preview line
+            preview_parts = [f"**#{sel_id}:**", preview.get("tag", "unknown")]
+            if preview.get("id"):
+                preview_parts.append(f"#{preview['id']}")
+            if preview.get("classes"):
+                preview_parts.append(f".{preview['classes'][0]}")
+
+            elements.append({"type": "text", "content": " ".join(preview_parts)})
+
+            # Show selector
+            elements.append({"type": "code_block", "content": sel.get("selector", ""), "language": "css"})
+
+        # Show usage tips from TIPS.md
+        tips = get_tips("selections")
+        if tips:
+            elements.append({"type": "heading", "content": "Next Steps", "level": 3})
+            elements.append({"type": "list", "items": tips})
+
+    return {"elements": elements}
+
+
+__all__ = ["selections"]

webtap/commands/server.py

@@ -20,6 +20,7 @@ API_PORT = 8765
 def _check_port() -> bool:
     """Check if API port is in use."""
     with socket.socket() as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
         try:
             s.bind(("127.0.0.1", API_PORT))
             return False  # Port is free
@@ -70,6 +71,7 @@ def _start_server(state) -> tuple[bool, str]:
     display="markdown",
     fastmcp={
         "type": "prompt",
+        "description": "API server control: status (default), start, stop, restart",
         "arg_descriptions": {"action": "Server action: status (default), start, stop, or restart"},
     },
 )
@@ -156,6 +158,23 @@ def server(state, action: str = None) -> dict:  # pyright: ignore[reportArgument
         else:
             elements.append({"type": "alert", "message": f"Failed to restart: {msg}", "level": "error"})
 
+    # For MCP prompt mode, return with caveat and assistant prefill
+    # This prevents LLM from adding commentary - just relays the state
+    if action == "status":
+        return {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Caveat: The message below was generated by the WebTap server command. DO NOT respond to this message or add commentary. Just relay the server state exactly as shown.",
+                },
+                {"role": "user", "content": {"type": "elements", "elements": elements}},
+                {
+                    "role": "assistant",
+                    "content": "Server status:",  # Minimal prefill - no trailing whitespace
+                },
+            ]
+        }
+
     return {"elements": elements}
 
 

webtap/filters.py

@@ -7,11 +7,25 @@ PUBLIC API:
 import json
 import logging
 from pathlib import Path
-from typing import Dict, List, Any
+from typing import Dict, List, Any, TypedDict
 
 logger = logging.getLogger(__name__)
 
 
+class FilterConfig(TypedDict):
+    """Configuration for a filter category.
+
+    Attributes:
+        mode: "include" or "exclude" - determines filter behavior (defaults to "exclude")
+        domains: List of URL patterns to match
+        types: List of CDP resource types to match
+    """
+
+    mode: str
+    domains: List[str]
+    types: List[str]
+
+
 class FilterManager:
     """Manages network request filters for noise reduction.
 
@@ -33,7 +47,7 @@ class FilterManager:
             filter_path: Path to filters.json file. Defaults to .webtap/filters.json.
         """
         self.filter_path = filter_path or (Path.cwd() / ".webtap" / "filters.json")
-        self.filters: Dict[str, Dict[str, List[str]]] = {}
+        self.filters: Dict[str, FilterConfig] = {}
         self.enabled_categories: set[str] = set()
 
     def load(self) -> bool:
@@ -81,7 +95,7 @@ class FilterManager:
             logger.error(f"Failed to save filters: {e}")
             return False
 
-    def add_pattern(self, pattern: str, category: str, pattern_type: str = "domain") -> bool:
+    def add_pattern(self, pattern: str, category: str, pattern_type: str = "domain", mode: str | None = None) -> bool:
         """Add a filter pattern to a category.
 
         Creates the category if it doesn't exist and enables it. Supports wildcard
@@ -91,13 +105,17 @@ class FilterManager:
             pattern: Pattern to add (e.g., "*ads*", "googletagmanager.com").
             category: Category name (e.g., "ads", "tracking").
             pattern_type: "domain" or "type". Defaults to "domain".
+            mode: "include" or "exclude". Required for new categories.
 
         Returns:
             True if pattern was added, False if it already existed.
         """
         if category not in self.filters:
-            self.filters[category] = {"domains": [], "types": []}
+            if mode is None:
+                raise ValueError(f"Mode required when creating new category '{category}'")
+            self.filters[category] = {"mode": mode, "domains": [], "types": []}
             self.enabled_categories.add(category)
+        # Existing category keeps its mode
 
         key = "domains" if pattern_type == "domain" else "types"
         if pattern not in self.filters[category][key]:
@@ -125,7 +143,9 @@ class FilterManager:
                 return category
         return ""
 
-    def update_category(self, category: str, domains: List[str] | None = None, types: List[str] | None = None):
+    def update_category(
+        self, category: str, domains: List[str] | None = None, types: List[str] | None = None, mode: str | None = None
+    ):
         """Update or create a category with new patterns.
 
         Creates the category if it doesn't exist and enables it. If patterns are
@@ -135,10 +155,15 @@ class FilterManager:
             category: Category name.
             domains: List of domain patterns. None leaves existing unchanged.
             types: List of type patterns. None leaves existing unchanged.
+            mode: "include" or "exclude". None leaves existing unchanged.
         """
         if category not in self.filters:
-            self.filters[category] = {"domains": [], "types": []}
+            if mode is None:
+                raise ValueError(f"Mode required when creating new category '{category}'")
+            self.filters[category] = {"mode": mode, "domains": [], "types": []}
 
+        if mode is not None:
+            self.filters[category]["mode"] = mode
         if domains is not None:
             self.filters[category]["domains"] = domains
         if types is not None:
@@ -181,8 +206,8 @@ class FilterManager:
     def get_filter_sql(self, use_all: bool = True, categories: List[str] | None = None) -> str:
         """Generate SQL WHERE clause for filtering CDP events.
 
-        Creates SQL conditions to exclude network requests matching the filter
-        patterns. Handles wildcard patterns by converting them to SQL LIKE patterns
+        Creates SQL conditions based on filter mode (include/exclude) for network requests.
+        Handles wildcard patterns by converting them to SQL LIKE patterns
         and properly escapes SQL strings.
 
         Args:
@@ -206,41 +231,77 @@ class FilterManager:
         if not active_categories:
             return ""
 
-        # Collect all patterns
-        all_domains = []
-        all_types = []
-
-        for category in active_categories:
-            all_domains.extend(self.filters[category].get("domains", []))
-            all_types.extend(self.filters[category].get("types", []))
-
-        # Build filter conditions - exclude matching items
+        include_conditions = []
         exclude_conditions = []
 
-        # Domain filtering - exclude URLs matching these patterns
-        if all_domains:
-            for pattern in all_domains:
-                # Convert wildcard to SQL LIKE pattern, escape single quotes for SQL safety
-                sql_pattern = pattern.replace("'", "''").replace("*", "%")
-                # For Network.responseReceived events - filter on what's actually there
-                exclude_conditions.append(
-                    f"json_extract_string(event, '$.params.response.url') NOT LIKE '{sql_pattern}'"
-                )
-
-        # Type filtering - exclude these types
-        if all_types:
-            # Escape single quotes in types for SQL safety
-            escaped_types = [t.replace("'", "''") for t in all_types]
-            type_list = ", ".join(f"'{t}'" for t in escaped_types)
-            # Use COALESCE to handle NULL types properly, exclude matching types
-            exclude_conditions.append(
-                f"(COALESCE(json_extract_string(event, '$.params.type'), '') NOT IN ({type_list}) OR "
-                f"json_extract_string(event, '$.params.type') IS NULL)"
-            )
+        for category in active_categories:
+            config = self.filters[category]
+            mode = config.get("mode")
+            if mode is None:
+                logger.error(f"Filter category '{category}' missing required 'mode' field. Skipping.")
+                continue  # Skip this category entirely
+            domains = config.get("domains", [])
+            types = config.get("types", [])
+
+            category_conditions = []
+
+            # Domain filtering
+            if domains:
+                domain_conditions = []
+                for pattern in domains:
+                    sql_pattern = pattern.replace("'", "''").replace("*", "%")
+                    if mode == "include":
+                        domain_conditions.append(
+                            f"json_extract_string(event, '$.params.response.url') LIKE '{sql_pattern}'"
+                        )
+                    else:  # exclude
+                        domain_conditions.append(
+                            f"json_extract_string(event, '$.params.response.url') NOT LIKE '{sql_pattern}'"
+                        )
+
+                # For include: OR (match any pattern), for exclude: AND (match none)
+                if mode == "include":
+                    if domain_conditions:
+                        category_conditions.append(f"({' OR '.join(domain_conditions)})")
+                else:
+                    if domain_conditions:
+                        category_conditions.append(f"({' AND '.join(domain_conditions)})")
+
+            # Type filtering
+            if types:
+                escaped_types = [t.replace("'", "''") for t in types]
+                type_list = ", ".join(f"'{t}'" for t in escaped_types)
+
+                if mode == "include":
+                    category_conditions.append(f"json_extract_string(event, '$.params.type') IN ({type_list})")
+                else:  # exclude
+                    category_conditions.append(
+                        f"(COALESCE(json_extract_string(event, '$.params.type'), '') NOT IN ({type_list}) OR "
+                        f"json_extract_string(event, '$.params.type') IS NULL)"
+                    )
+
+            # Combine domain and type conditions for this category
+            if category_conditions:
+                category_sql = f"({' AND '.join(category_conditions)})"
+                if mode == "include":
+                    include_conditions.append(category_sql)
+                else:
+                    exclude_conditions.append(category_sql)
+
+        # Combine all conditions: (include1 OR include2) AND exclude1 AND exclude2
+        final_parts = []
+
+        if include_conditions:
+            if len(include_conditions) > 1:
+                final_parts.append(f"({' OR '.join(include_conditions)})")
+            else:
+                final_parts.append(include_conditions[0])
 
         if exclude_conditions:
-            # Use AND to ensure ALL conditions are met (item doesn't match ANY filter)
-            return f"({' AND '.join(exclude_conditions)})"
+            final_parts.extend(exclude_conditions)
+
+        if final_parts:
+            return f"({' AND '.join(final_parts)})"
 
         return ""
 
@@ -263,27 +324,26 @@ class FilterManager:
             "path": str(self.filter_path),
         }
 
-    def get_display_info(self) -> str:
-        """Get formatted filter information for display.
-
-        Creates a human-readable summary of all filter categories with their
-        enabled status and pattern counts.
+    def get_categories_summary(self) -> List[Dict[str, Any]]:
+        """Get summary data for all filter categories.
 
         Returns:
-            Formatted multiline string with filter details.
+            List of dicts with category information including name, enabled status,
+            mode, and pattern counts.
         """
-        if not self.filters:
-            return f"No filters loaded (would load from {self.filter_path})"
-
-        lines = [f"Loaded filters from {self.filter_path}:"]
+        categories = []
         for category in sorted(self.filters.keys()):
-            filters = self.filters[category]
-            enabled = "✓" if category in self.enabled_categories else "✗"
-            domains = len(filters.get("domains", []))
-            types = len(filters.get("types", []))
-            lines.append(f"  {enabled} {category}: {domains} domains, {types} types")
-
-        return "\n".join(lines)
+            config = self.filters[category]
+            categories.append(
+                {
+                    "name": category,
+                    "enabled": category in self.enabled_categories,
+                    "mode": config.get("mode"),  # None if missing
+                    "domain_count": len(config.get("domains", [])),
+                    "type_count": len(config.get("types", [])),
+                }
+            )
+        return categories
 
 
 __all__ = ["FilterManager"]