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

mcp_ticketer/core/milestone_manager.py

@@ -0,0 +1,252 @@
+"""Local milestone storage manager.
+
+This module provides local persistent storage for milestones in the
+.mcp-ticketer/milestones.json file. It handles CRUD operations for
+milestones with automatic timestamp management and filtering support.
+
+The storage format is JSON with the following structure:
+{
+    "version": "1.0",
+    "milestones": {
+        "milestone-id-1": {...},
+        "milestone-id-2": {...}
+    }
+}
+
+Example:
+    >>> from pathlib import Path
+    >>> from mcp_ticketer.core.milestone_manager import MilestoneManager
+    >>> from mcp_ticketer.core.models import Milestone
+    >>>
+    >>> config_dir = Path.home() / ".mcp-ticketer"
+    >>> manager = MilestoneManager(config_dir)
+    >>>
+    >>> milestone = Milestone(
+    ...     id="mile-001",
+    ...     name="v2.1.0 Release",
+    ...     labels=["v2.1", "release"]
+    ... )
+    >>> saved = manager.save_milestone(milestone)
+    >>> retrieved = manager.get_milestone("mile-001")
+
+Note:
+    Related to ticket 1M-607: Add milestone support (Phase 1 - Core Infrastructure)
+
+"""
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+from .models import Milestone
+
+logger = logging.getLogger(__name__)
+
+
+class MilestoneManager:
+    """Manages local milestone storage in .mcp-ticketer/milestones.json.
+
+    This class provides a simple file-based storage mechanism for milestones,
+    with automatic timestamp management and filtering capabilities. It is
+    designed to work alongside adapter-specific milestone implementations.
+
+    Attributes:
+        config_dir: Path to .mcp-ticketer configuration directory
+        milestones_file: Path to milestones.json storage file
+
+    """
+
+    def __init__(self, config_dir: Path):
+        """Initialize milestone manager.
+
+        Creates the storage file if it doesn't exist. Ensures the config
+        directory exists before attempting to create the storage file.
+
+        Args:
+            config_dir: Path to .mcp-ticketer directory
+
+        """
+        self.config_dir = config_dir
+        self.milestones_file = config_dir / "milestones.json"
+        self._ensure_storage()
+
+    def _ensure_storage(self) -> None:
+        """Ensure milestone storage file exists.
+
+        Creates the config directory and initializes an empty storage file
+        if it doesn't exist. Uses atomic write to prevent corruption.
+
+        """
+        if not self.milestones_file.exists():
+            self.config_dir.mkdir(parents=True, exist_ok=True)
+            self._save_data({"milestones": {}, "version": "1.0"})
+            logger.info(f"Initialized milestone storage at {self.milestones_file}")
+
+    def _load_data(self) -> dict:
+        """Load milestone data from file.
+
+        Returns:
+            Dictionary containing milestones and version info
+
+        Note:
+            Returns empty structure if file doesn't exist or is corrupted
+
+        """
+        try:
+            with open(self.milestones_file, encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError) as e:
+            logger.warning(
+                f"Failed to load milestones from {self.milestones_file}: {e}"
+            )
+            return {"milestones": {}, "version": "1.0"}
+
+    def _save_data(self, data: dict) -> None:
+        """Save milestone data to file.
+
+        Uses atomic write pattern to prevent corruption. Serializes datetime
+        objects to ISO format strings automatically.
+
+        Args:
+            data: Dictionary containing milestones and version info
+
+        """
+        with open(self.milestones_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, default=self._json_serializer)
+
+    @staticmethod
+    def _json_serializer(obj):
+        """Custom JSON serializer for datetime objects.
+
+        Args:
+            obj: Object to serialize
+
+        Returns:
+            ISO format string for datetime, original object otherwise
+
+        """
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+    def save_milestone(self, milestone: Milestone) -> Milestone:
+        """Save or update milestone in local storage.
+
+        Automatically updates the updated_at timestamp before saving.
+        If the milestone doesn't have an ID, generates one based on name.
+
+        Args:
+            milestone: Milestone to save
+
+        Returns:
+            Saved milestone with updated timestamp
+
+        """
+        data = self._load_data()
+
+        # Generate ID if not present
+        if not milestone.id:
+            # Simple ID generation based on name
+            import uuid
+
+            milestone.id = str(uuid.uuid4())[:8]
+
+        # Update timestamp
+        milestone.updated_at = datetime.utcnow()
+        if not milestone.created_at:
+            milestone.created_at = datetime.utcnow()
+
+        # Convert to dict for storage
+        milestone_dict = milestone.model_dump(mode="json")
+        data["milestones"][milestone.id] = milestone_dict
+
+        self._save_data(data)
+        logger.debug(f"Saved milestone {milestone.id} ({milestone.name})")
+        return milestone
+
+    def get_milestone(self, milestone_id: str) -> Milestone | None:
+        """Get milestone by ID.
+
+        Args:
+            milestone_id: Milestone identifier
+
+        Returns:
+            Milestone object or None if not found
+
+        """
+        data = self._load_data()
+        milestone_data = data["milestones"].get(milestone_id)
+
+        if not milestone_data:
+            logger.debug(f"Milestone {milestone_id} not found")
+            return None
+
+        return Milestone(**milestone_data)
+
+    def list_milestones(
+        self,
+        project_id: str | None = None,
+        state: str | None = None,
+    ) -> list[Milestone]:
+        """List milestones with optional filters.
+
+        Filters are applied in sequence: project_id, then state.
+        Results are sorted by target_date (None values appear last).
+
+        Args:
+            project_id: Filter by project ID
+            state: Filter by state (open, active, completed, closed)
+
+        Returns:
+            List of milestones matching filters, sorted by target_date
+
+        """
+        data = self._load_data()
+        milestones = []
+
+        for milestone_data in data["milestones"].values():
+            milestone = Milestone(**milestone_data)
+
+            # Apply filters
+            if project_id and milestone.project_id != project_id:
+                continue
+            if state and milestone.state != state:
+                continue
+
+            milestones.append(milestone)
+
+        # Sort by target_date (None values last)
+        milestones.sort(
+            key=lambda m: (
+                m.target_date is None,
+                m.target_date if m.target_date else datetime.max,
+            )
+        )
+
+        logger.debug(
+            f"Listed {len(milestones)} milestones "
+            f"(project_id={project_id}, state={state})"
+        )
+        return milestones
+
+    def delete_milestone(self, milestone_id: str) -> bool:
+        """Delete milestone from storage.
+
+        Args:
+            milestone_id: Milestone identifier
+
+        Returns:
+            True if deleted, False if not found
+
+        """
+        data = self._load_data()
+
+        if milestone_id not in data["milestones"]:
+            logger.warning(f"Cannot delete milestone {milestone_id}: not found")
+            return False
+
+        del data["milestones"][milestone_id]
+        self._save_data(data)
+        logger.info(f"Deleted milestone {milestone_id}")
+        return True

mcp_ticketer/core/models.py

@@ -519,6 +519,351 @@ class ProjectUpdate(BaseModel):
     )
 
 
+class Milestone(BaseModel):
+    """Universal milestone model for cross-platform support.
+
+    A milestone is a collection of issues grouped by labels with a target date.
+    Progress is calculated by counting closed vs total issues matching the labels.
+
+    Platform Mappings:
+    - Linear: Milestones (with labels and target dates)
+    - GitHub: Milestones (native support with due dates)
+    - JIRA: Versions/Releases (with target dates)
+    - Asana: Projects with dates (workaround via filtering)
+
+    The model follows the user's definition: "A milestone is a list of labels
+    with target dates, into which issues can be grouped."
+
+    Attributes:
+        id: Unique milestone identifier
+        name: Milestone name
+        target_date: Target completion date (ISO format: YYYY-MM-DD)
+        state: Milestone state (open, active, completed, closed)
+        description: Milestone description
+        labels: Labels that define this milestone's scope
+        total_issues: Total issues in milestone (calculated)
+        closed_issues: Closed issues in milestone (calculated)
+        progress_pct: Progress percentage 0-100 (calculated)
+        project_id: Associated project/epic ID
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+        platform_data: Platform-specific metadata
+
+    Example:
+        >>> milestone = Milestone(
+        ...     name="v2.1.0 Release",
+        ...     target_date=date(2025, 12, 31),
+        ...     labels=["v2.1", "release"],
+        ...     project_id="proj-123"
+        ... )
+        >>> milestone.total_issues = 15
+        >>> milestone.closed_issues = 8
+        >>> milestone.progress_pct = 53.3
+
+    Note:
+        Related to ticket 1M-607: Add milestone support (Phase 1 - Core Infrastructure)
+
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str | None = Field(None, description="Unique milestone identifier")
+    name: str = Field(..., min_length=1, description="Milestone name")
+    target_date: datetime | None = Field(
+        None, description="Target completion date (ISO format: YYYY-MM-DD)"
+    )
+    state: str = Field(
+        "open", description="Milestone state: open, active, completed, closed"
+    )
+    description: str = Field("", description="Milestone description")
+
+    # Label-based grouping (user's definition)
+    labels: list[str] = Field(
+        default_factory=list, description="Labels that define this milestone"
+    )
+
+    # Progress tracking (calculated fields)
+    total_issues: int = Field(0, ge=0, description="Total issues in milestone")
+    closed_issues: int = Field(0, ge=0, description="Closed issues in milestone")
+    progress_pct: float = Field(
+        0.0, ge=0.0, le=100.0, description="Progress percentage (0-100)"
+    )
+
+    # Metadata
+    project_id: str | None = Field(None, description="Associated project ID")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
+
+    # Platform-specific data
+    platform_data: dict[str, Any] = Field(
+        default_factory=dict, description="Platform-specific metadata"
+    )
+
+
+class ProjectState(str, Enum):
+    """Project state across platforms.
+
+    Maps to different platform concepts:
+    - Linear: planned, started, completed, paused, canceled
+    - GitHub V2: OPEN, CLOSED (with status field for more granular states)
+    - JIRA: Not directly supported (use project status or custom fields)
+
+    Attributes:
+        PLANNED: Project is planned but not yet started
+        ACTIVE: Project is actively being worked on
+        COMPLETED: Project is finished successfully
+        ARCHIVED: Project is archived (no longer active)
+        CANCELLED: Project was cancelled before completion
+
+    """
+
+    PLANNED = "planned"
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    ARCHIVED = "archived"
+    CANCELLED = "cancelled"
+
+
+class ProjectVisibility(str, Enum):
+    """Project visibility setting.
+
+    Controls who can view the project across platforms.
+
+    Attributes:
+        PUBLIC: Visible to everyone
+        PRIVATE: Visible only to members
+        TEAM: Visible to team members
+
+    """
+
+    PUBLIC = "public"
+    PRIVATE = "private"
+    TEAM = "team"
+
+
+class ProjectScope(str, Enum):
+    """Project organizational scope.
+
+    Defines the level at which a project exists in the organization hierarchy.
+
+    Platform Mappings:
+    - Linear: TEAM (projects belong to teams) or ORGANIZATION
+    - GitHub: REPOSITORY, USER, or ORGANIZATION
+    - JIRA: PROJECT (inherent) or ORGANIZATION (via project hierarchy)
+
+    Attributes:
+        USER: User-level project (GitHub Projects V2)
+        TEAM: Team-level project (Linear, GitHub org teams)
+        ORGANIZATION: Organization-level project (cross-team)
+        REPOSITORY: Repository-scoped project (GitHub)
+
+    """
+
+    USER = "user"
+    TEAM = "team"
+    ORGANIZATION = "organization"
+    REPOSITORY = "repository"
+
+
+class Project(BaseModel):
+    """Unified project model across platforms.
+
+    Projects represent strategic-level containers for issues, superseding the
+    Epic model with a more comprehensive structure that maps cleanly to:
+    - Linear Projects
+    - GitHub Projects V2
+    - JIRA Projects/Epics
+
+    This model provides backward compatibility through conversion utilities
+    (see project_utils.py) while enabling richer project management features.
+
+    Attributes:
+        id: Unique identifier in MCP Ticketer namespace
+        platform: Platform identifier ("linear", "github", "jira")
+        platform_id: Original platform-specific identifier
+        scope: Organizational scope of the project
+        name: Project name (required)
+        description: Detailed project description
+        state: Current project state
+        visibility: Who can view the project
+        url: Direct URL to project in platform
+        created_at: When project was created
+        updated_at: When project was last modified
+        start_date: Planned or actual start date
+        target_date: Target completion date
+        completed_at: Actual completion date
+        owner_id: Project owner/lead user ID
+        owner_name: Project owner/lead display name
+        team_id: Team this project belongs to
+        team_name: Team display name
+        child_issues: List of issue IDs in this project
+        issue_count: Total number of issues
+        completed_count: Number of completed issues
+        in_progress_count: Number of in-progress issues
+        progress_percentage: Overall completion percentage
+        extra_data: Platform-specific additional data
+
+    Example:
+        >>> project = Project(
+        ...     id="proj-123",
+        ...     platform="linear",
+        ...     platform_id="eac28953c267",
+        ...     scope=ProjectScope.TEAM,
+        ...     name="MCP Ticketer v2.0",
+        ...     state=ProjectState.ACTIVE,
+        ...     visibility=ProjectVisibility.TEAM
+        ... )
+
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    # Core identification
+    id: str = Field(..., description="Unique identifier")
+    platform: str = Field(..., description="Platform name (linear, github, jira)")
+    platform_id: str = Field(..., description="Original platform ID")
+    scope: ProjectScope = Field(..., description="Organizational scope")
+
+    # Basic information
+    name: str = Field(..., min_length=1, description="Project name")
+    description: str | None = Field(None, description="Project description")
+    state: ProjectState = Field(ProjectState.PLANNED, description="Current state")
+    visibility: ProjectVisibility = Field(
+        ProjectVisibility.TEAM, description="Visibility"
+    )
+
+    # URLs and references
+    url: str | None = Field(None, description="Direct URL to project")
+
+    # Dates
+    created_at: datetime | None = Field(None, description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
+    start_date: datetime | None = Field(None, description="Start date")
+    target_date: datetime | None = Field(None, description="Target completion date")
+    completed_at: datetime | None = Field(None, description="Completion timestamp")
+
+    # Ownership
+    owner_id: str | None = Field(None, description="Owner user ID")
+    owner_name: str | None = Field(None, description="Owner display name")
+    team_id: str | None = Field(None, description="Team ID")
+    team_name: str | None = Field(None, description="Team display name")
+
+    # Issue relationships
+    child_issues: list[str] = Field(default_factory=list, description="Child issue IDs")
+    issue_count: int | None = Field(None, ge=0, description="Total issue count")
+    completed_count: int | None = Field(None, ge=0, description="Completed issues")
+    in_progress_count: int | None = Field(None, ge=0, description="In-progress issues")
+    progress_percentage: float | None = Field(
+        None, ge=0.0, le=100.0, description="Completion percentage"
+    )
+
+    # Platform-specific data
+    extra_data: dict[str, Any] = Field(
+        default_factory=dict, description="Platform-specific metadata"
+    )
+
+    def calculate_progress(self) -> float:
+        """Calculate progress percentage from issue counts.
+
+        Returns:
+            Progress percentage (0-100), or 0 if no issues
+
+        """
+        if not self.issue_count or self.issue_count == 0:
+            return 0.0
+
+        completed = self.completed_count or 0
+        return (completed / self.issue_count) * 100.0
+
+
+class ProjectStatistics(BaseModel):
+    """Statistics and metrics for a project.
+
+    Provides calculated metrics for project health and progress tracking.
+    These statistics are typically computed from current project state
+    rather than stored directly.
+
+    Attributes:
+        project_id: ID of the project these stats belong to (optional for compatibility)
+        total_issues: Total number of issues (legacy field, use total_count)
+        completed_issues: Count of completed issues (legacy field, use completed_count)
+        in_progress_issues: Count of in-progress issues (legacy field, use in_progress_count)
+        open_issues: Count of open/backlog issues (legacy field, use open_count)
+        blocked_issues: Count of blocked issues (legacy field, use blocked_count)
+        total_count: Total number of issues (preferred)
+        open_count: Count of open issues (preferred)
+        in_progress_count: Count of in-progress issues (preferred)
+        completed_count: Count of completed issues (preferred)
+        blocked_count: Count of blocked issues (preferred)
+        priority_low_count: Count of low priority issues
+        priority_medium_count: Count of medium priority issues
+        priority_high_count: Count of high priority issues
+        priority_critical_count: Count of critical priority issues
+        health: Project health status (on_track, at_risk, off_track)
+        progress_percentage: Overall completion percentage
+        velocity: Issues completed per week (if available)
+        estimated_completion: Projected completion date
+
+    Example:
+        >>> stats = ProjectStatistics(
+        ...     total_count=50,
+        ...     completed_count=30,
+        ...     in_progress_count=15,
+        ...     open_count=5,
+        ...     blocked_count=0,
+        ...     priority_high_count=10,
+        ...     health="on_track",
+        ...     progress_percentage=60.0
+        ... )
+
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    # Legacy fields for backward compatibility (optional)
+    project_id: str | None = Field(None, description="Project identifier (legacy)")
+    total_issues: int | None = Field(
+        None, ge=0, description="Total issue count (legacy)"
+    )
+    completed_issues: int | None = Field(
+        None, ge=0, description="Completed issues (legacy)"
+    )
+    in_progress_issues: int | None = Field(
+        None, ge=0, description="In-progress issues (legacy)"
+    )
+    open_issues: int | None = Field(
+        None, ge=0, description="Open/backlog issues (legacy)"
+    )
+    blocked_issues: int | None = Field(
+        None, ge=0, description="Blocked issues (legacy)"
+    )
+
+    # New preferred fields
+    total_count: int = Field(0, ge=0, description="Total issue count")
+    open_count: int = Field(0, ge=0, description="Open issues")
+    in_progress_count: int = Field(0, ge=0, description="In-progress issues")
+    completed_count: int = Field(0, ge=0, description="Completed issues")
+    blocked_count: int = Field(0, ge=0, description="Blocked issues")
+
+    # Priority distribution
+    priority_low_count: int = Field(0, ge=0, description="Low priority issues")
+    priority_medium_count: int = Field(0, ge=0, description="Medium priority issues")
+    priority_high_count: int = Field(0, ge=0, description="High priority issues")
+    priority_critical_count: int = Field(
+        0, ge=0, description="Critical priority issues"
+    )
+
+    # Health and progress
+    health: str = Field(
+        "on_track", description="Health status: on_track, at_risk, off_track"
+    )
+    progress_percentage: float = Field(0.0, ge=0.0, le=100.0, description="Progress %")
+    velocity: float | None = Field(None, description="Issues/week completion rate")
+    estimated_completion: datetime | None = Field(
+        None, description="Projected completion date"
+    )
+
+
 class SearchQuery(BaseModel):
     """Search query parameters."""