mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/cli/update_checker.py

@@ -0,0 +1,313 @@
+"""Update checker for mcp-ticketer package.
+
+This module provides functionality to check PyPI for new versions and notify users.
+Uses the existing HTTP client infrastructure to avoid code duplication.
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+# Try to import packaging, fall back to simple string comparison if unavailable
+try:
+    from packaging.version import Version
+
+    HAS_PACKAGING = True
+except ImportError:
+    HAS_PACKAGING = False
+
+    class Version:
+        """Fallback version comparison using simple string sorting.
+
+        This is a minimal fallback when packaging is not available.
+        Works correctly for most semantic versions (X.Y.Z format).
+        """
+
+        def __init__(self, version_string: str):
+            """Initialize with version string."""
+            self.version_string = version_string
+            # Parse into tuple of integers for proper comparison
+            try:
+                parts = version_string.split(".")
+                # Handle pre-release versions by splitting on non-digit chars
+                self.parts = []
+                for part in parts:
+                    # Extract leading digits
+                    digits = ""
+                    for char in part:
+                        if char.isdigit():
+                            digits += char
+                        else:
+                            break
+                    if digits:
+                        self.parts.append(int(digits))
+            except (ValueError, AttributeError):
+                # Fallback to string comparison if parsing fails
+                self.parts = None
+
+        def __gt__(self, other: "Version") -> bool:
+            """Compare versions."""
+            if self.parts is not None and other.parts is not None:
+                # Proper numeric comparison
+                return self.parts > other.parts
+            # Fallback to string comparison
+            return self.version_string > other.version_string
+
+        def __eq__(self, other: object) -> bool:
+            """Check equality."""
+            if not isinstance(other, Version):
+                return False
+            if self.parts is not None and other.parts is not None:
+                return self.parts == other.parts
+            return self.version_string == other.version_string
+
+
+from ..__version__ import __version__
+
+logger = logging.getLogger(__name__)
+
+# Cache configuration
+CACHE_DIR = Path.home() / ".mcp-ticketer"
+CACHE_FILE = CACHE_DIR / "update_check_cache.json"
+CACHE_DURATION_HOURS = 24
+
+# PyPI API configuration
+PYPI_API_URL = "https://pypi.org/pypi/mcp-ticketer/json"
+PYPI_PROJECT_URL = "https://pypi.org/project/mcp-ticketer/"
+
+
+class UpdateInfo:
+    """Container for update information."""
+
+    def __init__(
+        self,
+        current_version: str,
+        latest_version: str,
+        needs_update: bool,
+        pypi_url: str,
+        release_date: str | None = None,
+        checked_at: str | None = None,
+    ):
+        """Initialize update information.
+
+        Args:
+            current_version: Currently installed version
+            latest_version: Latest version on PyPI
+            needs_update: Whether an update is available
+            pypi_url: URL to package on PyPI
+            release_date: Release date of latest version (ISO format)
+            checked_at: Timestamp of when check was performed (ISO format)
+
+        """
+        self.current_version = current_version
+        self.latest_version = latest_version
+        self.needs_update = needs_update
+        self.pypi_url = pypi_url
+        self.release_date = release_date
+        self.checked_at = checked_at or datetime.now().isoformat()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "current_version": self.current_version,
+            "latest_version": self.latest_version,
+            "needs_update": self.needs_update,
+            "pypi_url": self.pypi_url,
+            "release_date": self.release_date,
+            "checked_at": self.checked_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "UpdateInfo":
+        """Create from dictionary."""
+        return cls(
+            current_version=data["current_version"],
+            latest_version=data["latest_version"],
+            needs_update=data["needs_update"],
+            pypi_url=data["pypi_url"],
+            release_date=data.get("release_date"),
+            checked_at=data.get("checked_at"),
+        )
+
+
+def _ensure_cache_dir() -> None:
+    """Ensure cache directory exists."""
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        logger.warning(f"Failed to create cache directory: {e}")
+
+
+def _load_cache() -> dict[str, Any] | None:
+    """Load cached update information.
+
+    Returns:
+        Cached data or None if cache doesn't exist or is invalid
+
+    """
+    try:
+        if not CACHE_FILE.exists():
+            return None
+
+        with open(CACHE_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+
+        # Validate cache structure
+        if not isinstance(data, dict) or "checked_at" not in data:
+            logger.debug("Invalid cache format, ignoring")
+            return None
+
+        return data
+    except (OSError, json.JSONDecodeError) as e:
+        logger.debug(f"Failed to load cache: {e}")
+        return None
+
+
+def _save_cache(update_info: UpdateInfo) -> None:
+    """Save update information to cache.
+
+    Args:
+        update_info: Update information to cache
+
+    """
+    try:
+        _ensure_cache_dir()
+        with open(CACHE_FILE, "w", encoding="utf-8") as f:
+            json.dump(update_info.to_dict(), f, indent=2)
+    except OSError as e:
+        logger.warning(f"Failed to save cache: {e}")
+
+
+def should_check_updates(force: bool = False) -> bool:
+    """Check if enough time has passed since last check.
+
+    Args:
+        force: If True, always return True (force check)
+
+    Returns:
+        True if check should be performed
+
+    """
+    if force:
+        return True
+
+    cache = _load_cache()
+    if not cache:
+        return True
+
+    try:
+        checked_at = datetime.fromisoformat(cache["checked_at"])
+        age = datetime.now() - checked_at
+        return age > timedelta(hours=CACHE_DURATION_HOURS)
+    except (ValueError, KeyError) as e:
+        logger.debug(f"Invalid cache timestamp: {e}")
+        return True
+
+
+async def check_for_updates(force: bool = False) -> UpdateInfo:
+    """Check PyPI for latest version.
+
+    Args:
+        force: If True, bypass cache and force check
+
+    Returns:
+        UpdateInfo object with version information
+
+    Raises:
+        Exception: If PyPI API request fails
+
+    """
+    # Suppress httpx INFO logging to keep output clean
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+
+    current_version = __version__
+
+    # Check cache first (unless forced)
+    if not force:
+        cache = _load_cache()
+        if cache and cache.get("current_version") == current_version:
+            # Return cached info if it's for the current version
+            return UpdateInfo.from_dict(cache)
+
+    # Fetch from PyPI - use httpx directly for simplicity
+    import httpx
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.get(PYPI_API_URL)
+        response.raise_for_status()
+        response_data = response.json()
+
+        # Extract version information
+        latest_version = response_data["info"]["version"]
+
+        # Get release date from releases data
+        releases = response_data.get("releases", {})
+        release_date = None
+        if latest_version in releases and releases[latest_version]:
+            # Get upload_time from first file in the release
+            upload_time = releases[latest_version][0].get("upload_time")
+            if upload_time:
+                # Convert to ISO format date only
+                release_date = upload_time.split("T")[0]
+
+        # Compare versions
+        needs_update = Version(latest_version) > Version(current_version)
+
+        # Create update info
+        update_info = UpdateInfo(
+            current_version=current_version,
+            latest_version=latest_version,
+            needs_update=needs_update,
+            pypi_url=PYPI_PROJECT_URL,
+            release_date=release_date,
+        )
+
+        # Cache the result
+        _save_cache(update_info)
+
+        return update_info
+
+
+def detect_installation_method() -> str:
+    """Detect how mcp-ticketer was installed.
+
+    Returns:
+        Installation method: 'pipx', 'uv', or 'pip'
+
+    """
+    # Check for pipx
+    if "pipx" in sys.prefix or "pipx" in sys.executable:
+        return "pipx"
+
+    # Check for uv
+    if "uv" in sys.prefix or "uv" in sys.executable:
+        return "uv"
+    if ".venv" in sys.prefix and Path(sys.prefix).parent.name == ".venv":
+        # Common uv pattern
+        uv_bin = Path(sys.prefix).parent.parent / "uv"
+        if uv_bin.exists():
+            return "uv"
+
+    # Default to pip
+    return "pip"
+
+
+def get_upgrade_command() -> str:
+    """Get the appropriate upgrade command for the installation method.
+
+    Returns:
+        Command string to upgrade mcp-ticketer
+
+    """
+    method = detect_installation_method()
+
+    commands = {
+        "pipx": "pipx upgrade mcp-ticketer",
+        "uv": "uv pip install --upgrade mcp-ticketer",
+        "pip": "pip install --upgrade mcp-ticketer",
+    }
+
+    return commands.get(method, "pip install --upgrade mcp-ticketer")

mcp_ticketer/cli/utils.py

@@ -4,9 +4,10 @@ import asyncio
 import json
 import logging
 import os
+from collections.abc import Callable
 from functools import wraps
 from pathlib import Path
-from typing import Any, Callable, Optional, TypeVar
+from typing import Any, TypeVar
 
 import typer
 from rich.console import Console
@@ -154,8 +155,8 @@ class CommonPatterns:
 
     @staticmethod
     def get_adapter(
-        override_adapter: Optional[str] = None, override_config: Optional[dict] = None
-    ):
+        override_adapter: str | None = None, override_config: dict | None = None
+    ) -> Any:
         """Get configured adapter instance with environment variable support."""
         config = CommonPatterns.load_config()
 
@@ -206,7 +207,7 @@ class CommonPatterns:
     def queue_operation(
         ticket_data: dict[str, Any],
         operation: str,
-        adapter_name: Optional[str] = None,
+        adapter_name: str | None = None,
         show_progress: bool = True,
     ) -> str:
         """Queue an operation and optionally start the worker."""
@@ -265,7 +266,7 @@ class CommonPatterns:
         console.print(table)
 
     @staticmethod
-    def display_ticket_details(ticket: Task, comments: Optional[list] = None) -> None:
+    def display_ticket_details(ticket: Task, comments: list | None = None) -> None:
         """Display detailed ticket information."""
         console.print(f"\n[bold]Ticket: {ticket.id}[/bold]")
         console.print(f"Title: {ticket.title}")
@@ -320,33 +321,35 @@ class CommonPatterns:
                 )
 
 
-def async_command(f: Callable[..., T]) -> Callable[..., T]:
-    """Decorator to handle async CLI commands."""
+def async_command(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Handle async CLI commands via decorator."""
 
     @wraps(f)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
         return asyncio.run(f(*args, **kwargs))
 
     return wrapper
 
 
-def with_adapter(f: Callable) -> Callable:
-    """Decorator to inject adapter instance into CLI commands."""
+def with_adapter(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Inject adapter instance into CLI commands via decorator."""
 
     @wraps(f)
-    def wrapper(adapter: Optional[str] = None, *args, **kwargs):
+    def wrapper(adapter: str | None = None, *args: Any, **kwargs: Any) -> Any:
         adapter_instance = CommonPatterns.get_adapter(override_adapter=adapter)
         return f(adapter_instance, *args, **kwargs)
 
     return wrapper
 
 
-def with_progress(message: str = "Processing..."):
-    """Decorator to show progress spinner for long-running operations."""
+def with_progress(
+    message: str = "Processing...",
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Show progress spinner for long-running operations via decorator."""
 
-    def decorator(f: Callable) -> Callable:
+    def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(f)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
             with Progress(
                 SpinnerColumn(),
                 TextColumn("[progress.description]{task.description}"),
@@ -360,12 +363,14 @@ def with_progress(message: str = "Processing..."):
     return decorator
 
 
-def validate_required_fields(**field_map):
-    """Decorator to validate required fields are provided."""
+def validate_required_fields(
+    **field_map: str,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Validate required fields are provided via decorator."""
 
-    def decorator(f: Callable) -> Callable:
+    def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(f)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
             missing_fields = []
             for field_name, display_name in field_map.items():
                 if field_name in kwargs and kwargs[field_name] is None:
@@ -375,7 +380,7 @@ def validate_required_fields(**field_map):
                 console.print(
                     f"[red]Error:[/red] Missing required fields: {', '.join(missing_fields)}"
                 )
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             return f(*args, **kwargs)
 
@@ -384,24 +389,24 @@ def validate_required_fields(**field_map):
     return decorator
 
 
-def handle_adapter_errors(f: Callable) -> Callable:
-    """Decorator to handle common adapter errors gracefully."""
+def handle_adapter_errors(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Handle common adapter errors gracefully via decorator."""
 
     @wraps(f)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
         try:
             return f(*args, **kwargs)
         except ConnectionError as e:
             console.print(f"[red]Connection Error:[/red] {e}")
             console.print("Check your network connection and adapter configuration")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
         except ValueError as e:
             console.print(f"[red]Configuration Error:[/red] {e}")
             console.print("Run 'mcp-ticketer init' to configure your adapter")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
         except Exception as e:
             console.print(f"[red]Unexpected Error:[/red] {e}")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
     return wrapper
 
@@ -446,7 +451,7 @@ class ConfigValidator:
         return issues
 
     @staticmethod
-    def _get_env_var(adapter_type: str, field: str) -> Optional[str]:
+    def _get_env_var(adapter_type: str, field: str) -> str | None:
         """Get corresponding environment variable name for a config field."""
         env_mapping = {
             "github": {
@@ -467,39 +472,39 @@ class ConfigValidator:
 class CommandBuilder:
     """Builder for common CLI command patterns."""
 
-    def __init__(self):
-        self._validators = []
-        self._handlers = []
-        self._decorators = []
+    def __init__(self) -> None:
+        self._validators: list[Callable[..., Any]] = []
+        self._handlers: list[Callable[..., Any]] = []
+        self._decorators: list[Callable[..., Any]] = []
 
-    def with_adapter_validation(self):
+    def with_adapter_validation(self) -> "CommandBuilder":
         """Add adapter configuration validation."""
         self._validators.append(self._validate_adapter)
         return self
 
-    def with_async_support(self):
+    def with_async_support(self) -> "CommandBuilder":
         """Add async support to command."""
         self._decorators.append(async_command)
         return self
 
-    def with_error_handling(self):
+    def with_error_handling(self) -> "CommandBuilder":
         """Add error handling decorator."""
         self._decorators.append(handle_adapter_errors)
         return self
 
-    def with_progress(self, message: str = "Processing..."):
+    def with_progress(self, message: str = "Processing...") -> "CommandBuilder":
         """Add progress spinner."""
         self._decorators.append(with_progress(message))
         return self
 
-    def build(self, func: Callable) -> Callable:
+    def build(self, func: Callable[..., Any]) -> Callable[..., Any]:
         """Build the decorated function."""
         decorated_func = func
         for decorator in reversed(self._decorators):
             decorated_func = decorator(decorated_func)
         return decorated_func
 
-    def _validate_adapter(self, *args, **kwargs):
+    def _validate_adapter(self, *args: Any, **kwargs: Any) -> None:
         """Validate adapter configuration."""
         config = CommonPatterns.load_config()
         default_adapter = config.get("default_adapter", "aitrackdown")
@@ -513,22 +518,22 @@ class CommandBuilder:
             for issue in issues:
                 console.print(f"  • {issue}")
             console.print("Run 'mcp-ticketer init' to fix configuration")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
 
-def create_standard_ticket_command(operation: str):
+def create_standard_ticket_command(operation: str) -> Callable[..., str]:
     """Create a standard ticket operation command."""
 
     def command_template(
-        ticket_id: Optional[str] = None,
-        title: Optional[str] = None,
-        description: Optional[str] = None,
-        priority: Optional[Priority] = None,
-        state: Optional[TicketState] = None,
-        assignee: Optional[str] = None,
-        tags: Optional[list[str]] = None,
-        adapter: Optional[str] = None,
-    ):
+        ticket_id: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        priority: Priority | None = None,
+        state: TicketState | None = None,
+        assignee: str | None = None,
+        tags: list[str] | None = None,
+        adapter: str | None = None,
+    ) -> str:
         """Template for ticket commands."""
         # Build ticket data
         ticket_data = {}
@@ -567,11 +572,11 @@ class TicketCommands:
     @async_command
     @handle_adapter_errors
     async def list_tickets(
-        adapter_instance,
-        state: Optional[TicketState] = None,
-        priority: Optional[Priority] = None,
+        adapter_instance: Any,
+        state: TicketState | None = None,
+        priority: Priority | None = None,
         limit: int = 10,
-    ):
+    ) -> None:
         """List tickets with filters."""
         filters = {}
         if state:
@@ -586,13 +591,13 @@ class TicketCommands:
     @async_command
     @handle_adapter_errors
     async def show_ticket(
-        adapter_instance, ticket_id: str, show_comments: bool = False
-    ):
+        adapter_instance: Any, ticket_id: str, show_comments: bool = False
+    ) -> None:
         """Show ticket details."""
         ticket = await adapter_instance.read(ticket_id)
         if not ticket:
             console.print(f"[red]✗[/red] Ticket not found: {ticket_id}")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
         comments = None
         if show_comments:
@@ -603,11 +608,11 @@ class TicketCommands:
     @staticmethod
     def create_ticket(
         title: str,
-        description: Optional[str] = None,
+        description: str | None = None,
         priority: Priority = Priority.MEDIUM,
-        tags: Optional[list[str]] = None,
-        assignee: Optional[str] = None,
-        adapter: Optional[str] = None,
+        tags: list[str] | None = None,
+        assignee: str | None = None,
+        adapter: str | None = None,
     ) -> str:
         """Create a new ticket."""
         ticket_data = {
@@ -622,19 +627,19 @@ class TicketCommands:
 
     @staticmethod
     def update_ticket(
-        ticket_id: str, updates: dict[str, Any], adapter: Optional[str] = None
+        ticket_id: str, updates: dict[str, Any], adapter: str | None = None
     ) -> str:
         """Update a ticket."""
         if not updates:
             console.print("[yellow]No updates specified[/yellow]")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
         updates["ticket_id"] = ticket_id
         return CommonPatterns.queue_operation(updates, "update", adapter)
 
     @staticmethod
     def transition_ticket(
-        ticket_id: str, state: TicketState, adapter: Optional[str] = None
+        ticket_id: str, state: TicketState, adapter: str | None = None
     ) -> str:
         """Transition ticket state."""
         ticket_data = {

mcp_ticketer/core/__init__.py

@@ -1,16 +1,29 @@
 """Core models and abstractions for MCP Ticketer."""
 
 from .adapter import BaseAdapter
-from .models import Comment, Epic, Priority, Task, TicketState, TicketType
+from .instructions import (
+                           InstructionsError,
+                           InstructionsNotFoundError,
+                           InstructionsValidationError,
+                           TicketInstructionsManager,
+                           get_instructions,
+)
+from .models import Attachment, Comment, Epic, Priority, Task, TicketState, TicketType
 from .registry import AdapterRegistry
 
 __all__ = [
     "Epic",
     "Task",
     "Comment",
+    "Attachment",
     "TicketState",
     "Priority",
     "TicketType",
     "BaseAdapter",
     "AdapterRegistry",
+    "TicketInstructionsManager",
+    "InstructionsError",
+    "InstructionsNotFoundError",
+    "InstructionsValidationError",
+    "get_instructions",
 ]