"""GitHub adapter implementation using REST API v3 and GraphQL API v4."""

import builtins
import re
from datetime import datetime
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


class GitHubStateMapping:
    """GitHub issue states and label-based extended states."""

    # GitHub native states
    OPEN = "open"
    CLOSED = "closed"

    # Extended states via labels
    STATE_LABELS = {
        TicketState.IN_PROGRESS: "in-progress",
        TicketState.READY: "ready",
        TicketState.TESTED: "tested",
        TicketState.WAITING: "waiting",
        TicketState.BLOCKED: "blocked",
    }

    # Priority labels
    PRIORITY_LABELS = {
        Priority.CRITICAL: ["P0", "critical", "urgent"],
        Priority.HIGH: ["P1", "high"],
        Priority.MEDIUM: ["P2", "medium"],
        Priority.LOW: ["P3", "low"],
    }


class GitHubGraphQLQueries:
    """GraphQL queries for GitHub API v4."""

    ISSUE_FRAGMENT = """
        fragment IssueFields on Issue {
            id
            number
            title
            body
            state
            createdAt
            updatedAt
            url
            author {
                login
            }
            assignees(first: 10) {
                nodes {
                    login
                    email
                }
            }
            labels(first: 20) {
                nodes {
                    name
                    color
                }
            }
            milestone {
                id
                number
                title
                state
                description
            }
            projectCards(first: 10) {
                nodes {
                    project {
                        name
                        url
                    }
                    column {
                        name
                    }
                }
            }
            comments(first: 100) {
                nodes {
                    id
                    body
                    author {
                        login
                    }
                    createdAt
                }
            }
            reactions(first: 10) {
                nodes {
                    content
                    user {
                        login
                    }
                }
            }
        }
    """

    GET_ISSUE = """
        query GetIssue($owner: String!, $repo: String!, $number: Int!) {
            repository(owner: $owner, name: $repo) {
                issue(number: $number) {
                    ...IssueFields
                }
            }
        }
    """

    SEARCH_ISSUES = """
        query SearchIssues($query: String!, $first: Int!, $after: String) {
            search(query: $query, type: ISSUE, first: $first, after: $after) {
                issueCount
                pageInfo {
                    hasNextPage
                    endCursor
                }
                nodes {
                    ... on Issue {
                        ...IssueFields
                    }
                }
            }
        }
    """


class GitHubAdapter(BaseAdapter[Task]):
    """Adapter for GitHub Issues tracking system."""

    def __init__(self, config: dict[str, Any]):
        """Initialize GitHub adapter.

        Args:
            config: Configuration with:
                - 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
                - use_projects_v2: Enable Projects v2 (default: False)
                - custom_priority_scheme: Custom priority label mapping

        """
        super().__init__(config)

        # 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(
                f"GitHub adapter missing required configuration: {missing}"
            )

        # 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")
        )

        # 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")
        self.graphql_url = (
            f"{self.api_url}/graphql"
            if "github.com" in self.api_url
            else f"{self.api_url}/api/graphql"
        )

        # Configuration options
        self.use_projects_v2 = config.get("use_projects_v2", False)
        self.custom_priority_scheme = config.get("custom_priority_scheme", {})

        # HTTP client with authentication
        self.headers = {
            "Authorization": f"Bearer {self.token}",
            "Accept": "application/vnd.github.v3+json",
            "X-GitHub-Api-Version": "2022-11-28",
        }

        self.client = httpx.AsyncClient(
            base_url=self.api_url,
            headers=self.headers,
            timeout=30.0,
        )

        # Cache for labels and milestones
        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. Set it in .env.local or environment.",
            )
        if not self.owner:
            return (
                False,
                "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. Set GITHUB_REPO in .env.local "
                "or configure with 'mcp-ticketer init --adapter github "
                "--github-repo <repo>'",
            )
        return True, ""

    def _get_state_mapping(self) -> dict[TicketState, str]:
        """Map universal states to GitHub states."""
        return {
            TicketState.OPEN: GitHubStateMapping.OPEN,
            TicketState.IN_PROGRESS: GitHubStateMapping.OPEN,  # with label
            TicketState.READY: GitHubStateMapping.OPEN,  # with label
            TicketState.TESTED: GitHubStateMapping.OPEN,  # with label
            TicketState.DONE: GitHubStateMapping.CLOSED,
            TicketState.WAITING: GitHubStateMapping.OPEN,  # with label
            TicketState.BLOCKED: GitHubStateMapping.OPEN,  # with label
            TicketState.CLOSED: GitHubStateMapping.CLOSED,
        }

    def _get_state_label(self, state: TicketState) -> str | None:
        """Get the label name for extended states."""
        return GitHubStateMapping.STATE_LABELS.get(state)

    def _get_priority_from_labels(self, labels: list[str]) -> Priority:
        """Extract priority from issue labels."""
        label_names = [label.lower() for label in labels]

        # Check custom priority scheme first
        if self.custom_priority_scheme:
            for priority_str, label_patterns in self.custom_priority_scheme.items():
                for pattern in label_patterns:
                    if any(pattern.lower() in label for label in label_names):
                        return Priority(priority_str)

        # Check default priority labels
        for priority, priority_labels in GitHubStateMapping.PRIORITY_LABELS.items():
            for priority_label in priority_labels:
                if priority_label.lower() in label_names:
                    return priority

        return Priority.MEDIUM

    def _get_priority_label(self, priority: Priority) -> str:
        """Get label name for a priority level."""
        # Check custom scheme first
        if self.custom_priority_scheme:
            labels = self.custom_priority_scheme.get(priority.value, [])
            if labels:
                return labels[0]

        # Use default labels
        labels = GitHubStateMapping.PRIORITY_LABELS.get(priority, [])
        return (
            labels[0]
            if labels
            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
        if issue["state"] == "closed":
            return TicketState.CLOSED

        # Check labels for extended states
        labels = []
        if "labels" in issue:
            if isinstance(issue["labels"], list):
                labels = [
                    label.get("name", "") if isinstance(label, dict) else str(label)
                    for label in issue["labels"]
                ]
            elif isinstance(issue["labels"], dict) and "nodes" in issue["labels"]:
                labels = [label["name"] for label in issue["labels"]["nodes"]]

        label_names = [label.lower() for label in labels]

        # Check for extended state labels
        for state, label_name in GitHubStateMapping.STATE_LABELS.items():
            if label_name.lower() in label_names:
                return state

        return TicketState.OPEN

    def _task_from_github_issue(self, issue: dict[str, Any]) -> Task:
        """Convert GitHub issue to universal Task."""
        # Extract labels
        labels = []
        if "labels" in issue:
            if isinstance(issue["labels"], list):
                labels = [
                    label.get("name", "") if isinstance(label, dict) else str(label)
                    for label in issue["labels"]
                ]
            elif isinstance(issue["labels"], dict) and "nodes" in issue["labels"]:
                labels = [label["name"] for label in issue["labels"]["nodes"]]

        # Extract state
        state = self._extract_state_from_issue(issue)

        # Extract priority
        priority = self._get_priority_from_labels(labels)

        # Extract assignee
        assignee = None
        if "assignees" in issue:
            if isinstance(issue["assignees"], list) and issue["assignees"]:
                assignee = issue["assignees"][0].get("login")
            elif isinstance(issue["assignees"], dict) and "nodes" in issue["assignees"]:
                nodes = issue["assignees"]["nodes"]
                if nodes:
                    assignee = nodes[0].get("login")
        elif "assignee" in issue and issue["assignee"]:
            assignee = issue["assignee"].get("login")

        # Extract parent epic (milestone)
        parent_epic = None
        if issue.get("milestone"):
            parent_epic = str(issue["milestone"]["number"])

        # Parse dates
        created_at = None
        if issue.get("created_at"):
            created_at = datetime.fromisoformat(
                issue["created_at"].replace("Z", "+00:00")
            )
        elif issue.get("createdAt"):
            created_at = datetime.fromisoformat(
                issue["createdAt"].replace("Z", "+00:00")
            )

        updated_at = None
        if issue.get("updated_at"):
            updated_at = datetime.fromisoformat(
                issue["updated_at"].replace("Z", "+00:00")
            )
        elif issue.get("updatedAt"):
            updated_at = datetime.fromisoformat(
                issue["updatedAt"].replace("Z", "+00:00")
            )

        # Build metadata
        metadata = {
            "github": {
                "number": issue.get("number"),
                "url": issue.get("url") or issue.get("html_url"),
                "author": (
                    issue.get("user", {}).get("login")
                    if "user" in issue
                    else issue.get("author", {}).get("login")
                ),
                "labels": labels,
            }
        }

        # Add projects v2 info if available
        if "projectCards" in issue and issue["projectCards"].get("nodes"):
            metadata["github"]["projects"] = [
                {
                    "name": card["project"]["name"],
                    "column": card["column"]["name"],
                    "url": card["project"]["url"],
                }
                for card in issue["projectCards"]["nodes"]
            ]

        return Task(
            id=str(issue["number"]),
            title=issue["title"],
            description=issue.get("body") or issue.get("bodyText"),
            state=state,
            priority=priority,
            tags=labels,
            parent_epic=parent_epic,
            assignee=assignee,
            created_at=created_at,
            updated_at=updated_at,
            metadata=metadata,
        )

    async def _ensure_label_exists(
        self, label_name: str, color: str = "0366d6"
    ) -> None:
        """Ensure a label exists in the repository."""
        if not self._labels_cache:
            response = await self.client.get(f"/repos/{self.owner}/{self.repo}/labels")
            response.raise_for_status()
            self._labels_cache = response.json()

        # Check if label exists
        existing_labels = [label["name"].lower() for label in self._labels_cache]
        if label_name.lower() not in existing_labels:
            # Create the label
            response = await self.client.post(
                f"/repos/{self.owner}/{self.repo}/labels",
                json={"name": label_name, "color": color},
            )
            if response.status_code == 201:
                self._labels_cache.append(response.json())

    async def _graphql_request(
        self, query: str, variables: dict[str, Any]
    ) -> dict[str, Any]:
        """Execute a GraphQL query."""
        response = await self.client.post(
            self.graphql_url, json={"query": query, "variables": variables}
        )
        response.raise_for_status()

        data = response.json()
        if "errors" in data:
            raise ValueError(f"GraphQL errors: {data['errors']}")

        return data["data"]

    async def create(self, ticket: Task) -> Task:
        """Create a new GitHub issue."""
        # Validate credentials before attempting operation
        is_valid, error_message = self.validate_credentials()
        if not is_valid:
            raise ValueError(error_message)

        # Prepare labels
        labels = ticket.tags.copy() if ticket.tags else []

        # Add state label if needed
        state_label = self._get_state_label(ticket.state)
        if state_label:
            labels.append(state_label)
            await self._ensure_label_exists(state_label, "fbca04")

        # Add priority label
        priority_label = self._get_priority_label(ticket.priority)
        labels.append(priority_label)
        await self._ensure_label_exists(priority_label, "d73a4a")

        # Ensure all labels exist
        for label in labels:
            await self._ensure_label_exists(label)

        # Build issue data
        issue_data = {
            "title": ticket.title,
            "body": ticket.description or "",
            "labels": labels,
        }

        # Add assignee if specified
        if ticket.assignee:
            issue_data["assignees"] = [ticket.assignee]

        # Add milestone if parent_epic is specified
        if ticket.parent_epic:
            try:
                milestone_number = int(ticket.parent_epic)
                issue_data["milestone"] = milestone_number
            except ValueError:
                # Try to find milestone by title
                if not self._milestones_cache:
                    response = await self.client.get(
                        f"/repos/{self.owner}/{self.repo}/milestones"
                    )
                    response.raise_for_status()
                    self._milestones_cache = response.json()

                for milestone in self._milestones_cache:
                    if milestone["title"] == ticket.parent_epic:
                        issue_data["milestone"] = milestone["number"]
                        break

        # Create the issue
        response = await self.client.post(
            f"/repos/{self.owner}/{self.repo}/issues", json=issue_data
        )
        response.raise_for_status()

        created_issue = response.json()

        # If state requires closing, close the issue
        if ticket.state in [TicketState.DONE, TicketState.CLOSED]:
            await self.client.patch(
                f"/repos/{self.owner}/{self.repo}/issues/{created_issue['number']}",
                json={"state": "closed"},
            )
            created_issue["state"] = "closed"

        return self._task_from_github_issue(created_issue)

    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()
        if not is_valid:
            raise ValueError(error_message)

        try:
            issue_number = int(ticket_id)
        except ValueError:
            return None

        try:
            response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/issues/{issue_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]) -> Task | None:
        """Update a GitHub 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)
        except ValueError:
            return None

        # Get current issue to preserve labels
        response = await self.client.get(
            f"/repos/{self.owner}/{self.repo}/issues/{issue_number}"
        )
        if response.status_code == 404:
            return None
        response.raise_for_status()

        current_issue = response.json()
        current_labels = [label["name"] for label in current_issue.get("labels", [])]

        # Build update data
        update_data = {}

        if "title" in updates:
            update_data["title"] = updates["title"]

        if "description" in updates:
            update_data["body"] = updates["description"]

        # Handle state updates
        if "state" in updates:
            new_state = updates["state"]
            if isinstance(new_state, str):
                new_state = TicketState(new_state)

            # Remove old state labels
            labels_to_update = [
                label
                for label in current_labels
                if label.lower()
                not in [sl.lower() for sl in GitHubStateMapping.STATE_LABELS.values()]
            ]

            # Add new state label if needed
            state_label = self._get_state_label(new_state)
            if state_label:
                await self._ensure_label_exists(state_label, "fbca04")
                labels_to_update.append(state_label)

            update_data["labels"] = labels_to_update

            # Update issue state if needed
            if new_state in [TicketState.DONE, TicketState.CLOSED]:
                update_data["state"] = "closed"
            else:
                update_data["state"] = "open"

        # Handle priority updates
        if "priority" in updates:
            new_priority = updates["priority"]
            if isinstance(new_priority, str):
                new_priority = Priority(new_priority)

            # Remove old priority labels
            labels_to_update = update_data.get("labels", current_labels)
            all_priority_labels = []
            for labels in GitHubStateMapping.PRIORITY_LABELS.values():
                all_priority_labels.extend([label.lower() for label in labels])

            labels_to_update = [
                label
                for label in labels_to_update
                if label.lower() not in all_priority_labels
                and not re.match(r"^P[0-3]$", label, re.IGNORECASE)
            ]

            # Add new priority label
            priority_label = self._get_priority_label(new_priority)
            await self._ensure_label_exists(priority_label, "d73a4a")
            labels_to_update.append(priority_label)

            update_data["labels"] = labels_to_update

        # Handle assignee updates
        if "assignee" in updates:
            if updates["assignee"]:
                update_data["assignees"] = [updates["assignee"]]
            else:
                update_data["assignees"] = []

        # Handle tags updates
        if "tags" in updates:
            # Preserve state and priority labels
            preserved_labels = []
            for label in current_labels:
                if label.lower() in [
                    sl.lower() for sl in GitHubStateMapping.STATE_LABELS.values()
                ]:
                    preserved_labels.append(label)
                elif any(
                    label.lower() in [pl.lower() for pl in labels]
                    for labels in GitHubStateMapping.PRIORITY_LABELS.values()
                ):
                    preserved_labels.append(label)
                elif re.match(r"^P[0-3]$", label, re.IGNORECASE):
                    preserved_labels.append(label)

            # Add new tags
            for tag in updates["tags"]:
                await self._ensure_label_exists(tag)

            update_data["labels"] = preserved_labels + updates["tags"]

        # Apply updates
        if update_data:
            response = await self.client.patch(
                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}",
                json=update_data,
            )
            response.raise_for_status()

            updated_issue = response.json()
            return self._task_from_github_issue(updated_issue)

        return await self.read(ticket_id)

    async def delete(self, ticket_id: str) -> bool:
        """Delete (close) a GitHub 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)
        except ValueError:
            return False

        try:
            response = await self.client.patch(
                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}",
                json={"state": "closed", "state_reason": "not_planned"},
            )
            response.raise_for_status()
            return True
        except httpx.HTTPError:
            return False

    async def list(
        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
    ) -> list[Task]:
        """List GitHub issues with filters."""
        # Build query parameters
        params: dict[str, Any] = {
            "per_page": min(limit, 100),  # GitHub max is 100
            "page": (offset // limit) + 1 if limit > 0 else 1,
        }

        if filters:
            # State filter
            if "state" in filters:
                state = filters["state"]
                if isinstance(state, str):
                    state = TicketState(state)

                if state in [TicketState.DONE, TicketState.CLOSED]:
                    params["state"] = "closed"
                else:
                    params["state"] = "open"
                    # Add label filter for extended states
                    state_label = self._get_state_label(state)
                    if state_label:
                        params["labels"] = state_label

            # Priority filter via labels
            if "priority" in filters:
                priority = filters["priority"]
                if isinstance(priority, str):
                    priority = Priority(priority)
                priority_label = self._get_priority_label(priority)

                if "labels" in params:
                    params["labels"] += f",{priority_label}"
                else:
                    params["labels"] = priority_label

            # Assignee filter
            if "assignee" in filters:
                params["assignee"] = filters["assignee"]

            # Milestone filter (parent_epic)
            if "parent_epic" in filters:
                params["milestone"] = filters["parent_epic"]

        response = await self.client.get(
            f"/repos/{self.owner}/{self.repo}/issues", params=params
        )
        response.raise_for_status()

        issues = response.json()

        # Store rate limit info
        self._rate_limit = {
            "limit": response.headers.get("X-RateLimit-Limit"),
            "remaining": response.headers.get("X-RateLimit-Remaining"),
            "reset": response.headers.get("X-RateLimit-Reset"),
        }

        # Filter out pull requests (they appear as issues in the API)
        issues = [issue for issue in issues if "pull_request" not in issue]

        return [self._task_from_github_issue(issue) for issue in issues]

    async def search(self, query: SearchQuery) -> builtins.list[Task]:
        """Search GitHub issues using advanced search syntax."""
        # Build GitHub search query
        search_parts = [f"repo:{self.owner}/{self.repo}", "is:issue"]

        # Text search
        if query.query:
            # Escape special characters for GitHub search
            escaped_query = query.query.replace('"', '\\"')
            search_parts.append(f'"{escaped_query}"')

        # State filter
        if query.state:
            if query.state in [TicketState.DONE, TicketState.CLOSED]:
                search_parts.append("is:closed")
            else:
                search_parts.append("is:open")
                # Add label filter for extended states
                state_label = self._get_state_label(query.state)
                if state_label:
                    search_parts.append(f'label:"{state_label}"')

        # Priority filter
        if query.priority:
            priority_label = self._get_priority_label(query.priority)
            search_parts.append(f'label:"{priority_label}"')

        # Assignee filter
        if query.assignee:
            search_parts.append(f"assignee:{query.assignee}")

        # Tags filter
        if query.tags:
            for tag in query.tags:
                search_parts.append(f'label:"{tag}"')

        # Build final search query
        github_query = " ".join(search_parts)

        # Use GraphQL for better search capabilities
        full_query = (
            GitHubGraphQLQueries.ISSUE_FRAGMENT + GitHubGraphQLQueries.SEARCH_ISSUES
        )

        variables = {
            "query": github_query,
            "first": min(query.limit, 100),
            "after": None,
        }

        # Handle pagination for offset
        if query.offset > 0:
            # We need to paginate through to get to the offset
            # This is inefficient but GitHub doesn't support direct offset
            pages_to_skip = query.offset // 100
            for _ in range(pages_to_skip):
                temp_result = await self._graphql_request(full_query, variables)
                page_info = temp_result["search"]["pageInfo"]
                if page_info["hasNextPage"]:
                    variables["after"] = page_info["endCursor"]
                else:
                    return []  # Offset beyond available results

        result = await self._graphql_request(full_query, variables)

        issues = []
        for node in result["search"]["nodes"]:
            if node:  # Some nodes might be null
                # Convert GraphQL format to REST format for consistency
                rest_format = {
                    "number": node["number"],
                    "title": node["title"],
                    "body": node["body"],
                    "state": node["state"].lower(),
                    "created_at": node["createdAt"],
                    "updated_at": node["updatedAt"],
                    "html_url": node["url"],
                    "labels": node.get("labels", {}).get("nodes", []),
                    "milestone": node.get("milestone"),
                    "assignees": node.get("assignees", {}).get("nodes", []),
                    "author": node.get("author"),
                }
                issues.append(self._task_from_github_issue(rest_format))

        return issues

    async def transition_state(
        self, ticket_id: str, target_state: TicketState
    ) -> Task | None:
        """Transition GitHub issue to a new state."""
        # Validate transition
        if not await self.validate_transition(ticket_id, target_state):
            return None

        # Update state
        return await self.update(ticket_id, {"state": target_state})

    async def add_comment(self, comment: Comment) -> Comment:
        """Add a comment to a GitHub issue."""
        try:
            issue_number = int(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(
            f"/repos/{self.owner}/{self.repo}/issues/{issue_number}/comments",
            json={"body": comment.content},
        )
        response.raise_for_status()

        created_comment = response.json()

        return Comment(
            id=str(created_comment["id"]),
            ticket_id=comment.ticket_id,
            author=created_comment["user"]["login"],
            content=created_comment["body"],
            created_at=datetime.fromisoformat(
                created_comment["created_at"].replace("Z", "+00:00")
            ),
            metadata={
                "github": {
                    "id": created_comment["id"],
                    "url": created_comment["html_url"],
                    "author_avatar": created_comment["user"]["avatar_url"],
                }
            },
        )

    async def get_comments(
        self, ticket_id: str, limit: int = 10, offset: int = 0
    ) -> builtins.list[Comment]:
        """Get comments for a GitHub issue."""
        try:
            issue_number = int(ticket_id)
        except ValueError:
            return []

        params = {
            "per_page": min(limit, 100),
            "page": (offset // limit) + 1 if limit > 0 else 1,
        }

        try:
            response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}/comments",
                params=params,
            )
            response.raise_for_status()

            comments = []
            for comment_data in response.json():
                comments.append(
                    Comment(
                        id=str(comment_data["id"]),
                        ticket_id=ticket_id,
                        author=comment_data["user"]["login"],
                        content=comment_data["body"],
                        created_at=datetime.fromisoformat(
                            comment_data["created_at"].replace("Z", "+00:00")
                        ),
                        metadata={
                            "github": {
                                "id": comment_data["id"],
                                "url": comment_data["html_url"],
                                "author_avatar": comment_data["user"]["avatar_url"],
                            }
                        },
                    )
                )

            return comments
        except httpx.HTTPError:
            return []

    async def get_rate_limit(self) -> dict[str, Any]:
        """Get current rate limit status."""
        response = await self.client.get("/rate_limit")
        response.raise_for_status()
        return response.json()

    async def create_milestone(self, epic: Epic) -> Epic:
        """Create a GitHub milestone as an Epic."""
        milestone_data = {
            "title": epic.title,
            "description": epic.description or "",
            "state": "open" if epic.state != TicketState.CLOSED else "closed",
        }

        response = await self.client.post(
            f"/repos/{self.owner}/{self.repo}/milestones", json=milestone_data
        )
        response.raise_for_status()

        created_milestone = response.json()
        return self._milestone_to_epic(created_milestone)

    async def get_milestone(self, milestone_number: int) -> Epic | None:
        """Get a GitHub milestone as an Epic."""
        try:
            response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_number}"
            )
            if response.status_code == 404:
                return None
            response.raise_for_status()

            milestone = response.json()
            return self._milestone_to_epic(milestone)
        except httpx.HTTPError:
            return None

    async def list_milestones(
        self, state: str = "open", limit: int = 10, offset: int = 0
    ) -> builtins.list[Epic]:
        """List GitHub milestones as Epics."""
        params = {
            "state": state,
            "per_page": min(limit, 100),
            "page": (offset // limit) + 1 if limit > 0 else 1,
        }

        response = await self.client.get(
            f"/repos/{self.owner}/{self.repo}/milestones", params=params
        )
        response.raise_for_status()

        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."""
        # This is typically done through PR description keywords like "fixes #123"
        # We can add a comment to track the link
        comment = f"Linked to PR #{pr_number}"

        response = await self.client.post(
            f"/repos/{self.owner}/{self.repo}/issues/{issue_number}/comments",
            json={"body": comment},
        )

        return response.status_code == 201

    async def create_pull_request(
        self,
        ticket_id: str,
        base_branch: str = "main",
        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)
            title: PR title (uses ticket title if not provided)
            body: PR description (auto-generated with issue link if not provided)
            draft: Create as draft PR

        Returns:
            Dictionary with PR details including number, url, and branch

        """
        try:
            issue_number = int(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)
        if not issue:
            raise ValueError(f"Issue #{ticket_id} not found")

        # Auto-generate branch name if not provided
        if not head_branch:
            # Create branch name from issue number and title
            # e.g., "123-fix-authentication-bug"
            safe_title = "-".join(
                issue.title.lower()
                .replace("[", "")
                .replace("]", "")
                .replace("#", "")
                .replace("/", "-")
                .replace("\\", "-")
                .split()[:5]  # Limit to 5 words
            )
            head_branch = f"{issue_number}-{safe_title}"

        # Auto-generate title if not provided
        if not title:
            # Include issue number in PR title
            title = f"[#{issue_number}] {issue.title}"

        # Auto-generate body if not provided
        if not body:
            body = f"""## Summary

This PR addresses issue #{issue_number}.

**Issue:** #{issue_number} - {issue.title}
**Link:** {issue.metadata.get('github', {}).get('url', '')}

## Description

{issue.description or 'No description provided.'}

## Changes

- [ ] Implementation details to be added

## Testing

- [ ] Tests have been added/updated
- [ ] All tests pass

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated if needed

Fixes #{issue_number}
"""

        # Check if the head branch exists
        try:
            branch_response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/branches/{head_branch}"
            )
            branch_exists = branch_response.status_code == 200
        except httpx.HTTPError:
            branch_exists = False

        if not branch_exists:
            # Get the base branch SHA
            base_response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/branches/{base_branch}"
            )
            base_response.raise_for_status()
            base_sha = base_response.json()["commit"]["sha"]

            # Create the new branch
            ref_response = await self.client.post(
                f"/repos/{self.owner}/{self.repo}/git/refs",
                json={
                    "ref": f"refs/heads/{head_branch}",
                    "sha": base_sha,
                },
            )

            if ref_response.status_code != 201:
                # Branch might already exist on remote, try to use it
                pass

        # Create the pull request
        pr_data = {
            "title": title,
            "body": body,
            "head": head_branch,
            "base": base_branch,
            "draft": draft,
        }

        pr_response = await self.client.post(
            f"/repos/{self.owner}/{self.repo}/pulls", json=pr_data
        )

        if pr_response.status_code == 422:
            # PR might already exist, try to get it
            search_response = await self.client.get(
                f"/repos/{self.owner}/{self.repo}/pulls",
                params={
                    "head": f"{self.owner}:{head_branch}",
                    "base": base_branch,
                    "state": "open",
                },
            )

            if search_response.status_code == 200:
                existing_prs = search_response.json()
                if existing_prs:
                    pr = existing_prs[0]
                    return {
                        "number": pr["number"],
                        "url": pr["html_url"],
                        "api_url": pr["url"],
                        "branch": head_branch,
                        "state": pr["state"],
                        "draft": pr.get("draft", False),
                        "title": pr["title"],
                        "existing": True,
                        "linked_issue": issue_number,
                    }

            raise ValueError(f"Failed to create PR: {pr_response.text}")

        pr_response.raise_for_status()
        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=pr_msg,
                author="system",
            )
        )

        return {
            "number": pr["number"],
            "url": pr["html_url"],
            "api_url": pr["url"],
            "branch": head_branch,
            "state": pr["state"],
            "draft": pr.get("draft", False),
            "title": pr["title"],
            "linked_issue": issue_number,
        }

    async def link_existing_pull_request(
        self,
        ticket_id: str,
        pr_url: str,
    ) -> dict[str, Any]:
        """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 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
        import re

        pr_pattern = r"github\.com/([^/]+)/([^/]+)/pull/(\d+)"
        match = re.search(pr_pattern, pr_url)

        if not match:
            raise ValueError(f"Invalid GitHub PR URL format: {pr_url}")

        pr_owner, pr_repo, pr_number = match.groups()

        # Verify the PR is from the same repository
        if pr_owner != self.owner or pr_repo != self.repo:
            raise ValueError(
                f"PR must be from the same repository ({self.owner}/{self.repo})"
            )

        # Get PR details
        pr_response = await self.client.get(
            f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}"
        )

        if pr_response.status_code == 404:
            raise ValueError(f"Pull request #{pr_number} not found")

        pr_response.raise_for_status()
        pr = pr_response.json()

        # Update PR body to include issue reference if not already present
        current_body = pr.get("body", "")
        issue_ref = f"#{issue_number}"

        if issue_ref not in current_body:
            # Add issue reference to the body
            updated_body = current_body or ""
            if updated_body:
                updated_body += "\n\n"
            updated_body += f"Related to #{issue_number}"

            # Update the PR
            update_response = await self.client.patch(
                f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}",
                json={"body": updated_body},
            )
            update_response.raise_for_status()

        # Add a comment to the issue about the PR
        await self.add_comment(
            Comment(
                ticket_id=ticket_id,
                content=f"Linked to pull request #{pr_number}: {pr_url}",
                author="system",
            )
        )

        return {
            "success": True,
            "pr_number": pr["number"],
            "pr_url": pr["html_url"],
            "pr_title": pr["title"],
            "pr_state": pr["state"],
            "linked_issue": 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 close(self) -> None:
        """Close the HTTP client connection."""
        await self.client.aclose()


# Register the adapter
AdapterRegistry.register("github", GitHubAdapter)
