mcp-ticketer 0.2.0__py3-none-any.whl → 2.2.9__py3-none-any.whl

mcp_ticketer/cli/utils.py

@@ -4,9 +4,11 @@ import asyncio
 import json
 import logging
 import os
+from collections.abc import Callable
+from datetime import datetime
 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
@@ -22,6 +24,118 @@ T = TypeVar("T")
 console = Console()
 logger = logging.getLogger(__name__)
 
+# Get version from package
+try:
+    from importlib.metadata import version
+
+    __version__ = version("mcp-ticketer")
+except Exception:
+    __version__ = "2.2.2"  # Fallback to known version
+
+
+def format_json_response(status: str, data: Any, message: str | None = None) -> str:
+    """Format response as JSON with standard structure.
+
+    Args:
+        status: Response status - "success" or "error"
+        data: Response data (dict, list, or any JSON-serializable type)
+        message: Optional human-readable message
+
+    Returns:
+        JSON string with standard format
+
+    Example:
+        >>> format_json_response("success", {"id": "1M-123", "title": "Fix bug"})
+        {
+          "status": "success",
+          "data": {"id": "1M-123", "title": "Fix bug"},
+          "metadata": {
+            "timestamp": "2025-12-05T10:30:00Z",
+            "version": "2.2.2"
+          }
+        }
+    """
+    response = {
+        "status": status,
+        "data": data,
+        "metadata": {
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "version": __version__,
+        },
+    }
+    if message:
+        response["message"] = message
+    return json.dumps(response, indent=2, default=str)
+
+
+def format_error_json(error: str | Exception, ticket_id: str | None = None) -> str:
+    """Format error response as JSON.
+
+    Args:
+        error: Error message or exception
+        ticket_id: Optional ticket ID that caused the error
+
+    Returns:
+        JSON error response
+    """
+    error_msg = str(error)
+    data = {"error": error_msg}
+    if ticket_id:
+        data["ticket_id"] = ticket_id
+    return format_json_response("error", data, message=error_msg)
+
+
+def serialize_task(task: Task) -> dict[str, Any]:
+    """Serialize Task object to JSON-compatible dict.
+
+    Args:
+        task: Task object to serialize
+
+    Returns:
+        Dictionary with task fields
+    """
+    task_dict = {
+        "id": task.id,
+        "title": task.title,
+        "state": task.state,
+        "priority": task.priority,
+        "description": task.description,
+        "tags": task.tags or [],
+        "assignee": task.assignee,
+    }
+
+    # Add timestamps if available
+    if task.created_at:
+        task_dict["created_at"] = (
+            task.created_at.isoformat()
+            if hasattr(task.created_at, "isoformat")
+            else str(task.created_at)
+        )
+    if task.updated_at:
+        task_dict["updated_at"] = (
+            task.updated_at.isoformat()
+            if hasattr(task.updated_at, "isoformat")
+            else str(task.updated_at)
+        )
+
+    # Add parent relationships
+    if hasattr(task, "parent_epic") and task.parent_epic:
+        task_dict["parent_epic"] = task.parent_epic
+    if hasattr(task, "parent_issue") and task.parent_issue:
+        task_dict["parent_issue"] = task.parent_issue
+
+    # Add URL from metadata if available
+    if task.metadata:
+        if isinstance(task.metadata, dict):
+            # Linear metadata structure
+            if "linear" in task.metadata and "url" in task.metadata["linear"]:
+                task_dict["url"] = task.metadata["linear"]["url"]
+            # Generic url field
+            elif "url" in task.metadata:
+                task_dict["url"] = task.metadata["url"]
+
+    return task_dict
+
 
 class CommonPatterns:
     """Common CLI patterns and utilities."""
@@ -81,6 +195,7 @@ class CommonPatterns:
         # Try environment discovery as fallback
         try:
             from ..core.config import ConfigurationManager
+
             config_manager = ConfigurationManager()
             app_config = config_manager.load_config()
 
@@ -88,24 +203,27 @@ class CommonPatterns:
             enabled_adapters = app_config.get_enabled_adapters()
             if enabled_adapters:
                 # Use the first enabled adapter as default
