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

mcp_ticketer/adapters/github.py

@@ -3,7 +3,8 @@
 import builtins
 import re
 from datetime import datetime
-from typing import Any, Optional
+from pathlib import Path
+from typing import Any
 
 import httpx
 
@@ -141,11 +142,11 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         Args:
             config: Configuration with:
-                - token: GitHub Personal Access Token (or GITHUB_TOKEN env var)
+                - token: GitHub PAT (or GITHUB_TOKEN env var)
                 - owner: Repository owner (or GITHUB_OWNER env var)
                 - repo: Repository name (or GITHUB_REPO env var)
-                - api_url: Optional API URL for GitHub Enterprise (defaults to github.com)
-                - use_projects_v2: Enable GitHub Projects v2 integration (default: False)
+                - api_url: Optional API URL for GitHub Enterprise
+                - use_projects_v2: Enable Projects v2 (default: False)
                 - custom_priority_scheme: Custom priority label mapping
 
         """
@@ -157,11 +158,12 @@ class GitHubAdapter(BaseAdapter[Task]):
         # Validate required configuration
         missing_keys = validate_adapter_config("github", full_config)
         if missing_keys:
+            missing = ", ".join(missing_keys)
             raise ValueError(
-                f"GitHub adapter missing required configuration: {', '.join(missing_keys)}"
+                f"GitHub adapter missing required configuration: {missing}"
             )
 
-        # Get authentication token - support both 'api_key' and 'token' for compatibility
+        # Get authentication token - support 'api_key' and 'token'
         self.token = (
             full_config.get("api_key")
             or full_config.get("token")
@@ -198,8 +200,8 @@ class GitHubAdapter(BaseAdapter[Task]):
         )
 
         # Cache for labels and milestones
-        self._labels_cache: Optional[list[dict[str, Any]]] = None
-        self._milestones_cache: Optional[list[dict[str, Any]]] = None
+        self._labels_cache: list[dict[str, Any]] | None = None
+        self._milestones_cache: list[dict[str, Any]] | None = None
         self._rate_limit: dict[str, Any] = {}
 
     def validate_credentials(self) -> tuple[bool, str]:
@@ -212,17 +214,21 @@ class GitHubAdapter(BaseAdapter[Task]):
         if not self.token:
             return (
                 False,
-                "GITHUB_TOKEN is required but not found. Set it in .env.local or environment.",
+                "GITHUB_TOKEN is required. Set it in .env.local or environment.",
             )
         if not self.owner:
             return (
                 False,
-                "GitHub owner is required in configuration. Set GITHUB_OWNER in .env.local or configure with 'mcp-ticketer init --adapter github --github-owner <owner>'",
+                "GitHub owner is required. Set GITHUB_OWNER in .env.local "
+                "or configure with 'mcp-ticketer init --adapter github "
+                "--github-owner <owner>'",
             )
         if not self.repo:
             return (
                 False,
-                "GitHub repo is required in configuration. Set GITHUB_REPO in .env.local or configure with 'mcp-ticketer init --adapter github --github-repo <repo>'",
+                "GitHub repo is required. Set GITHUB_REPO in .env.local "
+                "or configure with 'mcp-ticketer init --adapter github "
+                "--github-repo <repo>'",
             )
         return True, ""
 
@@ -239,7 +245,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             TicketState.CLOSED: GitHubStateMapping.CLOSED,
         }
 
-    def _get_state_label(self, state: TicketState) -> Optional[str]:
+    def _get_state_label(self, state: TicketState) -> str | None:
         """Get the label name for extended states."""
         return GitHubStateMapping.STATE_LABELS.get(state)
 
@@ -278,6 +284,39 @@ class GitHubAdapter(BaseAdapter[Task]):
             else f"P{['0', '1', '2', '3'][list(Priority).index(priority)]}"
         )
 
+    def _milestone_to_epic(self, milestone: dict[str, Any]) -> Epic:
+        """Convert GitHub milestone to Epic model.
+
+        Args:
+            milestone: GitHub milestone data
+
+        Returns:
+            Epic instance
+
+        """
+        return Epic(
+            id=str(milestone["number"]),
+            title=milestone["title"],
+            description=milestone.get("description", ""),
+            state=(
+                TicketState.OPEN if milestone["state"] == "open" else TicketState.CLOSED
+            ),
+            created_at=datetime.fromisoformat(
+                milestone["created_at"].replace("Z", "+00:00")
+            ),
+            updated_at=datetime.fromisoformat(
+                milestone["updated_at"].replace("Z", "+00:00")
+            ),
+            metadata={
+                "github": {
+                    "number": milestone["number"],
+                    "url": milestone.get("html_url"),
+                    "open_issues": milestone.get("open_issues", 0),
+                    "closed_issues": milestone.get("closed_issues", 0),
+                }
+            },
+        )
+
     def _extract_state_from_issue(self, issue: dict[str, Any]) -> TicketState:
         """Extract ticket state from GitHub issue data."""
         # Check if closed
@@ -508,7 +547,7 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         return self._task_from_github_issue(created_issue)
 
-    async def read(self, ticket_id: str) -> Optional[Task]:
+    async def read(self, ticket_id: str) -> Task | None:
         """Read a GitHub issue by number."""
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
@@ -533,7 +572,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         except httpx.HTTPError:
             return None
 
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[Task]:
+    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Task | None:
         """Update a GitHub issue."""
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
@@ -685,11 +724,11 @@ class GitHubAdapter(BaseAdapter[Task]):
             return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
     ) -> list[Task]:
         """List GitHub issues with filters."""
         # Build query parameters
-        params = {
+        params: dict[str, Any] = {
             "per_page": min(limit, 100),  # GitHub max is 100
             "page": (offset // limit) + 1 if limit > 0 else 1,
         }
@@ -837,7 +876,7 @@ class GitHubAdapter(BaseAdapter[Task]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Transition GitHub issue to a new state."""
         # Validate transition
         if not await self.validate_transition(ticket_id, target_state):
