mcp-ticketer 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

mcp_ticketer/__init__.py

@@ -1,17 +1,8 @@
 """MCP Ticketer - Universal ticket management interface."""
 
-from .__version__ import (
-                          __author__,
-                          __author_email__,
-                          __copyright__,
-                          __description__,
-                          __license__,
-                          __title__,
-                          __version__,
-                          __version_info__,
-                          get_user_agent,
-                          get_version,
-)
+from .__version__ import (__author__, __author_email__, __copyright__,
+                          __description__, __license__, __title__, __version__,
+                          __version_info__, get_user_agent, get_version)
 
 __all__ = [
     "__version__",

mcp_ticketer/__version__.py

@@ -1,6 +1,6 @@
 """Version information for mcp-ticketer package."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"
 __version_info__ = tuple(int(part) for part in __version__.split("."))
 
 # Package metadata

mcp_ticketer/adapters/aitrackdown.py

@@ -2,12 +2,16 @@
 
 import builtins
 import json
+import logging
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 from ..core.adapter import BaseAdapter
-from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
+
+logger = logging.getLogger(__name__)
+from ..core.models import (Attachment, Comment, Epic, Priority, SearchQuery,
+                           Task, TicketState)
 from ..core.registry import AdapterRegistry
 
 # Import ai-trackdown-pytools when available
@@ -80,7 +84,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             TicketState.CLOSED: "closed",
         }
 
-    def _priority_to_ai(self, priority: Union[Priority, str]) -> str:
+    def _priority_to_ai(self, priority: Priority | str) -> str:
         """Convert universal priority to AI-Trackdown priority."""
         if isinstance(priority, Priority):
             return priority.value
@@ -219,7 +223,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
             "type": "epic",
         }
 
-    def _read_ticket_file(self, ticket_id: str) -> Optional[dict[str, Any]]:
+    def _read_ticket_file(self, ticket_id: str) -> dict[str, Any] | None:
         """Read ticket from file system."""
         ticket_file = self.tickets_dir / f"{ticket_id}.json"
         if ticket_file.exists():
@@ -233,7 +237,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         with open(ticket_file, "w") as f:
             json.dump(data, f, indent=2, default=str)
 
-    async def create(self, ticket: Union[Task, Epic]) -> Union[Task, Epic]:
+    async def create(self, ticket: Task | Epic) -> Task | Epic:
         """Create a new task."""
         # Generate ID if not provided
         if not ticket.id:
@@ -324,7 +328,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         )
         return await self.create(task)
 
-    async def read(self, ticket_id: str) -> Optional[Union[Task, Epic]]:
+    async def read(self, ticket_id: str) -> Task | Epic | None:
         """Read a task by ID."""
         if self.tracker:
             ai_ticket = self.tracker.get_ticket(ticket_id)
@@ -340,8 +344,8 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return None
 
     async def update(
-        self, ticket_id: str, updates: Union[dict[str, Any], Task]
-    ) -> Optional[Union[Task, Epic]]:
+        self, ticket_id: str, updates: dict[str, Any] | Task
+    ) -> Task | Epic | None:
         """Update a task or epic.
 
         Args:
@@ -403,7 +407,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
     ) -> list[Task]:
         """List tasks with pagination."""
         tasks = []
@@ -487,7 +491,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Transition task to new state."""
         # Validate transition
         if not await self.validate_transition(ticket_id, target_state):
@@ -534,7 +538,7 @@ class AITrackdownAdapter(BaseAdapter[Task]):
         # Apply limit and offset AFTER filtering
         return comments[offset : offset + limit]
 
-    async def get_epic(self, epic_id: str) -> Optional[Epic]:
+    async def get_epic(self, epic_id: str) -> Epic | None:
         """Get epic by ID.
 
         Args:
@@ -612,6 +616,234 @@ class AITrackdownAdapter(BaseAdapter[Task]):
                 tasks.append(ticket)
         return tasks
 
