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

webtap/commands/DEVELOPER_GUIDE.md

@@ -173,7 +173,7 @@ def command(state, param: int = 0)
 @app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "text/markdown"})
 def pages(state) -> dict:
     """List available pages."""
-    return build_table_response(
+    return table_response(
         title="Chrome Pages",
         headers=["Index", "Title", "URL"],
         rows=rows,
@@ -187,7 +187,7 @@ def pages(state) -> dict:
 def navigate(state, url: str) -> dict:
     """Navigate to URL."""
     # Perform action
-    return build_info_response(
+    return info_response(
         title="Navigation Complete",
         fields={"URL": url, "Status": "Success"}
     )
@@ -195,37 +195,75 @@ def navigate(state, url: str) -> dict:
 
 ## Error Handling
 
-Always use the error utilities from `_errors.py`:
+Always use the error utilities from `_builders.py`:
 
 ```python
-from webtap.commands._errors import check_connection, error_response
+from webtap.commands._builders import check_connection, error_response
 
 def my_command(state, ...):
     # Check connection first for commands that need it
     if error := check_connection(state):
         return error
-    
+
     # Validate parameters
     if not valid:
-        return error_response("invalid_param", "Parameter X must be Y")
-    
-    # Custom errors
-    return error_response("custom", custom_message="Specific error message")
+        return error_response("Parameter X must be Y", suggestions=["Try this", "Or that"])
+
+    # Simple errors
+    return error_response("Specific error message")
 ```
 
-## Utility Functions
+## Response Builders
 
-Use helpers from `_utils.py`:
+Use builders from `_builders.py`:
 
 ```python
-from webtap.commands._utils import (
-    build_table_response,    # For tables
-    build_info_response,     # For key-value info
-    parse_options,          # Parse dict with defaults
-    extract_option,         # Extract single option
-    truncate_string,        # Truncate long strings
-    format_size,           # Format byte sizes
-    format_id,             # Format IDs
+from webtap.commands._builders import (
+    # Table responses
+    table_response,         # Tables with headers, warnings, tips
+
+    # Info displays
+    info_response,          # Key-value pairs with optional heading
+
+    # Status responses
+    error_response,         # Errors with suggestions
+    success_response,       # Success messages with details
+    warning_response,       # Warnings with suggestions
+
+    # Code results
+    code_result_response,   # Code execution with result display
+    code_response,          # Simple code block display
+
+    # Connection helpers
+    check_connection,       # Helper for CDP connection validation
+    check_fetch_enabled,    # Helper for fetch interception validation
+)
+```
+
+### Usage Examples
+
+```python
+# Table with tips
+return table_response(
+    title="Network Requests",
+    headers=["ID", "URL", "Status"],
+    rows=rows,
+    summary=f"{len(rows)} requests",
+    tips=["Use body(ID) to fetch response body"]
+)
+
+# Code execution result
+return code_result_response(
+    "JavaScript Result",
+    code="2 + 2",
+    language="javascript",
+    result=4
+)
+
+# Error with suggestions
+return error_response(
+    "Not connected to Chrome",
+    suggestions=["Run pages()", "Use connect(0)"]
 )
 ```
 
@@ -300,15 +338,63 @@ Use explicit text instead of symbols for clarity:
 4. **MCP mode**: Test with `webtap --mcp` command
 5. **Markdown rendering**: Verify output displays correctly
 
+## TIPS.md Integration
+
+All commands should be documented in `TIPS.md` for consistent help and MCP descriptions:
+
+```python
+from webtap.commands._tips import get_tips, get_mcp_description
+
+# Get MCP description (for fastmcp metadata)
+mcp_desc = get_mcp_description("mycommand")
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"}
+)
+def mycommand(state, param: str) -> dict:
+    """My command description."""
+    # ... implementation ...
+
+    # Include tips in response
+    tips = get_tips("mycommand", context={"id": some_id})
+    return table_response(
+        headers=headers,
+        rows=rows,
+        tips=tips  # Automatically shown as "Next Steps"
+    )
+```
+
+### Adding to TIPS.md
+
+Add a section for your command:
+
+```markdown
+### mycommand
+Brief description of what the command does.
+
+#### Examples
+\```python
+mycommand("param1")              # Basic usage
+mycommand("param2", flag=True)   # With options
+\```
+
+#### Tips
+- **Related command:** `other_command()` - does related thing
+- **Advanced usage:** Use with `yet_another()` for X
+- **Context aware:** Tips support {id} placeholders from context dict
+```
+
 ## Checklist for New Commands
 
 - [ ] Use `@app.command()` decorator with `display="markdown"`
 - [ ] Add `fastmcp` metadata (type: "resource" or "tool")
 - [ ] Use simple types only (no unions, no Optional)
 - [ ] Add `# pyright: ignore[reportArgumentType]` for `dict = None`
-- [ ] Import utilities from `_utils.py` and `_errors.py`
-- [ ] Use `build_table_response()` or `build_info_response()`
+- [ ] Import builders from `_builders.py`
+- [ ] Use `table_response()`, `info_response()`, or `code_result_response()`
 - [ ] Check connection with `check_connection()` if needed
+- [ ] Add command section to `TIPS.md` with examples and tips
+- [ ] Use `get_tips()` to show tips in response
 - [ ] Document parameters clearly in docstring
-- [ ] Provide usage examples in docstring
 - [ ] Test in both REPL and MCP modes

webtap/commands/TIPS.md

@@ -150,4 +150,27 @@ Show paused requests and responses.
 - **Analyze body:** `body({id})` - fetch and examine response body
 - **Resume request:** `resume({id})` - continue the request
 - **Modify request:** `resume({id}, modifications={'url': '...'})`
-- **Fail request:** `fail({id}, 'BlockedByClient')` - block the request
+- **Fail request:** `fail({id}, 'BlockedByClient')` - block the request
+
+### selections
+Browser element selections with prompt and analysis.
+
+Access selected DOM elements and their properties via Python expressions. Elements are selected using the Chrome extension's selection mode.
+
+#### Examples
+```python
+selections()                                    # View all selections
+selections(expr="data['prompt']")              # Get prompt text
+selections(expr="data['selections']['1']")     # Get element #1 data
+selections(expr="data['selections']['1']['styles']")  # Get styles
+selections(expr="len(data['selections'])")     # Count selections
+selections(expr="{k: v['selector'] for k, v in data['selections'].items()}")  # All selectors
+```
+
+#### Tips
+- **Extract HTML:** `selections(expr="data['selections']['1']['outerHTML']")` - get element HTML
+- **Get CSS selector:** `selections(expr="data['selections']['1']['selector']")` - unique selector
+- **Use with js():** `js("element.offsetWidth", selection=1)` - integrate with JavaScript execution
+- **Access styles:** `selections(expr="data['selections']['1']['styles']['display']")` - computed CSS
+- **Get attributes:** `selections(expr="data['selections']['1']['preview']")` - tag, id, classes
+- **Inspect in prompts:** Use `@webtap:webtap://selections` resource in Claude Code for AI analysis

webtap/commands/_builders.py

@@ -1,4 +1,36 @@
-"""Response builders using ReplKit2 v0.10.0+ markdown elements."""
+"""Response builders using ReplKit2 v0.10.0+ markdown elements.
+
+USAGE GUIDELINES:
+
+Use builders for:
+  ✅ Simple responses (error, info, success, warning)
+  ✅ Tables with standard format
+  ✅ Code execution results
+  ✅ Repeated patterns across commands
+
+Use manual building for:
+  ❌ Complex multi-section layouts (>20 lines)
+  ❌ Conditional sections with deep nesting
+  ❌ Custom workflows (wizards, dashboards)
+  ❌ Dual-mode resource views with tutorials
+
+Examples:
+  - network() - Simple table → Use table_response()
+  - javascript() - Code result → Use code_result_response()
+  - server() - Custom dashboard → Manual OK
+  - selections() resource mode - Tutorial layout → Manual OK
+
+Available builders:
+  - table_response() - Tables with headers, warnings, tips
+  - info_response() - Key-value pairs with optional heading
+  - error_response() - Errors with suggestions
+  - success_response() - Success messages with details
+  - warning_response() - Warnings with suggestions
+  - check_connection() - Helper for CDP connection validation
+  - check_fetch_enabled() - Helper for fetch interception validation
+  - code_result_response() - Code execution with result display
+  - code_response() - Simple code block display
+"""
 
 from typing import Any
 
@@ -125,3 +157,109 @@ def warning_response(message: str, suggestions: list[str] | None = None) -> dict
         elements.append({"type": "list", "items": suggestions})
 
     return {"elements": elements}
+
+
+# Connection helpers
+
+
+def check_connection(state):
+    """Check CDP connection, return error response if not connected.
+
+    Returns error_response() if not connected, None otherwise.
+    Use pattern: `if error := check_connection(state): return error`
+
+    Args:
+        state: Application state containing CDP session.
+
+    Returns:
+        Error response dict if not connected, None if connected.
+    """
+    if not (state.cdp and state.cdp.is_connected):
+        return error_response(
+            "Not connected to Chrome",
+            suggestions=[
+                "Run `pages()` to see available tabs",
+                "Use `connect(0)` to connect to first tab",
+                "Or `connect(page_id='...')` for specific tab",
+            ],
+        )
+    return None
+
+
+def check_fetch_enabled(state):
+    """Check fetch interception, return error response if not enabled.
+
+    Args:
+        state: Application state containing fetch service.
+
+    Returns:
+        Error response dict if not enabled, None if enabled.
+    """
+    if not state.service.fetch.enabled:
+        return error_response(
+            "Fetch interception not enabled", suggestions=["Enable with `fetch('enable')` to pause requests"]
+        )
+    return None
+
+
+# Code result builders
+
+
+def code_result_response(
+    title: str,
+    code: str,
+    language: str,
+    result: Any = None,
+) -> dict:
+    """Build code execution result display.
+
+    Args:
+        title: Result heading (e.g. "JavaScript Result")
+        code: Source code executed
+        language: Syntax highlighting language
+        result: Execution result (supports dict/list/str/None)
+
+    Returns:
+        Markdown response with code and result
+    """
+    import json
+
+    elements = [
+        {"type": "heading", "content": title, "level": 2},
+        {"type": "code_block", "content": code, "language": language},
+    ]
+
+    if result is not None:
+        if isinstance(result, (dict, list)):
+            elements.append({"type": "code_block", "content": json.dumps(result, indent=2), "language": "json"})
+        else:
+            elements.append({"type": "text", "content": f"**Result:** `{result}`"})
+    else:
+        elements.append({"type": "text", "content": "**Result:** _(no return value)_"})
+
+    return {"elements": elements}
+
+
+def code_response(
+    content: str,
+    language: str = "",
+    title: str | None = None,
+) -> dict:
+    """Build simple code block response.
+
+    Args:
+        content: Code content to display
+        language: Syntax highlighting language
+        title: Optional heading above code block
+
+    Returns:
+        Markdown response with code block
+    """
+    elements = []
+
+    if title:
+        elements.append({"type": "heading", "content": title, "level": 2})
+
+    elements.append({"type": "code_block", "content": content, "language": language})
+
+    return {"elements": elements}

webtap/commands/body.py

@@ -3,8 +3,7 @@
 import json
 from webtap.app import app
 from webtap.commands._utils import evaluate_expression, format_expression_result
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import info_response, error_response
+from webtap.commands._builders import check_connection, info_response, error_response
 from webtap.commands._tips import get_mcp_description
 
 

webtap/commands/connection.py

@@ -1,8 +1,7 @@
 """Chrome browser connection management 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/console.py

@@ -1,8 +1,7 @@
 """Browser console message monitoring and display commands."""
 
 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
 
 

webtap/commands/events.py

@@ -2,8 +2,7 @@
 
 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._builders import check_connection, table_response
 from webtap.commands._tips import get_tips, get_mcp_description
 
 

webtap/commands/fetch.py

@@ -1,8 +1,7 @@
 """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._builders import check_connection, error_response, info_response, table_response
 from webtap.commands._tips import get_tips
 
 

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/commands/inspect.py

@@ -4,8 +4,7 @@ import json
 
 from webtap.app import app
 from webtap.commands._utils import evaluate_expression, format_expression_result
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import error_response
+from webtap.commands._builders import check_connection, error_response
 from webtap.commands._tips import get_mcp_description