@@ -850,8 +889,8 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Add a comment to a GitHub issue."""
         try:
             issue_number = int(comment.ticket_id)
-        except ValueError:
-            raise ValueError(f"Invalid issue number: {comment.ticket_id}")
+        except ValueError as e:
+            raise ValueError(f"Invalid issue number: {comment.ticket_id}") from e
 
         # Create comment
         response = await self.client.post(
@@ -945,33 +984,9 @@ class GitHubAdapter(BaseAdapter[Task]):
         response.raise_for_status()
 
         created_milestone = response.json()
+        return self._milestone_to_epic(created_milestone)
 
-        return Epic(
-            id=str(created_milestone["number"]),
-            title=created_milestone["title"],
-            description=created_milestone["description"],
-            state=(
-                TicketState.OPEN
-                if created_milestone["state"] == "open"
-                else TicketState.CLOSED
-            ),
-            created_at=datetime.fromisoformat(
-                created_milestone["created_at"].replace("Z", "+00:00")
-            ),
-            updated_at=datetime.fromisoformat(
-                created_milestone["updated_at"].replace("Z", "+00:00")
-            ),
-            metadata={
-                "github": {
-                    "number": created_milestone["number"],
-                    "url": created_milestone["html_url"],
-                    "open_issues": created_milestone["open_issues"],
-                    "closed_issues": created_milestone["closed_issues"],
-                }
-            },
-        )
-
-    async def get_milestone(self, milestone_number: int) -> Optional[Epic]:
+    async def get_milestone(self, milestone_number: int) -> Epic | None:
         """Get a GitHub milestone as an Epic."""
         try:
             response = await self.client.get(
@@ -982,31 +997,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             response.raise_for_status()
 
             milestone = response.json()
-
-            return Epic(
-                id=str(milestone["number"]),
-                title=milestone["title"],
-                description=milestone["description"],
-                state=(
-                    TicketState.OPEN
-                    if milestone["state"] == "open"
-                    else TicketState.CLOSED
-                ),
-                created_at=datetime.fromisoformat(
-                    milestone["created_at"].replace("Z", "+00:00")
-                ),
-                updated_at=datetime.fromisoformat(
-                    milestone["updated_at"].replace("Z", "+00:00")
-                ),
-                metadata={
-                    "github": {
-                        "number": milestone["number"],
-                        "url": milestone["html_url"],
-                        "open_issues": milestone["open_issues"],
-                        "closed_issues": milestone["closed_issues"],
-                    }
-                },
-            )
+            return self._milestone_to_epic(milestone)
         except httpx.HTTPError:
             return None
 
@@ -1025,36 +1016,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         )
         response.raise_for_status()
 
-        epics = []
-        for milestone in response.json():
-            epics.append(
-                Epic(
-                    id=str(milestone["number"]),
-                    title=milestone["title"],
-                    description=milestone["description"],
-                    state=(
-                        TicketState.OPEN
-                        if milestone["state"] == "open"
-                        else TicketState.CLOSED
-                    ),
-                    created_at=datetime.fromisoformat(
-                        milestone["created_at"].replace("Z", "+00:00")
-                    ),
-                    updated_at=datetime.fromisoformat(
-                        milestone["updated_at"].replace("Z", "+00:00")
-                    ),
-                    metadata={
-                        "github": {
-                            "number": milestone["number"],
-                            "url": milestone["html_url"],
-                            "open_issues": milestone["open_issues"],
-                            "closed_issues": milestone["closed_issues"],
-                        }
-                    },
-                )
-            )
-
-        return epics
+        return [self._milestone_to_epic(milestone) for milestone in response.json()]
 
     async def link_to_pull_request(self, issue_number: int, pr_number: int) -> bool:
         """Link an issue to a pull request using keywords."""
@@ -1073,9 +1035,9 @@ class GitHubAdapter(BaseAdapter[Task]):
         self,
         ticket_id: str,
         base_branch: str = "main",
-        head_branch: Optional[str] = None,
-        title: Optional[str] = None,
-        body: Optional[str] = None,
+        head_branch: str | None = None,
+        title: str | None = None,
+        body: str | None = None,
         draft: bool = False,
     ) -> dict[str, Any]:
         """Create a pull request linked to an issue.
