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

mcp_ticketer/adapters/linear/adapter.py

@@ -2,15 +2,21 @@
 
 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
 
@@ -92,10 +98,28 @@ class LinearAdapter(BaseAdapter[Task]):
                 "Linear API key is required (api_key or LINEAR_API_KEY env var)"
             )
 
-        # Clean API key - remove Bearer prefix if accidentally included in config
-        # (The client will add it back when making requests)
-        if self.api_key.startswith("Bearer "):
-            self.api_key = self.api_key.replace("Bearer ", "")
+        # Clean API key - remove common prefixes if accidentally included in config
+        # (The client will add Bearer back when making requests)
+        if isinstance(self.api_key, str):
+            # Remove Bearer prefix
+            if self.api_key.startswith("Bearer "):
+                self.api_key = self.api_key.replace("Bearer ", "")
+            # Remove environment variable name prefix (e.g., "LINEAR_API_KEY=")
+            if "=" in self.api_key:
+                parts = self.api_key.split("=", 1)
+                if len(parts) == 2 and parts[0].upper() in (
+                    "LINEAR_API_KEY",
+                    "API_KEY",
+                ):
+                    self.api_key = parts[1]
+
+            # Validate API key format (Linear keys start with "lin_api_")
+            if not self.api_key.startswith("lin_api_"):
+                raise ValueError(
+                    f"Invalid Linear API key format. Expected key starting with 'lin_api_', "
+                    f"got: {self.api_key[:15]}... "
+                    f"Please check your configuration and ensure the API key is correct."
+                )
 
         self.workspace = config.get("workspace", "")
         self.team_key = config.get("team_key")
@@ -144,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.
@@ -190,7 +214,150 @@ 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.
+
+        Args:
+            project_identifier: Project slug, name, short ID, or URL
+
+        Returns:
+            Full Linear project UUID, or None if not found
+
+        Raises:
+            ValueError: If project lookup fails
+
+        Examples:
+            - "crm-smart-monitoring-system" (slug)
+            - "CRM Smart Monitoring System" (name)
+            - "f59a41a96c52" (short ID from URL)
+            - "https://linear.app/travel-bta/project/crm-smart-monitoring-system-f59a41a96c52/overview" (full URL)
+
+        """
+        if not project_identifier:
+            return None
+
+        # Extract slug/ID from URL if full URL provided
+        if project_identifier.startswith("http"):
+            # Extract slug-shortid from URL like:
+            # https://linear.app/travel-bta/project/crm-smart-monitoring-system-f59a41a96c52/overview
+            parts = project_identifier.split("/project/")
+            if len(parts) > 1:
+                slug_with_id = parts[1].split("/")[
+                    0
+                ]  # Get "crm-smart-monitoring-system-f59a41a96c52"
+                project_identifier = slug_with_id
+            else:
+                raise ValueError(f"Invalid Linear project URL: {project_identifier}")
+
+        # 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(project_identifier) == 36 and project_identifier.count("-") == 4:
+            return project_identifier
+
+        # Query all projects and search for matching slug, name, or slugId
+        query = """
+            query GetProjects {
+                projects(first: 100) {
+                    nodes {
+                        id
+                        name
+                        slugId
+                    }
+                }
+            }
+        """
+
+        try:
+            result = await self.client.execute_query(query, {})
+            projects = result.get("projects", {}).get("nodes", [])
+
+            # Search for match by slug, slugId, name (case-insensitive)
+            project_lower = project_identifier.lower()
+            for project in projects:
+                # Check if identifier matches slug pattern (extracted from slugId)
+                slug_id = project.get("slugId", "")
+                if slug_id:
+                    # slugId format: "crm-smart-monitoring-system-f59a41a96c52"
+                    # Extract both the slug part and short ID
+                    if "-" in slug_id:
+                        parts = slug_id.rsplit(
+                            "-", 1
+                        )  # Split from right to get last part
+                        slug_part = parts[0]  # "crm-smart-monitoring-system"
+                        short_id = parts[1] if len(parts) > 1 else ""  # "f59a41a96c52"
+
+                        # Match full slugId, slug part, or short ID
+                        if (
+                            slug_id.lower() == project_lower
+                            or slug_part.lower() == project_lower
+                            or short_id.lower() == project_lower
+                        ):
+                            return project["id"]
+
+                # Also check exact name match (case-insensitive)
+                if project["name"].lower() == project_lower:
+                    return project["id"]
+
+            # No match found
+            return None
+
+        except Exception as 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.
@@ -205,7 +372,7 @@ class LinearAdapter(BaseAdapter[Task]):
             )
 
             workflow_states = {}
-            for state in result["workflowStates"]["nodes"]:
+            for state in result["team"]["states"]["nodes"]:
                 state_type = state["type"].lower()
                 if state_type not in workflow_states:
                     workflow_states[state_type] = state
@@ -215,15 +382,17 @@ 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.
+        """Load and cache labels for the team with retry logic.
 
         Args:
             team_id: Linear team ID
 
         """
+        logger = logging.getLogger(__name__)
+
         query = """
             query GetTeamLabels($teamId: String!) {
                 team(id: $teamId) {
@@ -239,15 +408,32 @@ class LinearAdapter(BaseAdapter[Task]):
             }
         """
 
-        try:
-            result = await self.client.execute_query(query, {"teamId": team_id})
-            self._labels_cache = result["team"]["labels"]["nodes"]
-        except Exception:
-            # Log error but don't fail - labels are optional
-            self._labels_cache = []
+        max_retries = 3
+        for attempt in range(max_retries):
+            try:
+                result = await self.client.execute_query(query, {"teamId": team_id})
+                labels = result.get("team", {}).get("labels", {}).get("nodes", [])
+                self._labels_cache = labels
+                logger.info(f"Loaded {len(labels)} labels for team {team_id}")
+                return  # Success
+
+            except Exception as e:
+                if attempt < max_retries - 1:
+                    wait_time = 2**attempt
+                    logger.warning(
+                        f"Failed to load labels (attempt {attempt + 1}/{max_retries}): {e}. "
+                        f"Retrying in {wait_time}s..."
+                    )
+                    await asyncio.sleep(wait_time)
+                else:
+                    logger.error(
+                        f"Failed to load team labels after {max_retries} attempts: {e}",
+                        exc_info=True,
+                    )
+                    self._labels_cache = []  # Explicitly empty on failure
 
     async def _resolve_label_ids(self, label_names: list[str]) -> list[str]:
-        """Resolve label names to Linear label IDs.
+        """Resolve label names to Linear label IDs with proper None vs empty list handling.
 
         Args:
             label_names: List of label names
@@ -256,16 +442,25 @@ class LinearAdapter(BaseAdapter[Task]):
             List of Linear label IDs that exist
 
         """
-        import logging
-
         logger = logging.getLogger(__name__)
 
-        if not self._labels_cache:
+        # None = not loaded yet, [] = loaded but empty or failed
+        if self._labels_cache is None:
             team_id = await self._ensure_team_id()
             await self._load_team_labels(team_id)
 
+        if self._labels_cache is None:
+            # Still None after load attempt - should not happen
+            logger.error(
+                "Label cache is None after load attempt. Tags will be skipped."
+            )
+            return []
+
         if not self._labels_cache:
-            logger.warning("No labels found in team cache")
+            # Empty list - either no labels in team or load failed
+            logger.warning(
+                f"Team has no labels available. Cannot resolve tags: {label_names}"
+            )
             return []
 
         # Create name -> ID mapping (case-insensitive)
@@ -328,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
 
@@ -377,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
@@ -413,19 +639,50 @@ class LinearAdapter(BaseAdapter[Task]):
                 # Remove labelIds if no labels resolved
                 issue_input.pop("labelIds", None)
 
+        # Resolve project ID if parent_epic is provided (supports slug, name, short ID, or URL)
+        if task.parent_epic:
+            project_id = await self._resolve_project_id(task.parent_epic)
+            if project_id:
+                issue_input["projectId"] = project_id
+            else:
+                # Log warning but don't fail - user may have provided invalid project
+                logging.getLogger(__name__).warning(
+                    f"Could not resolve project identifier '{task.parent_epic}' to UUID. "
+                    "Issue will be created without project assignment."
+                )
+                # 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.
@@ -490,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.
@@ -586,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(
@@ -603,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).
@@ -680,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.
@@ -744,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
@@ -835,7 +1196,7 @@ class LinearAdapter(BaseAdapter[Task]):
 
             comment_input = {
                 "issueId": linear_id,
-                "body": comment.body,
+                "body": comment.content,
             }
 
             result = await self.client.execute_mutation(
@@ -849,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
@@ -907,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()