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

provide/foundation/tools/__init__.py

@@ -0,0 +1,58 @@
+"""
+Provide Foundation Tools Module
+================================
+
+Unified tool management system for downloading, verifying, installing, and
+managing development tools across the provide-io ecosystem.
+
+This module provides:
+- Base classes for tool managers
+- Download orchestration with progress reporting
+- Checksum and signature verification
+- Installation handling for various formats
+- Version resolution (latest, semver, wildcards)
+- Caching with TTL support
+- Tool registry integration
+
+Example:
+    >>> from provide.foundation.tools import get_tool_manager
+    >>> from provide.foundation.config import BaseConfig
+    >>>
+    >>> config = BaseConfig()
+    >>> tf_manager = get_tool_manager("terraform", config)
+    >>> tf_manager.install("1.5.0")
+    PosixPath('/home/user/.wrknv/tools/terraform/1.5.0')
+"""
+
+from provide.foundation.tools.base import (
+    BaseToolManager,
+    ToolMetadata,
+    ToolError,
+)
+from provide.foundation.tools.cache import ToolCache
+from provide.foundation.tools.downloader import ToolDownloader
+from provide.foundation.tools.installer import ToolInstaller
+from provide.foundation.tools.registry import (
+    get_tool_manager,
+    get_tool_registry,
+    register_tool_manager,
+)
+from provide.foundation.tools.resolver import VersionResolver
+from provide.foundation.tools.verifier import ToolVerifier
+
+__all__ = [
+    # Base classes
+    "BaseToolManager",
+    "ToolMetadata",
+    "ToolError",
+    # Components
+    "ToolCache",
+    "ToolDownloader",
+    "ToolInstaller",
+    "ToolVerifier",
+    "VersionResolver",
+    # Registry functions
+    "get_tool_manager",
+    "get_tool_registry",
+    "register_tool_manager",
+]

provide/foundation/tools/base.py

