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

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

@@ -15,6 +15,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.3.0] - 2025-09-19
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webtap-tool
-Version: 0.2.3
+Version: 0.3.0
 Summary: Terminal-based web page inspector for AI debugging sessions
 Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
 Classifier: Development Status :: 3 - Alpha

{webtap_tool-0.2.3 → webtap_tool-0.3.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.3.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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webtap-tool"
-version = "0.2.3"
+version = "0.3.0"
 description = "Terminal-based web page inspector for AI debugging sessions"
 readme = "README.md"
 authors = [

webtap_tool-0.3.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.3.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.3.0}/src/webtap/app.py

@@ -84,6 +84,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.3.0/src/webtap/commands/server.py

@@ -0,0 +1,162 @@
+"""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",
+        "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"})
+
+    return {"elements": elements}
+
+
+__all__ = ["server"]

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"]