webtap-tool 0.2.3__tar.gz → 0.4.0__tar.gz

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/CHANGELOG.md

@@ -15,6 +15,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.4.0] - 2025-09-28
+
+### Added
+- Filter mode support: `include` and `exclude` modes for fine-grained request filtering
+- TypedDict for filter configuration ensuring type safety
+- Filter tip in `network()` command showing example usage
+- Markdown table display for filter categories replacing code blocks
+- CDP resource types documentation in filter command
+
+### Changed
+- **BREAKING**: Filter categories now require explicit `mode` field ("include" or "exclude")
+- **BREAKING**: Updated to ReplKit2 v0.12.0 - using `mcp_config` instead of `fastmcp` parameter
+- Filter core returns data (`get_categories_summary()`) instead of formatted strings
+- Presentation logic moved from FilterManager to command layer
+- Server command uses assistant prefill to prevent LLM commentary
+
+### Fixed
+- Alert element in network command now uses correct `message` field instead of `content`
+- Type annotations for optional parameters properly use `str | None`
+
+### Removed
+- Backward compatibility for filters without mode field
+- Emoji icons in filter display, using plain text indicators instead
+
+## [0.3.0] - 2025-09-19
+
+### Added
+- New `server` command for explicit API server management (start/stop/restart/status)
+- Server command implemented as MCP prompt returning markdown status information
+
+### Changed
+- **BREAKING**: API server no longer starts automatically - must be started explicitly with `server('start')`
+- API server management is now explicit and user-controlled
+
+### Fixed
+
+### Removed
+- Automatic API server startup on webtap launch
+- `/release` endpoint from API (no longer needed with explicit server management)
+
+## [0.2.4] - 2025-09-19
+
+### Added
+- New `server` command for explicit API server management (start/stop/restart/status)
+- Server command implemented as MCP prompt returning markdown status information
+
+### Changed
+- API server no longer starts automatically - must be started explicitly with `server('start')`
+- API server management is now explicit and user-controlled
+
+### Fixed
+
+### Removed
+- Automatic API server startup on webtap launch
+- `/release` endpoint from API (no longer needed with explicit server management)
+
 ## [0.2.3] - 2025-09-12
 
 ### Added

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webtap-tool
-Version: 0.2.3
+Version: 0.4.0
 Summary: Terminal-based web page inspector for AI debugging sessions
 Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
 Classifier: Development Status :: 3 - Alpha
@@ -21,7 +21,7 @@ Requires-Dist: platformdirs>=4.4.0
 Requires-Dist: protobuf>=6.32.0
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: replkit2[all]>=0.11.0
+Requires-Dist: replkit2[all]>=0.12.0
 Requires-Dist: requests>=2.32.4
 Requires-Dist: uvicorn>=0.35.0
 Requires-Dist: websocket-client>=1.8.0

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/extension/popup.html

@@ -150,15 +150,6 @@
 
     <div class="divider"></div>
 
-    <button
-      id="switchInstance"
-      style="width: 100%; font-size: 11px; margin-bottom: 8px"
-    >
-      Switch WebTap Instance
-    </button>
-
-    <div class="divider"></div>
-
     <div class="filter-section">
       <div
         style="

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/extension/popup.js

