mcp-ticketer 0.1.30__py3-none-any.whl → 1.2.11__py3-none-any.whl

mcp_ticketer/adapters/github.py

@@ -1,17 +1,21 @@
 """GitHub adapter implementation using REST API v3 and GraphQL API v4."""
 
 import builtins
-import os
+import logging
 import re
 from datetime import datetime
-from typing import Any, Optional
+from pathlib import Path
+from typing import Any
 
 import httpx
 
 from ..core.adapter import BaseAdapter
+from ..core.env_loader import load_adapter_config, validate_adapter_config
 from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
 from ..core.registry import AdapterRegistry
 
+logger = logging.getLogger(__name__)
+
 
 class GitHubStateMapping:
     """GitHub issue states and label-based extended states."""
@@ -132,6 +136,27 @@ class GitHubGraphQLQueries:
         }
     """
 
+    GET_PROJECT_ITERATIONS = """
+        query GetProjectIterations($projectId: ID!, $first: Int!, $after: String) {
+            node(id: $projectId) {
+                ... on ProjectV2 {
+                    iterations(first: $first, after: $after) {
+                        nodes {
+                            id
+                            title
+                            startDate
+                            duration
+                        }
+                        pageInfo {
+                            hasNextPage
+                            endCursor
+                        }
+                    }
+                }
+            }
+        }
+    """
+
 
 class GitHubAdapter(BaseAdapter[Task]):
     """Adapter for GitHub Issues tracking system."""
@@ -140,32 +165,39 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Initialize GitHub adapter.
 
         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
 
         """
         super().__init__(config)
 
-        # Get authentication token - support both 'api_key' and 'token' for compatibility
-        self.token = (
-            config.get("api_key") or config.get("token") or os.getenv("GITHUB_TOKEN")
-        )
-        if not self.token:
+        # Load configuration with environment variable resolution
+        full_config = load_adapter_config("github", config)
+
+        # Validate required configuration
+        missing_keys = validate_adapter_config("github", full_config)
+        if missing_keys:
+            missing = ", ".join(missing_keys)
             raise ValueError(
-                "GitHub token required (config.api_key, config.token or GITHUB_TOKEN env var)"
+                f"GitHub adapter missing required configuration: {missing}"
             )
 
-        # Get repository information
-        self.owner = config.get("owner") or os.getenv("GITHUB_OWNER")
-        self.repo = config.get("repo") or os.getenv("GITHUB_REPO")
+        # Get authentication token - support 'api_key' and 'token'
+        self.token = (
+            full_config.get("api_key")
+            or full_config.get("token")
+            or full_config.get("token")
+        )
 
-        if not self.owner or not self.repo:
-            raise ValueError("GitHub owner and repo are required")
+        # Get repository information
+        self.owner = full_config.get("owner")
+        self.repo = full_config.get("repo")
 
         # API URLs
         self.api_url = config.get("api_url", "https://api.github.com")
@@ -193,31 +225,36 @@ 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]:
         """Validate that required credentials are present.
 
         Returns:
+        -------
             (is_valid, error_message) - Tuple of validation result and error message
 
         """
         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, ""
 
@@ -234,7 +271,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)
 
@@ -273,6 +310,41 @@ 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
@@ -503,32 +575,74 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         return self._task_from_github_issue(created_issue)
 
-    async def read(self, ticket_id: str) -> Optional[Task]:
-        """Read a GitHub issue by number."""
+    async def read(self, ticket_id: str) -> Task | Epic | None:
+        """Read a GitHub issue OR milestone by number with unified find.
+
+        Tries to find the entity in the following order:
+        1. Issue (most common case) - returns Task
+        2. Milestone (project/epic) - returns Epic
+
+        Args:
+        ----
+            ticket_id: GitHub issue number or milestone number (as string)
+
+        Returns:
+        -------
+            Task if issue found,
+            Epic if milestone found,
+            None if not found as either type
+
+        Examples:
+        --------
+            >>> # Read issue #123
+            >>> task = await adapter.read("123")
+            >>> isinstance(task, Task)  # True
+            >>>
+            >>> # Read milestone #5
+            >>> epic = await adapter.read("5")
+            >>> isinstance(epic, Epic)  # True (if 5 is milestone, not issue)
+
+        """
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
         if not is_valid:
             raise ValueError(error_message)
 
         try:
-            issue_number = int(ticket_id)
+            entity_number = int(ticket_id)
         except ValueError:
             return None
 
+        # Try reading as Issue first (most common case)
         try:
             response = await self.client.get(
-                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}"
+                f"/repos/{self.owner}/{self.repo}/issues/{entity_number}"
             )
-            if response.status_code == 404:
-                return None
-            response.raise_for_status()
-
-            issue = response.json()
-            return self._task_from_github_issue(issue)
-        except httpx.HTTPError:
-            return None
-
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[Task]:
+            if response.status_code == 200:
+                response.raise_for_status()
+                issue = response.json()
+                logger.debug(f"Found GitHub entity as Issue: {ticket_id}")
+                return self._task_from_github_issue(issue)
+            elif response.status_code == 404:
+                # Not found as issue, will try milestone next
+                logger.debug(f"Not found as Issue ({ticket_id}), trying Milestone")
+        except httpx.HTTPError as e:
+            logger.debug(f"Error reading as Issue ({ticket_id}): {e}")
+
+        # Try reading as Milestone (Epic)
+        try:
+            milestone = await self.get_milestone(entity_number)
+            if milestone:
+                logger.debug(f"Found GitHub entity as Milestone: {ticket_id}")
+                return milestone
+        except Exception as e:
+            logger.debug(f"Error reading as Milestone ({ticket_id}): {e}")
+
+        # Not found as either Issue or Milestone
+        logger.warning(f"GitHub entity not found: {ticket_id}")
+        return None
+
+    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()
@@ -598,7 +712,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             labels_to_update = update_data.get("labels", current_labels)
             all_priority_labels = []
             for labels in GitHubStateMapping.PRIORITY_LABELS.values():
-                all_priority_labels.extend([l.lower() for l in labels])
+                all_priority_labels.extend([label.lower() for label in labels])
 
             labels_to_update = [
                 label
@@ -680,11 +794,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,
         }
@@ -832,7 +946,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):
@@ -845,8 +959,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(
@@ -940,33 +1054,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(
@@ -977,31 +1067,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
 
@@ -1020,36 +1086,63 @@ 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 [self._milestone_to_epic(milestone) for milestone in response.json()]
+
+    async def delete_epic(self, epic_id: str) -> bool:
+        """Delete a GitHub milestone (Epic).
+
+        Args:
+        ----
+            epic_id: Milestone number (not ID) as a string
+
+        Returns:
+        -------
+            True if successfully deleted, False otherwise
+
+        Raises:
+        ------
+            ValueError: If credentials are invalid or epic_id is not a valid number
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            # Extract milestone number from epic_id
+            milestone_number = int(epic_id)
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid milestone number '{epic_id}'. GitHub milestones use numeric IDs."
+            ) from e
+
+        try:
+            # Delete milestone using REST API
+            response = await self.client.delete(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_number}"
             )
 
-        return epics
+            # GitHub returns 204 No Content on successful deletion
+            if response.status_code == 204:
+                return True
+
+            # Handle 404 errors gracefully
+            if response.status_code == 404:
+                return False
+
+            # Other errors - raise for visibility
+            response.raise_for_status()
+            return True
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                # Milestone not found
+                return False
+            # Re-raise other HTTP errors
+            raise ValueError(f"Failed to delete milestone: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Failed to delete milestone: {e}") from e
 
     async def link_to_pull_request(self, issue_number: int, pr_number: int) -> bool:
         """Link an issue to a pull request using keywords."""
@@ -1068,14 +1161,15 @@ 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.
 
         Args:
+        ----
             ticket_id: Issue number to link the PR to
             base_branch: Target branch for the PR (default: main)
             head_branch: Source branch name (auto-generated if not provided)
@@ -1084,13 +1178,14 @@ class GitHubAdapter(BaseAdapter[Task]):
             draft: Create as draft PR
 
         Returns:
+        -------
             Dictionary with PR details including number, url, and branch
 
         """
         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)
@@ -1224,10 +1319,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",
             )
         )
