webtap-tool 0.1.5__tar.gz → 0.2.0__tar.gz

{webtap_tool-0.1.5 → webtap_tool-0.2.0}/CHANGELOG.md

@@ -15,6 +15,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.2.0] - 2025-09-12
+
+### Added
+- Cross-platform support (Linux and macOS)
+- `setup-cleanup` command to identify and remove old WebTap installations
+- `--bindfs` flag for `setup-chrome` to mount real Chrome profile for debugging (Linux only)
+- Unified `chrome-debug` wrapper at `~/.local/bin/chrome-debug`
+- Separate Chrome Debug launcher (doesn't override system Chrome)
+- Platform detection with XDG-compliant paths via platformdirs
+
+### Changed
+- Chrome wrapper location from `~/.local/bin/wrappers/google-chrome-stable` to `~/.local/bin/chrome-debug`
+- Desktop entry from `google-chrome.desktop` override to separate `chrome-debug.desktop`
+- Extension location to platform-appropriate data directories
+- Setup service refactored into platform-aware modules
+
+### Fixed
+- Cleanup command now detects all old installation locations
+
+### Removed
+
 ## [0.1.5] - 2025-09-10
 
 ### Added

{webtap_tool-0.1.5 → webtap_tool-0.2.0}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: webtap-tool
-Version: 0.1.5
+Version: 0.2.0
 Summary: Terminal-based web page inspector for AI debugging sessions
 Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
 Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Classifier: Topic :: Software Development :: Debuggers
@@ -15,6 +17,7 @@ Requires-Dist: fastapi>=0.116.1
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: lxml>=6.0.1
 Requires-Dist: msgpack-python>=0.5.6
+Requires-Dist: platformdirs>=4.4.0
 Requires-Dist: protobuf>=6.32.0
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pyyaml>=6.0.2

{webtap_tool-0.1.5 → webtap_tool-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webtap-tool"
-version = "0.1.5"
+version = "0.2.0"
 description = "Terminal-based web page inspector for AI debugging sessions"
 readme = "README.md"
 authors = [
@@ -10,6 +10,8 @@ requires-python = ">=3.12"
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3.12",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
     "Topic :: Software Development :: Debuggers",
     "Topic :: Internet :: WWW/HTTP :: Browsers",
 ]
@@ -21,6 +23,7 @@ dependencies = [
     "httpx>=0.28.1",
     "lxml>=6.0.1",
     "msgpack-python>=0.5.6",
+    "platformdirs>=4.4.0",
     "protobuf>=6.32.0",
     "pyjwt>=2.10.1",
     "pyyaml>=6.0.2",

{webtap_tool-0.1.5 → webtap_tool-0.2.0}/src/webtap/commands/setup.py

@@ -29,7 +29,10 @@ def setup_filters(state, force: bool = False) -> dict:
     fastmcp={"enabled": False},
 )
 def setup_extension(state, force: bool = False) -> dict:
-    """Download Chrome extension to ~/.config/webtap/extension/.
+    """Download Chrome extension to platform-appropriate location.
+
+    Linux: ~/.local/share/webtap/extension/
+    macOS: ~/Library/Application Support/webtap/extension/
 
     Args:
         force: Overwrite existing files (default: False)
@@ -47,33 +50,40 @@ def setup_extension(state, force: bool = False) -> dict:
     typer={"name": "setup-chrome", "help": "Install Chrome wrapper script for debugging"},
     fastmcp={"enabled": False},
 )
-def setup_chrome(state, force: bool = False) -> dict:
-    """Install Chrome wrapper to ~/.local/bin/wrappers/google-chrome-stable.
+def setup_chrome(state, force: bool = False, bindfs: bool = False) -> dict:
+    """Install Chrome wrapper script 'chrome-debug' to ~/.local/bin/.
+
+    The wrapper enables remote debugging on port 9222.
+    Same location on both Linux and macOS: ~/.local/bin/chrome-debug
 
     Args:
         force: Overwrite existing script (default: False)
+        bindfs: Use bindfs to mount real Chrome profile for debugging (Linux only, default: False)
 
     Returns:
         Markdown-formatted result with success/error messages
     """
     service = SetupService()
-    result = service.install_chrome_wrapper(force=force)
+    result = service.install_chrome_wrapper(force=force, bindfs=bindfs)
     return _format_setup_result(result, "chrome")
 
 
 @app.command(
     display="markdown",
-    typer={"name": "setup-desktop", "help": "Install desktop entry to use Chrome wrapper from GUI"},
+    typer={"name": "setup-desktop", "help": "Install Chrome Debug GUI launcher"},
     fastmcp={"enabled": False},
 )
 def setup_desktop(state, force: bool = False) -> dict:
-    """Install desktop entry to ~/.local/share/applications/google-chrome.desktop.
+    """Install Chrome Debug GUI launcher (separate from system Chrome).
 
-    This makes the Chrome wrapper work when launching from GUI (app launcher, dock, etc).
-    The desktop entry overrides the system Chrome launcher to use our debug-enabled wrapper.
+    Linux: Creates desktop entry at ~/.local/share/applications/chrome-debug.desktop
+           Shows as "Chrome Debug" in application menu.
+
+    macOS: Creates app bundle at ~/Applications/Chrome Debug.app
+           Shows as "Chrome Debug" in Launchpad and Spotlight.
 
     Args:
-        force: Overwrite existing desktop entry (default: False)
+        force: Overwrite existing launcher (default: False)
 
     Returns:
         Markdown-formatted result with success/error messages
@@ -159,3 +169,90 @@ def _format_setup_result(result: dict, component: str) -> dict:
             )
 
     return {"elements": elements}
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "setup-cleanup", "help": "Clean up old WebTap installations"},
+    fastmcp={"enabled": False},
+)
+def setup_cleanup(state, dry_run: bool = True) -> dict:
+    """Clean up old WebTap installations from previous versions.
+
+    Checks for and removes:
+    - Old extension location (~/.config/webtap/extension/)
+    - Old desktop entries created by webtap
+    - Unmounted bindfs directories
+
+    Args:
+        dry_run: Only show what would be cleaned (default: True)
+
+    Returns:
+        Markdown report of cleanup actions
+    """
+    service = SetupService()
+    result = service.cleanup_old_installations(dry_run=dry_run)
+
+    elements = []
+
+    # Header
+    elements.append({"type": "heading", "level": 2, "content": "WebTap Cleanup Report"})
+
+    # Old installations found
+    if result.get("old_extension"):
+        elements.append({"type": "heading", "level": 3, "content": "Old Extension Location"})
+        elements.append({"type": "text", "content": f"Found: `{result['old_extension']['path']}`"})
+        elements.append({"type": "text", "content": f"Size: {result['old_extension']['size']}"})
+        if not dry_run and result["old_extension"].get("removed"):
+            elements.append({"type": "alert", "message": "✓ Removed old extension", "level": "success"})
+        elif dry_run:
+            elements.append({"type": "alert", "message": "Would remove (dry-run mode)", "level": "info"})
+
+    # Old Chrome wrapper
+    if result.get("old_wrapper"):
+        elements.append({"type": "heading", "level": 3, "content": "Old Chrome Wrapper"})
+        elements.append({"type": "text", "content": f"Found: `{result['old_wrapper']['path']}`"})
+        if not dry_run and result["old_wrapper"].get("removed"):
+            elements.append({"type": "alert", "message": "✓ Removed old wrapper", "level": "success"})
+        elif dry_run:
+            elements.append({"type": "alert", "message": "Would remove (dry-run mode)", "level": "info"})
+
+    # Old desktop entry
+    if result.get("old_desktop"):
+        elements.append({"type": "heading", "level": 3, "content": "Old Desktop Entry"})
+        elements.append({"type": "text", "content": f"Found: `{result['old_desktop']['path']}`"})
+        if not dry_run and result["old_desktop"].get("removed"):
+            elements.append({"type": "alert", "message": "✓ Removed old desktop entry", "level": "success"})
+        elif dry_run:
+            elements.append({"type": "alert", "message": "Would remove (dry-run mode)", "level": "info"})
+
+    # Check for bindfs mounts
+    if result.get("bindfs_mount"):
+        elements.append({"type": "heading", "level": 3, "content": "Bindfs Mount Detected"})
+        elements.append({"type": "text", "content": f"Mount: `{result['bindfs_mount']}`"})
+        elements.append(
+            {"type": "alert", "message": "To unmount: fusermount -u " + result["bindfs_mount"], "level": "warning"}
+        )
+
+    # Summary
+    elements.append({"type": "heading", "level": 3, "content": "Summary"})
+    if dry_run:
+        elements.append({"type": "text", "content": "**Dry-run mode** - no changes made"})
+        elements.append({"type": "text", "content": "To perform cleanup: `setup-cleanup --no-dry-run`"})
+    else:
+        elements.append({"type": "alert", "message": "Cleanup completed", "level": "success"})
+
+    # Next steps
+    elements.append({"type": "heading", "level": 3, "content": "Next Steps"})
+    elements.append(
+        {
+            "type": "list",
+            "items": [
+                "Run `setup-extension` to install extension in new location",
+                "Run `setup-chrome --bindfs` for bindfs mode or `setup-chrome` for standard mode",
+                "Run `setup-desktop` to create Chrome Debug launcher",
+            ],
+        }
+    )
+
+    return {"elements": elements}

webtap_tool-0.2.0/src/webtap/services/setup/__init__.py

@@ -0,0 +1,178 @@
+"""Setup service for installing WebTap components (cross-platform).
+
+PUBLIC API:
+  - SetupService: Main service class for all setup operations
+"""
+
+from typing import Dict, Any
+
+from .filters import FilterSetupService
+from .extension import ExtensionSetupService
+from .chrome import ChromeSetupService
+from .desktop import DesktopSetupService
+from .platform import get_platform_info, ensure_directories
+
+
+class SetupService:
+    """Orchestrator service for installing WebTap components.
+
+    Delegates to specialized service classes for each component type.
+    """
+
+    def __init__(self):
+        """Initialize setup service with platform information."""
+        self.info = get_platform_info()
+        ensure_directories()
+
+        # Initialize component services
+        self.filters_service = FilterSetupService()
+        self.extension_service = ExtensionSetupService()
+        self.chrome_service = ChromeSetupService()
+        self.desktop_service = DesktopSetupService()
+
+    def install_filters(self, force: bool = False) -> Dict[str, Any]:
+        """Install filter configuration.
+
+        Args:
+            force: Overwrite existing file
+
+        Returns:
+            Dict with success, message, path, details
+        """
+        return self.filters_service.install_filters(force=force)
+
+    def install_extension(self, force: bool = False) -> Dict[str, Any]:
+        """Install Chrome extension files.
+
+        Args:
+            force: Overwrite existing files
+
+        Returns:
+            Dict with success, message, path, details
+        """
+        return self.extension_service.install_extension(force=force)
+
+    def install_chrome_wrapper(self, force: bool = False, bindfs: bool = False) -> Dict[str, Any]:
+        """Install Chrome wrapper script.
+
+        Args:
+            force: Overwrite existing script
+            bindfs: Use bindfs to mount real Chrome profile (Linux only)
+
+        Returns:
+            Dict with success, message, path, details
+        """
+        return self.chrome_service.install_wrapper(force=force, bindfs=bindfs)
+
+    def install_desktop_entry(self, force: bool = False) -> Dict[str, Any]:
+        """Install desktop entry or app bundle for GUI integration.
+
+        On Linux: Creates .desktop file
+        On macOS: Creates .app bundle
+
+        Args:
+            force: Overwrite existing entry
+
+        Returns:
+            Dict with success, message, path, details
+        """
+        return self.desktop_service.install_launcher(force=force)
+
+    def get_platform_info(self) -> Dict[str, Any]:
+        """Get platform information for debugging.
+
+        Returns:
+            Platform information including paths and capabilities
+        """
+        return self.info
+
+    def cleanup_old_installations(self, dry_run: bool = True) -> Dict[str, Any]:
+        """Clean up old WebTap installations.
+
+        Checks locations that webtap previously wrote to:
+        - ~/.config/webtap/extension/ (old extension location)
+        - ~/.local/bin/wrappers/google-chrome-stable (old wrapper location)
+        - ~/.local/share/applications/google-chrome.desktop (old desktop entry)
+        - ~/.config/google-chrome-debug (bindfs mount)
+
+        Args:
+            dry_run: If True, only report what would be done
+
+        Returns:
+            Dict with cleanup results
+        """
+        import shutil
+        import subprocess
+        from pathlib import Path
+
+        result = {}
+
+        # Check old extension location
+        old_extension_path = Path.home() / ".config" / "webtap" / "extension"
+        if old_extension_path.exists():
+            # Calculate size
+            size = sum(f.stat().st_size for f in old_extension_path.rglob("*") if f.is_file())
+            size_str = f"{size / 1024:.1f} KB" if size > 0 else "empty"
+
+            result["old_extension"] = {"path": str(old_extension_path), "size": size_str, "removed": False}
+
+            if not dry_run:
+                try:
+                    shutil.rmtree(old_extension_path)
+                    result["old_extension"]["removed"] = True
+                    # Also try to remove parent if empty
+                    parent = old_extension_path.parent
+                    if parent.exists() and not any(parent.iterdir()):
+                        parent.rmdir()
+                except Exception as e:
+                    result["old_extension"]["error"] = str(e)
+
+        # Check old Chrome wrapper location
+        old_wrapper_path = Path.home() / ".local" / "bin" / "wrappers" / "google-chrome-stable"
+        if old_wrapper_path.exists():
+            result["old_wrapper"] = {"path": str(old_wrapper_path), "removed": False}
+
+            if not dry_run:
+                try:
+                    old_wrapper_path.unlink()
+                    result["old_wrapper"]["removed"] = True
+                    # Try to remove wrappers dir if empty (but keep it if other wrappers exist)
+                    wrappers_dir = old_wrapper_path.parent
+                    if wrappers_dir.exists() and not any(wrappers_dir.iterdir()):
+                        wrappers_dir.rmdir()
+                except Exception as e:
+                    result["old_wrapper"]["error"] = str(e)
+
+        # Check old desktop entry
+        old_desktop_path = Path.home() / ".local" / "share" / "applications" / "google-chrome.desktop"
+        if old_desktop_path.exists():
+            # Check if it's our override (contains reference to wrapper)
+            try:
+                content = old_desktop_path.read_text()
+                if "wrappers/google-chrome-stable" in content or "webtap" in content.lower():
+                    result["old_desktop"] = {"path": str(old_desktop_path), "removed": False}
+
+                    if not dry_run:
+                        try:
+                            old_desktop_path.unlink()
+                            result["old_desktop"]["removed"] = True
+                        except Exception as e:
+                            result["old_desktop"]["error"] = str(e)
+            except Exception:
+                pass  # If we can't read it, skip it
+
+        # Check for bindfs mount
+        debug_dir = Path.home() / ".config" / "google-chrome-debug"
+        if debug_dir.exists():
+            try:
+                # Check if it's a mount point
+                output = subprocess.run(["mountpoint", "-q", str(debug_dir)], capture_output=True)
+                if output.returncode == 0:
+                    result["bindfs_mount"] = str(debug_dir)
+            except (FileNotFoundError, OSError):
+                pass  # mountpoint command might not exist
+
+        return result
+
+
+__all__ = ["SetupService"]

webtap_tool-0.2.0/src/webtap/services/setup/chrome.py

@@ -0,0 +1,227 @@
+"""Chrome setup service for installing wrapper scripts (cross-platform)."""
+
+import os
+import logging
+from typing import Dict, Any
+
+from .platform import get_platform_info, ensure_directories
+
+logger = logging.getLogger(__name__)
+
+# Wrapper script templates
+LINUX_BINDFS_WRAPPER = """#!/bin/bash
+# Chrome Debug Launcher for Linux (bindfs mode)
+# Generated by webtap setup-chrome --bindfs
+# Mounts your real Chrome profile via bindfs for debugging with full session state
+
+DEBUG_DIR="$HOME/.config/google-chrome-debug"
+REAL_DIR="$HOME/.config/google-chrome"
+PORT=${{WEBTAP_PORT:-9222}}
+CHROME_BIN="{chrome_path}"
+
+# Check if bindfs is installed
+if ! command -v bindfs &>/dev/null; then
+    echo "Error: bindfs not installed. Install with:" >&2
+    echo "  Ubuntu/Debian: sudo apt install bindfs" >&2
+    echo "  Arch: yay -S bindfs" >&2
+    echo "  Fedora: sudo dnf install bindfs" >&2
+    exit 1
+fi
+
+# Check if real Chrome profile exists
+if [ ! -d "$REAL_DIR" ]; then
+    echo "Error: Chrome profile not found at $REAL_DIR" >&2
+    echo "Please run Chrome normally first to create a profile" >&2
+    exit 1
+fi
+
+# Mount real profile via bindfs if not already mounted
+if ! mountpoint -q "$DEBUG_DIR" 2>/dev/null; then
+    mkdir -p "$DEBUG_DIR"
+    if ! bindfs --no-allow-other "$REAL_DIR" "$DEBUG_DIR"; then
+        echo "Error: Failed to mount Chrome profile via bindfs" >&2
+        exit 1
+    fi
+    echo "Chrome debug profile mounted. To unmount: fusermount -u $DEBUG_DIR" >&2
+fi
+
+# Launch Chrome with debugging on bindfs mount
+exec "$CHROME_BIN" \\
+    --remote-debugging-port="$PORT" \\
+    --remote-allow-origins='*' \\
+    --user-data-dir="$DEBUG_DIR" \\
+    "$@"
+"""
+
+LINUX_STANDARD_WRAPPER = """#!/bin/bash
+# Chrome Debug Launcher for Linux
+# Generated by webtap setup-chrome
+
+# Configuration
+PORT=${{WEBTAP_PORT:-9222}}
+PROFILE_BASE="{profile_dir}"
+CHROME_BIN="{chrome_path}"
+
+# Profile handling
+if [ "$1" = "--temp" ]; then
+    PROFILE_DIR="$(mktemp -d /tmp/webtap-chrome-XXXXXX)"
+    shift
+    echo "Using temporary profile: $PROFILE_DIR" >&2
+else
+    PROFILE_DIR="$PROFILE_BASE/default"
+    mkdir -p "$PROFILE_DIR"
+fi
+
+# Launch Chrome with debugging
+exec "$CHROME_BIN" \\
+    --remote-debugging-port="$PORT" \\
+    --user-data-dir="$PROFILE_DIR" \\
+    --no-first-run \\
+    --no-default-browser-check \\
+    "$@"
+"""
+
+MACOS_WRAPPER = """#!/bin/bash
+# Chrome Debug Launcher for macOS
+# Generated by webtap setup-chrome
+
+# Configuration
+PORT=${{WEBTAP_PORT:-9222}}
+PROFILE_BASE="{profile_dir}"
+CHROME_APP="{chrome_path}"
+
+# Profile handling
+if [ "$1" = "--temp" ]; then
+    PROFILE_DIR="$(mktemp -d /tmp/webtap-chrome-XXXXXX)"
+    shift
+    echo "Using temporary profile: $PROFILE_DIR" >&2
+else
+    PROFILE_DIR="$PROFILE_BASE/default"
+    mkdir -p "$PROFILE_DIR"
+fi
+
+# Launch Chrome with debugging
+exec "$CHROME_APP" \\
+    --remote-debugging-port="$PORT" \\
+    --user-data-dir="$PROFILE_DIR" \\
+    --no-first-run \\
+    --no-default-browser-check \\
+    "$@"
+"""
+
+
+class ChromeSetupService:
+    """Chrome wrapper installation service (cross-platform)."""
+
+    def __init__(self):
+        self.info = get_platform_info()
+        self.paths = self.info["paths"]
+        self.chrome = self.info["chrome"]
+
+        # Unified wrapper location for both platforms
+        self.wrapper_dir = self.paths["bin_dir"]  # ~/.local/bin
+        self.wrapper_name = self.chrome["wrapper_name"]  # chrome-debug
+        self.wrapper_path = self.wrapper_dir / self.wrapper_name
+
+        # Profile locations
+        self.profile_dir = self.paths["data_dir"] / "profiles"
+        self.temp_profile_dir = self.paths["runtime_dir"] / "profiles"
+
+    def install_wrapper(self, force: bool = False, bindfs: bool = False) -> Dict[str, Any]:
+        """Install Chrome wrapper script appropriate for platform.
+
+        Args:
+            force: Overwrite existing wrapper
+            bindfs: Use bindfs to mount real Chrome profile (Linux only)
+
+        Returns:
+            Installation result
+        """
+        if not self.chrome["found"]:
+            return {
+                "success": False,
+                "message": "Chrome not found on system",
+                "details": "Please install Google Chrome first",
+            }
+
+        if self.wrapper_path.exists() and not force:
+            return {
+                "success": False,
+                "message": f"Wrapper already exists at {self.wrapper_path}",
+                "details": "Use --force to overwrite",
+                "path": str(self.wrapper_path),
+            }
+
+        # Ensure directories exist
+        ensure_directories()
+        self.wrapper_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate platform-specific wrapper
+        if self.info["is_macos"]:
+            wrapper_content = self._generate_macos_wrapper()
+        else:
+            wrapper_content = self._generate_linux_wrapper(bindfs=bindfs)
+
+        self.wrapper_path.write_text(wrapper_content)
+        self.wrapper_path.chmod(0o755)
+
+        # Check if wrapper dir is in PATH
+        path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+        in_path = str(self.wrapper_dir) in path_dirs
+
+        logger.info(f"Installed Chrome wrapper to {self.wrapper_path}")
+
+        # Build detailed message with PATH setup instructions
+        if in_path:
+            details = "✅ Run 'chrome-debug' to launch Chrome with debugging"
+        else:
+            shell = os.environ.get("SHELL", "/bin/bash")
+            if "zsh" in shell:
+                rc_file = "~/.zshrc"
+            elif "fish" in shell:
+                rc_file = "~/.config/fish/config.fish"
+            else:
+                rc_file = "~/.bashrc"
+
+            details = (
+                f"⚠️  Add to PATH to use from terminal:\n"
+                f"echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> {rc_file}\n"
+                f"source {rc_file}\n\n"
+                f"Or run directly: ~/.local/bin/chrome-debug\n"
+                f"✅ GUI launcher will work regardless (uses full path)"
+            )
+
+        return {
+            "success": True,
+            "message": "Chrome wrapper 'chrome-debug' installed successfully",
+            "path": str(self.wrapper_path),
+            "details": details,
+        }
+
+    def _generate_linux_wrapper(self, bindfs: bool = False) -> str:
+        """Generate Linux wrapper script with optional bindfs support.
+
+        Args:
+            bindfs: If True, use bindfs to mount real Chrome profile
+
+        Returns:
+            Wrapper script content
+        """
+        chrome_path = self.chrome["path"]
+        profile_dir = self.profile_dir
+
+        if bindfs:
+            return LINUX_BINDFS_WRAPPER.format(chrome_path=chrome_path)
+        else:
+            return LINUX_STANDARD_WRAPPER.format(chrome_path=chrome_path, profile_dir=profile_dir)
+
+    def _generate_macos_wrapper(self) -> str:
+        """Generate macOS wrapper script.
+
+        Returns:
+            Wrapper script content
+        """
+        chrome_path = self.chrome["path"]
+        profile_dir = self.profile_dir
+
+        return MACOS_WRAPPER.format(chrome_path=chrome_path, profile_dir=profile_dir)