-                default_adapter = app_config.default_adapter or list(enabled_adapters.keys())[0]
+                default_adapter = (
+                    app_config.default_adapter or list(enabled_adapters.keys())[0]
+                )
 
                 # Convert to legacy format
-                legacy_config = {
-                    "default_adapter": default_adapter,
-                    "adapters": {}
-                }
+                legacy_config = {"default_adapter": default_adapter, "adapters": {}}
 
                 # Convert adapter configs to dict format
                 for name, adapter_config in enabled_adapters.items():
-                    if hasattr(adapter_config, 'model_dump'):
-                        legacy_config["adapters"][name] = adapter_config.model_dump(exclude_none=False)
-                    elif hasattr(adapter_config, 'dict'):
+                    if hasattr(adapter_config, "model_dump"):
+                        legacy_config["adapters"][name] = adapter_config.model_dump(
+                            exclude_none=False
+                        )
+                    elif hasattr(adapter_config, "dict"):
                         legacy_config["adapters"][name] = adapter_config.dict()
                     else:
                         legacy_config["adapters"][name] = adapter_config
 
-                logger.info(f"Loaded configuration from environment discovery: {list(enabled_adapters.keys())}")
+                logger.info(
+                    f"Loaded configuration from environment discovery: {list(enabled_adapters.keys())}"
+                )
                 return legacy_config
 
         except Exception as e:
@@ -150,8 +268,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()
 
@@ -202,7 +320,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."""
@@ -212,12 +330,13 @@ class CommonPatterns:
 
         # Add to queue with explicit project directory
         from pathlib import Path
+
         queue = Queue()
         queue_id = queue.add(
             ticket_data=ticket_data,
             adapter=adapter_name,
             operation=operation,
-            project_dir=str(Path.cwd())  # Explicitly pass current project directory
+            project_dir=str(Path.cwd()),  # Explicitly pass current project directory
         )
 
         if show_progress:
@@ -260,7 +379,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}")
@@ -315,33 +434,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}"),
@@ -355,12 +476,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:
@@ -370,7 +493,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)
 
@@ -379,24 +502,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
 
@@ -441,7 +564,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": {
@@ -462,39 +585,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")
@@ -508,22 +631,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 = {}
@@ -562,11 +685,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:
@@ -581,13 +704,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:
@@ -598,11 +721,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 = {
@@ -617,19 +740,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,79 @@
 """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 .milestone_manager import MilestoneManager
+from .models import (
+    Attachment,
+    Comment,
+    Epic,
+    Milestone,
+    Priority,
+    Project,
+    ProjectScope,
+    ProjectState,
+    ProjectStatistics,
+    ProjectUpdate,
+    ProjectUpdateHealth,
+    ProjectVisibility,
+    Task,
+    TicketState,
+    TicketType,
+)
+from .project_utils import (
+    epic_to_project,
+    project_to_epic,
+)
 from .registry import AdapterRegistry
+from .state_matcher import (
+    SemanticStateMatcher,
+    StateMatchResult,
+    ValidationResult,
+    get_state_matcher,
+)
 
 __all__ = [
+    # Core ticket models
     "Epic",
     "Task",
     "Comment",
+    "Attachment",
+    "Milestone",
+    # Project models
+    "Project",
+    "ProjectScope",
+    "ProjectState",
+    "ProjectStatistics",
+    "ProjectVisibility",
+    "ProjectUpdate",
+    "ProjectUpdateHealth",
+    # Project utilities
+    "epic_to_project",
+    "project_to_epic",
+    # Enums
     "TicketState",
     "Priority",
     "TicketType",
+    # Adapters
     "BaseAdapter",
     "AdapterRegistry",
+    # Managers
+    "MilestoneManager",
+    "TicketInstructionsManager",
+    # Instructions
+    "InstructionsError",
+    "InstructionsNotFoundError",
+    "InstructionsValidationError",
+    "get_instructions",
+    # State matching
+    "SemanticStateMatcher",
+    "StateMatchResult",
+    "ValidationResult",
+    "get_state_matcher",
 ]