webtap-tool 0.11.0__py3-none-any.whl

webtap/commands/filters.py

@@ -0,0 +1,116 @@
+"""Filter group management commands."""
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import info_response, error_response, table_response
+from webtap.commands._tips import get_mcp_description
+
+_filters_desc = get_mcp_description("filters")
+
+
+@app.command(
+    display="markdown", fastmcp={"type": "tool", "mime_type": "text/markdown", "description": _filters_desc or ""}
+)
+def filters(
+    state,
+    add: str = None,  # pyright: ignore[reportArgumentType]
+    remove: str = None,  # pyright: ignore[reportArgumentType]
+    enable: str = None,  # pyright: ignore[reportArgumentType]
+    disable: str = None,  # pyright: ignore[reportArgumentType]
+    hide: dict = None,  # pyright: ignore[reportArgumentType]
+) -> dict:
+    """Manage filter groups for noise reduction.
+
+    Args:
+        add: Create new group with this name (requires hide=)
+        remove: Delete group by name
+        enable: Enable group by name
+        disable: Disable group by name
+        hide: Filter config for add {"types": [...], "urls": [...]}
+
+    Examples:
+        filters()                                           # Show all groups
+        filters(add="assets", hide={"types": ["Image"]})   # Create group
+        filters(enable="assets")                            # Enable group
+        filters(disable="assets")                           # Disable group
+        filters(remove="assets")                            # Delete group
+    """
+    try:
+        # Handle add - create new group
+        if add:
+            if not hide:
+                return error_response("hide= required when adding a group")
+
+            state.client.call("filters.add", name=add, hide=hide)
+            return info_response(
+                title="Group Created",
+                fields={
+                    "Name": add,
+                    "Types": ", ".join(hide.get("types", [])) or "-",
+                    "URLs": ", ".join(hide.get("urls", [])) or "-",
+                },
+            )
+
+        # Handle remove - delete group
+        if remove:
+            result = state.client.call("filters.remove", name=remove)
+            if result.get("removed"):
+                return info_response(title="Group Removed", fields={"Name": remove})
+            return error_response(f"Group '{remove}' not found")
+
+        # Handle enable - toggle group on (in-memory)
+        if enable:
+            result = state.client.call("filters.enable", name=enable)
+            if result.get("enabled"):
+                return info_response(title="Group Enabled", fields={"Name": enable})
+            return error_response(f"Group '{enable}' not found")
+
+        # Handle disable - toggle group off (in-memory)
+        if disable:
+            result = state.client.call("filters.disable", name=disable)
+            if result.get("disabled"):
+                return info_response(title="Group Disabled", fields={"Name": disable})
+            return error_response(f"Group '{disable}' not found")
+
+        # Default: list all groups with status
+        status = state.client.call("filters.status")
+
+        if not status:
+            return {
+                "elements": [
+                    {"type": "heading", "content": "Filter Groups", "level": 2},
+                    {"type": "text", "content": "No filter groups configured."},
+                    {
+                        "type": "text",
+                        "content": 'Create one: `filters(add="assets", hide={"types": ["Image", "Font"]})`',
+                    },
+                ]
+            }
+
+        # Build table
+        rows = []
+        for name, group in status.items():
+            hide_cfg = group.get("hide", {})
+            rows.append(
+                {
+                    "Group": name,
+                    "Status": "enabled" if group.get("enabled") else "disabled",
+                    "Types": ", ".join(hide_cfg.get("types", [])) or "-",
+                    "URLs": ", ".join(hide_cfg.get("urls", [])) or "-",
+                }
+            )
+
+        return table_response(
+            title="Filter Groups",
+            headers=["Group", "Status", "Types", "URLs"],
+            rows=rows,
+            tips=["Enabled groups hide matching requests from network()"],
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+
+__all__ = ["filters"]

webtap/commands/javascript.py

@@ -0,0 +1,73 @@
+"""JavaScript code execution in browser context."""
+
+from replkit2.types import ExecutionContext
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import error_response, code_result_response
+from webtap.commands._tips import get_mcp_description
+
+mcp_desc = get_mcp_description("js")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown", "description": mcp_desc}
+    if mcp_desc
+    else {"type": "tool", "mime_type": "text/markdown"},
+)
+def js(
+    state,
+    code: str,
+    selection: int = None,  # pyright: ignore[reportArgumentType]
+    persist: bool = False,
+    wait_return: bool = True,
+    await_promise: bool = False,
+    _ctx: ExecutionContext = None,  # pyright: ignore[reportArgumentType]
+) -> dict:
+    """Execute JavaScript in the browser. Uses fresh scope by default to avoid redeclaration errors.
+
+    Args:
+        code: JavaScript code to execute (single expression by default, multi-statement with persist=True)
+        selection: Browser element selection number - makes 'element' variable available
+        persist: Keep variables in global scope across calls (default: False)
+        wait_return: Wait for and return result (default: True)
+        await_promise: Await promises before returning (default: False)
+
+    Examples:
+        js("document.title")                           # Fresh scope (default)
+        js("[...document.links].map(a => a.href)")    # Single expression works
+        js("var x = 1; x + 1", persist=True)          # Multi-statement needs persist=True
+        js("element.offsetWidth", selection=1)        # With browser element
+        js("fetch('/api')", await_promise=True)       # Async operation
+        js("element.remove()", selection=1, wait_return=False)  # No return needed
+    """
+    try:
+        result = state.client.call(
+            "js",
+            code=code,
+            selection=selection,
+            persist=persist,
+            await_promise=await_promise,
+            return_value=wait_return,
+        )
+
+        if wait_return:
+            return code_result_response("JavaScript Result", code, "javascript", result=result.get("value"))
+        else:
+            # Truncate code for display
+            is_repl = _ctx and _ctx.is_repl()
+            max_len = 50 if is_repl else 200
+            display_code = code if len(code) <= max_len else code[:max_len] + "..."
+
+            return {
+                "elements": [
+                    {"type": "heading", "content": "JavaScript Execution", "level": 2},
+                    {"type": "text", "content": f"**Status:** Executed\n\n**Expression:** `{display_code}`"},
+                ]
+            }
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))

webtap/commands/js_export.py

@@ -0,0 +1,73 @@
+"""Export JavaScript evaluation results to local files.
+
+This module provides the js_export command for saving JS eval output.
+"""
+
+from webtap.app import app
+from webtap.commands._builders import error_response, success_response
+from webtap.commands._code_generation import ensure_output_directory
+
+
+@app.command(display="markdown", fastmcp={"type": "tool"})
+def js_export(
+    state,
+    code: str,
+    output: str,
+    selection: int = None,  # pyright: ignore[reportArgumentType]
+    persist: bool = False,
+    await_promise: bool = False,
+) -> dict:
+    """Export JavaScript evaluation result to a local file.
+
+    Args:
+        code: JavaScript expression to evaluate (result is written to file)
+        output: Output file path
+        selection: Browser selection number to bind to 'element' variable. Defaults to None.
+        persist: Keep variables in global scope. Defaults to False.
+        await_promise: Await promise results. Defaults to False.
+
+    Returns:
+        Success or error response with file details.
+
+    Examples:
+        js_export("setEquipment.toString()", "out/fn.js")
+        js_export("JSON.stringify(x2netvars, null, 2)", "out/vars.json")
+    """
+    # Execute JS via RPC
+    try:
+        result = state.client.call(
+            "js",
+            code=code,
+            selection=selection,
+            persist=persist,
+            await_promise=await_promise,
+            return_value=True,
+        )
+    except Exception as e:
+        return error_response(f"JavaScript execution failed: {e}")
+
+    if not result.get("executed"):
+        return error_response("JavaScript execution did not complete")
+
+    value = result.get("value")
+    if value is None:
+        return error_response("Expression returned null/undefined")
+
+    # Convert to string if needed
+    content = value if isinstance(value, str) else str(value)
+
+    # Write to file
+    output_path = ensure_output_directory(output)
+    try:
+        output_path.write_text(content)
+    except Exception as e:
+        return error_response(f"Failed to write file: {e}")
+
+    return success_response(
+        "Exported successfully",
+        details={
+            "Output": str(output_path),
+            "Size": f"{output_path.stat().st_size} bytes",
+            "Lines": len(content.splitlines()),
+        },
+    )

webtap/commands/launch.py

@@ -0,0 +1,72 @@
+"""Chrome launch commands for WebTap."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from webtap.app import app
+from webtap.commands._builders import success_response, error_response
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "run-chrome", "help": "Launch Chrome with debugging enabled"},
+    fastmcp={"enabled": False},
+)
+def run_chrome(state, detach: bool = True, port: int = 9222) -> dict:
+    """Launch Chrome with debugging enabled for WebTap.
+
+    Args:
+        detach: Run Chrome in background (default: True)
+        port: Debugging port (default: 9222)
+
+    Returns:
+        Status message
+    """
+    # Find Chrome executable
+    chrome_paths = [
+        "google-chrome-stable",
+        "google-chrome",
+        "chromium-browser",
+        "chromium",
+    ]
+
+    chrome_exe = None
+    for path in chrome_paths:
+        if shutil.which(path):
+            chrome_exe = path
+            break
+
+    if not chrome_exe:
+        return error_response(
+            "Chrome not found",
+            suggestions=[
+                "Install google-chrome-stable: sudo apt install google-chrome-stable",
+                "Or install chromium: sudo apt install chromium-browser",
+            ],
+        )
+
+    # Simple: use clean temp profile for debugging
+    temp_config = Path("/tmp/webtap-chrome-debug")
+    temp_config.mkdir(parents=True, exist_ok=True)
+
+    # Launch Chrome
+    cmd = [chrome_exe, f"--remote-debugging-port={port}", "--remote-allow-origins=*", f"--user-data-dir={temp_config}"]
+
+    if detach:
+        subprocess.Popen(cmd, start_new_session=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return success_response(
+            f"Launched {chrome_exe}",
+            details={
+                "Port": str(port),
+                "Mode": "Background (detached)",
+                "Profile": "Temporary (clean)",
+                "Next step": "Run connect() to attach WebTap",
+            },
+        )
+    else:
+        result = subprocess.run(cmd)
+        if result.returncode == 0:
+            return success_response("Chrome closed normally")
+        else:
+            return error_response(f"Chrome exited with code {result.returncode}")

webtap/commands/navigation.py

@@ -0,0 +1,197 @@
+"""Browser navigation commands."""
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import info_response, error_response, table_response
+from webtap.commands._tips import get_tips
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown"},
+)
+def navigate(state, url: str) -> dict:
+    """Navigate to URL.
+
+    Args:
+        url: URL to navigate to
+
+    Returns:
+        Navigation result with frame and loader IDs
+    """
+    try:
+        result = state.client.call("navigate", url=url)
+
+        if result.get("error"):
+            return error_response(f"Navigation error: {result['error']}")
+
+        return info_response(
+            title="Navigation",
+            fields={
+                "URL": url,
+                "Frame ID": result.get("frame_id", ""),
+                "Loader ID": result.get("loader_id", ""),
+            },
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"Navigation failed: {e}")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown"},
+)
+def reload(state, ignore_cache: bool = False) -> dict:
+    """Reload the current page.
+
+    Args:
+        ignore_cache: Force reload ignoring cache
+    """
+    try:
+        result = state.client.call("reload", ignore_cache=ignore_cache)
+
+        return info_response(
+            title="Page Reload",
+            fields={
+                "Status": "Page reloaded",
+                "Cache": "Ignored" if result.get("ignore_cache") else "Used",
+            },
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"Reload failed: {e}")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown"},
+)
+def back(state) -> dict:
+    """Navigate back in history."""
+    try:
+        result = state.client.call("back")
+
+        if not result.get("navigated"):
+            return info_response(
+                title="Navigation Back",
+                fields={"Status": result.get("reason", "Cannot go back")},
+            )
+
+        return info_response(
+            title="Navigation Back",
+            fields={
+                "Status": "Navigated back",
+                "Page": result.get("title", ""),
+                "URL": result.get("url", ""),
+                "Index": f"{result.get('index', 0) + 1} of {result.get('total', 0)}",
+            },
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"Back navigation failed: {e}")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "mime_type": "text/markdown"},
+)
+def forward(state) -> dict:
+    """Navigate forward in history."""
+    try:
+        result = state.client.call("forward")
+
+        if not result.get("navigated"):
+            return info_response(
+                title="Navigation Forward",
+                fields={"Status": result.get("reason", "Cannot go forward")},
+            )
+
+        return info_response(
+            title="Navigation Forward",
+            fields={
+                "Status": "Navigated forward",
+                "Page": result.get("title", ""),
+                "URL": result.get("url", ""),
+                "Index": f"{result.get('index', 0) + 1} of {result.get('total', 0)}",
+            },
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"Forward navigation failed: {e}")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "resource", "mime_type": "text/markdown"},
+)
+def page(state) -> dict:
+    """Get current page information."""
+    try:
+        result = state.client.call("page")
+        tips = get_tips("page")
+
+        return info_response(
+            title=result.get("title", "Untitled Page"),
+            fields={
+                "URL": result.get("url", ""),
+                "ID": result.get("id", ""),
+                "Type": result.get("type", ""),
+            },
+            tips=tips,
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"Page info failed: {e}")
+
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "resource", "mime_type": "text/markdown"},
+)
+def history(state) -> dict:
+    """Get navigation history."""
+    try:
+        result = state.client.call("history")
+        entries = result.get("entries", [])
+
+        if not entries:
+            return info_response(
+                title="Navigation History",
+                fields={"Status": "No history entries"},
+            )
+
+        # Format rows for table
+        rows = []
+        for e in entries:
+            marker = "→ " if e.get("current") else "  "
+            rows.append(
+                {
+                    "": marker,
+                    "ID": e.get("id", ""),
+                    "Title": e.get("title", "")[:40],
+                    "URL": e.get("url", "")[:60],
+                    "Type": e.get("type", ""),
+                }
+            )
+
+        return table_response(
+            title="Navigation History",
+            rows=rows,
+            summary=f"{len(entries)} entries",
+        )
+
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(f"History failed: {e}")

webtap/commands/network.py

@@ -0,0 +1,136 @@
+"""Network request monitoring and display commands."""
+
+from replkit2.types import ExecutionContext
+
+from webtap.app import app
+from webtap.client import RPCError
+from webtap.commands._builders import table_response, error_response, format_size
+from webtap.commands._tips import get_tips
+
+# Truncation values for REPL mode (compact display)
+_REPL_TRUNCATE = {
+    "ReqID": {"max": 12, "mode": "end"},
+    "URL": {"max": 60, "mode": "middle"},
+}
+
+# Truncation values for MCP mode (generous for LLM context)
+_MCP_TRUNCATE = {
+    "ReqID": {"max": 50, "mode": "end"},
+    "URL": {"max": 200, "mode": "middle"},
+}
+
+
+@app.command(
+    display="markdown",
+    fastmcp=[{"type": "resource", "mime_type": "text/markdown"}, {"type": "tool", "mime_type": "text/markdown"}],
+)
+def network(
+    state,
+    status: int = None,  # pyright: ignore[reportArgumentType]
+    method: str = None,  # pyright: ignore[reportArgumentType]
+    resource_type: str = None,  # pyright: ignore[reportArgumentType]
+    url: str = None,  # pyright: ignore[reportArgumentType]
+    req_state: str = None,  # pyright: ignore[reportArgumentType]
+    show_all: bool = False,
+    limit: int = 50,
+    _ctx: ExecutionContext = None,  # pyright: ignore[reportArgumentType]
+) -> dict:
+    """List network requests with inline filters.
+
+    Args:
+        status: Filter by HTTP status code (e.g., 404, 500)
+        method: Filter by HTTP method (e.g., "POST", "GET")
+        resource_type: Filter by resource type (e.g., "xhr", "fetch", "websocket")
+        url: Filter by URL pattern (supports * wildcard)
+        req_state: Filter by state (pending, loading, complete, failed, paused)
+        show_all: Bypass noise filter groups
+        limit: Max results (default 50)
+
+    Examples:
+        network()                    # Default with noise filter
+        network(status=404)          # Only 404s
+        network(method="POST")       # Only POST requests
+        network(resource_type="websocket")  # Only WebSocket
+        network(url="*api*")         # URLs containing "api"
+        network(req_state="paused")  # Only paused requests
+        network(show_all=True)       # Show everything
+    """
+    # Build params, omitting None values
+    params = {"limit": limit, "show_all": show_all}
+    if status is not None:
+        params["status"] = status
+    if method is not None:
+        params["method"] = method
+    if resource_type is not None:
+        params["resource_type"] = resource_type
+    if url is not None:
+        params["url"] = url
+    if req_state is not None:
+        params["state"] = req_state
+
+    try:
+        result = state.client.call("network", **params)
+        requests = result.get("requests", [])
+    except RPCError as e:
+        return error_response(e.message)
+    except Exception as e:
+        return error_response(str(e))
+
+    # Mode-specific configuration
+    is_repl = _ctx and _ctx.is_repl()
+
+    # Check if any request has pause_stage (to show Pause column)
+    has_pause = any(r.get("pause_stage") for r in requests)
+
+    # Build rows with mode-specific formatting
+    rows = []
+    for r in requests:
+        row = {
+            "ID": str(r["id"]),
+            "ReqID": r["request_id"],
+            "Method": r["method"],
+            "Status": str(r["status"]) if r["status"] else "-",
+            "URL": r["url"],
+            "Type": r["type"] or "-",
+            # REPL: human-friendly format, MCP: raw bytes for LLM
+            "Size": format_size(r["size"]) if is_repl else (r["size"] or 0),
+            "State": r.get("state", "-"),
+        }
+        # Add Pause column if relevant
+        if has_pause:
+            row["Pause"] = r.get("pause_stage") or "-"
+        rows.append(row)
+
+    # Build response with developer guidance
+    warnings = []
+    if limit and len(requests) == limit:
+        warnings.append(f"Showing {limit} most recent (use limit parameter to see more)")
+
+    # Get tips from TIPS.md with context
+    combined_tips = []
+    if not show_all:
+        combined_tips.append("Use show_all=True to bypass filter groups")
+
+    if rows:
+        example_id = rows[0]["ID"]
+        context_tips = get_tips("network", context={"id": example_id})
+        if context_tips:
+            combined_tips.extend(context_tips)
+
+    # Use mode-specific truncation
+    truncate = _REPL_TRUNCATE if is_repl else _MCP_TRUNCATE
+
+    # Build headers dynamically
+    headers = ["ID", "ReqID", "Method", "Status", "URL", "Type", "Size", "State"]
+    if has_pause:
+        headers.append("Pause")
+
+    return table_response(
+        title="Network Requests",
+        headers=headers,
+        rows=rows,
+        summary=f"{len(rows)} requests" if rows else None,
+        warnings=warnings,
+        tips=combined_tips if combined_tips else None,
+        truncate=truncate,
+    )