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

mcp_ticketer/core/env_discovery.py

@@ -6,6 +6,7 @@ environment files, including:
 - Support for multiple naming conventions
 - Project information extraction
 - Security validation
+- 1Password CLI integration for secret references
 """
 
 import logging
@@ -15,6 +16,7 @@ from typing import Any
 
 from dotenv import dotenv_values
 
+from .onepassword_secrets import OnePasswordConfig, OnePasswordSecretsLoader
 from .project_config import AdapterType
 
 logger = logging.getLogger(__name__)
@@ -155,14 +157,27 @@ class EnvDiscovery:
         ".env.development",
     ]
 
-    def __init__(self, project_path: Path | None = None):
+    def __init__(
+        self,
+        project_path: Path | None = None,
+        enable_1password: bool = True,
+        onepassword_config: OnePasswordConfig | None = None,
+    ):
         """Initialize discovery.
 
         Args:
             project_path: Path to project root (defaults to cwd)
+            enable_1password: Enable 1Password CLI integration for secret resolution
+            onepassword_config: Configuration for 1Password integration
 
         """
         self.project_path = project_path or Path.cwd()
+        self.enable_1password = enable_1password
+        self.op_loader = (
+            OnePasswordSecretsLoader(onepassword_config or OnePasswordConfig())
+            if enable_1password
+            else None
+        )
 
     def discover(self) -> DiscoveryResult:
         """Discover adapter configurations from environment files.
@@ -241,7 +256,22 @@ class EnvDiscovery:
             file_path = self.project_path / env_file
             if file_path.exists():
                 try:
-                    env_vars = dotenv_values(file_path)
+                    # Check if file contains 1Password references and use op loader if available
+                    if self.op_loader and self.enable_1password:
+                        content = file_path.read_text(encoding="utf-8")
+                        if "op://" in content:
+                            logger.info(
+                                f"Detected 1Password references in {env_file}, "
+                                "attempting to resolve..."
+                            )
+                            env_vars = self.op_loader.load_secrets_from_env_file(
+                                file_path
+                            )
+                        else:
+                            env_vars = dotenv_values(file_path)
+                    else:
+                        env_vars = dotenv_values(file_path)
+
                     # Filter out None values
                     env_vars = {k: v for k, v in env_vars.items() if v is not None}
                     merged_env.update(env_vars)
@@ -623,7 +653,7 @@ class EnvDiscovery:
 
 
 def discover_config(project_path: Path | None = None) -> DiscoveryResult:
-    """Convenience function to discover configuration.
+    """Discover configuration from environment files.
 
     Args:
         project_path: Path to project root (defaults to cwd)

mcp_ticketer/core/env_loader.py

@@ -29,8 +29,9 @@ class EnvKeyConfig:
 
 
 class UnifiedEnvLoader:
-    """Unified environment loader that handles multiple naming conventions
-    and provides consistent environment loading across all contexts.
+    """Unified environment loader that handles multiple naming conventions.
+
+    Provides consistent environment loading across all contexts.
     """
 
     # Define key aliases for all adapters
@@ -131,7 +132,7 @@ class UnifiedEnvLoader:
         # Fallback to current directory
         return Path.cwd()
 
-    def _load_env_files(self):
+    def _load_env_files(self) -> None:
         """Load environment variables from .env files."""
         env_files = [
             self.project_root / ".env.local",
@@ -144,7 +145,7 @@ class UnifiedEnvLoader:
                 logger.debug(f"Loading environment from: {env_file}")
                 self._load_env_file(env_file)
 
-    def _load_env_file(self, env_file: Path):
+    def _load_env_file(self, env_file: Path) -> None:
         """Load variables from a single .env file."""
         try:
             with open(env_file) as f:
@@ -321,7 +322,7 @@ def get_env_loader() -> UnifiedEnvLoader:
 def load_adapter_config(
     adapter_name: str, base_config: dict[str, Any] | None = None
 ) -> dict[str, Any]:
-    """Convenience function to load adapter configuration with environment variables.
+    """Load adapter configuration with environment variables.
 
     Args:
         adapter_name: Name of the adapter ('linear', 'jira', 'github')
@@ -335,7 +336,7 @@ def load_adapter_config(
 
 
 def validate_adapter_config(adapter_name: str, config: dict[str, Any]) -> list[str]:
-    """Convenience function to validate adapter configuration.
+    """Validate adapter configuration.
 
     Args:
         adapter_name: Name of the adapter

mcp_ticketer/core/exceptions.py

@@ -1,4 +1,10 @@
-"""Exception classes for MCP Ticketer."""
+"""Exception classes for MCP Ticketer.
+
+Error Severity Classification:
+    CRITICAL - System-level issues (auth, config, network) → Always suggest diagnostics
+    MEDIUM - Resource issues (not found, permissions) → Suggest diagnostics
+    LOW - User input errors (validation, state transitions) → No diagnostics
+"""
 
 from __future__ import annotations
 
@@ -35,7 +41,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 +94,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 +132,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

@@ -206,7 +206,7 @@ class BaseHTTPClient:
         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()