@@ -0,0 +1,348 @@
+"""
+Base classes for tool management.
+
+This module provides the foundation for tool managers, including
+the base manager class and metadata structures.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from attrs import define, field
+
+from provide.foundation.config import BaseConfig
+from provide.foundation.errors import FoundationError
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class ToolError(FoundationError):
+    """Base exception for tool-related errors."""
+    
+    pass
+
+
+class ToolNotFoundError(ToolError):
+    """Raised when a tool or version cannot be found."""
+    
+    pass
+
+
+class ToolInstallError(ToolError):
+    """Raised when tool installation fails."""
+    
+    pass
+
+
+class ToolVerificationError(ToolError):
+    """Raised when tool verification fails."""
+    
+    pass
+
+
+@define
+class ToolMetadata:
+    """
+    Metadata about a tool version.
+    
+    Attributes:
+        name: Tool name (e.g., "terraform").
+        version: Version string (e.g., "1.5.0").
+        platform: Platform identifier (e.g., "linux", "darwin").
+        arch: Architecture (e.g., "amd64", "arm64").
+        checksum: Optional checksum for verification.
+        signature: Optional GPG/PGP signature.
+        download_url: URL to download the tool.
+        checksum_url: URL to download checksums file.
+        install_path: Where the tool is/will be installed.
+        env_vars: Environment variables to set.
+        dependencies: Other tools this depends on.
+        executable_name: Name of the executable file.
+    """
+    
+    name: str
+    version: str
+    platform: str
+    arch: str
+    checksum: str | None = None
+    signature: str | None = None
+    download_url: str | None = None
+    checksum_url: str | None = None
+    install_path: Path | None = None
+    env_vars: dict[str, str] = field(factory=dict)
+    dependencies: list[str] = field(factory=list)
+    executable_name: str | None = None
+
+
+class BaseToolManager(ABC):
+    """
+    Abstract base class for tool managers.
+    
+    Provides common functionality for downloading, verifying, and installing
+    development tools. Subclasses must implement platform-specific logic.
+    
+    Attributes:
+        config: Configuration object.
+        tool_name: Name of the tool being managed.
+        executable_name: Name of the executable file.
+        supported_platforms: List of supported platforms.
+    """
+    
+    # Class attributes to be overridden by subclasses
+    tool_name: str = ""
+    executable_name: str = ""
+    supported_platforms: list[str] = ["linux", "darwin", "windows"]
+    
+    def __init__(self, config: BaseConfig):
+        """
+        Initialize the tool manager.
+        
+        Args:
+            config: Configuration object containing settings.
+        """
+        if not self.tool_name:
+            raise ToolError("Subclass must define tool_name")
+        if not self.executable_name:
+            raise ToolError("Subclass must define executable_name")
+            
+        self.config = config
+        
+        # Lazy-load components to avoid circular imports
+        self._cache = None
+        self._downloader = None
+        self._verifier = None
+        self._installer = None
+        self._resolver = None
+        
+        log.debug(f"Initialized {self.tool_name} manager")
+    
+    @property
+    def cache(self):
+        """Get or create cache instance."""
+        if self._cache is None:
+            from provide.foundation.tools.cache import ToolCache
+            self._cache = ToolCache()
+        return self._cache
+    
+    @property
+    def downloader(self):
+        """Get or create downloader instance."""
+        if self._downloader is None:
+            from provide.foundation.tools.downloader import ToolDownloader
+            from provide.foundation.transport import UniversalClient
+            self._downloader = ToolDownloader(UniversalClient())
+        return self._downloader
+    
+    @property
+    def verifier(self):
+        """Get or create verifier instance."""
+        if self._verifier is None:
+            from provide.foundation.tools.verifier import ToolVerifier
+            self._verifier = ToolVerifier()
+        return self._verifier
+    
+    @property
+    def installer(self):
+        """Get or create installer instance."""
+        if self._installer is None:
+            from provide.foundation.tools.installer import ToolInstaller
+            self._installer = ToolInstaller()
+        return self._installer
+    
+    @property
+    def resolver(self):
+        """Get or create version resolver instance."""
+        if self._resolver is None:
+            from provide.foundation.tools.resolver import VersionResolver
+            self._resolver = VersionResolver()
+        return self._resolver
+    
+    @abstractmethod
+    def get_metadata(self, version: str) -> ToolMetadata:
+        """
+        Get metadata for a specific version.
+        
+        Args:
+            version: Version string to get metadata for.
+            
+        Returns:
+            ToolMetadata object with download URLs and checksums.
+        """
+        pass
+    
+    @abstractmethod
+    def get_available_versions(self) -> list[str]:
+        """
+        Get list of available versions from upstream.
+        
+        Returns:
+            List of version strings available for download.
+        """
+        pass
+    
+    def resolve_version(self, spec: str) -> str:
+        """
+        Resolve a version specification to a concrete version.
+        
+        Args:
+            spec: Version specification (e.g., "latest", "~1.5.0").
+            
+        Returns:
+            Concrete version string.
+            
+        Raises:
+            ToolNotFoundError: If version cannot be resolved.
+        """
+        available = self.get_available_versions()
+        if not available:
+            raise ToolNotFoundError(f"No versions available for {self.tool_name}")
+        
+        resolved = self.resolver.resolve(spec, available)
+        if not resolved:
+            raise ToolNotFoundError(
+                f"Cannot resolve version '{spec}' for {self.tool_name}"
+            )
+        
+        log.debug(f"Resolved {self.tool_name} version {spec} to {resolved}")
+        return resolved
+    
+    def install(self, version: str = "latest", force: bool = False) -> Path:
+        """
+        Install a specific version of the tool.
+        
+        Args:
+            version: Version to install (default: "latest").
+            force: Force reinstall even if cached.
+            
+        Returns:
+            Path to the installed tool.
+            
+        Raises:
+            ToolInstallError: If installation fails.
+        """
+        # Resolve version
+        if version in ["latest", "stable", "dev"] or version.startswith(("~", "^")):
+            version = self.resolve_version(version)
+        
+        # Check cache unless forced
+        if not force:
+            if cached_path := self.cache.get(self.tool_name, version):
+                log.info(f"Using cached {self.tool_name} {version}")
+                return cached_path
+        
+        log.info(f"Installing {self.tool_name} {version}")
+        
+        # Get metadata
+        metadata = self.get_metadata(version)
+        if not metadata.download_url:
+            raise ToolInstallError(
+                f"No download URL for {self.tool_name} {version}"
+            )
+        
+        # Download
+        download_path = Path("/tmp") / f"{self.tool_name}-{version}"
+        artifact_path = self.downloader.download_with_progress(
+            metadata.download_url,
+            download_path,
+            metadata.checksum
+        )
+        
+        # Verify if checksum provided
+        if metadata.checksum:
+            if not self.verifier.verify_checksum(artifact_path, metadata.checksum):
+                artifact_path.unlink()
+                raise ToolVerificationError(
+                    f"Checksum verification failed for {self.tool_name} {version}"
+                )
+        
+        # Install
+        install_path = self.installer.install(artifact_path, metadata)
+        
+        # Cache the installation
+        self.cache.store(self.tool_name, version, install_path)
+        
+        # Clean up download
+        if artifact_path.exists():
+            artifact_path.unlink()
+        
+        log.info(f"Successfully installed {self.tool_name} {version} to {install_path}")
+        return install_path
+    
+    def uninstall(self, version: str) -> bool:
+        """
+        Uninstall a specific version.
+        
+        Args:
+            version: Version to uninstall.
+            
+        Returns:
+            True if uninstalled, False if not found.
+        """
+        # Invalidate cache
+        self.cache.invalidate(self.tool_name, version)
+        
+        # Remove from filesystem
+        install_path = self.get_install_path(version)
+        if install_path.exists():
+            import shutil
+            shutil.rmtree(install_path)
+            log.info(f"Uninstalled {self.tool_name} {version}")
+            return True
+        
+        return False
+    
+    def get_install_path(self, version: str) -> Path:
+        """
+        Get the installation path for a version.
+        
+        Args:
+            version: Version string.
+            
+        Returns:
+            Path where the version is/will be installed.
+        """
+        base_path = Path.home() / ".wrknv" / "tools" / self.tool_name / version
+        return base_path
+    
+    def is_installed(self, version: str) -> bool:
+        """
+        Check if a version is installed.
+        
+        Args:
+            version: Version to check.
+            
+        Returns:
+            True if installed, False otherwise.
+        """
+        install_path = self.get_install_path(version)
+        executable = install_path / "bin" / self.executable_name
+        return executable.exists()
+    
+    def get_platform_info(self) -> dict[str, str]:
+        """
+        Get current platform information.
+        
+        Returns:
+            Dictionary with platform and arch keys.
+        """
+        import platform
+        
+        system = platform.system().lower()
+        if system == "darwin":
+            system = "darwin"
+        elif system == "linux":
+            system = "linux"
+        elif system == "windows":
+            system = "windows"
+        
+        machine = platform.machine().lower()
+        if machine in ["x86_64", "amd64"]:
+            arch = "amd64"
+        elif machine in ["aarch64", "arm64"]:
+            arch = "arm64"
+        else:
+            arch = machine
+        
+        return {"platform": system, "arch": arch}

provide/foundation/tools/cache.py

@@ -0,0 +1,266 @@
+"""
+Caching system for installed tools.
+
+Provides TTL-based caching to avoid re-downloading tools
+that are already installed and valid.
+"""
+
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from provide.foundation.errors import FoundationError
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class CacheError(FoundationError):
+    """Raised when cache operations fail."""
+    
+    pass
+
+
+class ToolCache:
+    """
+    Cache for installed tools with TTL support.
+    
+    Tracks installed tool locations and expiration times to
+    avoid unnecessary re-downloads and installations.
+    """
+    
+    def __init__(self, cache_dir: Path | None = None):
+        """
+        Initialize the cache.
+        
+        Args:
+            cache_dir: Cache directory (defaults to ~/.wrknv/cache).
+        """
+        self.cache_dir = cache_dir or (Path.home() / ".wrknv" / "cache")
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.metadata_file = self.cache_dir / "metadata.json"
+        self.metadata = self._load_metadata()
+    
+    def _load_metadata(self) -> dict[str, dict]:
+        """
+        Load cache metadata from disk.
+        
+        Returns:
+            Cache metadata dictionary.
+        """
+        if self.metadata_file.exists():
+            try:
+                with self.metadata_file.open() as f:
+                    return json.load(f)
+            except Exception as e:
+                log.warning(f"Failed to load cache metadata: {e}")
+        
+        return {}
+    
+    def _save_metadata(self) -> None:
+        """Save cache metadata to disk."""
+        try:
+            with self.metadata_file.open("w") as f:
+                json.dump(self.metadata, f, indent=2)
+        except Exception as e:
+            log.error(f"Failed to save cache metadata: {e}")
+    
+    def get(self, tool: str, version: str) -> Path | None:
+        """
+        Get cached tool path if valid.
+        
+        Args:
+            tool: Tool name.
+            version: Tool version.
+            
+        Returns:
+            Path to cached tool if valid, None otherwise.
+        """
+        key = f"{tool}:{version}"
+        
+        if entry := self.metadata.get(key):
+            path = Path(entry["path"])
+            
+            # Check if path exists
+            if not path.exists():
+                log.debug(f"Cache miss: {key} path doesn't exist")
+                self.invalidate(tool, version)
+                return None
+            
+            # Check if expired
+            if self._is_expired(entry):
+                log.debug(f"Cache miss: {key} expired")
+                self.invalidate(tool, version)
+                return None
+            
+            log.debug(f"Cache hit: {key}")
+            return path
+        
+        log.debug(f"Cache miss: {key} not in cache")
+        return None
+    
+    def store(
+        self,
+        tool: str,
+        version: str,
+        path: Path,
+        ttl_days: int = 7
+    ) -> None:
+        """
+        Store tool in cache.
+        
+        Args:
+            tool: Tool name.
+            version: Tool version.
+            path: Path to installed tool.
+            ttl_days: Time-to-live in days.
+        """
+        key = f"{tool}:{version}"
+        
+        self.metadata[key] = {
+            "path": str(path),
+            "tool": tool,
+            "version": version,
+            "cached_at": datetime.now().isoformat(),
+            "ttl_days": ttl_days,
+        }
+        
+        self._save_metadata()
+        log.debug(f"Cached {key} at {path} (TTL: {ttl_days} days)")
+    
+    def invalidate(self, tool: str, version: str | None = None) -> None:
+        """
+        Invalidate cache entries.
+        
+        Args:
+            tool: Tool name.
+            version: Specific version, or None for all versions.
+        """
+        if version:
+            # Invalidate specific version
+            key = f"{tool}:{version}"
+            if key in self.metadata:
+                del self.metadata[key]
+                log.debug(f"Invalidated cache for {key}")
+        else:
+            # Invalidate all versions of tool
+            keys_to_remove = [
+                k for k in self.metadata
+                if self.metadata[k].get("tool") == tool
+            ]
+            for key in keys_to_remove:
+                del self.metadata[key]
+                log.debug(f"Invalidated cache for {key}")
+        
+        self._save_metadata()
+    
+    def _is_expired(self, entry: dict) -> bool:
+        """
+        Check if cache entry is expired.
+        
+        Args:
+            entry: Cache entry dictionary.
+            
+        Returns:
+            True if expired, False otherwise.
+        """
+        try:
+            cached_at = datetime.fromisoformat(entry["cached_at"])
+            ttl_days = entry.get("ttl_days", 7)
+            
+            if ttl_days <= 0:
+                # Never expires
+                return False
+            
+            expiry = cached_at + timedelta(days=ttl_days)
+            return datetime.now() > expiry
+        except Exception as e:
+            log.debug(f"Error checking expiry: {e}")
+            return True  # Treat as expired if we can't determine
+    
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        self.metadata = {}
+        self._save_metadata()
+        log.info("Cleared tool cache")
+    
+    def list_cached(self) -> list[dict]:
+        """
+        List all cached tools.
+        
+        Returns:
+            List of cache entries with metadata.
+        """
+        results = []
+        
+        for key, entry in self.metadata.items():
+            # Add expiry status
+            entry = entry.copy()
+            entry["key"] = key
+            entry["expired"] = self._is_expired(entry)
+            
+            # Calculate days until expiry
+            try:
+                cached_at = datetime.fromisoformat(entry["cached_at"])
+                ttl_days = entry.get("ttl_days", 7)
+                if ttl_days > 0:
+                    expiry = cached_at + timedelta(days=ttl_days)
+                    days_left = (expiry - datetime.now()).days
+                    entry["days_until_expiry"] = max(0, days_left)
+                else:
+                    entry["days_until_expiry"] = -1  # Never expires
+            except Exception:
+                entry["days_until_expiry"] = 0
+            
+            results.append(entry)
+        
+        return results
+    
+    def get_size(self) -> int:
+        """
+        Get total size of cached tools in bytes.
+        
+        Returns:
+            Total size in bytes.
+        """
+        total = 0
+        
+        for entry in self.metadata.values():
+            path = Path(entry["path"])
+            if path.exists():
+                try:
+                    # Calculate directory size
+                    if path.is_dir():
+                        total += sum(
+                            f.stat().st_size
+                            for f in path.rglob("*")
+                            if f.is_file()
+                        )
+                    else:
+                        total += path.stat().st_size
+                except Exception as e:
+                    log.debug(f"Failed to get size of {path}: {e}")
+        
+        return total
+    
+    def prune_expired(self) -> int:
+        """
+        Remove expired entries from cache.
+        
+        Returns:
+            Number of entries removed.
+        """
+        expired_keys = [
+            key for key, entry in self.metadata.items()
+            if self._is_expired(entry)
+        ]
+        
+        for key in expired_keys:
+            del self.metadata[key]
+        
+        if expired_keys:
+            self._save_metadata()
+            log.info(f"Pruned {len(expired_keys)} expired cache entries")
+        
+        return len(expired_keys)