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

mcp_ticketer/core/exceptions.py

@@ -35,7 +35,7 @@ class AdapterError(MCPTicketerError):
         self.original_error = original_error
 
     def __str__(self) -> str:
-        """String representation of the error."""
+        """Return string representation of the error."""
         base_msg = f"[{self.adapter_name}] {super().__str__()}"
         if self.original_error:
             base_msg += f" (caused by: {self.original_error})"
@@ -88,7 +88,7 @@ class ValidationError(MCPTicketerError):
         self.value = value
 
     def __str__(self) -> str:
-        """String representation of the error."""
+        """Return string representation of the error."""
         base_msg = super().__str__()
         if self.field:
             base_msg += f" (field: {self.field})"
@@ -126,7 +126,7 @@ class StateTransitionError(MCPTicketerError):
         self.to_state = to_state
 
     def __str__(self) -> str:
-        """String representation of the error."""
+        """Return string representation of the error."""
         return f"{super().__str__()} ({self.from_state} -> {self.to_state})"
 
 

mcp_ticketer/core/http_client.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 import time
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any
 
 import httpx
 from httpx import AsyncClient, TimeoutException
@@ -32,8 +32,8 @@ class RetryConfig:
         max_delay: float = 60.0,
         exponential_base: float = 2.0,
         jitter: bool = True,
-        retry_on_status: Optional[list[int]] = None,
-        retry_on_exceptions: Optional[list[type]] = None,
+        retry_on_status: list[int] | None = None,
+        retry_on_exceptions: list[type] | None = None,
     ):
         self.max_retries = max_retries
         self.initial_delay = initial_delay
@@ -94,11 +94,11 @@ class BaseHTTPClient:
     def __init__(
         self,
         base_url: str,
-        headers: Optional[dict[str, str]] = None,
-        auth: Optional[Union[httpx.Auth, tuple]] = None,
+        headers: dict[str, str] | None = None,
+        auth: httpx.Auth | tuple | None = None,
         timeout: float = 30.0,
-        retry_config: Optional[RetryConfig] = None,
-        rate_limiter: Optional[RateLimiter] = None,
+        retry_config: RetryConfig | None = None,
+        rate_limiter: RateLimiter | None = None,
         verify_ssl: bool = True,
         follow_redirects: bool = True,
     ):
@@ -132,7 +132,7 @@ class BaseHTTPClient:
             "errors": 0,
         }
 
-        self._client: Optional[AsyncClient] = None
+        self._client: AsyncClient | None = None
 
     async def _get_client(self) -> AsyncClient:
         """Get or create HTTP client instance."""
@@ -148,7 +148,7 @@ class BaseHTTPClient:
         return self._client
 
     async def _calculate_delay(
-        self, attempt: int, response: Optional[httpx.Response] = None
+        self, attempt: int, response: httpx.Response | None = None
     ) -> float:
         """Calculate delay for retry attempt."""
         if response and response.status_code == 429:
@@ -178,7 +178,7 @@ class BaseHTTPClient:
     def _should_retry(
         self,
         exception: Exception,
-        response: Optional[httpx.Response] = None,
+        response: httpx.Response | None = None,
         attempt: int = 1,
     ) -> bool:
         """Determine if request should be retried."""