@@ -1251,17 +1347,19 @@ Fixes #{issue_number}
         """Link an existing pull request to a ticket.
 
         Args:
+        ----
             ticket_id: Issue number to link the PR to
             pr_url: GitHub PR URL to link
 
         Returns:
+        -------
             Dictionary with link status and PR details
 
         """
         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
@@ -1329,6 +1427,658 @@ Fixes #{issue_number}
             "message": f"Successfully linked PR #{pr_number} to issue #{issue_number}",
         }
 
+    async def get_collaborators(self) -> builtins.list[dict[str, Any]]:
+        """Get repository collaborators."""
+        response = await self.client.get(
+            f"/repos/{self.owner}/{self.repo}/collaborators"
+        )
+        response.raise_for_status()
+        return response.json()
+
+    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 list_cycles(
+        self, project_id: str | None = None, limit: int = 50
+    ) -> builtins.list[dict[str, Any]]:
+        """List GitHub Project iterations (cycles/sprints).
+
+        GitHub Projects V2 uses "iterations" for sprint/cycle functionality.
+        Requires a project node ID (not numeric ID).
+
+        Args:
+        ----
+            project_id: GitHub Project V2 node ID (e.g., 'PVT_kwDOABcdefgh').
+                       This is required for Projects V2. Can be found in the
+                       project's GraphQL ID.
+            limit: Maximum number of iterations to return (default: 50)
+
+        Returns:
+        -------
+            List of iteration dictionaries with fields:
+                - id: Iteration node ID
+                - title: Iteration title/name
+                - startDate: Start date (ISO format)
+                - duration: Duration in days
+                - endDate: Calculated end date (startDate + duration)
+
+        Raises:
+        ------
+            ValueError: If project_id not provided or credentials invalid
+            httpx.HTTPError: If GraphQL query fails
+
+        Example:
+        -------
+            >>> iterations = await adapter.list_cycles(
+            ...     project_id="PVT_kwDOABCD1234",
+            ...     limit=10
+            ... )
+            >>> for iteration in iterations:
+            ...     print(f"{iteration['title']}: {iteration['startDate']} ({iteration['duration']} days)")
+
+        Note:
+        ----
+            GitHub Projects V2 node IDs can be obtained via the GitHub GraphQL API.
+            This is different from project numbers shown in the UI.
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        if not project_id:
+            raise ValueError(
+                "project_id is required for GitHub Projects V2. "
+                "Provide a project node ID (e.g., 'PVT_kwDOABcdefgh'). "
+                "Find this via GraphQL API: query { organization(login: 'org') { "
+                "projectV2(number: 1) { id } } }"
+            )
+
+        # Execute GraphQL query to fetch iterations
+        query = GitHubGraphQLQueries.GET_PROJECT_ITERATIONS
+        variables = {"projectId": project_id, "first": min(limit, 100), "after": None}
+
+        try:
+            result = await self._graphql_request(query, variables)
+
+            # Extract iterations from response
+            project_node = result.get("node")
+            if not project_node:
+                raise ValueError(
+                    f"Project not found with ID: {project_id}. "
+                    "Verify the project ID is correct and you have access."
+                )
+
+            iterations_data = project_node.get("iterations", {})
+            iteration_nodes = iterations_data.get("nodes", [])
+
+            # Transform to standard format and calculate end dates
+            iterations = []
+            for iteration in iteration_nodes:
+                # Calculate end date from start date + duration
+                start_date = iteration.get("startDate")
+                duration = iteration.get("duration", 0)
+
+                end_date = None
+                if start_date and duration:
+                    from datetime import datetime, timedelta
+
+                    start_dt = datetime.fromisoformat(start_date.replace("Z", "+00:00"))
+                    end_dt = start_dt + timedelta(days=duration)
+                    end_date = end_dt.isoformat()
+
+                iterations.append(
+                    {
+                        "id": iteration["id"],
+                        "title": iteration.get("title", ""),
+                        "startDate": start_date,
+                        "duration": duration,
+                        "endDate": end_date,
+                    }
+                )
+
+            return iterations
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except Exception as e:
+            raise ValueError(f"Failed to list project iterations: {e}") from e
+
+    async def get_issue_status(self, issue_number: int) -> dict[str, Any]:
+        """Get rich status information for a GitHub issue.
+
+        GitHub issues have binary states (open/closed) natively. Extended status
+        tracking uses labels following the status:* convention (e.g., status:in_progress).
+
+        Args:
+        ----
+            issue_number: GitHub issue number
+
+        Returns:
+        -------
+            Dictionary with comprehensive status information:
+                - state: Native GitHub state ('open' or 'closed')
+                - status_label: Extended status from labels (in_progress, blocked, etc.)
+                - extended_state: Universal TicketState value
+                - labels: All issue labels
+                - state_reason: For closed issues (completed or not_planned)
+                - metadata: Additional issue metadata (assignees, milestone, etc.)
+
+        Raises:
+        ------
+            ValueError: If credentials invalid or issue not found
+            httpx.HTTPError: If API request fails
+
+        Example:
+        -------
+            >>> status = await adapter.get_issue_status(123)
+            >>> print(f"Issue #{status['number']}: {status['extended_state']}")
+            >>> print(f"Native state: {status['state']}")
+            >>> if status['status_label']:
+            ...     print(f"Label-based status: {status['status_label']}")
+
+        Note:
+        ----
+            GitHub's binary state model is extended via labels:
+            - open + no label = OPEN
+            - open + status:in-progress = IN_PROGRESS
+            - open + status:blocked = BLOCKED
+            - closed = CLOSED (check state_reason for details)
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            # Fetch issue via REST API
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}"
+            )
+
+            if response.status_code == 404:
+                raise ValueError(f"Issue #{issue_number} not found")
+
+            response.raise_for_status()
+            issue = response.json()
+
+            # Extract labels
+            labels = [label["name"] for label in issue.get("labels", [])]
+
+            # Derive extended state from issue data
+            extended_state = self._extract_state_from_issue(issue)
+
+            # Find status label if present
+            status_label = None
+            for _state, label_name in GitHubStateMapping.STATE_LABELS.items():
+                if label_name.lower() in [label.lower() for label in labels]:
+                    status_label = label_name
+                    break
+
+            # Build comprehensive status response
+            status_info = {
+                "number": issue["number"],
+                "state": issue["state"],  # 'open' or 'closed'
+                "status_label": status_label,  # Label-based extended status
+                "extended_state": extended_state.value,  # Universal TicketState
+                "labels": labels,
+                "state_reason": issue.get(
+                    "state_reason"
+                ),  # 'completed' or 'not_planned'
+                "metadata": {
+                    "title": issue["title"],
+                    "url": issue["html_url"],
+                    "assignees": [
+                        assignee["login"] for assignee in issue.get("assignees", [])
+                    ],
+                    "milestone": (
+                        issue.get("milestone", {}).get("title")
+                        if issue.get("milestone")
+                        else None
+                    ),
+                    "created_at": issue["created_at"],
+                    "updated_at": issue["updated_at"],
+                    "closed_at": issue.get("closed_at"),
+                },
+            }
+
+            return status_info
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except httpx.HTTPError as e:
+            raise ValueError(f"Failed to get issue status: {e}") from e
+
+    async def list_issue_statuses(self) -> builtins.list[dict[str, Any]]:
+        """List available issue statuses in GitHub.
+
+        Returns all possible issue statuses including native GitHub states
+        and extended label-based states.
+
+        Returns:
+        -------
+            List of status dictionaries with fields:
+                - name: Status name (e.g., 'open', 'in_progress', 'closed')
+                - type: Status type ('native' or 'extended')
+                - label: Associated label name (for extended statuses)
+                - description: Human-readable description
+                - category: Status category (open, in_progress, done, etc.)
+
+        Example:
+        -------
+            >>> statuses = await adapter.list_issue_statuses()
+            >>> for status in statuses:
+            ...     print(f"{status['name']}: {status['description']}")
+            ...     if status['type'] == 'extended':
+            ...         print(f"  Label: {status['label']}")
+
+        Note:
+        ----
+            GitHub natively supports only 'open' and 'closed' states.
+            Extended statuses are implemented via labels following the
+            status:* naming convention (e.g., status:in-progress).
+
+        """
+        # Define native GitHub states
+        statuses = [
+            {
+                "name": "open",
+                "type": "native",
+                "label": None,
+                "description": "Issue is open and not yet completed",
+                "category": "open",
+            },
+            {
+                "name": "closed",
+                "type": "native",
+                "label": None,
+                "description": "Issue is closed (completed or not planned)",
+                "category": "done",
+            },
+        ]
+
+        # Add extended label-based states
+        for state, label_name in GitHubStateMapping.STATE_LABELS.items():
+            statuses.append(
+                {
+                    "name": state.value,
+                    "type": "extended",
+                    "label": label_name,
+                    "description": f"Issue is {state.value.replace('_', ' ')} (tracked via label)",
+                    "category": state.value,
+                }
+            )
+
+        return statuses
+
+    async def list_project_labels(
+        self, milestone_number: int | None = None
+    ) -> builtins.list[dict[str, Any]]:
+        """List labels used in a GitHub milestone (project/epic).
+
+        If milestone_number is provided, returns only labels used by issues
+        in that milestone. Otherwise, returns all repository labels.
+
+        Args:
+        ----
+            milestone_number: Optional milestone number to filter labels.
+                            If None, returns all repository labels.
+
+        Returns:
+        -------
+            List of label dictionaries with fields:
+                - id: Label identifier (name)
+                - name: Label name
+                - color: Label color (hex without #)
+                - description: Label description (if available)
+                - usage_count: Number of issues using this label (if milestone filtered)
+
+        Example:
+        -------
+            >>> # Get all repository labels
+            >>> all_labels = await adapter.list_project_labels()
+            >>> print(f"Repository has {len(all_labels)} labels")
+            >>>
+            >>> # Get labels used in milestone 5
+            >>> milestone_labels = await adapter.list_project_labels(milestone_number=5)
+            >>> for label in milestone_labels:
+            ...     print(f"{label['name']}: used by {label['usage_count']} issues")
+
+        Note:
+        ----
+            Labels are repository-scoped in GitHub, not milestone-scoped.
+            When filtering by milestone, this method queries issues in that
+            milestone and extracts their unique labels.
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            if milestone_number is None:
+                # Return all repository labels (delegate to existing method)
+                return await self.list_labels()
+
+            # Query issues in the milestone
+            params = {
+                "milestone": str(milestone_number),
+                "state": "all",
+                "per_page": 100,
+            }
+
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/issues", params=params
+            )
+            response.raise_for_status()
+            issues = response.json()
+
+            # Extract unique labels from issues
+            label_usage = {}  # {label_name: {data, count}}
+            for issue in issues:
+                # Skip pull requests
+                if "pull_request" in issue:
+                    continue
+
+                for label in issue.get("labels", []):
+                    label_name = label["name"]
+                    if label_name not in label_usage:
+                        label_usage[label_name] = {
+                            "id": label_name,
+                            "name": label_name,
+                            "color": label["color"],
+                            "description": label.get("description", ""),
+                            "usage_count": 0,
+                        }
+                    label_usage[label_name]["usage_count"] += 1
+
+            # Convert to list and sort by usage count
+            labels = list(label_usage.values())
+            labels.sort(key=lambda x: x["usage_count"], reverse=True)
+
+            return labels
+
+        except httpx.HTTPError as e:
+            raise ValueError(f"Failed to list project labels: {e}") from e
+
     async def close(self) -> None:
         """Close the HTTP client connection."""
         await self.client.aclose()