@@ -1094,8 +1056,8 @@ class GitHubAdapter(BaseAdapter[Task]):
         """
         try:
             issue_number = int(ticket_id)
-        except ValueError:
-            raise ValueError(f"Invalid issue number: {ticket_id}")
+        except ValueError as e:
+            raise ValueError(f"Invalid issue number: {ticket_id}") from e
 
         # Get the issue details
         issue = await self.read(ticket_id)
@@ -1229,10 +1191,11 @@ Fixes #{issue_number}
         pr = pr_response.json()
 
         # Add a comment to the issue about the PR
+        pr_msg = f"Pull request #{pr['number']} has been created: " f"{pr['html_url']}"
         await self.add_comment(
             Comment(
                 ticket_id=ticket_id,
-                content=f"Pull request #{pr['number']} has been created: {pr['html_url']}",
+                content=pr_msg,
                 author="system",
             )
         )
@@ -1265,8 +1228,8 @@ Fixes #{issue_number}
         """
         try:
             issue_number = int(ticket_id)
-        except ValueError:
-            raise ValueError(f"Invalid issue number: {ticket_id}")
+        except ValueError as e:
+            raise ValueError(f"Invalid issue number: {ticket_id}") from e
 
         # Parse PR URL to extract owner, repo, and PR number
         # Expected format: https://github.com/owner/repo/pull/123
