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

mcp_ticketer/adapters/linear/adapter.py

@@ -4,15 +4,19 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import mimetypes
 import os
+from pathlib import Path
 from typing import Any
 
 try:
+    import httpx
     from gql import gql
     from gql.transport.exceptions import TransportQueryError
 except ImportError:
     gql = None
     TransportQueryError = Exception
+    httpx = None
 
 import builtins
 
@@ -164,7 +168,7 @@ class LinearAdapter(BaseAdapter[Task]):
             self._initialized = True
 
         except Exception as e:
-            raise ValueError(f"Failed to initialize Linear adapter: {e}")
+            raise ValueError(f"Failed to initialize Linear adapter: {e}") from e
 
     async def _ensure_team_id(self) -> str:
         """Ensure we have a team ID, resolving from team_key if needed.
@@ -210,7 +214,7 @@ class LinearAdapter(BaseAdapter[Task]):
             return self.team_id
 
         except Exception as e:
-            raise ValueError(f"Failed to resolve team '{self.team_key}': {e}")
+            raise ValueError(f"Failed to resolve team '{self.team_key}': {e}") from e
 
     async def _resolve_project_id(self, project_identifier: str) -> str | None:
         """Resolve project identifier (slug, name, short ID, or URL) to full UUID.
@@ -300,7 +304,60 @@ class LinearAdapter(BaseAdapter[Task]):
             return None
 
         except Exception as e:
-            raise ValueError(f"Failed to resolve project '{project_identifier}': {e}")
+            raise ValueError(
+                f"Failed to resolve project '{project_identifier}': {e}"
+            ) from e
+
+    async def _resolve_issue_id(self, issue_identifier: str) -> str | None:
+        """Resolve issue identifier (like "ENG-842") to full UUID.
+
+        Args:
+            issue_identifier: Issue identifier (e.g., "ENG-842") or UUID
+
+        Returns:
+            Full Linear issue UUID, or None if not found
+
+        Raises:
+            ValueError: If issue lookup fails
+
+        Examples:
+            - "ENG-842" (issue identifier)
+            - "BTA-123" (issue identifier)
+            - "a1b2c3d4-e5f6-7890-abcd-ef1234567890" (already a UUID)
+
+        """
+        if not issue_identifier:
+            return None
+
+        # If it looks like a full UUID already (exactly 36 chars with exactly 4 dashes), return it
+        # UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+        if len(issue_identifier) == 36 and issue_identifier.count("-") == 4:
+            return issue_identifier
+
+        # Query issue by identifier to get its UUID
+        query = """
+            query GetIssueId($identifier: String!) {
+                issue(id: $identifier) {
+                    id
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_query(
+                query, {"identifier": issue_identifier}
+            )
+
+            if result.get("issue"):
+                return result["issue"]["id"]
+
+            # No match found
+            return None
+
+        except Exception as e:
+            raise ValueError(
+                f"Failed to resolve issue '{issue_identifier}': {e}"
+            ) from e
 
     async def _load_workflow_states(self, team_id: str) -> None:
         """Load and cache workflow states for the team.
@@ -325,7 +382,7 @@ class LinearAdapter(BaseAdapter[Task]):
             self._workflow_states = workflow_states
 
         except Exception as e:
-            raise ValueError(f"Failed to load workflow states: {e}")
+            raise ValueError(f"Failed to load workflow states: {e}") from e
 
     async def _load_team_labels(self, team_id: str) -> None:
         """Load and cache labels for the team with retry logic.
@@ -466,23 +523,48 @@ class LinearAdapter(BaseAdapter[Task]):
         return mapping
 
     async def _get_user_id(self, user_identifier: str) -> str | None:
-        """Get Linear user ID from email or display name.
+        """Get Linear user ID from email, display name, or user ID.
 
         Args:
-            user_identifier: Email address or display name
+            user_identifier: Email, display name, or user ID
 
         Returns:
             Linear user ID or None if not found
 
         """
-        # Try to get user by email first
+        if not user_identifier:
+            return None
+
+        # Try email lookup first (most specific)
         user = await self.client.get_user_by_email(user_identifier)
         if user:
             return user["id"]
 
-        # If not found by email, could implement search by display name
-        # For now, assume the identifier is already a user ID
-        return user_identifier if user_identifier else None
+        # Try name search (displayName or full name)
+        users = await self.client.get_users_by_name(user_identifier)
+        if users:
+            if len(users) == 1:
+                # Exact match found
+                return users[0]["id"]
+            else:
+                # Multiple matches - try exact match
+                for u in users:
+                    if (
+                        u.get("displayName", "").lower() == user_identifier.lower()
+                        or u.get("name", "").lower() == user_identifier.lower()
+                    ):
+                        return u["id"]
+
+                # No exact match - log ambiguity and return first
+                logging.getLogger(__name__).warning(
+                    f"Multiple users match '{user_identifier}': "
+                    f"{[u.get('displayName', u.get('name')) for u in users]}. "
+                    f"Using first match: {users[0].get('displayName')}"
+                )
+                return users[0]["id"]
+
+        # Assume it's already a user ID
+        return user_identifier
 
     # CRUD Operations
 
@@ -515,7 +597,13 @@ class LinearAdapter(BaseAdapter[Task]):
         return await self._create_task(ticket)
 
     async def _create_task(self, task: Task) -> Task:
-        """Create a Linear issue from a Task.
+        """Create a Linear issue or sub-issue from a Task.
+
+        Creates a top-level issue when task.parent_issue is not set, or a
+        sub-issue (child of another issue) when task.parent_issue is provided.
+        In Linear terminology:
+        - Issue: Top-level work item (no parent)
+        - Sub-issue: Child work item (has parent issue)
 
         Args:
             task: Task to create
@@ -565,19 +653,36 @@ class LinearAdapter(BaseAdapter[Task]):
                 # Remove projectId if we couldn't resolve it
                 issue_input.pop("projectId", None)
 
+        # Resolve parent issue ID if provided (creates a sub-issue when parent is set)
+        # Supports identifiers like "ENG-842" or UUIDs
+        if task.parent_issue:
+            issue_id = await self._resolve_issue_id(task.parent_issue)
+            if issue_id:
+                issue_input["parentId"] = issue_id
+            else:
+                # Log warning but don't fail - user may have provided invalid issue
+                logging.getLogger(__name__).warning(
+                    f"Could not resolve issue identifier '{task.parent_issue}' to UUID. "
+                    "Sub-issue will be created without parent assignment."
+                )
+                # Remove parentId if we couldn't resolve it
+                issue_input.pop("parentId", None)
+
         try:
             result = await self.client.execute_mutation(
                 CREATE_ISSUE_MUTATION, {"input": issue_input}
             )
 
             if not result["issueCreate"]["success"]:
-                raise ValueError("Failed to create Linear issue")
+                item_type = "sub-issue" if task.parent_issue else "issue"
+                raise ValueError(f"Failed to create Linear {item_type}")
 
             created_issue = result["issueCreate"]["issue"]
             return map_linear_issue_to_task(created_issue)
 
         except Exception as e:
-            raise ValueError(f"Failed to create Linear issue: {e}")
+            item_type = "sub-issue" if task.parent_issue else "issue"
+            raise ValueError(f"Failed to create Linear {item_type}: {e}") from e
 
     async def _create_epic(self, epic: Epic) -> Epic:
         """Create a Linear project from an Epic.
@@ -642,7 +747,98 @@ class LinearAdapter(BaseAdapter[Task]):
             return map_linear_project_to_epic(created_project)
 
         except Exception as e:
-            raise ValueError(f"Failed to create Linear project: {e}")
+            raise ValueError(f"Failed to create Linear project: {e}") from e
+
+    async def update_epic(self, epic_id: str, updates: dict[str, Any]) -> Epic | None:
+        """Update a Linear project (Epic) with specified fields.
+
+        Args:
+            epic_id: Linear project UUID or slug-shortid
+            updates: Dictionary of fields to update. Supported fields:
+                - title: Project name
+                - description: Project description
+                - state: Project state (e.g., "planned", "started", "completed", "canceled")
+                - target_date: Target completion date (ISO format YYYY-MM-DD)
+                - color: Project color
+                - icon: Project icon
+
+        Returns:
+            Updated Epic object or None if not found
+
+        Raises:
+            ValueError: If update fails or project not found
+
+        """
+        # Validate credentials before attempting operation
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        # Resolve project identifier to UUID if needed
+        project_uuid = await self._resolve_project_id(epic_id)
+        if not project_uuid:
+            raise ValueError(f"Project '{epic_id}' not found")
+
+        # Build update input from updates dict
+        update_input = {}
+
+        if "title" in updates:
+            update_input["name"] = updates["title"]
+        if "description" in updates:
+            update_input["description"] = updates["description"]
+        if "state" in updates:
+            update_input["state"] = updates["state"]
+        if "target_date" in updates:
+            update_input["targetDate"] = updates["target_date"]
+        if "color" in updates:
+            update_input["color"] = updates["color"]
+        if "icon" in updates:
+            update_input["icon"] = updates["icon"]
+
+        # ProjectUpdate mutation
+        update_query = """
+            mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
+                projectUpdate(id: $id, input: $input) {
+                    success
+                    project {
+                        id
+                        name
+                        description
+                        state
+                        createdAt
+                        updatedAt
+                        url
+                        icon
+                        color
+                        targetDate
+                        startedAt
+                        completedAt
+                        teams {
+                            nodes {
+                                id
+                                name
+                                key
+                                description
+                            }
+                        }
+                    }
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_mutation(
+                update_query, {"id": project_uuid, "input": update_input}
+            )
+
+            if not result["projectUpdate"]["success"]:
+                raise ValueError(f"Failed to update Linear project '{epic_id}'")
+
+            updated_project = result["projectUpdate"]["project"]
+            return map_linear_project_to_epic(updated_project)
+
+        except Exception as e:
+            raise ValueError(f"Failed to update Linear project: {e}") from e
 
     async def read(self, ticket_id: str) -> Task | None:
         """Read a Linear issue by identifier with full details.
@@ -738,10 +934,23 @@ class LinearAdapter(BaseAdapter[Task]):
                     update_input["assigneeId"] = user_id
 
             # Resolve label names to IDs if provided
-            if "tags" in updates and updates["tags"]:
-                label_ids = await self._resolve_label_ids(updates["tags"])
-                if label_ids:
-                    update_input["labelIds"] = label_ids
+            if "tags" in updates:
+                if updates["tags"]:  # Non-empty list
+                    label_ids = await self._resolve_label_ids(updates["tags"])
+                    if label_ids:
+                        update_input["labelIds"] = label_ids
+                else:  # Empty list = remove all labels
+                    update_input["labelIds"] = []
+
+            # Resolve project ID if parent_epic is provided (supports slug, name, short ID, or URL)
+            if "parent_epic" in updates and updates["parent_epic"]:
+                project_id = await self._resolve_project_id(updates["parent_epic"])
+                if project_id:
+                    update_input["projectId"] = project_id
+                else:
+                    logging.getLogger(__name__).warning(
+                        f"Could not resolve project identifier '{updates['parent_epic']}'"
+                    )
 
             # Execute update
             result = await self.client.execute_mutation(
@@ -755,7 +964,7 @@ class LinearAdapter(BaseAdapter[Task]):
             return map_linear_issue_to_task(updated_issue)
 
         except Exception as e:
-            raise ValueError(f"Failed to update Linear issue: {e}")
+            raise ValueError(f"Failed to update Linear issue: {e}") from e
 
     async def delete(self, ticket_id: str) -> bool:
         """Delete a Linear issue (archive it).
@@ -832,7 +1041,7 @@ class LinearAdapter(BaseAdapter[Task]):
             return tasks
 
         except Exception as e:
-            raise ValueError(f"Failed to list Linear issues: {e}")
+            raise ValueError(f"Failed to list Linear issues: {e}") from e
 
     async def search(self, query: SearchQuery) -> builtins.list[Task]:
         """Search Linear issues using comprehensive filters.
@@ -896,7 +1105,7 @@ class LinearAdapter(BaseAdapter[Task]):
             return tasks
 
         except Exception as e:
-            raise ValueError(f"Failed to search Linear issues: {e}")
+            raise ValueError(f"Failed to search Linear issues: {e}") from e
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
@@ -1001,7 +1210,7 @@ class LinearAdapter(BaseAdapter[Task]):
             return map_linear_comment_to_comment(created_comment, comment.ticket_id)
 
         except Exception as e:
-            raise ValueError(f"Failed to add comment: {e}")
+            raise ValueError(f"Failed to add comment: {e}") from e
 
     async def get_comments(
         self, ticket_id: str, limit: int = 10, offset: int = 0
@@ -1059,6 +1268,299 @@ class LinearAdapter(BaseAdapter[Task]):
         except Exception:
             return []
 
+    async def list_labels(self) -> builtins.list[dict[str, Any]]:
+        """List all labels available in the Linear team.
+
+        Returns:
+            List of label dictionaries with 'id', 'name', and 'color' fields
+
+        """
+        # Ensure labels are loaded
+        if self._labels_cache is None:
+            team_id = await self._ensure_team_id()
+            await self._load_team_labels(team_id)
+
+        # Return cached labels or empty list if not available
+        if not self._labels_cache:
+            return []
+
+        # Transform to standardized format
+        return [
+            {
+                "id": label["id"],
+                "name": label["name"],
+                "color": label.get("color", ""),
+            }
+            for label in self._labels_cache
+        ]
+
+    async def upload_file(self, file_path: str, mime_type: str | None = None) -> str:
+        """Upload a file to Linear's storage and return the asset URL.
+
+        This method implements Linear's three-step file upload process:
+        1. Request a pre-signed upload URL via fileUpload mutation
+        2. Upload the file to S3 using the pre-signed URL
+        3. Return the asset URL for use in attachments
+
+        Args:
+            file_path: Path to the file to upload
+            mime_type: MIME type of the file. If None, will be auto-detected.
+
+        Returns:
+            Asset URL that can be used with attachmentCreate mutation
+
+        Raises:
+            ValueError: If file doesn't exist, upload fails, or httpx not available
+            FileNotFoundError: If the specified file doesn't exist
+
+        """
+        if httpx is None:
+            raise ValueError(
+                "httpx library not installed. Install with: pip install httpx"
+            )
+
+        # Validate file exists
+        file_path_obj = Path(file_path)
+        if not file_path_obj.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        if not file_path_obj.is_file():
+            raise ValueError(f"Path is not a file: {file_path}")
+
+        # Get file info
+        file_size = file_path_obj.stat().st_size
+        filename = file_path_obj.name
+
+        # Auto-detect MIME type if not provided
+        if mime_type is None:
+            mime_type, _ = mimetypes.guess_type(file_path)
+            if mime_type is None:
+                # Default to binary if can't detect
+                mime_type = "application/octet-stream"
+
+        # Step 1: Request pre-signed upload URL
+        upload_mutation = """
+            mutation FileUpload($contentType: String!, $filename: String!, $size: Int!) {
+                fileUpload(contentType: $contentType, filename: $filename, size: $size) {
+                    success
+                    uploadFile {
+                        uploadUrl
+                        assetUrl
+                        headers {
+                            key
+                            value
+                        }
+                    }
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_mutation(
+                upload_mutation,
+                {
+                    "contentType": mime_type,
+                    "filename": filename,
+                    "size": file_size,
+                },
+            )
+
+            if not result["fileUpload"]["success"]:
+                raise ValueError("Failed to get upload URL from Linear API")
+
+            upload_file_data = result["fileUpload"]["uploadFile"]
+            upload_url = upload_file_data["uploadUrl"]
+            asset_url = upload_file_data["assetUrl"]
+            headers_list = upload_file_data.get("headers", [])
+
+            # Convert headers list to dict
+            upload_headers = {h["key"]: h["value"] for h in headers_list}
+            # Add Content-Type header
+            upload_headers["Content-Type"] = mime_type
+
+            # Step 2: Upload file to S3 using pre-signed URL
+            async with httpx.AsyncClient() as http_client:
+                with open(file_path, "rb") as f:
+                    file_content = f.read()
+
+                response = await http_client.put(
+                    upload_url,
+                    content=file_content,
+                    headers=upload_headers,
+                    timeout=60.0,  # 60 second timeout for large files
+                )
+
+                if response.status_code not in (200, 201, 204):
+                    raise ValueError(
+                        f"Failed to upload file to S3. Status: {response.status_code}, "
+                        f"Response: {response.text}"
+                    )
+
+            # Step 3: Return asset URL
+            logging.getLogger(__name__).info(
+                f"Successfully uploaded file '{filename}' ({file_size} bytes) to Linear"
+            )
+            return asset_url
+
+        except Exception as e:
+            raise ValueError(f"Failed to upload file '{filename}': {e}") from e
+
+    async def attach_file_to_issue(
+        self,
+        issue_id: str,
+        file_url: str,
+        title: str,
+        subtitle: str | None = None,
+        comment_body: str | None = None,
+    ) -> dict[str, Any]:
+        """Attach a file to a Linear issue.
+
+        The file must already be uploaded using upload_file() or be a publicly
+        accessible URL.
+
+        Args:
+            issue_id: Linear issue identifier (e.g., "ENG-842") or UUID
+            file_url: URL of the file (from upload_file() or external URL)
+            title: Title for the attachment
+            subtitle: Optional subtitle for the attachment
+            comment_body: Optional comment text to include with the attachment
+
+        Returns:
+            Dictionary with attachment details including id, title, url, etc.
+
+        Raises:
+            ValueError: If attachment creation fails or issue not found
+
+        """
+        # Resolve issue identifier to UUID
+        issue_uuid = await self._resolve_issue_id(issue_id)
+        if not issue_uuid:
+            raise ValueError(f"Issue '{issue_id}' not found")
+
+        # Build attachment input
+        attachment_input: dict[str, Any] = {
+            "issueId": issue_uuid,
+            "title": title,
+            "url": file_url,
+        }
+
+        if subtitle:
+            attachment_input["subtitle"] = subtitle
+
+        if comment_body:
+            attachment_input["commentBody"] = comment_body
+
+        # Create attachment mutation
+        attachment_mutation = """
+            mutation AttachmentCreate($input: AttachmentCreateInput!) {
+                attachmentCreate(input: $input) {
+                    success
+                    attachment {
+                        id
+                        title
+                        url
+                        subtitle
+                        metadata
+                        createdAt
+                        updatedAt
+                    }
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_mutation(
+                attachment_mutation, {"input": attachment_input}
+            )
+
+            if not result["attachmentCreate"]["success"]:
+                raise ValueError(f"Failed to attach file to issue '{issue_id}'")
+
+            attachment = result["attachmentCreate"]["attachment"]
+            logging.getLogger(__name__).info(
+                f"Successfully attached file '{title}' to issue '{issue_id}'"
+            )
+            return attachment
+
+        except Exception as e:
+            raise ValueError(f"Failed to attach file to issue '{issue_id}': {e}") from e
+
+    async def attach_file_to_epic(
+        self,
+        epic_id: str,
+        file_url: str,
+        title: str,
+        subtitle: str | None = None,
+    ) -> dict[str, Any]:
+        """Attach a file to a Linear project (Epic).
+
+        The file must already be uploaded using upload_file() or be a publicly
+        accessible URL.
+
+        Args:
+            epic_id: Linear project UUID or slug-shortid
+            file_url: URL of the file (from upload_file() or external URL)
+            title: Title for the attachment
+            subtitle: Optional subtitle for the attachment
+
+        Returns:
+            Dictionary with attachment details including id, title, url, etc.
+
+        Raises:
+            ValueError: If attachment creation fails or project not found
+
+        """
+        # Resolve project identifier to UUID
+        project_uuid = await self._resolve_project_id(epic_id)
+        if not project_uuid:
+            raise ValueError(f"Project '{epic_id}' not found")
+
+        # Build attachment input (use projectId instead of issueId)
+        attachment_input: dict[str, Any] = {
+            "projectId": project_uuid,
+            "title": title,
+            "url": file_url,
+        }
+
+        if subtitle:
+            attachment_input["subtitle"] = subtitle
+
+        # Create attachment mutation (same as for issues)
+        attachment_mutation = """
+            mutation AttachmentCreate($input: AttachmentCreateInput!) {
+                attachmentCreate(input: $input) {
+                    success
+                    attachment {
+                        id
+                        title
+                        url
+                        subtitle
+                        metadata
+                        createdAt
+                        updatedAt
+                    }
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_mutation(
+                attachment_mutation, {"input": attachment_input}
+            )
+
+            if not result["attachmentCreate"]["success"]:
+                raise ValueError(f"Failed to attach file to project '{epic_id}'")
+
+            attachment = result["attachmentCreate"]["attachment"]
+            logging.getLogger(__name__).info(
+                f"Successfully attached file '{title}' to project '{epic_id}'"
+            )
+            return attachment
+
+        except Exception as e:
+            raise ValueError(
+                f"Failed to attach file to project '{epic_id}': {e}"
+            ) from e
+
     async def close(self) -> None:
         """Close the adapter and clean up resources."""
         await self.client.close()