+    def _sanitize_filename(self, filename: str) -> str:
+        """Sanitize filename to prevent security issues.
+
+        Args:
+            filename: Original filename
+
+        Returns:
+            Sanitized filename safe for filesystem
+
+        """
+        # Remove path separators and other dangerous characters
+        safe_chars = set(
+            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._- "
+        )
+        sanitized = "".join(c if c in safe_chars else "_" for c in filename)
+
+        # Ensure filename is not empty
+        if not sanitized.strip():
+            return "unnamed_file"
+
+        return sanitized.strip()
+
+    def _guess_content_type(self, file_path: Path) -> str:
+        """Guess MIME type from file extension.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            MIME type string
+
+        """
+        import mimetypes
+
+        content_type, _ = mimetypes.guess_type(str(file_path))
+        return content_type or "application/octet-stream"
+
+    def _calculate_checksum(self, file_path: Path) -> str:
+        """Calculate SHA256 checksum of file.
+
+        Args:
+            file_path: Path to file
+
+        Returns:
+            Hexadecimal checksum string
+
+        """
+        import hashlib
+
+        sha256 = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            # Read in chunks to handle large files
+            for chunk in iter(lambda: f.read(4096), b""):
+                sha256.update(chunk)
+
+        return sha256.hexdigest()
+
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: str | None = None,
+    ) -> Attachment:
+        """Attach a file to a ticket (local filesystem storage).
+
+        Args:
+            ticket_id: Ticket identifier
+            file_path: Local file path to attach
+            description: Optional attachment description
+
+        Returns:
+            Attachment metadata
+
+        Raises:
+            ValueError: If ticket doesn't exist
+            FileNotFoundError: If file doesn't exist
+
+        """
+        import shutil
+
+        # Validate ticket exists
+        ticket = await self.read(ticket_id)
+        if not ticket:
+            raise ValueError(f"Ticket {ticket_id} not found")
+
+        # Validate file exists
+        source_path = Path(file_path).resolve()
+        if not source_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Check file size (max 100MB for local storage)
+        size_mb = source_path.stat().st_size / (1024 * 1024)
+        if size_mb > 100:
+            raise ValueError(f"File too large: {size_mb:.2f}MB (max: 100MB)")
+
+        # Create attachments directory for this ticket
+        attachments_dir = self.base_path / "attachments" / ticket_id
+        attachments_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate unique filename with timestamp
+        timestamp = datetime.now().strftime("%Y%m%d%H%M%S%f")
+        safe_filename = self._sanitize_filename(source_path.name)
+        attachment_id = f"{timestamp}-{safe_filename}"
+        dest_path = attachments_dir / attachment_id
+
+        # Copy file to attachments directory
+        shutil.copy2(source_path, dest_path)
+
+        # Create attachment metadata
+        attachment = Attachment(
+            id=attachment_id,
+            ticket_id=ticket_id,
+            filename=source_path.name,
+            url=f"file://{dest_path.absolute()}",
+            content_type=self._guess_content_type(source_path),
+            size_bytes=source_path.stat().st_size,
+            created_at=datetime.now(),
+            description=description,
+            metadata={
+                "original_path": str(source_path),
+                "storage_path": str(dest_path),
+                "checksum": self._calculate_checksum(dest_path),
+            },
+        )
+
+        # Save metadata to JSON file
+        metadata_file = attachments_dir / f"{attachment_id}.json"
+        with open(metadata_file, "w") as f:
+            # Convert to dict and handle datetime serialization
+            data = attachment.model_dump()
+            json.dump(data, f, indent=2, default=str)
+
+        return attachment
+
+    async def get_attachments(self, ticket_id: str) -> builtins.list[Attachment]:
+        """Get all attachments for a ticket with path traversal protection.
+
+        Args:
+            ticket_id: Ticket identifier
+
+        Returns:
+            List of attachments (empty if none)
+
+        """
+        # Resolve and validate attachments directory
+        attachments_dir = (self.base_path / "attachments" / ticket_id).resolve()
+
+        # CRITICAL SECURITY CHECK: Ensure ticket directory is within base attachments
+        base_attachments = (self.base_path / "attachments").resolve()
+        if not str(attachments_dir).startswith(str(base_attachments)):
+            raise ValueError(f"Invalid ticket_id: path traversal detected")
+
+        if not attachments_dir.exists():
+            return []
+
+        attachments = []
+        for metadata_file in attachments_dir.glob("*.json"):
+            try:
+                with open(metadata_file) as f:
+                    data = json.load(f)
+                    # Convert ISO datetime strings back to datetime objects
+                    if isinstance(data.get("created_at"), str):
+                        data["created_at"] = datetime.fromisoformat(
+                            data["created_at"].replace("Z", "+00:00")
+                        )
+                    attachment = Attachment(**data)
+                    attachments.append(attachment)
+            except (json.JSONDecodeError, ValueError) as e:
+                # Log error but continue processing other attachments
+                logger.warning(
+                    "Failed to load attachment metadata from %s: %s",
+                    metadata_file,
+                    e,
+                )
+                continue
+
+        # Sort by creation time (newest first)
+        return sorted(
+            attachments,
+            key=lambda a: a.created_at or datetime.min,
+            reverse=True,
+        )
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str,
+    ) -> bool:
+        """Delete an attachment and its metadata with path traversal protection.
+
+        Args:
+            ticket_id: Ticket identifier
+            attachment_id: Attachment identifier
+
+        Returns:
+            True if deleted, False if not found
+
+        """
+        # Resolve base directory
+        attachments_dir = (self.base_path / "attachments" / ticket_id).resolve()
+
+        # Validate attachments directory exists
+        if not attachments_dir.exists():
+            return False
+
+        # Resolve file paths
+        attachment_file = (attachments_dir / attachment_id).resolve()
+        metadata_file = (attachments_dir / f"{attachment_id}.json").resolve()
+
+        # CRITICAL SECURITY CHECK: Ensure paths are within attachments_dir
+        base_resolved = attachments_dir.resolve()
+        if not str(attachment_file).startswith(str(base_resolved)):
+            raise ValueError(f"Invalid attachment path: path traversal detected in attachment_id")
+        if not str(metadata_file).startswith(str(base_resolved)):
+            raise ValueError(f"Invalid attachment path: path traversal detected in attachment_id")
+
+        # Delete files if they exist
+        deleted = False
+        if attachment_file.exists():
+            attachment_file.unlink()
+            deleted = True
+
+        if metadata_file.exists():
+            metadata_file.unlink()
+            deleted = True
+
+        return deleted
+
 
 # Register the adapter
 AdapterRegistry.register("aitrackdown", AITrackdownAdapter)