@@ -1342,12 +1305,266 @@ Fixes #{issue_number}
         response.raise_for_status()
         return response.json()
 
-    async def get_current_user(self) -> Optional[dict[str, Any]]:
+    async def get_current_user(self) -> dict[str, Any] | None:
         """Get current authenticated user information."""
         response = await self.client.get("/user")
         response.raise_for_status()
         return response.json()
 
+    async def list_labels(self) -> builtins.list[dict[str, Any]]:
+        """List all labels available in the repository.
+
+        Returns:
+            List of label dictionaries with 'id', 'name', and 'color' fields
+
+        """
+        if self._labels_cache:
+            return self._labels_cache
+
+        response = await self.client.get(f"/repos/{self.owner}/{self.repo}/labels")
+        response.raise_for_status()
+        labels = response.json()
+
+        # Transform to standardized format
+        standardized_labels = [
+            {"id": label["name"], "name": label["name"], "color": label["color"]}
+            for label in labels
+        ]
+
+        self._labels_cache = standardized_labels
+        return standardized_labels
+
+    async def update_milestone(
+        self, milestone_number: int, updates: dict[str, Any]
+    ) -> Epic | None:
+        """Update a GitHub milestone (Epic).
+
+        Args:
+            milestone_number: Milestone number (not ID)
+            updates: Dictionary with fields to update:
+                - title: Milestone title
+                - description: Milestone description (supports markdown)
+                - state: TicketState value (maps to open/closed)
+                - target_date: Due date in ISO format
+
+        Returns:
+            Updated Epic object or None if not found
+
+        Raises:
+            ValueError: If no fields to update
+            httpx.HTTPError: If API request fails
+
+        """
+        update_data = {}
+
+        # Map title directly
+        if "title" in updates:
+            update_data["title"] = updates["title"]
+
+        # Map description (supports markdown)
+        if "description" in updates:
+            update_data["description"] = updates["description"]
+
+        # Map state to GitHub milestone state
+        if "state" in updates:
+            state = updates["state"]
+            if isinstance(state, TicketState):
+                # GitHub only has open/closed
+                update_data["state"] = (
+                    "closed"
+                    if state in [TicketState.DONE, TicketState.CLOSED]
+                    else "open"
+                )
+            else:
+                update_data["state"] = state
+
+        # Map target_date to due_on
+        if "target_date" in updates:
+            # GitHub expects ISO 8601 format
+            target_date = updates["target_date"]
+            if isinstance(target_date, str):
+                update_data["due_on"] = target_date
+            elif hasattr(target_date, "isoformat"):
+                update_data["due_on"] = target_date.isoformat()
+
+        if not update_data:
+            raise ValueError("At least one field must be updated")
+
+        # Make API request
+        response = await self.client.patch(
+            f"/repos/{self.owner}/{self.repo}/milestones/{milestone_number}",
+            json=update_data,
+        )
+        response.raise_for_status()
+
+        # Convert response to Epic
+        milestone_data = response.json()
+        return self._milestone_to_epic(milestone_data)
+
+    async def update_epic(self, epic_id: str, updates: dict[str, Any]) -> Epic | None:
+        """Update a GitHub epic (milestone) by ID or number.
+
+        This is a convenience wrapper around update_milestone() that accepts
+        either a milestone number or the epic ID from the Epic object.
+
+        Args:
+            epic_id: Epic ID (e.g., "milestone-5") or milestone number as string
+            updates: Dictionary with fields to update
+
+        Returns:
+            Updated Epic object or None if not found
+
+        """
+        # Extract milestone number from ID
+        if epic_id.startswith("milestone-"):
+            milestone_number = int(epic_id.replace("milestone-", ""))
+        else:
+            milestone_number = int(epic_id)
+
+        return await self.update_milestone(milestone_number, updates)
+
+    async def add_attachment_to_issue(
+        self, issue_number: int, file_path: str, comment: str | None = None
+    ) -> dict[str, Any]:
+        """Attach file to GitHub issue via comment.
+
+        GitHub doesn't have direct file attachment API. This method:
+        1. Creates a comment with the file reference
+        2. Returns metadata about the attachment
+
+        Note: GitHub's actual file upload in comments requires browser-based
+        drag-and-drop or git-lfs. This method creates a placeholder comment
+        that users can edit to add actual file attachments through the UI.
+
+        Args:
+            issue_number: Issue number
+            file_path: Path to file to attach
+            comment: Optional comment text (defaults to "Attached: {filename}")
+
+        Returns:
+            Dictionary with comment data and file info
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file too large (>25 MB)
+
+        Note:
+            GitHub file size limit: 25 MB
+            Supported: Images, videos, documents
+
+        """
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Check file size (25 MB limit)
+        file_size = file_path_obj.stat().st_size
+        if file_size > 25 * 1024 * 1024:  # 25 MB
+            raise ValueError(
+                f"File too large: {file_size} bytes (max 25 MB). "
+                "Upload file externally and reference URL instead."
+            )
+
+        # Prepare comment body
+        comment_body = comment or f"📎 Attached: `{file_path_obj.name}`"
+        comment_body += (
+            f"\n\n*Note: File `{file_path_obj.name}` ({file_size} bytes) "
+            "needs to be manually uploaded through GitHub UI or referenced via URL.*"
+        )
+
+        # Create comment with file reference
+        response = await self.client.post(
+            f"/repos/{self.owner}/{self.repo}/issues/{issue_number}/comments",
+            json={"body": comment_body},
+        )
+        response.raise_for_status()
+
+        comment_data = response.json()
+
+        return {
+            "comment_id": comment_data["id"],
+            "comment_url": comment_data["html_url"],
+            "filename": file_path_obj.name,
+            "file_size": file_size,
+            "note": "File reference created. Upload file manually through GitHub UI.",
+        }
+
+    async def add_attachment_reference_to_milestone(
+        self, milestone_number: int, file_url: str, description: str
+    ) -> Epic | None:
+        """Add file reference to milestone description.
+
+        Since GitHub milestones don't support direct file attachments,
+        this method appends a markdown link to the milestone description.
+
+        Args:
+            milestone_number: Milestone number
+            file_url: URL to the file (external or GitHub-hosted)
+            description: Description/title for the file
+
+        Returns:
+            Updated Epic object
+
+        Example:
+            await adapter.add_attachment_reference_to_milestone(
+                5,
+                "https://example.com/spec.pdf",
+                "Technical Specification"
+            )
+            # Appends to description: "[Technical Specification](https://example.com/spec.pdf)"
+
+        """
+        # Get current milestone
+        response = await self.client.get(
+            f"/repos/{self.owner}/{self.repo}/milestones/{milestone_number}"
+        )
+        response.raise_for_status()
+        milestone = response.json()
+
+        # Append file reference to description
+        current_desc = milestone.get("description", "")
+        attachment_markdown = f"\n\n📎 [{description}]({file_url})"
+        new_description = current_desc + attachment_markdown
+
+        # Update milestone with new description
+        return await self.update_milestone(
+            milestone_number, {"description": new_description}
+        )
+
+    async def add_attachment(
+        self, ticket_id: str, file_path: str, description: str | None = None
+    ) -> dict[str, Any]:
+        """Add attachment to GitHub ticket (issue or milestone).
+
+        This method routes to appropriate attachment method based on ticket type:
+        - Issues: Creates comment with file reference
+        - Milestones: Not supported, raises NotImplementedError with guidance
+
+        Args:
+            ticket_id: Ticket identifier (issue number or milestone ID)
+            file_path: Path to file to attach
+            description: Optional description
+
+        Returns:
+            Attachment metadata
+
+        Raises:
+            NotImplementedError: For milestones (no native support)
+            FileNotFoundError: If file doesn't exist
+
+        """
+        # Determine ticket type from ID format
+        if ticket_id.startswith("milestone-"):
+            raise NotImplementedError(
+                "GitHub milestones do not support direct file attachments. "
+                "Workaround: Upload file externally and use "
+                "add_attachment_reference_to_milestone() to add URL to description."
+            )
+
+        # Assume it's an issue number
+        issue_number = int(ticket_id.replace("issue-", ""))
+        return await self.add_attachment_to_issue(issue_number, file_path, description)
+
     async def close(self) -> None:
         """Close the HTTP client connection."""
         await self.client.aclose()

mcp_ticketer/adapters/hybrid.py

@@ -8,7 +8,7 @@ import builtins
 import json
 import logging
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 from ..core.adapter import BaseAdapter
 from ..core.models import Comment, Epic, SearchQuery, Task, TicketState
@@ -129,7 +129,7 @@ class HybridAdapter(BaseAdapter):
 
     def _get_adapter_ticket_id(
         self, universal_id: str, adapter_name: str
-    ) -> Optional[str]:
+    ) -> str | None:
         """Get adapter-specific ticket ID from universal ID.
 
         Args:
@@ -153,7 +153,7 @@ class HybridAdapter(BaseAdapter):
 
         return f"hybrid-{uuid.uuid4().hex[:12]}"
 
-    async def create(self, ticket: Union[Task, Epic]) -> Union[Task, Epic]:
+    async def create(self, ticket: Task | Epic) -> Task | Epic:
         """Create ticket in all configured adapters.
 
         Args:
@@ -208,7 +208,7 @@ class HybridAdapter(BaseAdapter):
         return primary_ticket
 
     def _add_cross_references(
-        self, ticket: Union[Task, Epic], results: list[tuple[str, Union[Task, Epic]]]
+        self, ticket: Task | Epic, results: list[tuple[str, Task | Epic]]
     ) -> None:
         """Add cross-references to ticket description.
 
@@ -226,7 +226,7 @@ class HybridAdapter(BaseAdapter):
         else:
             ticket.description = cross_refs.strip()
 
-    async def read(self, ticket_id: str) -> Optional[Union[Task, Epic]]:
+    async def read(self, ticket_id: str) -> Task | Epic | None:
         """Read ticket from primary adapter.
 
         Args:
@@ -255,7 +255,7 @@ class HybridAdapter(BaseAdapter):
 
     async def update(
         self, ticket_id: str, updates: dict[str, Any]
-    ) -> Optional[Union[Task, Epic]]:
+    ) -> Task | Epic | None:
         """Update ticket across all adapters.
 
         Args:
@@ -300,7 +300,7 @@ class HybridAdapter(BaseAdapter):
 
         return None
 
-    def _find_universal_id(self, adapter_ticket_id: str) -> Optional[str]:
+    def _find_universal_id(self, adapter_ticket_id: str) -> str | None:
         """Find universal ID for an adapter-specific ticket ID.
 
         Args:
@@ -359,8 +359,8 @@ class HybridAdapter(BaseAdapter):
         return success_count > 0
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
-    ) -> list[Union[Task, Epic]]:
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
+    ) -> list[Task | Epic]:
         """List tickets from primary adapter.
 
         Args:
@@ -375,7 +375,7 @@ class HybridAdapter(BaseAdapter):
         primary = self.adapters[self.primary_adapter_name]
         return await primary.list(limit, offset, filters)
 
-    async def search(self, query: SearchQuery) -> builtins.list[Union[Task, Epic]]:
+    async def search(self, query: SearchQuery) -> builtins.list[Task | Epic]:
         """Search tickets in primary adapter.
 
         Args:
@@ -390,7 +390,7 @@ class HybridAdapter(BaseAdapter):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Union[Task, Epic]]:
+    ) -> Task | Epic | None:
         """Transition ticket state across all adapters.
 
         Args: