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

mcp_ticketer/core/models.py

@@ -160,6 +160,37 @@ class TicketState(str, Enum):
         """
         return target.value in self.valid_transitions().get(self, [])
 
+    def completion_level(self) -> int:
+        """Get numeric completion level for state ordering.
+
+        Higher numbers indicate more complete states. Used for parent/child
+        state constraints where parents must be at least as complete as
+        their most complete child.
+
+        Returns:
+            Completion level (0-7)
+
+        Example:
+            >>> TicketState.OPEN.completion_level()
+            0
+            >>> TicketState.DONE.completion_level()
+            6
+            >>> TicketState.DONE.completion_level() > TicketState.IN_PROGRESS.completion_level()
+            True
+
+        """
+        levels = {
+            TicketState.OPEN: 0,  # Not started
+            TicketState.BLOCKED: 1,  # Blocked
+            TicketState.WAITING: 2,  # Waiting
+            TicketState.IN_PROGRESS: 3,  # In progress
+            TicketState.READY: 4,  # Ready for review
+            TicketState.TESTED: 5,  # Tested
+            TicketState.DONE: 6,  # Done
+            TicketState.CLOSED: 7,  # Closed (terminal)
+        }
+        return levels.get(self, 0)
+
 
 class BaseTicket(BaseModel):
     """Base model for all ticket types with universal field mapping.
@@ -385,6 +416,454 @@ class Attachment(BaseModel):
         return f"Attachment({self.filename}{size_str})"
 
 
+class ProjectUpdateHealth(str, Enum):
+    """Project health status indicator for status updates.
+
+    Represents the health/status of a project at the time of an update.
+    These states map to different platform-specific health indicators:
+
+    Platform Mappings:
+    - Linear: on_track, at_risk, off_track (1:1 mapping)
+    - GitHub V2: Uses ProjectV2StatusOptionConfiguration
+      - complete: Project is finished
+      - inactive: Project is not actively being worked on
+    - Asana: On Track, At Risk, Off Track (1:1 mapping)
+    - JIRA: Not directly supported (workaround via status comments)
+
+    Attributes:
+        ON_TRACK: Project is progressing as planned
+        AT_RISK: Project has some issues but recoverable
+        OFF_TRACK: Project is significantly behind or blocked
+        COMPLETE: Project is finished (GitHub-specific)
+        INACTIVE: Project is not actively being worked on (GitHub-specific)
+
+    Note:
+        Related to ticket 1M-238: Add project updates support with flexible
+        project identification.
+
+    """
+
+    ON_TRACK = "on_track"  # Linear, Asana
+    AT_RISK = "at_risk"  # Linear, Asana
+    OFF_TRACK = "off_track"  # Linear, Asana
+    COMPLETE = "complete"  # GitHub only
+    INACTIVE = "inactive"  # GitHub only
+
+
+class ProjectUpdate(BaseModel):
+    """Represents a project status update across different platforms.
+
+    ProjectUpdate provides a unified interface for creating and retrieving
+    project status updates with health indicators, supporting Linear, GitHub V2,
+    Asana, and JIRA (via workaround).
+
+    Platform Mappings:
+    - Linear: ProjectUpdate entity with health, diff_markdown, staleness
+    - GitHub V2: ProjectV2StatusUpdate with status options
+    - Asana: Project Status Updates with color-coded health
+    - JIRA: Comments with custom formatting (workaround)
+
+    The model includes platform-specific optional fields to support features
+    like Linear's auto-generated diffs and staleness indicators.
+
+    Attributes:
+        id: Unique identifier for the update
+        project_id: ID of the project this update belongs to
+        project_name: Optional human-readable project name
+        body: Markdown-formatted update content (required)
+        health: Optional health status indicator
+        created_at: Timestamp when update was created
+        updated_at: Timestamp when update was last modified
+        author_id: Optional ID of the user who created the update
+        author_name: Optional human-readable author name
+        url: Optional direct URL to the update
+        diff_markdown: Linear-specific auto-generated diff of project changes
+        is_stale: Linear-specific indicator if update is outdated
+
+    Example:
+        >>> update = ProjectUpdate(
+        ...     project_id="PROJ-123",
+        ...     body="Sprint completed with 15/20 stories done",
+        ...     health=ProjectUpdateHealth.AT_RISK,
+        ...     created_at=datetime.now()
+        ... )
+        >>> print(update.model_dump_json())
+
+    Note:
+        Related to ticket 1M-238: Add project updates support with flexible
+        project identification.
+
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str = Field(..., description="Unique update identifier")
+    project_id: str = Field(..., description="Parent project identifier")
+    project_name: str | None = Field(None, description="Human-readable project name")
+    body: str = Field(..., min_length=1, description="Markdown update content")
+    health: ProjectUpdateHealth | None = Field(
+        None, description="Project health status"
+    )
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
+    author_id: str | None = Field(None, description="Update author identifier")
+    author_name: str | None = Field(None, description="Update author name")
+    url: str | None = Field(None, description="Direct URL to update")
+
+    # Platform-specific fields
+    diff_markdown: str | None = Field(
+        None, description="Linear: Auto-generated diff of project changes"
+    )
+    is_stale: bool | None = Field(
+        None, description="Linear: Indicator if update is outdated"
+    )
+
+
+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."""
 
@@ -393,5 +872,6 @@ class SearchQuery(BaseModel):
     priority: Priority | None = Field(None, description="Filter by priority")
     tags: list[str] | None = Field(None, description="Filter by tags")
     assignee: str | None = Field(None, description="Filter by assignee")
+    project: str | None = Field(None, description="Filter by project/epic ID or name")
     limit: int = Field(10, gt=0, le=100, description="Maximum results")
     offset: int = Field(0, ge=0, description="Result offset for pagination")

mcp_ticketer/core/onepassword_secrets.py

@@ -334,7 +334,7 @@ def check_op_cli_status() -> dict[str, Any]:
     """
     loader = OnePasswordSecretsLoader()
 
-    status = {
+    status: dict[str, Any] = {
         "installed": loader.is_op_available(),
         "authenticated": False,
         "version": None,