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

mcp_ticketer/core/adapter.py

@@ -1,11 +1,16 @@
 """Base adapter abstract class for ticket systems."""
 
+from __future__ import annotations
+
 import builtins
 from abc import ABC, abstractmethod
-from typing import Any, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
 
+if TYPE_CHECKING:
+    from .models import Attachment
+
 # Generic type for tickets
 T = TypeVar("T", Epic, Task)
 
@@ -57,7 +62,7 @@ class BaseAdapter(ABC, Generic[T]):
         pass
 
     @abstractmethod
-    async def read(self, ticket_id: str) -> Optional[T]:
+    async def read(self, ticket_id: str) -> T | None:
         """Read a ticket by ID.
 
         Args:
@@ -70,7 +75,7 @@ class BaseAdapter(ABC, Generic[T]):
         pass
 
     @abstractmethod
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[T]:
+    async def update(self, ticket_id: str, updates: dict[str, Any]) -> T | None:
         """Update a ticket.
 
         Args:
@@ -98,7 +103,7 @@ class BaseAdapter(ABC, Generic[T]):
 
     @abstractmethod
     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[T]:
         """List tickets with pagination and filters.
 
@@ -129,7 +134,7 @@ class BaseAdapter(ABC, Generic[T]):
     @abstractmethod
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[T]:
+    ) -> T | None:
         """Transition ticket to a new state.
 
         Args:
@@ -225,8 +230,8 @@ class BaseAdapter(ABC, Generic[T]):
     # Epic/Issue/Task Hierarchy Methods
 
     async def create_epic(
-        self, title: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Epic]:
+        self, title: str, description: str | None = None, **kwargs: Any
+    ) -> Epic | None:
         """Create epic (top-level grouping).
 
         Args:
@@ -249,7 +254,7 @@ class BaseAdapter(ABC, Generic[T]):
             return result
         return None
 
-    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:
@@ -265,7 +270,7 @@ class BaseAdapter(ABC, Generic[T]):
             return result
         return None
 
-    async def list_epics(self, **kwargs) -> builtins.list[Epic]:
+    async def list_epics(self, **kwargs: Any) -> builtins.list[Epic]:
         """List all epics.
 
         Args:
@@ -284,10 +289,10 @@ class BaseAdapter(ABC, Generic[T]):
     async def create_issue(
         self,
         title: str,
-        description: Optional[str] = None,
-        epic_id: Optional[str] = None,
-        **kwargs,
-    ) -> Optional[Task]:
+        description: str | None = None,
+        epic_id: str | None = None,
+        **kwargs: Any,
+    ) -> Task | None:
         """Create issue, optionally linked to epic.
 
         Args:
@@ -325,8 +330,8 @@ class BaseAdapter(ABC, Generic[T]):
         return [r for r in results if isinstance(r, Task) and r.is_issue()]
 
     async def create_task(
-        self, title: str, parent_id: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Task]:
+        self, title: str, parent_id: str, description: str | None = None, **kwargs: Any
+    ) -> Task | None:
         """Create task as sub-ticket of parent issue.
 
         Args:
@@ -375,6 +380,70 @@ class BaseAdapter(ABC, Generic[T]):
         results = await self.list(filters=filters)
         return [r for r in results if isinstance(r, Task) and r.is_task()]
 
+    # Attachment methods
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: str | None = None,
+    ) -> Attachment:
+        """Attach a file to a ticket.
+
+        Args:
+            ticket_id: Ticket identifier
+            file_path: Local file path to upload
+            description: Optional attachment description
+
+        Returns:
+            Created Attachment with metadata
+
+        Raises:
+            NotImplementedError: If adapter doesn't support attachments
+            FileNotFoundError: If file doesn't exist
+            ValueError: If ticket doesn't exist or upload fails
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments. "
+            "Use comments to reference external files instead."
+        )
+
+    async def get_attachments(self, ticket_id: str) -> list[Attachment]:
+        """Get all attachments for a ticket.
+
+        Args:
+            ticket_id: Ticket identifier
+
+        Returns:
+            List of attachments (empty if none or not supported)
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments."
+        )
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str,
+    ) -> bool:
+        """Delete an attachment (optional implementation).
+
+        Args:
+            ticket_id: Ticket identifier
+            attachment_id: Attachment identifier
+
+        Returns:
+            True if deleted, False otherwise
+
+        Raises:
+            NotImplementedError: If adapter doesn't support deletion
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support attachment deletion."
+        )
+
     async def close(self) -> None:
         """Close adapter and cleanup resources."""
         pass

mcp_ticketer/core/config.py

@@ -6,7 +6,7 @@ import os
 from enum import Enum
 from functools import lru_cache
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
@@ -27,27 +27,28 @@ class BaseAdapterConfig(BaseModel):
     """Base configuration for all adapters."""
 
     type: AdapterType
-    name: Optional[str] = None
+    name: str | None = None
     enabled: bool = True
     timeout: float = 30.0
     max_retries: int = 3
-    rate_limit: Optional[dict[str, Any]] = None
+    rate_limit: dict[str, Any] | None = None
 
 
 class GitHubConfig(BaseAdapterConfig):
     """GitHub adapter configuration."""
 
     type: AdapterType = AdapterType.GITHUB
-    token: Optional[str] = Field(None, env="GITHUB_TOKEN")
-    owner: Optional[str] = Field(None, env="GITHUB_OWNER")
-    repo: Optional[str] = Field(None, env="GITHUB_REPO")
+    token: str | None = Field(None, env="GITHUB_TOKEN")
+    owner: str | None = Field(None, env="GITHUB_OWNER")
+    repo: str | None = Field(None, env="GITHUB_REPO")
     api_url: str = "https://api.github.com"
     use_projects_v2: bool = False
-    custom_priority_scheme: Optional[dict[str, list[str]]] = None
+    custom_priority_scheme: dict[str, list[str]] | None = None
 
     @field_validator("token", mode="before")
     @classmethod
-    def validate_token(cls, v):
+    def validate_token(cls, v: Any) -> str:
+        """Validate GitHub token from config or environment."""
         if not v:
             v = os.getenv("GITHUB_TOKEN")
         if not v:
@@ -56,7 +57,8 @@ class GitHubConfig(BaseAdapterConfig):
 
     @field_validator("owner", mode="before")
     @classmethod
-    def validate_owner(cls, v):
+    def validate_owner(cls, v: Any) -> str:
+        """Validate GitHub repository owner from config or environment."""
         if not v:
             v = os.getenv("GITHUB_OWNER")
         if not v:
@@ -65,7 +67,8 @@ class GitHubConfig(BaseAdapterConfig):
 
     @field_validator("repo", mode="before")
     @classmethod
-    def validate_repo(cls, v):
+    def validate_repo(cls, v: Any) -> str:
+        """Validate GitHub repository name from config or environment."""
         if not v:
             v = os.getenv("GITHUB_REPO")
         if not v:
@@ -77,16 +80,17 @@ class JiraConfig(BaseAdapterConfig):
     """JIRA adapter configuration."""
 
     type: AdapterType = AdapterType.JIRA
-    server: Optional[str] = Field(None, env="JIRA_SERVER")
-    email: Optional[str] = Field(None, env="JIRA_EMAIL")
-    api_token: Optional[str] = Field(None, env="JIRA_API_TOKEN")
-    project_key: Optional[str] = Field(None, env="JIRA_PROJECT_KEY")
+    server: str | None = Field(None, env="JIRA_SERVER")
+    email: str | None = Field(None, env="JIRA_EMAIL")
+    api_token: str | None = Field(None, env="JIRA_API_TOKEN")
+    project_key: str | None = Field(None, env="JIRA_PROJECT_KEY")
     cloud: bool = True
     verify_ssl: bool = True
 
     @field_validator("server", mode="before")
     @classmethod
-    def validate_server(cls, v):
+    def validate_server(cls, v: Any) -> str:
+        """Validate JIRA server URL from config or environment."""
         if not v:
             v = os.getenv("JIRA_SERVER")
         if not v:
@@ -95,7 +99,8 @@ class JiraConfig(BaseAdapterConfig):
 
     @field_validator("email", mode="before")
     @classmethod
-    def validate_email(cls, v):
+    def validate_email(cls, v: Any) -> str:
+        """Validate JIRA user email from config or environment."""
         if not v:
             v = os.getenv("JIRA_EMAIL")
         if not v:
@@ -104,7 +109,8 @@ class JiraConfig(BaseAdapterConfig):
 
     @field_validator("api_token", mode="before")
     @classmethod
-    def validate_api_token(cls, v):
+    def validate_api_token(cls, v: Any) -> str:
+        """Validate JIRA API token from config or environment."""
         if not v:
             v = os.getenv("JIRA_API_TOKEN")
         if not v:
@@ -116,14 +122,14 @@ class LinearConfig(BaseAdapterConfig):
     """Linear adapter configuration."""
 
     type: AdapterType = AdapterType.LINEAR
-    api_key: Optional[str] = Field(None, env="LINEAR_API_KEY")
-    workspace: Optional[str] = None
-    team_key: Optional[str] = None  # Short team key like "BTA"
-    team_id: Optional[str] = None  # UUID team identifier
+    api_key: str | None = Field(None, env="LINEAR_API_KEY")
+    workspace: str | None = None
+    team_key: str | None = None  # Short team key like "BTA"
+    team_id: str | None = None  # UUID team identifier
     api_url: str = "https://api.linear.app/graphql"
 
     @model_validator(mode="after")
-    def validate_team_identifier(self):
+    def validate_team_identifier(self) -> "LinearConfig":
         """Ensure either team_key or team_id is provided."""
         if not self.team_key and not self.team_id:
             raise ValueError("Either team_key or team_id is required")
@@ -131,7 +137,8 @@ class LinearConfig(BaseAdapterConfig):
 
     @field_validator("api_key", mode="before")
     @classmethod
-    def validate_api_key(cls, v):
+    def validate_api_key(cls, v: Any) -> str:
+        """Validate Linear API key from config or environment."""
         if not v:
             v = os.getenv("LINEAR_API_KEY")
         if not v:
@@ -150,7 +157,7 @@ class QueueConfig(BaseModel):
     """Queue configuration."""
 
     provider: str = "sqlite"
-    connection_string: Optional[str] = None
+    connection_string: str | None = None
     batch_size: int = 10
     max_concurrent: int = 5
     retry_attempts: int = 3
@@ -162,7 +169,7 @@ class LoggingConfig(BaseModel):
 
     level: str = "INFO"
     format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-    file: Optional[str] = None
+    file: str | None = None
     max_size: str = "10MB"
     backup_count: int = 5
 
@@ -171,15 +178,15 @@ class AppConfig(BaseModel):
     """Main application configuration."""
 
     adapters: dict[
-        str, Union[GitHubConfig, JiraConfig, LinearConfig, AITrackdownConfig]
+        str, GitHubConfig | JiraConfig | LinearConfig | AITrackdownConfig
     ] = {}
     queue: QueueConfig = QueueConfig()
     logging: LoggingConfig = LoggingConfig()
     cache_ttl: int = 300  # Cache TTL in seconds
-    default_adapter: Optional[str] = None
+    default_adapter: str | None = None
 
     @model_validator(mode="after")
-    def validate_adapters(self):
+    def validate_adapters(self) -> "AppConfig":
         """Validate adapter configurations."""
         adapters = self.adapters
 
@@ -196,7 +203,7 @@ class AppConfig(BaseModel):
 
         return self
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         return self.adapters.get(adapter_name)
 
@@ -211,7 +218,7 @@ class ConfigurationManager:
     """Centralized configuration management with caching and validation."""
 
     _instance: Optional["ConfigurationManager"] = None
-    _config: Optional[AppConfig] = None
+    _config: AppConfig | None = None
     _config_file_paths: list[Path] = []
 
     def __new__(cls) -> "ConfigurationManager":
@@ -220,7 +227,7 @@ class ConfigurationManager:
             cls._instance = super().__new__(cls)
         return cls._instance
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize configuration manager."""
         if not hasattr(self, "_initialized"):
             self._initialized = True
@@ -266,7 +273,7 @@ class ConfigurationManager:
             logger.debug("No project-local config files found, will use defaults")
 
     @lru_cache(maxsize=1)
-    def load_config(self, config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+    def load_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Load and validate configuration from file and environment.
 
         Args:
@@ -437,7 +444,7 @@ class ConfigurationManager:
             return self.load_config()
         return self._config
 
-    def get_adapter_config(self, adapter_name: str) -> Optional[BaseAdapterConfig]:
+    def get_adapter_config(self, adapter_name: str) -> BaseAdapterConfig | None:
         """Get configuration for a specific adapter."""
         config = self.get_config()
         return config.get_adapter_config(adapter_name)
@@ -457,9 +464,7 @@ class ConfigurationManager:
         config = self.get_config()
         return config.logging
 
-    def reload_config(
-        self, config_file: Optional[Union[str, Path]] = None
-    ) -> AppConfig:
+    def reload_config(self, config_file: str | Path | None = None) -> AppConfig:
         """Reload configuration from file."""
         # Clear cache
         self.load_config.cache_clear()
@@ -492,7 +497,7 @@ class ConfigurationManager:
         self._config_cache[key] = value
         return value
 
-    def create_sample_config(self, output_path: Union[str, Path]) -> None:
+    def create_sample_config(self, output_path: str | Path) -> None:
         """Create a sample configuration file."""
         sample_config = {
             "adapters": {
@@ -539,11 +544,11 @@ def get_config() -> AppConfig:
     return config_manager.get_config()
 
 
-def get_adapter_config(adapter_name: str) -> Optional[BaseAdapterConfig]:
+def get_adapter_config(adapter_name: str) -> BaseAdapterConfig | None:
     """Get configuration for a specific adapter."""
     return config_manager.get_adapter_config(adapter_name)
 
 
-def reload_config(config_file: Optional[Union[str, Path]] = None) -> AppConfig:
+def reload_config(config_file: str | Path | None = None) -> AppConfig:
     """Reload the global configuration."""
     return config_manager.reload_config(config_file)

mcp_ticketer/core/env_discovery.py

@@ -6,15 +6,17 @@ environment files, including:
 - Support for multiple naming conventions
 - Project information extraction
 - Security validation
+- 1Password CLI integration for secret references
 """
 
 import logging
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from dotenv import dotenv_values
 
+from .onepassword_secrets import OnePasswordConfig, OnePasswordSecretsLoader
 from .project_config import AdapterType
 
 logger = logging.getLogger(__name__)
@@ -125,7 +127,7 @@ class DiscoveryResult:
     warnings: list[str] = field(default_factory=list)
     env_files_found: list[str] = field(default_factory=list)
 
-    def get_primary_adapter(self) -> Optional[DiscoveredAdapter]:
+    def get_primary_adapter(self) -> DiscoveredAdapter | None:
         """Get the adapter with highest confidence and completeness."""
         if not self.adapters:
             return None
@@ -136,7 +138,7 @@ class DiscoveryResult:
         )
         return sorted_adapters[0]
 
-    def get_adapter_by_type(self, adapter_type: str) -> Optional[DiscoveredAdapter]:
+    def get_adapter_by_type(self, adapter_type: str) -> DiscoveredAdapter | None:
         """Get discovered adapter by type."""
         for adapter in self.adapters:
             if adapter.adapter_type == adapter_type:
@@ -155,14 +157,27 @@ class EnvDiscovery:
         ".env.development",
     ]
 
-    def __init__(self, project_path: Optional[Path] = 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)
@@ -255,7 +285,7 @@ class EnvDiscovery:
 
     def _find_key_value(
         self, env_vars: dict[str, str], patterns: list[str]
-    ) -> Optional[str]:
+    ) -> str | None:
         """Find first matching key value from patterns.
 
         Args:
@@ -273,7 +303,7 @@ class EnvDiscovery:
 
     def _detect_linear(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect Linear adapter configuration.
 
         Args:
@@ -327,7 +357,7 @@ class EnvDiscovery:
 
     def _detect_github(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect GitHub adapter configuration.
 
         Args:
@@ -386,7 +416,7 @@ class EnvDiscovery:
 
     def _detect_jira(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect JIRA adapter configuration.
 
         Args:
@@ -442,7 +472,7 @@ class EnvDiscovery:
 
     def _detect_aitrackdown(
         self, env_vars: dict[str, str], found_in: str
-    ) -> Optional[DiscoveredAdapter]:
+    ) -> DiscoveredAdapter | None:
         """Detect AITrackdown adapter configuration.
 
         Args:
@@ -622,8 +652,8 @@ class EnvDiscovery:
         return warnings
 
 
-def discover_config(project_path: Optional[Path] = None) -> DiscoveryResult:
-    """Convenience function to discover configuration.
+def discover_config(project_path: Path | None = None) -> DiscoveryResult:
+    """Discover configuration from environment files.
 
     Args:
         project_path: Path to project root (defaults to cwd)

mcp_ticketer/core/env_loader.py

@@ -12,7 +12,7 @@ import logging
 import os
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -25,12 +25,13 @@ class EnvKeyConfig:
     aliases: list[str]
     description: str
     required: bool = False
-    default: Optional[str] = None
+    default: str | None = None
 
 
 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
@@ -105,7 +106,7 @@ class UnifiedEnvLoader:
         ),
     }
 
-    def __init__(self, project_root: Optional[Path] = None):
+    def __init__(self, project_root: Path | None = None):
         """Initialize the environment loader.
 
         Args:
@@ -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:
@@ -177,8 +178,8 @@ class UnifiedEnvLoader:
             logger.warning(f"Failed to load {env_file}: {e}")
 
     def get_value(
-        self, config_key: str, config: Optional[dict[str, Any]] = None
-    ) -> Optional[str]:
+        self, config_key: str, config: dict[str, Any] | None = None
+    ) -> str | None:
         """Get a configuration value using the key alias system.
 
         Args:
@@ -230,7 +231,7 @@ class UnifiedEnvLoader:
         return None
 
     def get_adapter_config(
-        self, adapter_name: str, base_config: Optional[dict[str, Any]] = None
+        self, adapter_name: str, base_config: dict[str, Any] | None = None
     ) -> dict[str, Any]:
         """Get complete configuration for an adapter with environment variable resolution.
 
@@ -307,7 +308,7 @@ class UnifiedEnvLoader:
 
 
 # Global instance
-_env_loader: Optional[UnifiedEnvLoader] = None
+_env_loader: UnifiedEnvLoader | None = None
 
 
 def get_env_loader() -> UnifiedEnvLoader:
@@ -319,9 +320,9 @@ def get_env_loader() -> UnifiedEnvLoader:
 
 
 def load_adapter_config(
-    adapter_name: str, base_config: Optional[dict[str, Any]] = None
+    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