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

mcp_ticketer/adapters/linear/client.py

@@ -7,7 +7,7 @@ from typing import Any
 
 try:
     from gql import Client, gql
-    from gql.transport.exceptions import TransportError
+    from gql.transport.exceptions import TransportError, TransportQueryError
     from gql.transport.httpx import HTTPXAsyncTransport
 except ImportError:
     # Handle missing gql dependency gracefully
@@ -15,6 +15,7 @@ except ImportError:
     gql = None
     HTTPXAsyncTransport = None
     TransportError = Exception
+    TransportQueryError = Exception
 
 from ...core.exceptions import AdapterError, AuthenticationError, RateLimitError
 
@@ -26,6 +27,7 @@ class LinearGraphQLClient:
         """Initialize the Linear GraphQL client.
 
         Args:
+        ----
             api_key: Linear API key
             timeout: Request timeout in seconds
 
@@ -38,9 +40,11 @@ class LinearGraphQLClient:
         """Create a new GraphQL client instance.
 
         Returns:
+        -------
             Configured GraphQL client
 
         Raises:
+        ------
             AuthenticationError: If API key is invalid
             AdapterError: If client creation fails
 
@@ -69,7 +73,7 @@ class LinearGraphQLClient:
             return client
 
         except Exception as e:
-            raise AdapterError(f"Failed to create Linear client: {e}", "linear")
+            raise AdapterError(f"Failed to create Linear client: {e}", "linear") from e
 
     async def execute_query(
         self,
@@ -80,14 +84,17 @@ class LinearGraphQLClient:
         """Execute a GraphQL query with error handling and retries.
 
         Args:
+        ----
             query_string: GraphQL query string
             variables: Query variables
             retries: Number of retry attempts
 
         Returns:
+        -------
             Query result data
 
         Raises:
+        ------
             AuthenticationError: If authentication fails
             RateLimitError: If rate limit is exceeded
             AdapterError: If query execution fails
@@ -104,21 +111,52 @@ class LinearGraphQLClient:
                     )
                 return result
 
+            except TransportQueryError as e:
+                """
+                Handle GraphQL validation errors (e.g., duplicate label names).
+                TransportQueryError is a subclass of TransportError with .errors attribute.
+
+                Related: 1M-398 - Label duplicate error handling
+                """
+                if e.errors:
+                    error_msg = e.errors[0].get("message", "Unknown GraphQL error")
+
+                    # Check for duplicate label errors specifically
+                    if (
+                        "duplicate" in error_msg.lower()
+                        and "label" in error_msg.lower()
+                    ):
+                        raise AdapterError(
+                            f"Label already exists: {error_msg}", "linear"
+                        ) from e
+
+                    # Other validation errors
+                    raise AdapterError(
+                        f"Linear GraphQL validation error: {error_msg}", "linear"
+                    ) from e
+
+                # Fallback if no errors attribute
+                raise AdapterError(f"Linear GraphQL error: {e}", "linear") from e
+
             except TransportError as e:
                 # Handle HTTP errors
                 if hasattr(e, "response") and e.response:
                     status_code = e.response.status
 
                     if status_code == 401:
-                        raise AuthenticationError("Invalid Linear API key", "linear")
+                        raise AuthenticationError(
+                            "Invalid Linear API key", "linear"
+                        ) from e
                     elif status_code == 403:
-                        raise AuthenticationError("Insufficient permissions", "linear")
+                        raise AuthenticationError(
+                            "Insufficient permissions", "linear"
+                        ) from e
                     elif status_code == 429:
                         # Rate limit exceeded
                         retry_after = e.response.headers.get("Retry-After", "60")
                         raise RateLimitError(
                             "Linear API rate limit exceeded", "linear", retry_after
-                        )
+                        ) from e
                     elif status_code >= 500:
                         # Server error - retry
                         if attempt < retries:
@@ -126,13 +164,13 @@ class LinearGraphQLClient:
                             continue
                         raise AdapterError(
                             f"Linear API server error: {status_code}", "linear"
-                        )
+                        ) from e
 
                 # Network or other transport error
                 if attempt < retries:
                     await asyncio.sleep(2**attempt)
                     continue
-                raise AdapterError(f"Linear API transport error: {e}", "linear")
+                raise AdapterError(f"Linear API transport error: {e}", "linear") from e
 
             except Exception as e:
                 # GraphQL or other errors
@@ -145,15 +183,19 @@ class LinearGraphQLClient:
                 ):
                     raise AuthenticationError(
                         f"Linear authentication failed: {error_msg}", "linear"
-                    )
+                    ) from e
                 elif "rate limit" in error_msg.lower():
-                    raise RateLimitError("Linear API rate limit exceeded", "linear")
+                    raise RateLimitError(
+                        "Linear API rate limit exceeded", "linear"
+                    ) from e
 
                 # Generic error
                 if attempt < retries:
                     await asyncio.sleep(2**attempt)
                     continue
-                raise AdapterError(f"Linear GraphQL error: {error_msg}", "linear")
+                raise AdapterError(
+                    f"Linear GraphQL error: {error_msg}", "linear"
+                ) from e
 
         # Should never reach here
         raise AdapterError("Maximum retries exceeded", "linear")
@@ -167,14 +209,17 @@ class LinearGraphQLClient:
         """Execute a GraphQL mutation with error handling.
 
         Args:
+        ----
             mutation_string: GraphQL mutation string
             variables: Mutation variables
             retries: Number of retry attempts
 
         Returns:
+        -------
             Mutation result data
 
         Raises:
+        ------
             AuthenticationError: If authentication fails
             RateLimitError: If rate limit is exceeded
             AdapterError: If mutation execution fails
@@ -186,9 +231,20 @@ class LinearGraphQLClient:
         """Test the connection to Linear API.
 
         Returns:
+        -------
             True if connection is successful, False otherwise
 
+        Design Decision: Enhanced Debug Logging (1M-431)
+        -------------------------------------------------
+        Added comprehensive logging to diagnose connection failures.
+        Logs API key preview, query results, and specific failure reasons
+        to help users troubleshoot authentication and configuration issues.
+
         """
+        import logging
+
+        logger = logging.getLogger(__name__)
+
         try:
             # Simple query to test authentication
             test_query = """
@@ -196,23 +252,53 @@ class LinearGraphQLClient:
                     viewer {
                         id
                         name
+                        email
                     }
                 }
             """
 
+            logger.debug(
+                f"Testing Linear API connection with API key: {self.api_key[:20]}..."
+            )
             result = await self.execute_query(test_query)
-            return bool(result.get("viewer"))
 
-        except Exception:
+            # Log the actual response for debugging
+            logger.debug(f"Linear API test response: {result}")
+
+            viewer = result.get("viewer")
+
+            if not viewer:
+                logger.warning(
+                    f"Linear test connection query succeeded but returned no viewer data. "
+                    f"Response: {result}"
+                )
+                return False
+
+            if not viewer.get("id"):
+                logger.warning(f"Linear viewer missing id field. Viewer data: {viewer}")
+                return False
+
+            logger.info(
+                f"Linear API connected successfully as: {viewer.get('name')} ({viewer.get('email')})"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(
+                f"Linear connection test failed: {type(e).__name__}: {e}",
+                exc_info=True,
+            )
             return False
 
     async def get_team_info(self, team_id: str) -> dict[str, Any] | None:
         """Get team information by ID.
 
         Args:
+        ----
             team_id: Linear team ID
 
         Returns:
+        -------
             Team information or None if not found
 
         """
@@ -238,9 +324,11 @@ class LinearGraphQLClient:
         """Get user information by email.
 
         Args:
+        ----
             email: User email address
 
         Returns:
+        -------
             User information or None if not found
 
         """
@@ -266,6 +354,52 @@ class LinearGraphQLClient:
         except Exception:
             return None
 
+    async def get_users_by_name(self, name: str) -> list[dict[str, Any]]:
+        """Search users by display name or full name.
+
+        Args:
+        ----
+            name: Display name or full name to search for
+
+        Returns:
+        -------
+            List of matching users (may be empty)
+
+        """
+        import logging
+
+        try:
+            query = """
+                query SearchUsers($nameFilter: String!) {
+                    users(
+                        filter: {
+                            or: [
+                                { displayName: { containsIgnoreCase: $nameFilter } }
+                                { name: { containsIgnoreCase: $nameFilter } }
+                            ]
+                        }
+                        first: 10
+                    ) {
+                        nodes {
+                            id
+                            name
+                            email
+                            displayName
+                            avatarUrl
+                            active
+                        }
+                    }
+                }
+            """
+
+            result = await self.execute_query(query, {"nameFilter": name})
+            users = result.get("users", {}).get("nodes", [])
+            return [u for u in users if u.get("active", True)]  # Filter active users
+
+        except Exception as e:
+            logging.getLogger(__name__).warning(f"Failed to search users by name: {e}")
+            return []
+
     async def close(self) -> None:
         """Close the client connection.
 

mcp_ticketer/adapters/linear/mappers.py

@@ -5,17 +5,22 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Any
 
-from ...core.models import Comment, Epic, Priority, Task, TicketState
+from ...core.models import Attachment, Comment, Epic, Priority, Task, TicketState
 from .types import extract_linear_metadata, get_universal_priority, get_universal_state
 
 
 def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
-    """Convert Linear issue data to universal Task model.
+    """Convert Linear issue or sub-issue data to universal Task model.
+
+    Handles both top-level issues (no parent) and sub-issues (child items
+    with a parent issue).
 
     Args:
+    ----
         issue_data: Raw Linear issue data from GraphQL
 
     Returns:
+    -------
         Universal Task model
 
     """
@@ -28,10 +33,11 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
     linear_priority = issue_data.get("priority", 3)
     priority = get_universal_priority(linear_priority)
 
-    # Map state
+    # Map state with synonym matching (1M-164)
     state_data = issue_data.get("state", {})
     state_type = state_data.get("type", "unstarted")
-    state = get_universal_state(state_type)
+    state_name = state_data.get("name")  # Extract state name for synonym matching
+    state = get_universal_state(state_type, state_name)
 
     # Extract assignee
     assignee = None
@@ -73,6 +79,9 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
             issue_data["updatedAt"].replace("Z", "+00:00")
         )
 
+    # Extract child issue IDs
+    children = extract_child_issue_ids(issue_data)
+
     # Extract Linear-specific metadata
     linear_metadata = extract_linear_metadata(issue_data)
     metadata = {"linear": linear_metadata} if linear_metadata else {}
@@ -88,6 +97,7 @@ def map_linear_issue_to_task(issue_data: dict[str, Any]) -> Task:
         tags=tags,
         parent_epic=parent_epic,
         parent_issue=parent_issue,
+        children=children,
         created_at=created_at,
         updated_at=updated_at,
         metadata=metadata,
@@ -98,9 +108,11 @@ def map_linear_project_to_epic(project_data: dict[str, Any]) -> Epic:
     """Convert Linear project data to universal Epic model.
 
     Args:
+    ----
         project_data: Raw Linear project data from GraphQL
 
     Returns:
+    -------
         Universal Epic model
 
     """
@@ -134,7 +146,7 @@ def map_linear_project_to_epic(project_data: dict[str, Any]) -> Epic:
         )
 
     # Extract Linear-specific metadata
-    metadata = {"linear": {}}
+    metadata: dict[str, Any] = {"linear": {}}
     if project_data.get("url"):
         metadata["linear"]["linear_url"] = project_data["url"]
     if project_data.get("icon"):
@@ -162,10 +174,12 @@ def map_linear_comment_to_comment(
     """Convert Linear comment data to universal Comment model.
 
     Args:
+    ----
         comment_data: Raw Linear comment data from GraphQL
         ticket_id: ID of the ticket this comment belongs to
 
     Returns:
+    -------
         Universal Comment model
 
     """
@@ -203,19 +217,24 @@ def map_linear_comment_to_comment(
 
 
 def build_linear_issue_input(task: Task, team_id: str) -> dict[str, Any]:
-    """Build Linear issue input from universal Task model.
+    """Build Linear issue or sub-issue input from universal Task model.
+
+    Creates input for a top-level issue when task.parent_issue is not set,
+    or for a sub-issue when task.parent_issue is provided.
 
     Args:
+    ----
         task: Universal Task model
         team_id: Linear team ID
 
     Returns:
+    -------
         Linear issue input dictionary
 
     """
     from .types import get_linear_priority
 
-    issue_input = {
+    issue_input: dict[str, Any] = {
         "title": task.title,
         "teamId": team_id,
     }
@@ -240,10 +259,19 @@ def build_linear_issue_input(task: Task, team_id: str) -> dict[str, Any]:
     if task.parent_epic:
         issue_input["projectId"] = task.parent_epic
 
-    # Add labels (tags) if provided
-    if task.tags:
-        # Note: This returns label names, will be resolved to IDs by adapter
-        issue_input["labelIds"] = task.tags  # Temporary - adapter will resolve
+    # DO NOT set labelIds here - adapter will handle label resolution
+    # Labels are resolved from names to UUIDs in LinearAdapter._create_task()
+    # If we set it here, we create a type mismatch (names vs UUIDs)
+    # The adapter's label resolution logic (lines 982-988) handles this properly
+    #
+    # Bug Fix (v1.1.1): Previously, setting labelIds to tag names here caused
+    # "Argument Validation Error" from Linear's GraphQL API. The API requires
+    # UUIDs (e.g., "uuid-1"), not names (e.g., "bug"). This was fixed by:
+    # 1. Removing labelIds assignment in mapper (this file)
+    # 2. Adding UUID validation in adapter._create_task() (adapter.py:1047-1060)
+    # 3. Changing GraphQL labelIds type to [String!]! (queries.py)
+    #
+    # See: docs/TROUBLESHOOTING.md#issue-argument-validation-error-when-creating-issues-with-labels
 
     # Add Linear-specific metadata
     if task.metadata and "linear" in task.metadata:
@@ -262,9 +290,11 @@ def build_linear_issue_update_input(updates: dict[str, Any]) -> dict[str, Any]:
     """Build Linear issue update input from update dictionary.
 
     Args:
+    ----
         updates: Dictionary of fields to update
 
     Returns:
+    -------
         Linear issue update input dictionary
 
     """
@@ -314,9 +344,11 @@ def extract_child_issue_ids(issue_data: dict[str, Any]) -> list[str]:
     """Extract child issue IDs from Linear issue data.
 
     Args:
+    ----
         issue_data: Raw Linear issue data from GraphQL
 
     Returns:
+    -------
         List of child issue identifiers
 
     """
@@ -324,3 +356,65 @@ def extract_child_issue_ids(issue_data: dict[str, Any]) -> list[str]:
     if issue_data.get("children", {}).get("nodes"):
         child_ids = [child["identifier"] for child in issue_data["children"]["nodes"]]
     return child_ids
+
+
+def map_linear_attachment_to_attachment(
+    attachment_data: dict[str, Any], ticket_id: str
+) -> Attachment:
+    """Convert Linear attachment data to universal Attachment model.
+
+    Args:
+    ----
+        attachment_data: Raw Linear attachment data from GraphQL
+        ticket_id: ID of the ticket this attachment belongs to
+
+    Returns:
+    -------
+        Universal Attachment model
+
+    Note:
+    ----
+        Linear attachment URLs require authentication with API key.
+        URLs are in format: https://files.linear.app/workspace/attachment-id/filename
+        Authentication header: Authorization: Bearer {api_key}
+
+    """
+    # Extract basic fields
+    attachment_id = attachment_data.get("id")
+    title = attachment_data.get("title", "Untitled")
+    url = attachment_data.get("url")
+    subtitle = attachment_data.get("subtitle")
+
+    # Extract dates
+    created_at = None
+    if attachment_data.get("createdAt"):
+        created_at = datetime.fromisoformat(
+            attachment_data["createdAt"].replace("Z", "+00:00")
+        )
+
+    if attachment_data.get("updatedAt"):
+        datetime.fromisoformat(attachment_data["updatedAt"].replace("Z", "+00:00"))
+
+    # Build metadata with Linear-specific fields
+    metadata = {
+        "linear": {
+            "id": attachment_id,
+            "title": title,
+            "subtitle": subtitle,
+            "metadata": attachment_data.get("metadata"),
+            "updated_at": attachment_data.get("updatedAt"),
+        }
+    }
+
+    return Attachment(
+        id=attachment_id,
+        ticket_id=ticket_id,
+        filename=title,  # Linear uses 'title' as filename
+        url=url,
+        content_type=None,  # Linear doesn't provide MIME type in GraphQL
+        size_bytes=None,  # Linear doesn't provide size in GraphQL
+        created_at=created_at,
+        created_by=None,  # Not included in standard fragment
+        description=subtitle,
+        metadata=metadata,
+    )