mcp-ticketer 2.0.1__py3-none-any.whl → 2.2.13__py3-none-any.whl

mcp_ticketer/cli/utils.py

@@ -5,6 +5,7 @@ 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, TypeVar
@@ -23,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."""

mcp_ticketer/core/__init__.py

@@ -8,17 +8,28 @@ from .instructions import (
     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,
@@ -28,22 +39,39 @@ from .state_matcher import (
 )
 
 __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",

mcp_ticketer/core/adapter.py

@@ -4,9 +4,22 @@ from __future__ import annotations
 
 import builtins
 from abc import ABC, abstractmethod
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
-from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
+from .models import (
+    Comment,
+    Epic,
+    Milestone,
+    Project,
+    ProjectScope,
+    ProjectState,
+    ProjectStatistics,
+    SearchQuery,
+    Task,
+    TicketState,
+    TicketType,
+)
 from .state_matcher import get_state_matcher
 
 if TYPE_CHECKING:
@@ -612,3 +625,356 @@ class BaseAdapter(ABC, Generic[T]):
     async def close(self) -> None:
         """Close adapter and cleanup resources."""
         pass
+
+    # Milestone Operations (Phase 1 - Abstract methods)
+
+    @abstractmethod
+    async def milestone_create(
+        self,
+        name: str,
+        target_date: datetime | None = None,
+        labels: list[str] | None = None,
+        description: str = "",
+        project_id: str | None = None,
+    ) -> Milestone:
+        """Create a new milestone.
+
+        Args:
+        ----
+            name: Milestone name
+            target_date: Target completion date (ISO format: YYYY-MM-DD)
+            labels: Labels that define this milestone
+            description: Milestone description
+            project_id: Associated project ID
+
+        Returns:
+        -------
+            Created Milestone object
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_get(self, milestone_id: str) -> Milestone | None:
+        """Get milestone by ID with progress calculation.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+
+        Returns:
+        -------
+            Milestone object with calculated progress, None if not found
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_list(
+        self,
+        project_id: str | None = None,
+        state: str | None = None,
+    ) -> builtins.list[Milestone]:
+        """List milestones with optional filters.
+
+        Args:
+        ----
+            project_id: Filter by project
+            state: Filter by state (open, active, completed, closed)
+
+        Returns:
+        -------
+            List of Milestone objects
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_update(
+        self,
+        milestone_id: str,
+        name: str | None = None,
+        target_date: datetime | None = None,
+        state: str | None = None,
+        labels: list[str] | None = None,
+        description: str | None = None,
+    ) -> Milestone | None:
+        """Update milestone properties.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            name: New name (optional)
+            target_date: New target date (optional)
+            state: New state (optional)
+            labels: New labels (optional)
+            description: New description (optional)
+
+        Returns:
+        -------
+            Updated Milestone object, None if not found
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_delete(self, milestone_id: str) -> bool:
+        """Delete milestone.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+
+        Returns:
+        -------
+            True if deleted successfully, False otherwise
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_get_issues(
+        self,
+        milestone_id: str,
+        state: str | None = None,
+    ) -> builtins.list[Task]:
+        """Get issues associated with milestone.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            state: Filter by issue state (optional)
+
+        Returns:
+        -------
+            List of Task objects (issues)
+
+        """
+        pass
+
+    # Project Operations (Phase 1 - Abstract methods)
+    # These methods are optional - adapters that don't support projects
+    # can raise NotImplementedError with a helpful message
+
+    async def project_list(
+        self,
+        scope: ProjectScope | None = None,
+        state: ProjectState | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> builtins.list[Project]:
+        """List projects with optional filters.
+
+        Args:
+        ----
+            scope: Filter by project scope (user, team, org, repo)
+            state: Filter by project state
+            limit: Maximum results (default: 50)
+            offset: Pagination offset (default: 0)
+
+        Returns:
+        -------
+            List of Project objects
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use Epic operations for this adapter."
+        )
+
+    async def project_get(self, project_id: str) -> Project | None:
+        """Get project by ID.
+
+        Args:
+        ----
+            project_id: Project identifier (platform-specific or unified)
+
+        Returns:
+        -------
+            Project object if found, None otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use get_epic() for this adapter."
+        )
+
+    async def project_create(
+        self,
+        name: str,
+        description: str | None = None,
+        state: ProjectState = ProjectState.PLANNED,
+        target_date: datetime | None = None,
+        **kwargs: Any,
+    ) -> Project:
+        """Create new project.
+
+        Args:
+        ----
+            name: Project name (required)
+            description: Project description
+            state: Initial project state (default: PLANNED)
+            target_date: Target completion date
+            **kwargs: Platform-specific additional fields
+
+        Returns:
+        -------
+            Created Project object
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use create_epic() for this adapter."
+        )
+
+    async def project_update(
+        self,
+        project_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        state: ProjectState | None = None,
+        **kwargs: Any,
+    ) -> Project | None:
+        """Update project properties.
+
+        Args:
+        ----
+            project_id: Project identifier
+            name: New name (optional)
+            description: New description (optional)
+            state: New state (optional)
+            **kwargs: Platform-specific fields to update
+
+        Returns:
+        -------
+            Updated Project object, None if not found
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_delete(self, project_id: str) -> bool:
+        """Delete or archive project.
+
+        Args:
+        ----
+            project_id: Project identifier
+
+        Returns:
+        -------
+            True if deleted successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_get_issues(
+        self, project_id: str, state: TicketState | None = None
+    ) -> builtins.list[Task]:
+        """Get all issues in project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            state: Filter by issue state (optional)
+
+        Returns:
+        -------
+            List of Task objects (issues in project)
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use list_issues_by_epic() for this adapter."
+        )
+
+    async def project_add_issue(self, project_id: str, issue_id: str) -> bool:
+        """Add issue to project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            issue_id: Issue identifier to add
+
+        Returns:
+        -------
+            True if added successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_remove_issue(self, project_id: str, issue_id: str) -> bool:
+        """Remove issue from project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            issue_id: Issue identifier to remove
+
+        Returns:
+        -------
+            True if removed successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_get_statistics(self, project_id: str) -> ProjectStatistics:
+        """Get project statistics and metrics.
+
+        Calculates or retrieves statistics including issue counts by state,
+        progress percentage, and velocity metrics.
+
+        Args:
+        ----
+            project_id: Project identifier
+
+        Returns:
+        -------
+            ProjectStatistics object with calculated metrics
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project statistics."
+        )