@@ -198,15 +198,15 @@ class BaseHTTPClient:
 
     async def request(
         self,
-        method: Union[HTTPMethod, str],
+        method: HTTPMethod | str,
         endpoint: str,
-        data: Optional[dict[str, Any]] = None,
-        json: Optional[dict[str, Any]] = None,
-        params: Optional[dict[str, Any]] = None,
-        headers: Optional[dict[str, str]] = None,
-        timeout: Optional[float] = None,
+        data: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
         retry_count: int = 0,
-        **kwargs,
+        **kwargs: Any,
     ) -> httpx.Response:
         """Make HTTP request with retry and rate limiting.
 
@@ -293,27 +293,27 @@ class BaseHTTPClient:
             # No more retries, re-raise the exception
             raise
 
-    async def get(self, endpoint: str, **kwargs) -> httpx.Response:
+    async def get(self, endpoint: str, **kwargs: Any) -> httpx.Response:
         """Make GET request."""
         return await self.request(HTTPMethod.GET, endpoint, **kwargs)
 
-    async def post(self, endpoint: str, **kwargs) -> httpx.Response:
+    async def post(self, endpoint: str, **kwargs: Any) -> httpx.Response:
         """Make POST request."""
         return await self.request(HTTPMethod.POST, endpoint, **kwargs)
 
-    async def put(self, endpoint: str, **kwargs) -> httpx.Response:
+    async def put(self, endpoint: str, **kwargs: Any) -> httpx.Response:
         """Make PUT request."""
         return await self.request(HTTPMethod.PUT, endpoint, **kwargs)
 
-    async def patch(self, endpoint: str, **kwargs) -> httpx.Response:
+    async def patch(self, endpoint: str, **kwargs: Any) -> httpx.Response:
         """Make PATCH request."""
         return await self.request(HTTPMethod.PATCH, endpoint, **kwargs)
 
-    async def delete(self, endpoint: str, **kwargs) -> httpx.Response:
+    async def delete(self, endpoint: str, **kwargs: Any) -> httpx.Response:
         """Make DELETE request."""
         return await self.request(HTTPMethod.DELETE, endpoint, **kwargs)
 
-    async def get_json(self, endpoint: str, **kwargs) -> dict[str, Any]:
+    async def get_json(self, endpoint: str, **kwargs: Any) -> dict[str, Any]:
         """Make GET request and return JSON response."""
         response = await self.get(endpoint, **kwargs)
 
@@ -323,7 +323,7 @@ class BaseHTTPClient:
 
         return response.json()
 
-    async def post_json(self, endpoint: str, **kwargs) -> dict[str, Any]:
+    async def post_json(self, endpoint: str, **kwargs: Any) -> dict[str, Any]:
         """Make POST request and return JSON response."""
         response = await self.post(endpoint, **kwargs)
 
@@ -333,7 +333,7 @@ class BaseHTTPClient:
 
         return response.json()
 
-    async def put_json(self, endpoint: str, **kwargs) -> dict[str, Any]:
+    async def put_json(self, endpoint: str, **kwargs: Any) -> dict[str, Any]:
         """Make PUT request and return JSON response."""
         response = await self.put(endpoint, **kwargs)
 
@@ -343,7 +343,7 @@ class BaseHTTPClient:
 
         return response.json()
 
-    async def patch_json(self, endpoint: str, **kwargs) -> dict[str, Any]:
+    async def patch_json(self, endpoint: str, **kwargs: Any) -> dict[str, Any]:
         """Make PATCH request and return JSON response."""
         response = await self.patch(endpoint, **kwargs)
 

mcp_ticketer/core/instructions.py

@@ -0,0 +1,405 @@
+"""Ticket writing instructions management.
+
+This module provides a unified interface for managing ticket writing instructions
+that guide AI agents and users in creating well-structured, consistent tickets.
+
+The instructions can be:
+- Default (embedded in the package)
+- Custom (project-specific, stored in .mcp-ticketer/instructions.md)
+
+Example:
+    >>> from mcp_ticketer.core.instructions import get_instructions
+    >>> instructions = get_instructions()
+    >>> print(instructions)
+
+    >>> # For project-specific management
+    >>> from mcp_ticketer.core.instructions import TicketInstructionsManager
+    >>> manager = TicketInstructionsManager(project_dir="/path/to/project")
+    >>> manager.set_instructions("Custom instructions here...")
+    >>> if manager.has_custom_instructions():
+    ...     print("Using custom instructions")
+
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .exceptions import MCPTicketerError
+
+logger = logging.getLogger(__name__)
+
+
+class InstructionsError(MCPTicketerError):
+    """Base exception for instructions-related errors.
+
+    Raised when there are issues loading, saving, or validating ticket
+    writing instructions.
+    """
+
+    pass
+
+
+class InstructionsNotFoundError(InstructionsError):
+    """Exception raised when instructions file cannot be found.
+
+    This typically occurs when trying to load custom instructions from a
+    file path that doesn't exist, or when the default instructions file
+    is missing from the package.
+    """
+
+    pass
+
+
+class InstructionsValidationError(InstructionsError):
+    """Exception raised when instructions content is invalid.
+
+    Raised when instructions content fails validation rules such as:
+    - Empty content
+    - Content too short (< 100 characters)
+    - Invalid encoding
+    """
+
+    pass
+
+
+class TicketInstructionsManager:
+    """Manages ticket writing instructions for a project.
+
+    This class handles loading, saving, and validating ticket writing instructions.
+    It supports both default (embedded) instructions and custom project-specific
+    instructions.
+
+    The default instructions are embedded in the package at:
+        src/mcp_ticketer/defaults/ticket_instructions.md
+
+    Custom instructions are stored in the project directory at:
+        {project_dir}/.mcp-ticketer/instructions.md
+
+    Attributes:
+        project_dir: Path to the project root directory
+
+    Example:
+        >>> manager = TicketInstructionsManager("/path/to/project")
+        >>> instructions = manager.get_instructions()
+        >>> print(f"Using {'custom' if manager.has_custom_instructions() else 'default'}")
+
+        >>> # Set custom instructions
+        >>> manager.set_instructions("My custom guidelines...")
+        >>> assert manager.has_custom_instructions()
+
+        >>> # Revert to defaults
+        >>> manager.delete_instructions()
+        >>> assert not manager.has_custom_instructions()
+
+    """
+
+    # Class-level constant for custom instructions filename
+    INSTRUCTIONS_FILENAME = "instructions.md"
+    DEFAULT_INSTRUCTIONS_FILENAME = "ticket_instructions.md"
+    CONFIG_DIR = ".mcp-ticketer"
+
+    def __init__(self, project_dir: str | Path | None = None):
+        """Initialize the instructions manager.
+
+        Args:
+            project_dir: Path to the project root directory. If None, uses current
+                working directory. The project directory is where the .mcp-ticketer
+                folder will be created for custom instructions.
+
+        Raises:
+            InstructionsError: If project_dir is invalid or inaccessible
+
+        """
+        if project_dir is None:
+            project_dir = Path.cwd()
+        else:
+            project_dir = Path(project_dir)
+
+        if not project_dir.exists():
+            raise InstructionsError(f"Project directory does not exist: {project_dir}")
+
+        if not project_dir.is_dir():
+            raise InstructionsError(f"Project path is not a directory: {project_dir}")
+
+        self.project_dir = project_dir.resolve()
+        logger.debug(f"Initialized TicketInstructionsManager for: {self.project_dir}")
+
+    def get_instructions(self) -> str:
+        """Get the current ticket writing instructions.
+
+        Returns custom instructions if they exist, otherwise returns the default
+        embedded instructions.
+
+        Returns:
+            The ticket writing instructions as a string
+
+        Raises:
+            InstructionsError: If instructions cannot be loaded
+            InstructionsNotFoundError: If default instructions are missing (package error)
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> instructions = manager.get_instructions()
+            >>> # Use instructions to guide ticket creation
+            >>> print(instructions[:100])
+
+        """
+        if self.has_custom_instructions():
+            logger.debug("Loading custom instructions")
+            custom_path = self.get_instructions_path()
+            try:
+                return custom_path.read_text(encoding="utf-8")
+            except Exception as e:
+                raise InstructionsError(
+                    f"Failed to read custom instructions from {custom_path}: {e}"
+                ) from e
+        else:
+            logger.debug("Loading default instructions")
+            return self.get_default_instructions()
+
+    def get_default_instructions(self) -> str:
+        """Get the default embedded ticket writing instructions.
+
+        The default instructions are shipped with the package and provide
+        comprehensive guidelines for ticket creation.
+
+        Returns:
+            The default ticket writing instructions as a string
+
+        Raises:
+            InstructionsNotFoundError: If the default instructions file is missing
+                from the package (indicates package corruption or installation issue)
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> defaults = manager.get_default_instructions()
+            >>> # Always returns the same content regardless of project
+
+        """
+        # Get the path to the defaults directory (sibling to core)
+        package_root = Path(__file__).parent.parent
+        default_path = package_root / "defaults" / self.DEFAULT_INSTRUCTIONS_FILENAME
+
+        if not default_path.exists():
+            raise InstructionsNotFoundError(
+                f"Default instructions file not found at: {default_path}. "
+                "This indicates a package installation issue."
+            )
+
+        try:
+            content = default_path.read_text(encoding="utf-8")
+            logger.debug(f"Loaded default instructions from {default_path}")
+            return content
+        except Exception as e:
+            raise InstructionsError(
+                f"Failed to read default instructions from {default_path}: {e}"
+            ) from e
+
+    def set_instructions(self, content: str) -> None:
+        r"""Set custom ticket writing instructions for the project.
+
+        Creates or overwrites the custom instructions file in the project's
+        .mcp-ticketer directory. The content is validated before saving.
+
+        Args:
+            content: The custom instructions content to save
+
+        Raises:
+            InstructionsValidationError: If content fails validation
+            InstructionsError: If instructions cannot be written to disk
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> custom = "# My Team's Ticket Guidelines\n\n..."
+            >>> manager.set_instructions(custom)
+            >>> assert manager.has_custom_instructions()
+
+        """
+        # Validate content
+        self._validate_instructions(content)
+
+        # Ensure config directory exists
+        config_dir = self.project_dir / self.CONFIG_DIR
+        config_dir.mkdir(exist_ok=True, parents=True)
+
+        # Write instructions file
+        instructions_path = self.get_instructions_path()
+        try:
+            instructions_path.write_text(content, encoding="utf-8")
+            logger.info(f"Saved custom instructions to {instructions_path}")
+        except Exception as e:
+            raise InstructionsError(
+                f"Failed to write instructions to {instructions_path}: {e}"
+            ) from e
+
+    def set_instructions_from_file(self, file_path: str | Path) -> None:
+        """Load and set custom instructions from a file.
+
+        Reads instructions from the specified file and sets them as custom
+        instructions for the project. The file content is validated before saving.
+
+        Args:
+            file_path: Path to the file containing instructions
+
+        Raises:
+            InstructionsNotFoundError: If the source file doesn't exist
+            InstructionsValidationError: If file content fails validation
+            InstructionsError: If instructions cannot be loaded or saved
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> manager.set_instructions_from_file("team_guidelines.md")
+            >>> assert manager.has_custom_instructions()
+
+        """
+        source_path = Path(file_path)
+
+        if not source_path.exists():
+            raise InstructionsNotFoundError(
+                f"Instructions file not found: {source_path}"
+            )
+
+        if not source_path.is_file():
+            raise InstructionsError(f"Path is not a file: {source_path}")
+
+        try:
+            content = source_path.read_text(encoding="utf-8")
+            logger.debug(f"Read instructions from {source_path}")
+        except Exception as e:
+            raise InstructionsError(
+                f"Failed to read instructions from {source_path}: {e}"
+            ) from e
+
+        # Use set_instructions to validate and save
+        self.set_instructions(content)
+
+    def delete_instructions(self) -> bool:
+        """Delete custom instructions and revert to defaults.
+
+        Removes the custom instructions file if it exists. After deletion,
+        get_instructions() will return the default instructions.
+
+        Returns:
+            True if custom instructions were deleted, False if they didn't exist
+
+        Raises:
+            InstructionsError: If instructions file cannot be deleted
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> manager.set_instructions("Custom instructions")
+            >>> assert manager.delete_instructions()  # Returns True
+            >>> assert not manager.has_custom_instructions()
+            >>> assert not manager.delete_instructions()  # Returns False
+
+        """
+        instructions_path = self.get_instructions_path()
+
+        if not instructions_path.exists():
+            logger.debug("No custom instructions to delete")
+            return False
+
+        try:
+            instructions_path.unlink()
+            logger.info(f"Deleted custom instructions at {instructions_path}")
+            return True
+        except Exception as e:
+            raise InstructionsError(
+                f"Failed to delete instructions at {instructions_path}: {e}"
+            ) from e
+
+    def has_custom_instructions(self) -> bool:
+        """Check if custom instructions exist for this project.
+
+        Returns:
+            True if custom instructions file exists, False otherwise
+
+        Example:
+            >>> manager = TicketInstructionsManager()
+            >>> if manager.has_custom_instructions():
+            ...     print("Using project-specific guidelines")
+            ... else:
+            ...     print("Using default guidelines")
+
+        """
+        return self.get_instructions_path().exists()
+
+    def get_instructions_path(self) -> Path:
+        """Get the path to the custom instructions file.
+
+        Returns:
+            Path object pointing to where custom instructions are (or would be) stored
+
+        Note:
+            This returns the path even if the file doesn't exist yet. Use
+            has_custom_instructions() to check if the file exists.
+
+        Example:
+            >>> manager = TicketInstructionsManager("/path/to/project")
+            >>> path = manager.get_instructions_path()
+            >>> print(path)  # /path/to/project/.mcp-ticketer/instructions.md
+
+        """
+        return self.project_dir / self.CONFIG_DIR / self.INSTRUCTIONS_FILENAME
+
+    def _validate_instructions(self, content: str) -> None:
+        """Validate instructions content.
+
+        Performs validation checks on instructions content:
+        - Not empty
+        - Minimum length (100 characters)
+        - Contains markdown headers (warning only)
+
+        Args:
+            content: The instructions content to validate
+
+        Raises:
+            InstructionsValidationError: If content fails validation
+
+        """
+        if not content or not content.strip():
+            raise InstructionsValidationError("Instructions content cannot be empty")
+
+        if len(content.strip()) < 100:
+            raise InstructionsValidationError(
+                f"Instructions content too short ({len(content)} characters). "
+                "Minimum 100 characters required for meaningful guidelines."
+            )
+
+        # Warn if no markdown headers (not an error, just a quality check)
+        if not any(line.strip().startswith("#") for line in content.split("\n")):
+            logger.warning(
+                "Instructions don't contain markdown headers. "
+                "Consider using headers for better structure."
+            )
+
+
+def get_instructions(project_dir: str | Path | None = None) -> str:
+    """Get ticket writing instructions for a project.
+
+    This is a shorthand for creating a TicketInstructionsManager and calling
+    get_instructions(). Useful for simple cases where you just need the content.
+
+    Args:
+        project_dir: Path to the project root directory. If None, uses current
+            working directory.
+
+    Returns:
+        The ticket writing instructions (custom if available, otherwise default)
+
+    Raises:
+        InstructionsError: If instructions cannot be loaded
+
+    Example:
+        >>> from mcp_ticketer.core.instructions import get_instructions
+        >>> instructions = get_instructions()
+        >>> # Use instructions to guide ticket creation
+
+        >>> # For specific project
+        >>> instructions = get_instructions("/path/to/project")
+
+    """
+    manager = TicketInstructionsManager(project_dir)
+    return manager.get_instructions()

mcp_ticketer/core/mappers.py

@@ -3,7 +3,7 @@
 import logging
 from abc import ABC, abstractmethod
 from functools import lru_cache
-from typing import Any, Generic, Optional, TypeVar
+from typing import Any, Generic, TypeVar
 
 from .models import Priority, TicketState
 
@@ -27,11 +27,11 @@ class BiDirectionalDict(Generic[T, U]):
         self._reverse: dict[U, T] = {v: k for k, v in mapping.items()}
         self._cache: dict[str, Any] = {}
 
-    def get_forward(self, key: T, default: Optional[U] = None) -> Optional[U]:
+    def get_forward(self, key: T, default: U | None = None) -> U | None:
         """Get value by forward key."""
         return self._forward.get(key, default)
 
-    def get_reverse(self, key: U, default: Optional[T] = None) -> Optional[T]:
+    def get_reverse(self, key: U, default: T | None = None) -> T | None:
         """Get value by reverse key."""
         return self._reverse.get(key, default)
 
@@ -83,7 +83,7 @@ class StateMapper(BaseMapper):
     """Universal state mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize state mapper.
 
@@ -95,7 +95,7 @@ class StateMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
     def get_mapping(self) -> BiDirectionalDict:
@@ -229,7 +229,7 @@ class StateMapper(BaseMapper):
         """Check if adapter uses labels for extended states."""
         return self.adapter_type in ["github", "linear"]
 
-    def get_state_label(self, state: TicketState) -> Optional[str]:
+    def get_state_label(self, state: TicketState) -> str | None:
         """Get label name for extended states that require labels.
 
         Args:
@@ -258,7 +258,7 @@ class PriorityMapper(BaseMapper):
     """Universal priority mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize priority mapper.
 
@@ -270,7 +270,7 @@ class PriorityMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
     def get_mapping(self) -> BiDirectionalDict:
@@ -365,7 +365,7 @@ class PriorityMapper(BaseMapper):
                     ]:
                         result = Priority.LOW
                         break
-            elif isinstance(adapter_priority, (int, float)):
+            elif isinstance(adapter_priority, int | float):
                 # Handle numeric priorities (Linear-style)
                 if adapter_priority <= 1:
                     result = Priority.CRITICAL
@@ -483,7 +483,7 @@ class MapperRegistry:
 
     @classmethod
     def get_state_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> StateMapper:
         """Get or create state mapper for adapter type.
 
@@ -502,7 +502,7 @@ class MapperRegistry:
 
     @classmethod
     def get_priority_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> PriorityMapper:
         """Get or create priority mapper for adapter type.