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

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

@@ -15,6 +15,44 @@ 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
+- New `setup-desktop` command to install desktop entry for GUI Chrome integration
+- Desktop entry installation that overrides system Chrome launcher to use debug wrapper
+- Automatic detection and modification of system Chrome desktop files
+
+### Changed
+- Refactored setup service from monolithic file into modular components
+- Split `services/setup.py` into separate modules: `filters.py`, `extension.py`, `chrome.py`, `desktop.py`
+- Updated type hints to use modern Python 3.9+ style (`dict` instead of `Dict`)
+
+### Fixed
+- Code style issues across setup modules (imports, formatting, type hints)
+
+### Removed
+
 ## [0.1.4] - 2025-09-08
 
 ### Added

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

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: webtap-tool
-Version: 0.1.4
+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.4 → webtap_tool-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webtap-tool"
-version = "0.1.4"
+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.2.0/src/webtap/commands/setup.py

@@ -0,0 +1,258 @@
+"""Setup commands for WebTap components."""
+
+from webtap.app import app
+from webtap.services.setup import SetupService
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "setup-filters", "help": "Download filter configuration from GitHub"},
+    fastmcp={"enabled": False},
+)
+def setup_filters(state, force: bool = False) -> dict:
+    """Download filter configuration to ./.webtap/filters.json.
+
+    Args:
+        force: Overwrite existing file (default: False)
+
+    Returns:
+        Markdown-formatted result with success/error messages
+    """
+    service = SetupService()
+    result = service.install_filters(force=force)
+    return _format_setup_result(result, "filters")
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "setup-extension", "help": "Download Chrome extension from GitHub"},
+    fastmcp={"enabled": False},
+)
+def setup_extension(state, force: bool = False) -> dict:
+    """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)
+
+    Returns:
+        Markdown-formatted result with success/error messages
+    """
+    service = SetupService()
+    result = service.install_extension(force=force)
+    return _format_setup_result(result, "extension")
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "setup-chrome", "help": "Install Chrome wrapper script for debugging"},
+    fastmcp={"enabled": False},
+)
+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, bindfs=bindfs)
+    return _format_setup_result(result, "chrome")
+
+
+@app.command(
+    display="markdown",
+    typer={"name": "setup-desktop", "help": "Install Chrome Debug GUI launcher"},
+    fastmcp={"enabled": False},
+)
+def setup_desktop(state, force: bool = False) -> dict:
+    """Install Chrome Debug GUI launcher (separate from system Chrome).
+
+    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 launcher (default: False)
+
+    Returns:
+        Markdown-formatted result with success/error messages
+    """
+    service = SetupService()
+    result = service.install_desktop_entry(force=force)
+    return _format_setup_result(result, "desktop")
+
+
+def _format_setup_result(result: dict, component: str) -> dict:
+    """Format setup result as markdown."""
+    elements = []
+
+    # Main message as alert (using "message" key for consistency)
+    level = "success" if result["success"] else "error"
+    elements.append({"type": "alert", "message": result["message"], "level": level})
+
+    # Add details if present
+    if result.get("path"):
+        elements.append({"type": "text", "content": f"**Location:** `{result['path']}`"})
+    if result.get("details"):
+        elements.append({"type": "text", "content": f"**Details:** {result['details']}"})
+
+    # Component-specific next steps
+    if result["success"]:
+        if component == "filters":
+            elements.append({"type": "text", "content": "\n**Next steps:**"})
+            elements.append(
+                {
+                    "type": "list",
+                    "items": [
+                        "Run `filters('load')` to load the filters",
+                        "Run `filters()` to see loaded categories",
+                    ],
+                }
+            )
+        elif component == "extension":
+            elements.append({"type": "text", "content": "\n**To install in Chrome:**"})
+            elements.append(
+                {
+                    "type": "list",
+                    "items": [
+                        "Open chrome://extensions/",
+                        "Enable Developer mode",
+                        "Click 'Load unpacked'",
+                        f"Select {result['path']}",
+                    ],
+                }
+            )
+        elif component == "chrome":
+            if "Add to PATH" in result.get("details", ""):
+                elements.append({"type": "text", "content": "\n**Setup PATH:**"})
+                elements.append(
+                    {
+                        "type": "code_block",
+                        "language": "bash",
+                        "content": 'export PATH="$HOME/.local/bin/wrappers:$PATH"',
+                    }
+                )
+                elements.append({"type": "text", "content": "Add to ~/.bashrc to make permanent"})
+            else:
+                elements.append({"type": "text", "content": "\n**Usage:**"})
+                elements.append(
+                    {
+                        "type": "list",
+                        "items": [
+                            "Run `google-chrome-stable` to start Chrome with debugging",
+                            "Or use `run-chrome` command for direct launch",
+                        ],
+                    }
+                )
+        elif component == "desktop":
+            elements.append({"type": "text", "content": "\n**Next steps:**"})
+            elements.append(
+                {
+                    "type": "list",
+                    "items": [
+                        "Log out and log back in (or run `update-desktop-database ~/.local/share/applications`)",
+                        "Chrome will now launch with debugging enabled from GUI",
+                        "The wrapper at ~/.local/bin/wrappers/google-chrome-stable will be used",
+                    ],
+                }
+            )
+
+    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"]