mcp_ticketer/adapters/github.py

@@ -3,13 +3,14 @@
 import builtins
 import re
 from datetime import datetime
-from typing import Any, Optional
+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.models import (Comment, Epic, Priority, SearchQuery, Task,
+                           TicketState)
 from ..core.registry import AdapterRegistry
 
 
@@ -198,8 +199,8 @@ class GitHubAdapter(BaseAdapter[Task]):
         )
 
         # Cache for labels and milestones
-        self._labels_cache: Optional[list[dict[str, Any]]] = None
-        self._milestones_cache: Optional[list[dict[str, Any]]] = None
+        self._labels_cache: list[dict[str, Any]] | None = None
+        self._milestones_cache: list[dict[str, Any]] | None = None
         self._rate_limit: dict[str, Any] = {}
 
     def validate_credentials(self) -> tuple[bool, str]:
@@ -239,7 +240,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             TicketState.CLOSED: GitHubStateMapping.CLOSED,
         }
 
-    def _get_state_label(self, state: TicketState) -> Optional[str]:
+    def _get_state_label(self, state: TicketState) -> str | None:
         """Get the label name for extended states."""
         return GitHubStateMapping.STATE_LABELS.get(state)
 
@@ -508,7 +509,7 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         return self._task_from_github_issue(created_issue)
 
-    async def read(self, ticket_id: str) -> Optional[Task]:
+    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()
@@ -533,7 +534,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         except httpx.HTTPError:
             return None
 
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[Task]:
+    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()
@@ -685,7 +686,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             return False
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
     ) -> list[Task]:
         """List GitHub issues with filters."""
         # Build query parameters
@@ -837,7 +838,7 @@ class GitHubAdapter(BaseAdapter[Task]):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Task]:
+    ) -> Task | None:
         """Transition GitHub issue to a new state."""
         # Validate transition
         if not await self.validate_transition(ticket_id, target_state):
@@ -971,7 +972,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             },
         )
 
-    async def get_milestone(self, milestone_number: int) -> Optional[Epic]:
+    async def get_milestone(self, milestone_number: int) -> Epic | None:
         """Get a GitHub milestone as an Epic."""
         try:
             response = await self.client.get(
@@ -1073,9 +1074,9 @@ class GitHubAdapter(BaseAdapter[Task]):
         self,
         ticket_id: str,
         base_branch: str = "main",
-        head_branch: Optional[str] = None,
-        title: Optional[str] = None,
-        body: Optional[str] = None,
+        head_branch: str | None = None,
+        title: str | None = None,
+        body: str | None = None,
         draft: bool = False,
     ) -> dict[str, Any]:
         """Create a pull request linked to an issue.
@@ -1342,7 +1343,7 @@ Fixes #{issue_number}
         response.raise_for_status()
         return response.json()
 
-    async def get_current_user(self) -> Optional[dict[str, Any]]:
+    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()

mcp_ticketer/adapters/hybrid.py

@@ -8,7 +8,7 @@ import builtins
 import json
 import logging
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 from ..core.adapter import BaseAdapter
 from ..core.models import Comment, Epic, SearchQuery, Task, TicketState
@@ -129,7 +129,7 @@ class HybridAdapter(BaseAdapter):
 
     def _get_adapter_ticket_id(
         self, universal_id: str, adapter_name: str
-    ) -> Optional[str]:
+    ) -> str | None:
         """Get adapter-specific ticket ID from universal ID.
 
         Args:
@@ -153,7 +153,7 @@ class HybridAdapter(BaseAdapter):
 
         return f"hybrid-{uuid.uuid4().hex[:12]}"
 
-    async def create(self, ticket: Union[Task, Epic]) -> Union[Task, Epic]:
+    async def create(self, ticket: Task | Epic) -> Task | Epic:
         """Create ticket in all configured adapters.
 
         Args:
@@ -208,7 +208,7 @@ class HybridAdapter(BaseAdapter):
         return primary_ticket
 
     def _add_cross_references(
-        self, ticket: Union[Task, Epic], results: list[tuple[str, Union[Task, Epic]]]
+        self, ticket: Task | Epic, results: list[tuple[str, Task | Epic]]
     ) -> None:
         """Add cross-references to ticket description.
 
@@ -226,7 +226,7 @@ class HybridAdapter(BaseAdapter):
         else:
             ticket.description = cross_refs.strip()
 
-    async def read(self, ticket_id: str) -> Optional[Union[Task, Epic]]:
+    async def read(self, ticket_id: str) -> Task | Epic | None:
         """Read ticket from primary adapter.
 
         Args:
@@ -255,7 +255,7 @@ class HybridAdapter(BaseAdapter):
 
     async def update(
         self, ticket_id: str, updates: dict[str, Any]
-    ) -> Optional[Union[Task, Epic]]:
+    ) -> Task | Epic | None:
         """Update ticket across all adapters.
 
         Args:
@@ -300,7 +300,7 @@ class HybridAdapter(BaseAdapter):
 
         return None
 
-    def _find_universal_id(self, adapter_ticket_id: str) -> Optional[str]:
+    def _find_universal_id(self, adapter_ticket_id: str) -> str | None:
         """Find universal ID for an adapter-specific ticket ID.
 
         Args:
@@ -359,8 +359,8 @@ class HybridAdapter(BaseAdapter):
         return success_count > 0
 
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
-    ) -> list[Union[Task, Epic]]:
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
+    ) -> list[Task | Epic]:
         """List tickets from primary adapter.
 
         Args:
@@ -375,7 +375,7 @@ class HybridAdapter(BaseAdapter):
         primary = self.adapters[self.primary_adapter_name]
         return await primary.list(limit, offset, filters)
 
-    async def search(self, query: SearchQuery) -> builtins.list[Union[Task, Epic]]:
+    async def search(self, query: SearchQuery) -> builtins.list[Task | Epic]:
         """Search tickets in primary adapter.
 
         Args:
@@ -390,7 +390,7 @@ class HybridAdapter(BaseAdapter):
 
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[Union[Task, Epic]]:
+    ) -> Task | Epic | None:
         """Transition ticket state across all adapters.
 
         Args: