provide-foundation 0.0.0.dev0__py3-none-any.whl → 0.0.0.dev2__py3-none-any.whl

provide/foundation/tools/downloader.py

@@ -0,0 +1,224 @@
+"""
+Tool download orchestration with progress reporting.
+
+Provides capabilities for downloading tools with progress tracking,
+parallel downloads, and mirror support.
+"""
+
+import hashlib
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Callable
+
+from provide.foundation.errors import FoundationError
+from provide.foundation.logger import get_logger
+from provide.foundation.resilience import retry, fallback
+from provide.foundation.transport import UniversalClient
+
+log = get_logger(__name__)
+
+
+class DownloadError(FoundationError):
+    """Raised when download fails."""
+    
+    pass
+
+
+class ToolDownloader:
+    """
+    Advanced download capabilities for tools.
+    
+    Features:
+    - Progress reporting with callbacks
+    - Parallel downloads for multiple files
+    - Mirror fallback support
+    - Checksum verification
+    
+    Attributes:
+        client: Transport client for HTTP requests.
+        progress_callbacks: List of progress callback functions.
+    """
+    
+    def __init__(self, client: UniversalClient):
+        """
+        Initialize the downloader.
+        
+        Args:
+            client: Universal client for making HTTP requests.
+        """
+        self.client = client
+        self.progress_callbacks: list[Callable[[int, int], None]] = []
+    
+    def add_progress_callback(self, callback: Callable[[int, int], None]) -> None:
+        """
+        Add a progress callback.
+        
+        Args:
+            callback: Function that receives (downloaded_bytes, total_bytes).
+        """
+        self.progress_callbacks.append(callback)
+    
+    def _report_progress(self, downloaded: int, total: int) -> None:
+        """
+        Report progress to all callbacks.
+        
+        Args:
+            downloaded: Bytes downloaded so far.
+            total: Total bytes to download (0 if unknown).
+        """
+        for callback in self.progress_callbacks:
+            try:
+                callback(downloaded, total)
+            except Exception as e:
+                log.warning(f"Progress callback failed: {e}")
+    
+    @retry(max_attempts=3, base_delay=1.0)
+    def download_with_progress(
+        self,
+        url: str,
+        dest: Path,
+        checksum: str | None = None
+    ) -> Path:
+        """
+        Download a file with progress reporting.
+        
+        Args:
+            url: URL to download from.
+            dest: Destination file path.
+            checksum: Optional checksum for verification.
+            
+        Returns:
+            Path to the downloaded file.
+            
+        Raises:
+            DownloadError: If download or verification fails.
+        """
+        log.debug(f"Downloading {url} to {dest}")
+        
+        # Ensure parent directory exists
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Stream download with progress
+        with self.client.stream("GET", url) as response:
+            # Get total size if available
+            total_size = int(response.headers.get("content-length", 0))
+            downloaded = 0
+            
+            # Write to file and report progress
+            with dest.open("wb") as f:
+                for chunk in response.iter_bytes(8192):
+                    f.write(chunk)
+                    downloaded += len(chunk)
+                    self._report_progress(downloaded, total_size)
+        
+        # Verify checksum if provided
+        if checksum:
+            if not self.verify_checksum(dest, checksum):
+                dest.unlink()
+                raise DownloadError(f"Checksum mismatch for {url}")
+        
+        log.info(f"Downloaded {url} successfully")
+        return dest
+    
+    def verify_checksum(self, file_path: Path, expected: str) -> bool:
+        """
+        Verify file checksum.
+        
+        Args:
+            file_path: Path to file to verify.
+            expected: Expected checksum (hex string).
+            
+        Returns:
+            True if checksum matches, False otherwise.
+        """
+        # Default to SHA256
+        hasher = hashlib.sha256()
+        
+        with file_path.open("rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                hasher.update(chunk)
+        
+        actual = hasher.hexdigest()
+        return actual == expected
+    
+    def download_parallel(
+        self,
+        urls: list[tuple[str, Path]]
+    ) -> list[Path]:
+        """
+        Download multiple files in parallel.
+        
+        Args:
+            urls: List of (url, destination) tuples.
+            
+        Returns:
+            List of downloaded file paths in the same order as input.
+            
+        Raises:
+            DownloadError: If any download fails.
+        """
+        errors = []
+        
+        with ThreadPoolExecutor(max_workers=4) as executor:
+            # Submit all downloads, maintaining order with index
+            futures = [
+                executor.submit(self.download_with_progress, url, dest)
+                for url, dest in urls
+            ]
+            
+            # Collect results in order
+            results = []
+            for i, future in enumerate(futures):
+                url, dest = urls[i]
+                try:
+                    result = future.result()
+                    results.append(result)
+                except Exception as e:
+                    errors.append((url, e))
+                    log.error(f"Failed to download {url}: {e}")
+        
+        if errors:
+            raise DownloadError(f"Some downloads failed: {errors}")
+        
+        return results
+    
+    def download_with_mirrors(
+        self,
+        mirrors: list[str],
+        dest: Path
+    ) -> Path:
+        """
+        Try multiple mirrors until one succeeds using fallback pattern.
+        
+        Args:
+            mirrors: List of mirror URLs to try.
+            dest: Destination file path.
+            
+        Returns:
+            Path to downloaded file.
+            
+        Raises:
+            DownloadError: If all mirrors fail.
+        """
+        from provide.foundation.resilience.fallback import FallbackChain
+        
+        if not mirrors:
+            raise DownloadError("No mirrors provided")
+        
+        # Create fallback functions for each mirror
+        fallback_funcs = []
+        for mirror_url in mirrors:
+            def create_mirror_func(url):
+                def mirror_download():
+                    log.debug(f"Trying mirror: {url}")
+                    return self.download_with_progress(url, dest)
+                return mirror_download
+            fallback_funcs.append(create_mirror_func(mirror_url))
+        
+        # Use FallbackChain to try mirrors in order
+        chain = FallbackChain(fallbacks=fallback_funcs[1:])  # All but first are fallbacks
+        
+        try:
+            return chain.execute(fallback_funcs[0])  # First is primary
+        except Exception as e:
+            raise DownloadError(f"All mirrors failed: {e}")

provide/foundation/tools/installer.py

@@ -0,0 +1,254 @@
+"""
+Tool installation manager for various archive formats.
+
+Handles extraction and installation of tools from different
+archive formats (zip, tar, gz, etc.) and binary files.
+"""
+
+import shutil
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+
+from provide.foundation.errors import FoundationError
+from provide.foundation.logger import get_logger
+from provide.foundation.tools.base import ToolMetadata
+
+log = get_logger(__name__)
+
+
+class InstallError(FoundationError):
+    """Raised when installation fails."""
+    
+    pass
+
+
+class ToolInstaller:
+    """
+    Handle tool installation from various artifact formats.
+    
+    Supports:
+    - ZIP archives
+    - TAR archives (with compression)
+    - Single binary files
+    - Platform-specific installation patterns
+    """
+    
+    def install(self, artifact: Path, metadata: ToolMetadata) -> Path:
+        """
+        Install tool from artifact.
+        
+        Args:
+            artifact: Path to downloaded artifact.
+            metadata: Tool metadata with installation info.
+            
+        Returns:
+            Path to installed tool directory.
+            
+        Raises:
+            InstallError: If installation fails.
+        """
+        if not artifact.exists():
+            raise InstallError(f"Artifact not found: {artifact}")
+        
+        # Determine install directory
+        install_dir = self.get_install_dir(metadata)
+        
+        log.info(f"Installing {metadata.name} {metadata.version} to {install_dir}")
+        
+        # Extract based on file type
+        suffix = artifact.suffix.lower()
+        if suffix == ".zip":
+            self.extract_zip(artifact, install_dir)
+        elif suffix in [".tar", ".gz", ".tgz", ".bz2", ".xz"]:
+            self.extract_tar(artifact, install_dir)
+        elif self.is_binary(artifact):
+            self.install_binary(artifact, install_dir, metadata)
+        else:
+            raise InstallError(f"Unknown artifact type: {suffix}")
+        
+        # Set permissions
+        self.set_permissions(install_dir, metadata)
+        
+        # Create symlinks if needed
+        self.create_symlinks(install_dir, metadata)
+        
+        log.info(f"Successfully installed {metadata.name} to {install_dir}")
+        return install_dir
+    
+    def get_install_dir(self, metadata: ToolMetadata) -> Path:
+        """
+        Get installation directory for tool.
+        
+        Args:
+            metadata: Tool metadata.
+            
+        Returns:
+            Installation directory path.
+        """
+        if metadata.install_path:
+            return metadata.install_path
+        
+        # Default to ~/.wrknv/tools/<name>/<version>
+        base = Path.home() / ".wrknv" / "tools"
+        return base / metadata.name / metadata.version
+    
+    def extract_zip(self, archive: Path, dest: Path) -> None:
+        """
+        Extract ZIP archive.
+        
+        Args:
+            archive: Path to ZIP file.
+            dest: Destination directory.
+        """
+        log.debug(f"Extracting ZIP {archive} to {dest}")
+        
+        dest.mkdir(parents=True, exist_ok=True)
+        
+        with zipfile.ZipFile(archive, "r") as zf:
+            # Check for unsafe paths
+            for member in zf.namelist():
+                if member.startswith("/") or ".." in member:
+                    raise InstallError(f"Unsafe path in archive: {member}")
+            
+            zf.extractall(dest)
+    
+    def extract_tar(self, archive: Path, dest: Path) -> None:
+        """
+        Extract tar archive (with optional compression).
+        
+        Args:
+            archive: Path to tar file.
+            dest: Destination directory.
+        """
+        log.debug(f"Extracting tar {archive} to {dest}")
+        
+        dest.mkdir(parents=True, exist_ok=True)
+        
+        # Determine mode based on extension
+        mode = "r"
+        if archive.suffix in [".gz", ".tgz"]:
+            mode = "r:gz"
+        elif archive.suffix == ".bz2":
+            mode = "r:bz2"
+        elif archive.suffix == ".xz":
+            mode = "r:xz"
+        
+        with tarfile.open(archive, mode) as tf:
+            # Check for unsafe paths
+            for member in tf.getmembers():
+                if member.name.startswith("/") or ".." in member.name:
+                    raise InstallError(f"Unsafe path in archive: {member.name}")
+            
+            tf.extractall(dest)
+    
+    def is_binary(self, file_path: Path) -> bool:
+        """
+        Check if file is a binary executable.
+        
+        Args:
+            file_path: Path to check.
+            
+        Returns:
+            True if file appears to be binary.
+        """
+        # Check if file has no extension or common binary extensions
+        if not file_path.suffix or file_path.suffix in [".exe", ".bin"]:
+            # Try to read first few bytes
+            try:
+                with file_path.open("rb") as f:
+                    header = f.read(4)
+                    # Check for common binary signatures
+                    if header.startswith(b"\x7fELF"):  # Linux ELF
+                        return True
+                    if header.startswith(b"MZ"):  # Windows PE
+                        return True
+                    if header.startswith(b"\xfe\xed\xfa"):  # macOS Mach-O
+                        return True
+                    if header.startswith(b"\xca\xfe\xba\xbe"):  # macOS universal
+                        return True
+            except Exception:
+                pass
+        
+        return False
+    
+    def install_binary(
+        self,
+        binary: Path,
+        dest: Path,
+        metadata: ToolMetadata
+    ) -> None:
+        """
+        Install single binary file.
+        
+        Args:
+            binary: Path to binary file.
+            dest: Destination directory.
+            metadata: Tool metadata.
+        """
+        log.debug(f"Installing binary {binary} to {dest}")
+        
+        dest.mkdir(parents=True, exist_ok=True)
+        bin_dir = dest / "bin"
+        bin_dir.mkdir(exist_ok=True)
+        
+        # Determine target name
+        target_name = metadata.executable_name or binary.name
+        target = bin_dir / target_name
+        
+        # Copy binary
+        shutil.copy2(binary, target)
+        
+        # Make executable
+        target.chmod(0o755)
+    
+    def set_permissions(self, install_dir: Path, metadata: ToolMetadata) -> None:
+        """
+        Set appropriate permissions on installed files.
+        
+        Args:
+            install_dir: Installation directory.
+            metadata: Tool metadata.
+        """
+        import platform
+        
+        if platform.system() == "Windows":
+            return  # Windows handles permissions differently
+        
+        # Find executables and make them executable
+        bin_dir = install_dir / "bin"
+        if bin_dir.exists():
+            for file in bin_dir.iterdir():
+                if file.is_file():
+                    file.chmod(0o755)
+        
+        # Check for executable name in root
+        if metadata.executable_name:
+            exe_path = install_dir / metadata.executable_name
+            if exe_path.exists():
+                exe_path.chmod(0o755)
+    
+    def create_symlinks(self, install_dir: Path, metadata: ToolMetadata) -> None:
+        """
+        Create symlinks for easier access.
+        
+        Args:
+            install_dir: Installation directory.
+            metadata: Tool metadata.
+        """
+        import platform
+        
+        if platform.system() == "Windows":
+            return  # Windows doesn't support symlinks easily
+        
+        # Create version-less symlink
+        if metadata.name and metadata.version:
+            parent = install_dir.parent
+            latest_link = parent / "latest"
+            
+            if latest_link.exists() or latest_link.is_symlink():
+                latest_link.unlink()
+            
+            latest_link.symlink_to(install_dir)
+            log.debug(f"Created symlink {latest_link} -> {install_dir}")

provide/foundation/tools/registry.py

@@ -0,0 +1,223 @@
+"""
+Tool registry management using the foundation hub.
+
+Provides registration and discovery of tool managers using
+the main hub registry with proper dimension separation.
+"""
+
+import importlib.metadata
+from typing import Any
+
+from provide.foundation.config import BaseConfig
+from provide.foundation.hub import get_hub
+from provide.foundation.logger import get_logger
+from provide.foundation.tools.base import BaseToolManager
+
+log = get_logger(__name__)
+
+
+class ToolRegistry:
+    """
+    Wrapper around the hub registry for tool management.
+    
+    Uses the main hub registry with dimension="tool_manager"
+    to avoid namespace pollution while leveraging existing
+    registry infrastructure.
+    """
+    
+    DIMENSION = "tool_manager"
+    
+    def __init__(self):
+        """Initialize the tool registry."""
+        self.hub = get_hub()
+        self._discover_tools()
+    
+    def _discover_tools(self) -> None:
+        """
+        Auto-discover tool managers via entry points.
+        
+        Looks for entry points in the "wrknv.tools" group
+        and automatically registers them.
+        """
+        try:
+            # Get entry points for tool managers
+            if hasattr(importlib.metadata, 'entry_points'):
+                # Python 3.10+
+                eps = importlib.metadata.entry_points()
+                if hasattr(eps, 'select'):
+                    # Python 3.10+ with select method
+                    group_eps = eps.select(group="wrknv.tools")
+                else:
+                    # Fallback for older API
+                    group_eps = eps.get("wrknv.tools", [])
+            else:
+                # Python 3.8-3.9
+                eps = importlib.metadata.entry_points()
+                group_eps = eps.get("wrknv.tools", [])
+            
+            for ep in group_eps:
+                try:
+                    manager_class = ep.load()
+                    self.register_tool_manager(ep.name, manager_class)
+                    log.debug(f"Auto-discovered tool manager: {ep.name}")
+                except Exception as e:
+                    log.warning(f"Failed to load tool manager {ep.name}: {e}")
+        except Exception as e:
+            log.debug(f"Entry point discovery not available: {e}")
+    
+    def register_tool_manager(
+        self,
+        name: str,
+        manager_class: type[BaseToolManager],
+        aliases: list[str] | None = None
+    ) -> None:
+        """
+        Register a tool manager with the hub.
+        
+        Args:
+            name: Tool name (e.g., "terraform").
+            manager_class: Tool manager class.
+            aliases: Optional aliases for the tool.
+        """
+        # Prepare metadata
+        metadata = {
+            "tool_name": manager_class.tool_name,
+            "executable": manager_class.executable_name,
+            "platforms": manager_class.supported_platforms,
+        }
+        
+        # Register with hub
+        self.hub.registry.register(
+            name=name,
+            value=manager_class,
+            dimension=self.DIMENSION,
+            metadata=metadata,
+            aliases=aliases,
+            replace=True  # Allow re-registration for updates
+        )
+        
+        log.info(f"Registered tool manager: {name}")
+    
+    def get_tool_manager_class(self, name: str) -> type[BaseToolManager] | None:
+        """
+        Get a tool manager class by name.
+        
+        Args:
+            name: Tool name or alias.
+            
+        Returns:
+            Tool manager class, or None if not found.
+        """
+        return self.hub.registry.get(name, dimension=self.DIMENSION)
+    
+    def create_tool_manager(
+        self,
+        name: str,
+        config: BaseConfig
+    ) -> BaseToolManager | None:
+        """
+        Create a tool manager instance.
+        
+        Args:
+            name: Tool name or alias.
+            config: Configuration object.
+            
+        Returns:
+            Tool manager instance, or None if not found.
+        """
+        manager_class = self.get_tool_manager_class(name)
+        if manager_class:
+            return manager_class(config)
+        return None
+    
+    def list_tools(self) -> list[tuple[str, dict[str, Any]]]:
+        """
+        List all registered tools.
+        
+        Returns:
+            List of (name, metadata) tuples.
+        """
+        tools = []
+        for name, entry in self.hub.registry.list_dimension(self.DIMENSION):
+            metadata = entry.metadata if hasattr(entry, 'metadata') else {}
+            tools.append((name, metadata))
+        return tools
+    
+    def get_tool_info(self, name: str) -> dict[str, Any] | None:
+        """
+        Get information about a specific tool.
+        
+        Args:
+            name: Tool name or alias.
+            
+        Returns:
+            Tool metadata dictionary, or None if not found.
+        """
+        entry = self.hub.registry.get_entry(name, dimension=self.DIMENSION)
+        if entry and hasattr(entry, 'metadata'):
+            return entry.metadata
+        return None
+    
+    def is_tool_registered(self, name: str) -> bool:
+        """
+        Check if a tool is registered.
+        
+        Args:
+            name: Tool name or alias.
+            
+        Returns:
+            True if registered, False otherwise.
+        """
+        return self.get_tool_manager_class(name) is not None
+
+
+# Global registry instance
+_tool_registry: ToolRegistry | None = None
+
+
+def get_tool_registry() -> ToolRegistry:
+    """
+    Get the global tool registry instance.
+    
+    Returns:
+        Tool registry instance.
+    """
+    global _tool_registry
+    if _tool_registry is None:
+        _tool_registry = ToolRegistry()
+    return _tool_registry
+
+
+def register_tool_manager(
+    name: str,
+    manager_class: type[BaseToolManager],
+    aliases: list[str] | None = None
+) -> None:
+    """
+    Register a tool manager with the global registry.
+    
+    Args:
+        name: Tool name.
+        manager_class: Tool manager class.
+        aliases: Optional aliases.
+    """
+    registry = get_tool_registry()
+    registry.register_tool_manager(name, manager_class, aliases)
+
+
+def get_tool_manager(
+    name: str,
+    config: BaseConfig
+) -> BaseToolManager | None:
+    """
+    Get a tool manager instance from the global registry.
+    
+    Args:
+        name: Tool name or alias.
+        config: Configuration object.
+        
+    Returns:
+        Tool manager instance, or None if not found.
+    """
+    registry = get_tool_registry()
+    return registry.create_tool_manager(name, config)