hatch-xclam 0.7.0__py3-none-any.whl

hatch/registry_explorer.py

@@ -0,0 +1,171 @@
+"""Utilities for exploring a Hatch package registry.
+
+This module provides functions to search and extract information from
+a Hatch registry data structure (see hatch_all_pkg_metadata_schema.json).
+"""
+from typing import Any, Dict, List, Optional, Tuple
+from packaging.version import Version, InvalidVersion
+from packaging.specifiers import SpecifierSet, InvalidSpecifier
+
+def find_repository(registry: Dict[str, Any], repo_name: str) -> Optional[Dict[str, Any]]:
+    """Find a repository by name.
+    
+    Args:
+        registry (Dict[str, Any]): The registry data.
+        repo_name (str): Name of the repository to find.
+        
+    Returns:
+        Optional[Dict[str, Any]]: Repository data if found, None otherwise.
+    """
+    for repo in registry.get("repositories", []):
+        if repo.get("name") == repo_name:
+            return repo
+    return None
+
+def list_repositories(registry: Dict[str, Any]) -> List[str]:
+    """List all repository names in the registry.
+    
+    Args:
+        registry (Dict[str, Any]): The registry data.
+        
+    Returns:
+        List[str]: List of repository names.
+    """
+    return [repo.get("name") for repo in registry.get("repositories", [])]
+
+def find_package(registry: Dict[str, Any], package_name: str, repo_name: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """Find a package by name, optionally within a specific repository.
+    
+    Args:
+        registry (Dict[str, Any]): The registry data.
+        package_name (str): Name of the package to find.
+        repo_name (str, optional): Name of the repository to search in. Defaults to None.
+        
+    Returns:
+        Optional[Dict[str, Any]]: Package data if found, None otherwise.
+    """
+    repos = registry.get("repositories", [])
+    if repo_name:
+        repos = [r for r in repos if r.get("name") == repo_name]
+    for repo in repos:
+        for pkg in repo.get("packages", []):
+            if pkg.get("name") == package_name:
+                return pkg
+    return None
+
+def list_packages(registry: Dict[str, Any], repo_name: Optional[str] = None) -> List[str]:
+    """List all package names, optionally within a specific repository.
+    
+    Args:
+        registry (Dict[str, Any]): The registry data.
+        repo_name (str, optional): Name of the repository to list packages from. Defaults to None.
+        
+    Returns:
+        List[str]: List of package names.
+    """
+    packages = []
+    repos = registry.get("repositories", [])
+    if repo_name:
+        repos = [r for r in repos if r.get("name") == repo_name]
+    for repo in repos:
+        for pkg in repo.get("packages", []):
+            packages.append(pkg.get("name"))
+    return packages
+
+def get_latest_version(pkg: Dict[str, Any]) -> Optional[str]:
+    """Get the latest version string for a package dict.
+    
+    Args:
+        pkg (Dict[str, Any]): The package dictionary.
+        
+    Returns:
+        Optional[str]: Latest version string if available, None otherwise.
+    """
+    return pkg.get("latest_version")
+
+def _match_version_constraint(version: str, constraint: str) -> bool:
+    """Check if a version string matches a constraint.
+    
+    Uses the 'packaging' library for robust version comparison.
+    If a simple version like "1.0.0" is passed as constraint, it's treated as "==1.0.0".
+    
+    Args:
+        version (str): Version string to check.
+        constraint (str): Version constraint (e.g., '>=1.2.0').
+        
+    Returns:
+        bool: True if version matches constraint, False otherwise.
+    """
+    try:
+        v = Version(version)
+        
+        # Convert the constraint to a proper SpecifierSet if it doesn't have an operator
+        if constraint and not any(constraint.startswith(op) for op in ['==', '!=', '<=', '>=', '<', '>']):
+            constraint = f"=={constraint}"
+            
+        # Accept constraints like '==1.2.3', '>=1.0.0', etc.
+        spec = SpecifierSet(constraint)
+        return v in spec
+    except (InvalidVersion, InvalidSpecifier):
+        # If we can't parse versions, fall back to string comparison
+        return version == constraint
+
+def find_package_version(pkg: Dict[str, Any], version_constraint: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """Find a version dict for a package, optionally matching a version constraint.
+    
+    This function uses a multi-step approach to find the appropriate version:
+    1. If no constraint is given, it returns the latest version
+    2. If that's not found, it falls back to the highest version number
+    3. For specific constraints, it sorts versions and checks compatibility
+    
+    Args:
+        pkg (Dict[str, Any]): The package dictionary.
+        version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None.
+
+    Returns:
+        Optional[Dict[str, Any]]: The version dict matching the constraint or latest version.
+    """
+    versions = pkg.get("versions", [])
+    if not versions:
+        return None
+    if not version_constraint:
+        # Return the version dict matching latest_version
+        latest = pkg.get("latest_version")
+        for v in versions:
+            if v.get("version") == latest:
+                return v
+        # fallback: return the highest version
+        try:
+            return max(versions, key=lambda x: Version(x.get("version", "0")))
+        except Exception:
+            return versions[-1]    # Try to find a version matching the constraint
+    try:
+        sorted_versions = sorted(versions, key=lambda x: Version(x.get("version", "0")), reverse=True)
+    except Exception:
+         sorted_versions = versions
+    
+    # If no exact match, try parsing as a constraint
+    for v in sorted_versions:
+        if _match_version_constraint(v.get("version", ""), version_constraint):
+            return v
+    return None
+
+def get_package_release_url(pkg: Dict[str, Any], version_constraint: Optional[str] = None) -> Tuple[Optional[str], Optional[str]]:
+    """Get the release URI for a package version matching the constraint (or latest).
+
+    Args:
+        pkg (Dict[str, Any]): The package dictionary.
+        version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None.
+        
+    Returns:
+        Tuple[Optional[str], Optional[str]]: A tuple containing:
+            - str: The release URI satisfying the constraint (or None)
+            - str: The matching version string (or None)
+    """
+    if pkg is None:
+        return None, None
+
+    vdict = find_package_version(pkg, version_constraint)
+    if vdict:
+        return vdict.get("release_uri"), vdict.get("version")
+    return None, None

hatch/registry_retriever.py

@@ -0,0 +1,335 @@
+"""Registry retriever for Hatch package management.
+
+This module provides functionality to retrieve and manage the Hatch package registry,
+supporting both online and simulation modes with caching at file system and in-memory levels.
+"""
+
+import os
+import json
+import logging
+import requests
+import hashlib
+import time
+import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional, Tuple, Union
+from urllib.parse import urlparse
+
+class RegistryRetriever:
+    """Manages the retrieval and caching of the Hatch package registry.
+    
+    Provides caching at file system level and in-memory level with persistent
+    timestamp tracking for cache freshness across CLI invocations.
+    Works in both local simulation and online GitHub environments.
+    Handles registry timing issues with fallback to previous day's registry.
+    """
+    
+    def __init__(
+        self, 
+        cache_ttl: int = 86400,  # Default TTL is 24 hours
+        local_cache_dir: Optional[Path] = None,
+        simulation_mode: bool = False,  # Set to True when running in local simulation mode
+        local_registry_cache_path: Optional[Path] = None
+    ):
+        """Initialize the registry retriever.
+        
+        Args:
+            cache_ttl (int): Time-to-live for cache in seconds. Defaults to 86400 (24 hours).
+            local_cache_dir (Path, optional): Directory to store local cache files. Defaults to ~/.hatch.
+            simulation_mode (bool): Whether to operate in local simulation mode. Defaults to False.
+            local_registry_cache_path (Path, optional): Path to local registry file. Defaults to None.
+        """
+        self.logger = logging.getLogger('hatch.registry_retriever')
+        self.logger.setLevel(logging.INFO)
+
+        self.cache_ttl = cache_ttl
+        self.simulation_mode = simulation_mode
+        self.is_delayed = False  # Flag to indicate if using a previous day's registry
+        
+        # Initialize cache directory
+        self.cache_dir = local_cache_dir or Path.home() / ".hatch"
+        
+        # Create cache directory if it doesn't exist
+        self.cache_dir.mkdir(parents=True, exist_ok=True)        # Set up registry source based on mode
+        if simulation_mode:
+            # Local simulation mode - use local registry file
+            self.registry_cache_path = local_registry_cache_path or self.cache_dir / "registry" / "hatch_packages_registry.json"
+                
+            # Use file:// URL format for local files
+            self.registry_url = f"file://{str(self.registry_cache_path.absolute())}"
+            self.logger.info(f"Operating in simulation mode with registry at: {self.registry_cache_path}")
+        else:
+            # Online mode - set today's date as the default target
+            self.today_date = datetime.datetime.now(datetime.timezone.utc).date()
+            self.today_str = self.today_date.strftime('%Y-%m-%d')
+            
+            # We'll set the initial URL to today, but might fall back to yesterday
+            self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{self.today_str}/hatch_packages_registry.json"
+            self.logger.info(f"Operating in online mode with registry at: {self.registry_url}")
+        
+            # Generate cache filename - same regardless of which day's registry we end up using
+            self.registry_cache_path = self.cache_dir / "registry" / "hatch_packages_registry.json"
+        
+        # In-memory cache
+        self._registry_cache = None
+        self._last_fetch_time = 0
+        
+        # Set up persistent timestamp file path
+        self._last_fetch_time_path = self.cache_dir / "registry" / ".last_fetch_time"
+        
+        # Load persistent timestamp on initialization
+        self._load_last_fetch_time()
+    
+    def _load_last_fetch_time(self) -> None:
+        """Load the last fetch timestamp from persistent storage.
+        
+        Reads the timestamp from the .last_fetch_time file and sets
+        self._last_fetch_time accordingly. If the file is missing or
+        corrupt, treats the cache as outdated.
+        """
+        try:
+            if self._last_fetch_time_path.exists():
+                with open(self._last_fetch_time_path, 'r', encoding='utf-8') as f:
+                    timestamp_str = f.read().strip()
+                    # Parse ISO8601 timestamp
+                    timestamp_dt = datetime.datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+                    self._last_fetch_time = timestamp_dt.timestamp()
+                    self.logger.debug(f"Loaded last fetch time from disk: {timestamp_str}")
+            else:
+                self.logger.debug("No persistent timestamp file found, treating cache as outdated")
+        except Exception as e:
+            self.logger.warning(f"Failed to read persistent timestamp: {e}, treating cache as outdated")
+            self._last_fetch_time = 0
+    
+    def _save_last_fetch_time(self) -> None:
+        """Save the current fetch timestamp to persistent storage.
+        
+        Writes the current UTC timestamp to the .last_fetch_time file
+        in ISO8601 format for persistence across CLI invocations.
+        """
+        try:
+            # Ensure directory exists
+            self._last_fetch_time_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Write current UTC time in ISO8601 format
+            current_time = datetime.datetime.now(datetime.timezone.utc)
+            timestamp_str = current_time.isoformat().replace('+00:00', 'Z')
+            
+            with open(self._last_fetch_time_path, 'w', encoding='utf-8') as f:
+                f.write(timestamp_str)
+            
+            self.logger.debug(f"Saved last fetch time to disk: {timestamp_str}")
+        except Exception as e:
+            self.logger.warning(f"Failed to save persistent timestamp: {e}")
+    
+    def _read_local_cache(self) -> Dict[str, Any]:
+        """Read the registry from local cache file.
+        
+        Returns:
+            Dict[str, Any]: Registry data from cache.
+            
+        Raises:
+            Exception: If reading the cache file fails.
+        """
+        try:
+            with open(self.registry_cache_path, 'r') as f:
+                return json.load(f)
+        except Exception as e:
+            self.logger.error(f"Failed to read local registry file: {e}")
+            raise e
+    
+    def _write_local_cache(self, registry_data: Dict[str, Any]) -> None:
+        """Write the registry data to local cache file.
+        
+        Args:
+            registry_data (Dict[str, Any]): Registry data to cache.
+        """
+        try:
+            with open(self.registry_cache_path, 'w') as f:
+                json.dump(registry_data, f, indent=2)
+        except Exception as e:
+            self.logger.error(f"Failed to write local cache: {e}")
+
+    def _fetch_remote_registry(self) -> Dict[str, Any]:
+        """Fetch registry data from remote URL with fallback to previous day.
+        
+        Attempts to fetch today's registry first, falling back to previous day if necessary.
+        Updates the is_delayed flag based on which registry was successfully retrieved.
+        
+        Returns:
+            Dict[str, Any]: Registry data from remote source.
+            
+        Raises:
+            Exception: If fetching both today's and yesterday's registry fails.
+        """
+        if self.simulation_mode:
+            try:
+                self.logger.info(f"Fetching registry from {self.registry_url}")
+                with open(self.registry_cache_path, 'r') as f:
+                    return json.load(f)
+            except Exception as e:
+                self.logger.error(f"Failed to fetch registry in simulation mode: {e}")
+                raise e
+        
+        # Online mode - try today's registry first
+        date = self.today_date.strftime('%Y-%m-%d')
+        if self._registry_exists(date):
+            self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{date}/hatch_packages_registry.json"
+            self.is_delayed = False  # Reset delayed flag for today's registry
+        else:
+            self.logger.info(f"Today's registry ({date}) not found, falling back to yesterday's")
+            # Fall back to yesterday's registry
+            yesterday = self.today_date - datetime.timedelta(days=1)
+            date = yesterday.strftime('%Y-%m-%d')
+
+            if not self._registry_exists(date):
+                self.logger.error(f"Yesterday's registry ({date}) also not found, cannot proceed")
+                raise Exception("No valid registry found for today or yesterday")
+            
+            # Use yesterday's registry URL
+            self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{date}/hatch_packages_registry.json"
+            self.is_delayed = True  # Set delayed flag for yesterday's registry
+
+        try:
+            self.logger.info(f"Fetching registry from {self.registry_url}")
+            response = requests.get(self.registry_url, timeout=30)
+            response.raise_for_status()
+            return response.json()
+        
+        except Exception as e:
+            self.logger.error(f"Failed to fetch registry from {self.registry_url}: {e}")
+            raise e
+    
+    def _registry_exists(self, date_str: str) -> bool:
+        """Check if registry for the given date exists.
+        
+        Makes a HEAD request to check if the release page for the given date exists.
+        
+        Args:
+            date_str (str): Date string in YYYY-MM-DD format.
+            
+        Returns:
+            bool: True if registry exists, False otherwise.
+        """
+        if self.simulation_mode:
+            return self.registry_cache_path.exists()
+        
+
+        url = f"https://github.com/CrackingShells/Hatch-Registry/releases/tag/{date_str}"
+        try:
+            response = requests.head(url, timeout=10)
+            return response.status_code == 200
+        except Exception:
+            return False
+    
+    def get_registry(self, force_refresh: bool = False) -> Dict[str, Any]:
+        """Fetch the registry file.
+        
+        This method implements a multi-level caching strategy:
+        1. First checks the in-memory cache
+        2. Then checks the local file cache
+        3. Finally fetches from the source (local file or remote URL)
+        
+        The fetched data is stored in both the in-memory and file caches.
+        
+        Args:
+            force_refresh (bool, optional): Force refresh the registry even if cache is valid. Defaults to False.
+            
+        Returns:
+            Dict[str, Any]: Registry data.
+            
+        Raises:
+            Exception: If fetching the registry fails.
+        """
+        current_time = datetime.datetime.now(datetime.timezone.utc).timestamp()
+        
+        # Check if in-memory cache is valid
+        if (not force_refresh and 
+            self._registry_cache is not None and 
+            current_time - self._last_fetch_time < self.cache_ttl):
+            self.logger.debug("Using in-memory cache")
+            return self._registry_cache
+        
+        # Ensure registry cache directory exists
+        self.registry_cache_path.parent.mkdir(parents=True, exist_ok=True)
+            
+        # Check if local cache is not outdated
+        if not force_refresh and not self.is_cache_outdated():
+            try:
+                self.logger.debug("Using local cache file")
+                registry_data = self._read_local_cache()
+                # Update in-memory cache
+                self._registry_cache = registry_data
+                self._last_fetch_time = current_time
+                
+                return registry_data
+            except Exception as e:
+                self.logger.warning(f"Error reading local cache: {e}, will fetch from source instead")
+                # If reading cache fails, continue to fetch from source
+            
+        # Fetch from source based on mode
+        try:
+            if self.simulation_mode:
+                # In simulation mode, we must have a local registry file
+                registry_data = self._read_local_cache()
+            else:
+                # In online mode, fetch from remote URL
+                registry_data = self._fetch_remote_registry()
+            
+            # Update local cache
+            # Note that in case of simulation mode AND default cache path,
+            # we are rewriting the same file with the same content
+            self._write_local_cache(registry_data)
+            
+            # Update in-memory cache
+            self._registry_cache = registry_data
+            self._last_fetch_time = current_time
+            
+            # Update persistent timestamp
+            self._save_last_fetch_time()
+            
+            return registry_data
+            
+        except Exception as e:
+            self.logger.error(f"Failed to fetch registry: {e}")
+            raise e
+    
+    def is_cache_outdated(self) -> bool:
+        """Check if the cached registry is outdated.
+        
+        Determines if the cached registry is outdated based on the persistent
+        timestamp and cache TTL. Falls back to file mtime for backward compatibility
+        if no persistent timestamp is available.
+        
+        Returns:
+            bool: True if cache is outdated, False if cache is current.
+        """
+        if not self.registry_cache_path.exists():
+            return True  # If file doesn't exist, consider it outdated
+
+        now = datetime.datetime.now(datetime.timezone.utc)
+        
+        # Use persistent timestamp if available (primary method)
+        if self._last_fetch_time > 0:
+            time_since_fetch = now.timestamp() - self._last_fetch_time
+            if time_since_fetch > self.cache_ttl:
+                return True
+            
+            # Also check if cache is not from today (existing logic)
+            last_fetch_dt = datetime.datetime.fromtimestamp(
+                self._last_fetch_time, tz=datetime.timezone.utc
+            )
+            if last_fetch_dt.date() < now.date():
+                return True
+
+            return False
+        
+        return False
+
+# Example usage
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    retriever = RegistryRetriever()
+    registry = retriever.get_registry()
+    print(f"Found {len(registry.get('repositories', []))} repositories")
+    print(f"Registry last updated: {registry.get('last_updated')}")

hatch/template_generator.py

@@ -0,0 +1,179 @@
+"""
+Template Generator for Hatch packages.
+
+This module contains functions to generate template files for Hatch MCP server packages.
+Each function generates a specific file for the package template.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("hatch.template_generator")
+
+
+def generate_init_py() -> str:
+    """Generate the __init__.py file content for a template package.
+
+    Returns:
+        str: Content for __init__.py file.
+    """
+    return "# Hatch package initialization\n"
+
+
+def generate_mcp_server_py(package_name: str) -> str:
+    """Generate the mcp_server.py file content for a template package.
+
+    Args:
+        package_name (str): Name of the package.
+
+    Returns:
+        str: Content for mcp_server.py file.
+    """
+    return f"""from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(\"{package_name}\", log_level=\"WARNING\")
+
+@mcp.tool()
+def example_tool(param: str) -> str:
+    \"\"\"Example tool function.
+
+    Args:
+        param (str): Example parameter.
+
+    Returns:
+        str: Example result.
+    \"\"\"
+    return f\"Processed: {{param}}\"
+
+if __name__ == \"__main__\":
+    mcp.run()
+"""
+
+
+def generate_hatch_mcp_server_entry_py(package_name: str) -> str:
+    """Generate the hatch_mcp_server_entry.py file content for a template package.
+
+    Args:
+        package_name (str): Name of the package.
+
+    Returns:
+        str: Content for hatch_mcp_server_entry.py file.
+    """
+    return f"""from hatch_mcp_server import HatchMCP
+from mcp_server import mcp
+
+hatch_mcp = HatchMCP(\"{package_name}\",
+                     fast_mcp=mcp,
+                     origin_citation=\"Origin citation for {package_name}\",
+                     mcp_citation=\"MCP citation for {package_name}\")
+
+if __name__ == \"__main__\":
+    hatch_mcp.server.run()
+"""
+
+
+def generate_metadata_json(package_name: str, description: str = ""):
+    """Generate the metadata JSON content for a template package.
+
+    Args:
+        package_name (str): Name of the package.
+        description (str, optional): Package description. Defaults to empty string.
+
+    Returns:
+        dict: Metadata dictionary.
+    """
+    return {
+        "package_schema_version": "1.2.1",
+        "name": package_name,
+        "version": "0.1.0",
+        "description": description or f"A Hatch package for {package_name}",
+        "tags": [],
+        "author": {"name": "Hatch User", "email": ""},
+        "license": {"name": "MIT"},
+        "entry_point": {
+            "mcp_server": "mcp_server.py",
+            "hatch_mcp_server": "hatch_mcp_server_entry.py",
+        },
+        "tools": [{"name": "example_tool", "description": "Example tool function"}],
+        "citations": {
+            "origin": f"Origin citation for {package_name}",
+            "mcp": f"MCP citation for {package_name}",
+        },
+    }
+
+
+def generate_readme_md(package_name: str, description: str = "") -> str:
+    """Generate the README.md file content for a template package.
+
+    Args:
+        package_name (str): Name of the package.
+        description (str, optional): Package description. Defaults to empty string.
+
+    Returns:
+        str: Content for README.md file.
+    """
+    return f"""# {package_name}
+
+{description}
+
+## Tools
+
+- **example_tool**: Example tool function
+"""
+
+
+def create_package_template(
+    target_dir: Path, package_name: str, description: str = ""
+) -> Path:
+    """Create a package template directory with all necessary files.
+
+    This function orchestrates the generation of a complete package structure by:
+    1. Creating the package directory
+    2. Generating and writing the __init__.py file
+    3. Generating and writing the mcp_server.py file with example tools
+    4. Generating and writing the hatch_mcp_server_entry.py file that wraps the MCP server
+    5. Creating the hatch_metadata.json with package information
+    6. Generating a README.md with basic documentation
+
+    Args:
+        target_dir (Path): Directory where the package should be created.
+        package_name (str): Name of the package.
+        description (str, optional): Package description. Defaults to empty string.
+
+    Returns:
+        Path: Path to the created package directory.
+    """
+    logger.info(f"Creating package template for {package_name} in {target_dir}")
+
+    # Create package directory
+    package_dir = target_dir / package_name
+    package_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create __init__.py
+    init_content = generate_init_py()
+    with open(package_dir / "__init__.py", "w") as f:
+        f.write(init_content)
+
+    # Create mcp_server.py
+    mcp_server_content = generate_mcp_server_py(package_name)
+    with open(package_dir / "mcp_server.py", "w") as f:
+        f.write(mcp_server_content)
+
+    # Create hatch_mcp_server_entry.py
+    hatch_mcp_server_entry_content = generate_hatch_mcp_server_entry_py(package_name)
+    with open(package_dir / "hatch_mcp_server_entry.py", "w") as f:
+        f.write(hatch_mcp_server_entry_content)
+
+    # Create metadata.json
+    metadata = generate_metadata_json(package_name, description)
+    with open(package_dir / "hatch_metadata.json", "w") as f:
+        json.dump(metadata, f, indent=2)
+
+    # Create README.md
+    readme_content = generate_readme_md(package_name, description)
+    with open(package_dir / "README.md", "w") as f:
+        f.write(readme_content)
+
+    logger.info(f"Package template created successfully at {package_dir}")
+    return package_dir