@@ -1,7 +1,7 @@
-// API helper - communicate with WebTap service
+// API helper - communicate with WebTap service on port 8765
 async function api(endpoint, method = "GET", body = null) {
   try {
-    const opts = { 
+    const opts = {
       method,
       // Add timeout to detect unresponsive server faster
       signal: AbortSignal.timeout(3000)
@@ -40,9 +40,6 @@ async function loadPages() {
     return;
   }
 
-  // Update instance info tooltip
-  document.getElementById("switchInstance").title =
-    `PID: ${info.pid} | Events: ${info.events}`;
 
   const pages = info.pages || [];
   const select = document.getElementById("pageList");
@@ -266,26 +263,6 @@ document.getElementById("disableAllFilters").onclick = async () => {
   setTimeout(updateFilters, 100);
 };
 
-// Switch to a different WebTap instance
-document.getElementById("switchInstance").onclick = async () => {
-  const result = await api("/release", "POST");
-  if (!result.error) {
-    document.getElementById("status").innerHTML =
-      '<span style="color: #666">Port released. Start new WebTap.</span>';
-    // Disable controls until reconnected
-    document.getElementById("connect").disabled = true;
-    document.getElementById("disconnect").disabled = true;
-    document.getElementById("fetchToggle").disabled = true;
-    // Try to reconnect after delay
-    setTimeout(() => {
-      loadPages();
-      updateStatus();
-    }, 2000);
-  } else {
-    document.getElementById("status").innerHTML =
-      `<span class="error">Error: ${result.error}</span>`;
-  }
-};
 
 // Update all status from server - single source of truth
 async function updateStatus() {

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webtap-tool"
-version = "0.2.3"
+version = "0.4.0"
 description = "Terminal-based web page inspector for AI debugging sessions"
 readme = "README.md"
 authors = [
@@ -27,7 +27,7 @@ dependencies = [
     "protobuf>=6.32.0",
     "pyjwt>=2.10.1",
     "pyyaml>=6.0.2",
-    "replkit2[all]>=0.11.0",
+    "replkit2[all]>=0.12.0",
     "requests>=2.32.4",
     "uvicorn>=0.35.0",
     "websocket-client>=1.8.0",
@@ -51,3 +51,13 @@ build-backend = "hatchling.build"
 
 [tool.uv.sources]
 replkit2 = { path = "../../../replkit2", editable = true }
+
+[tool.basedpyright]
+typeCheckingMode = "standard"
+pythonVersion = "3.12"
+pythonPlatform = "Linux"
+include = ["src/**/*.py"]
+
+[tool.ruff]
+line-length = 120
+include = ["src/**/*.py"]

webtap_tool-0.4.0/src/webtap/__init__.py

@@ -0,0 +1,39 @@
+"""WebTap - Chrome DevTools Protocol REPL.
+
+Main entry point for WebTap browser debugging tool. Provides both REPL and MCP
+functionality for Chrome DevTools Protocol interaction with native CDP event
+storage and on-demand querying.
+
+PUBLIC API:
+  - app: Main ReplKit2 App instance
+  - main: Entry point function for CLI
+"""
+
+import sys
+
+from webtap.app import app
+
+
+def main():
+    """Entry point for the WebTap REPL.
+
+    Starts in one of three modes:
+    - CLI mode (with --cli flag) for command-line interface
+    - MCP mode (with --mcp flag) for Model Context Protocol server
+    - REPL mode (default) for interactive shell
+
+    The API server for Chrome extension communication must be started
+    explicitly using the server('start') command.
+    """
+    if "--mcp" in sys.argv:
+        app.mcp.run()
+    elif "--cli" in sys.argv:
+        # Remove --cli from argv before passing to Typer
+        sys.argv.remove("--cli")
+        app.cli()  # Run CLI mode via Typer
+    else:
+        # Run REPL
+        app.run(title="WebTap - Chrome DevTools Protocol REPL")
+
+
+__all__ = ["app", "main"]

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/src/webtap/api.py

@@ -199,21 +199,6 @@ async def disable_all_filters() -> Dict[str, Any]:
     return {"enabled": [], "total": 0}
 
 
-@api.post("/release")
-async def release_port() -> Dict[str, Any]:
-    """Release API port for another WebTap instance."""
-    logger.info("Releasing API port for another instance")
-
-    # Schedule graceful shutdown after response
-    def shutdown():
-        # Just set the flag to stop uvicorn, don't kill the whole process
-        global _shutdown_requested
-        _shutdown_requested = True
-
-    threading.Timer(0.5, shutdown).start()
-    return {"message": "Releasing port 8765"}
-
-
 # Flag to signal shutdown
 _shutdown_requested = False
 

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/src/webtap/app.py

@@ -56,10 +56,9 @@ class WebTapState:
 app = App(
     "webtap",
     WebTapState,
-    uri_scheme="webtap",
-    fastmcp={
-        "description": "Chrome DevTools Protocol debugger",
-        "tags": {"browser", "debugging", "chrome", "cdp"},
+    mcp_config={
+        "uri_scheme": "webtap",
+        "instructions": "Chrome DevTools Protocol debugger",
     },
     typer_config={
         "add_completion": False,  # Hide shell completion options
@@ -84,6 +83,7 @@ else:
     from webtap.commands import inspect  # noqa: E402, F401
     from webtap.commands import fetch  # noqa: E402, F401
     from webtap.commands import body  # noqa: E402, F401
+    from webtap.commands import server  # noqa: E402, F401
     from webtap.commands import setup  # noqa: E402, F401
     from webtap.commands import launch  # noqa: E402, F401
 

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/src/webtap/commands/filters.py

@@ -7,46 +7,19 @@ 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
+    Manage network request filters with include/exclude modes.
+
+    CDP Types: Document, XHR, Fetch, Image, Stylesheet, Script, Font, Media, Other, Ping
+    Domains filter URLs, types filter Chrome's resource loading mechanism.
+
+    Actions:
+        list: Show all categories (default)
+        show: Display category - config: {"category": "api"}
+        add: Add patterns - config: {"category": "api", "patterns": ["*api*"], "type": "domain", "mode": "include"}
+        remove: Remove patterns - config: {"patterns": ["*api*"], "type": "domain"}
+        update: Replace category - config: {"category": "api", "mode": "include", "domains": [...], "types": ["XHR", "Fetch"]}
+        delete/enable/disable: Manage category - config: {"category": "api"}
+        save/load: Persist to/from disk
     """
     fm = state.service.filters
     cfg = config or {}
@@ -54,14 +27,35 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
     # 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": ""},
-                ]
-            }
+            # Build table data
+            categories = fm.get_categories_summary()
+            rows = []
+            for cat in categories:
+                mode = cat["mode"] or "exclude"
+                mode_display = "include" if mode == "include" else "exclude"
+                if cat["mode"] is None:
+                    mode_display = "exclude*"  # Asterisk indicates missing mode field
+
+                rows.append(
+                    {
+                        "Category": cat["name"],
+                        "Status": "enabled" if cat["enabled"] else "disabled",
+                        "Mode": mode_display,
+                        "Domains": str(cat["domain_count"]),
+                        "Types": str(cat["type_count"]),
+                    }
+                )
+
+            elements = [
+                {"type": "heading", "content": "Filters Loaded", "level": 2},
+                {"type": "text", "content": f"From: `{fm.filter_path}`"},
+                {"type": "table", "headers": ["Category", "Status", "Mode", "Domains", "Types"], "rows": rows},
+            ]
+
+            if any(cat["mode"] is None for cat in categories):
+                elements.append({"type": "text", "content": "_* Mode not specified, defaulting to exclude_"})
+
+            return {"elements": elements}
         else:
             return error_response(f"No filters found at {fm.filter_path}")
 
@@ -82,6 +76,7 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
         category = cfg.get("category", "custom")
         patterns = cfg.get("patterns", [])
         pattern_type = cfg.get("type", "domain")
+        mode = cfg.get("mode")  # Required, no default
 
         if not patterns:
             # Legacy single pattern support
@@ -94,11 +89,14 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
 
         added = []
         failed = []
-        for pattern in patterns:
-            if fm.add_pattern(pattern, category, pattern_type):
-                added.append(pattern)
-            else:
-                failed.append(pattern)
+        try:
+            for pattern in patterns:
+                if fm.add_pattern(pattern, category, pattern_type, mode):
+                    added.append(pattern)
+                else:
+                    failed.append(pattern)
+        except ValueError as e:
+            return error_response(str(e))
 
         if added and not failed:
             return info_response(
@@ -107,6 +105,7 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
                     "Type": "Domain pattern" if pattern_type == "domain" else "Resource type",
                     "Patterns": ", ".join(added),
                     "Category": category,
+                    "Mode": mode,
                 },
             )
         elif failed:
@@ -149,8 +148,10 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
             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})
+        fm.update_category(category, domains=cfg.get("domains"), types=cfg.get("types"), mode=cfg.get("mode"))
+        return info_response(
+            title="Category Updated", fields={"Category": category, "Mode": cfg.get("mode", "exclude")}
+        )
 
     # Handle delete operation
     elif action == "delete":
@@ -193,10 +194,12 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
         if category in fm.filters:
             filters = fm.filters[category]
             enabled = "Enabled" if category in fm.enabled_categories else "Disabled"
+            mode = filters.get("mode", "exclude")
 
             elements = [
                 {"type": "heading", "content": f"Category: {category}", "level": 2},
                 {"type": "text", "content": f"**Status:** {enabled}"},
+                {"type": "text", "content": f"**Mode:** {mode}"},
             ]
 
             if filters.get("domains"):
@@ -212,13 +215,43 @@ def filters(state, action: str = "list", config: dict = None) -> dict:  # pyrigh
 
     # 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": ""},
-            ]
-        }
+        if not fm.filters:
+            return {
+                "elements": [
+                    {"type": "heading", "content": "Filter Configuration", "level": 2},
+                    {"type": "text", "content": f"No filters loaded (would load from `{fm.filter_path}`)"},
+                    {"type": "text", "content": "Use `filters('load')` to load filters from disk"},
+                ]
+            }
+
+        # Build table data
+        categories = fm.get_categories_summary()
+        rows = []
+        for cat in categories:
+            mode = cat["mode"] or "exclude"
+            mode_display = "include" if mode == "include" else "exclude"
+            if cat["mode"] is None:
+                mode_display = "exclude*"
+
+            rows.append(
+                {
+                    "Category": cat["name"],
+                    "Status": "enabled" if cat["enabled"] else "disabled",
+                    "Mode": mode_display,
+                    "Domains": str(cat["domain_count"]),
+                    "Types": str(cat["type_count"]),
+                }
+            )
+
+        elements = [
+            {"type": "heading", "content": "Filter Configuration", "level": 2},
+            {"type": "table", "headers": ["Category", "Status", "Mode", "Domains", "Types"], "rows": rows},
+        ]
+
+        if any(cat["mode"] is None for cat in categories):
+            elements.append({"type": "text", "content": "_* Mode not specified, defaulting to exclude_"})
+
+        return {"elements": elements}
 
     else:
         return error_response(f"Unknown action: {action}")

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/src/webtap/commands/network.py

@@ -3,7 +3,6 @@
 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
 
@@ -75,11 +74,34 @@ def network(state, limit: int = 20, filters: List[str] = None, no_filters: bool
         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,
+    # Build response elements manually to add filter tip
+    elements = []
+    elements.append({"type": "heading", "content": "Network Requests", "level": 2})
+
+    for warning in warnings or []:
+        elements.append({"type": "alert", "message": warning, "level": "warning"})
+
+    if rows:
+        elements.append(
+            {"type": "table", "headers": ["ID", "ReqID", "Method", "Status", "URL", "Type", "Size"], "rows": rows}
+        )
+    else:
+        elements.append({"type": "text", "content": "_No data available_"})
+
+    if f"{len(rows)} requests":
+        elements.append({"type": "text", "content": f"_{len(rows)} requests_"})
+
+    # Always show filter tip demonstrating both type AND domain filtering
+    elements.append(
+        {
+            "type": "alert",
+            "message": "Tip: Reduce noise with filters by type or domain. Example: `filters('update', {'category': 'api-only', 'mode': 'include', 'types': ['XHR', 'Fetch'], 'domains': ['*/api/*', '*/graphql/*']})`",
+            "level": "info",
+        }
     )
+
+    if tips:
+        elements.append({"type": "heading", "content": "Next Steps", "level": 3})
+        elements.append({"type": "list", "items": tips})
+
+    return {"elements": elements}

webtap_tool-0.4.0/src/webtap/commands/server.py

@@ -0,0 +1,180 @@
+"""API server management command.
+
+PUBLIC API:
+  - server: Manage API server (status/start/stop/restart)
+"""
+
+import socket
+import time
+import logging
+
+from webtap.app import app
+from webtap.api import start_api_server
+
+logger = logging.getLogger(__name__)
+
+# Fixed port for API server
+API_PORT = 8765
+
+
+def _check_port() -> bool:
+    """Check if API port is in use."""
+    with socket.socket() as s:
+        try:
+            s.bind(("127.0.0.1", API_PORT))
+            return False  # Port is free
+        except OSError:
+            return True  # Port is in use
+
+
+def _stop_server(state) -> tuple[bool, str]:
+    """Stop the server if this instance owns it."""
+    if not state.api_thread or not state.api_thread.is_alive():
+        return False, "Not running"
+
+    import webtap.api
+
+    webtap.api._shutdown_requested = True
+    state.api_thread.join(timeout=2.0)
+    state.api_thread = None
+
+    return True, "Server stopped"
+
+
+def _start_server(state) -> tuple[bool, str]:
+    """Start the server on port 8765."""
+    # Check if already running
+    if state.api_thread and state.api_thread.is_alive():
+        return True, f"Already running on port {API_PORT}"
+
+    # Check if port is in use
+    if _check_port():
+        return False, f"Port {API_PORT} already in use by another process"
+
+    # Start the server
+    thread = start_api_server(state, port=API_PORT)
+    if thread:
+        state.api_thread = thread
+
+        # Register cleanup
+        import atexit
+
+        atexit.register(lambda: state.cleanup() if state else None)
+
+        return True, f"Server started on port {API_PORT}"
+    else:
+        return False, "Failed to start server"
+
+
+@app.command(
+    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"},
+    },
+)
+def server(state, action: str = None) -> dict:  # pyright: ignore[reportArgumentType]
+    """API server status and management information.
+
+    Returns current server state and available actions.
+    """
+    if action is None:
+        action = "status"
+
+    action = action.lower()
+    owns_server = bool(state.api_thread and state.api_thread.is_alive())
+
+    # Build markdown elements based on action
+    elements = []
+
+    if action == "status" or action not in ["start", "stop", "restart"]:
+        # Status information
+        elements.append({"type": "heading", "content": "API Server Status", "level": 2})
+
+        if owns_server:
+            elements.append({"type": "text", "content": "**Status:** Running"})
+            elements.append({"type": "text", "content": f"**Port:** {API_PORT}"})
+            elements.append({"type": "text", "content": f"**URL:** http://127.0.0.1:{API_PORT}"})
+            elements.append({"type": "text", "content": f"**Health:** http://127.0.0.1:{API_PORT}/health"})
+            elements.append({"type": "text", "content": "**Extension:** Ready to connect"})
+        else:
+            port_in_use = _check_port()
+            if port_in_use:
+                elements.append({"type": "alert", "message": "Port 8765 in use by another process", "level": "warning"})
+                elements.append({"type": "text", "content": "Cannot start server until port is free"})
+            else:
+                elements.append({"type": "text", "content": "**Status:** Not running"})
+                elements.append({"type": "text", "content": f"**Port:** {API_PORT} (available)"})
+                elements.append({"type": "text", "content": "Use `server('start')` to start the API server"})
+
+        # Available actions
+        elements.append({"type": "heading", "content": "Available Actions", "level": 3})
+        actions = [
+            "`server('start')` - Start the API server",
+            "`server('stop')` - Stop the API server",
+            "`server('restart')` - Restart the API server",
+            "`server('status')` or `server()` - Show this status",
+        ]
+        elements.append({"type": "list", "items": actions})
+
+    elif action == "start":
+        if owns_server:
+            elements.append({"type": "alert", "message": f"Server already running on port {API_PORT}", "level": "info"})
+        else:
+            success, message = _start_server(state)
+            if success:
+                elements.append({"type": "alert", "message": message, "level": "success"})
+                elements.append({"type": "text", "content": f"**URL:** http://127.0.0.1:{API_PORT}"})
+                elements.append({"type": "text", "content": f"**Health:** http://127.0.0.1:{API_PORT}/health"})
+                elements.append({"type": "text", "content": "Chrome extension can now connect"})
+            else:
+                elements.append({"type": "alert", "message": message, "level": "error"})
+
+    elif action == "stop":
+        if not owns_server:
+            elements.append({"type": "text", "content": "Server not running"})
+        else:
+            success, message = _stop_server(state)
+            if success:
+                elements.append({"type": "alert", "message": message, "level": "success"})
+            else:
+                elements.append({"type": "alert", "message": message, "level": "error"})
+
+    elif action == "restart":
+        if owns_server:
+            success, msg = _stop_server(state)
+            if not success:
+                elements.append({"type": "alert", "message": f"Failed to stop: {msg}", "level": "error"})
+                return {"elements": elements}
+            time.sleep(0.5)
+
+        success, msg = _start_server(state)
+        if success:
+            elements.append({"type": "alert", "message": "Server restarted", "level": "success"})
+            elements.append({"type": "text", "content": f"**Port:** {API_PORT}"})
+            elements.append({"type": "text", "content": f"**URL:** http://127.0.0.1:{API_PORT}"})
+        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}
+
+
+__all__ = ["server"]

{webtap_tool-0.2.3 → webtap_tool-0.4.0}/src/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"]

webtap_tool-0.2.3/src/webtap/__init__.py

@@ -1,64 +0,0 @@
-"""WebTap - Chrome DevTools Protocol REPL.
-
-Main entry point for WebTap browser debugging tool. Provides both REPL and MCP
-functionality for Chrome DevTools Protocol interaction with native CDP event
-storage and on-demand querying.
-
-PUBLIC API:
-  - app: Main ReplKit2 App instance
-  - main: Entry point function for CLI
-"""
-
-import atexit
-import sys
-import logging
-
-from webtap.app import app
-from webtap.api import start_api_server
-
-logger = logging.getLogger(__name__)
-
-
-def main():
-    """Entry point for the WebTap REPL.
-
-    Starts in one of three modes:
-    - CLI mode (with --cli flag) for command-line interface
-    - MCP mode (with --mcp flag) for Model Context Protocol server
-    - REPL mode (default) for interactive shell
-
-    In REPL and MCP modes, the API server is started for Chrome extension
-    integration. The API server runs in background to handle extension requests.
-    """
-    # Start API server for Chrome extension (except in CLI mode)
-    if "--cli" not in sys.argv:
-        _start_api_server_safely()
-
-    if "--mcp" in sys.argv:
-        app.mcp.run()
-    elif "--cli" in sys.argv:
-        # Remove --cli from argv before passing to Typer
-        sys.argv.remove("--cli")
-        app.cli()  # Run CLI mode via Typer
-    else:
-        # Run REPL
-        app.run(title="WebTap - Chrome DevTools Protocol REPL")
-
-
-def _start_api_server_safely():
-    """Start API server with error handling and cleanup registration."""
-    try:
-        thread = start_api_server(app.state)
-        if thread and app.state:
-            app.state.api_thread = thread
-            logger.info("API server started on port 8765")
-
-            # Register cleanup to shut down API server on exit
-            atexit.register(lambda: app.state.cleanup() if app.state else None)
-        else:
-            logger.info("Port 8765 in use by another instance")
-    except Exception as e:
-        logger.warning(f"Failed to start API server: {e}")
-
-
-__all__ = ["app", "main"]