mcp-ticketer 0.1.37__py3-none-any.whl → 0.1.39__py3-none-any.whl

mcp_ticketer/cli/utils.py

@@ -210,10 +210,14 @@ class CommonPatterns:
             config = CommonPatterns.load_config()
             adapter_name = config.get("default_adapter", "aitrackdown")
 
-        # Add to queue
+        # Add to queue with explicit project directory
+        from pathlib import Path
         queue = Queue()
         queue_id = queue.add(
-            ticket_data=ticket_data, adapter=adapter_name, operation=operation
+            ticket_data=ticket_data,
+            adapter=adapter_name,
+            operation=operation,
+            project_dir=str(Path.cwd())  # Explicitly pass current project directory
         )
 
         if show_progress:

mcp_ticketer/core/env_loader.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""
+Unified Environment Loading System for MCP Ticketer.
+
+This module provides a resilient environment loading system that:
+1. Supports multiple naming conventions for each configuration key
+2. Loads from multiple sources (.env.local, .env, environment variables)
+3. Works consistently across CLI, worker processes, and MCP server
+4. Provides fallback mechanisms for different key aliases
+"""
+
+import os
+import logging
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Union
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EnvKeyConfig:
+    """Configuration for environment variable key aliases."""
+    primary_key: str
+    aliases: List[str]
+    description: str
+    required: bool = False
+    default: Optional[str] = None
+
+
+class UnifiedEnvLoader:
+    """
+    Unified environment loader that handles multiple naming conventions
+    and provides consistent environment loading across all contexts.
+    """
+    
+    # Define key aliases for all adapters
+    KEY_MAPPINGS = {
+        # Linear adapter keys
+        "linear_api_key": EnvKeyConfig(
+            primary_key="LINEAR_API_KEY",
+            aliases=["LINEAR_TOKEN", "LINEAR_ACCESS_TOKEN", "LINEAR_AUTH_TOKEN"],
+            description="Linear API key",
+            required=True
+        ),
+        "linear_team_id": EnvKeyConfig(
+            primary_key="LINEAR_TEAM_ID",
+            aliases=["LINEAR_TEAM_UUID", "LINEAR_TEAM_IDENTIFIER"],
+            description="Linear team ID (UUID)",
+            required=False
+        ),
+        "linear_team_key": EnvKeyConfig(
+            primary_key="LINEAR_TEAM_KEY",
+            aliases=["LINEAR_TEAM_IDENTIFIER", "LINEAR_TEAM_NAME"],
+            description="Linear team key (short name)",
+            required=False
+        ),
+        
+        # JIRA adapter keys
+        "jira_server": EnvKeyConfig(
+            primary_key="JIRA_SERVER",
+            aliases=["JIRA_URL", "JIRA_HOST", "JIRA_BASE_URL"],
+            description="JIRA server URL",
+            required=True
+        ),
+        "jira_email": EnvKeyConfig(
+            primary_key="JIRA_EMAIL",
+            aliases=["JIRA_USER", "JIRA_USERNAME", "JIRA_ACCESS_USER"],
+            description="JIRA user email",
+            required=True
+        ),
+        "jira_api_token": EnvKeyConfig(
+            primary_key="JIRA_API_TOKEN",
+            aliases=["JIRA_TOKEN", "JIRA_ACCESS_TOKEN", "JIRA_AUTH_TOKEN", "JIRA_PASSWORD"],
+            description="JIRA API token",
+            required=True
+        ),
+        "jira_project_key": EnvKeyConfig(
+            primary_key="JIRA_PROJECT_KEY",
+            aliases=["JIRA_PROJECT", "JIRA_PROJECT_ID"],
+            description="JIRA project key",
+            required=False
+        ),
+        
+        # GitHub adapter keys
+        "github_token": EnvKeyConfig(
+            primary_key="GITHUB_TOKEN",
+            aliases=["GITHUB_ACCESS_TOKEN", "GITHUB_API_TOKEN", "GITHUB_AUTH_TOKEN"],
+            description="GitHub access token",
+            required=True
+        ),
+        "github_owner": EnvKeyConfig(
+            primary_key="GITHUB_OWNER",
+            aliases=["GITHUB_USER", "GITHUB_USERNAME", "GITHUB_ORG"],
+            description="GitHub repository owner",
+            required=True
+        ),
+        "github_repo": EnvKeyConfig(
+            primary_key="GITHUB_REPO",
+            aliases=["GITHUB_REPOSITORY", "GITHUB_REPO_NAME"],
+            description="GitHub repository name",
+            required=True
+        ),
+    }
+    
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize the environment loader.
+        
+        Args:
+            project_root: Project root directory. If None, will auto-detect.
+        """
+        self.project_root = project_root or self._find_project_root()
+        self._env_cache: Dict[str, str] = {}
+        self._load_env_files()
+    
+    def _find_project_root(self) -> Path:
+        """Find the project root directory."""
+        current = Path.cwd()
+        
+        # Look for common project indicators
+        indicators = [".mcp-ticketer", ".git", "pyproject.toml", "setup.py"]
+        
+        while current != current.parent:
+            if any((current / indicator).exists() for indicator in indicators):
+                return current
+            current = current.parent
+        
+        # Fallback to current directory
+        return Path.cwd()
+    
+    def _load_env_files(self):
+        """Load environment variables from .env files."""
+        env_files = [
+            self.project_root / ".env.local",
+            self.project_root / ".env",
+            Path.home() / ".mcp-ticketer" / ".env",
+        ]
+        
+        for env_file in env_files:
+            if env_file.exists():
+                logger.debug(f"Loading environment from: {env_file}")
+                self._load_env_file(env_file)
+    
+    def _load_env_file(self, env_file: Path):
+        """Load variables from a single .env file."""
+        try:
+            with open(env_file, 'r') as f:
+                for line_num, line in enumerate(f, 1):
+                    line = line.strip()
+                    
+                    # Skip empty lines and comments
+                    if not line or line.startswith('#'):
+                        continue
+                    
+                    # Parse KEY=VALUE format
+                    if '=' in line:
+                        key, value = line.split('=', 1)
+                        key = key.strip()
+                        value = value.strip()
+                        
+                        # Remove quotes if present
+                        if value.startswith('"') and value.endswith('"'):
+                            value = value[1:-1]
+                        elif value.startswith("'") and value.endswith("'"):
+                            value = value[1:-1]
+                        
+                        # Only set if not already in environment
+                        if key not in os.environ:
+                            os.environ[key] = value
+                            self._env_cache[key] = value
+                            logger.debug(f"Loaded {key} from {env_file}")
+                        
+        except Exception as e:
+            logger.warning(f"Failed to load {env_file}: {e}")
+    
+    def get_value(self, config_key: str, config: Optional[Dict[str, Any]] = None) -> Optional[str]:
+        """
+        Get a configuration value using the key alias system.
+        
+        Args:
+            config_key: The configuration key (e.g., 'linear_api_key')
+            config: Optional configuration dictionary to check first
+            
+        Returns:
+            The value if found, None otherwise
+        """
+        if config_key not in self.KEY_MAPPINGS:
+            logger.warning(f"Unknown configuration key: {config_key}")
+            return None
+        
+        key_config = self.KEY_MAPPINGS[config_key]
+        
+        # 1. Check provided config dictionary first
+        if config:
+            # Check for the config key itself (without adapter prefix)
+            simple_key = config_key.split('_', 1)[1] if '_' in config_key else config_key
+            if simple_key in config:
+                value = config[simple_key]
+                if value:
+                    logger.debug(f"Found {config_key} in config as {simple_key}")
+                    return str(value)
+        
+        # 2. Check environment variables (primary key first, then aliases)
+        all_keys = [key_config.primary_key] + key_config.aliases
+        
+        for env_key in all_keys:
+            value = os.getenv(env_key)
+            if value:
+                logger.debug(f"Found {config_key} as {env_key}")
+                return value
+        
+        # 3. Return default if available
+        if key_config.default:
+            logger.debug(f"Using default for {config_key}")
+            return key_config.default
+        
+        # 4. Log if required key is missing
+        if key_config.required:
+            logger.warning(f"Required configuration key {config_key} not found. Tried: {all_keys}")
+        
+        return None
+    
+    def get_adapter_config(self, adapter_name: str, base_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Get complete configuration for an adapter with environment variable resolution.
+        
+        Args:
+            adapter_name: Name of the adapter ('linear', 'jira', 'github')
+            base_config: Base configuration dictionary
+            
+        Returns:
+            Complete configuration with environment variables resolved
+        """
+        config = base_config.copy() if base_config else {}
+        
+        # Get adapter-specific keys
+        adapter_keys = [key for key in self.KEY_MAPPINGS.keys() if key.startswith(f"{adapter_name}_")]
+        
+        for config_key in adapter_keys:
+            # Remove adapter prefix for the config key
+            simple_key = config_key.split('_', 1)[1]
+            
+            # Only set if not already in config or if config value is empty
+            if simple_key not in config or not config[simple_key]:
+                value = self.get_value(config_key, config)
+                if value:
+                    config[simple_key] = value
+        
+        return config
+    
+    def validate_adapter_config(self, adapter_name: str, config: Dict[str, Any]) -> List[str]:
+        """
+        Validate that all required configuration is present for an adapter.
+        
+        Args:
+            adapter_name: Name of the adapter
+            config: Configuration dictionary
+            
+        Returns:
+            List of missing required keys (empty if all required keys are present)
+        """
+        missing_keys = []
+        adapter_keys = [key for key in self.KEY_MAPPINGS.keys() if key.startswith(f"{adapter_name}_")]
+        
+        for config_key in adapter_keys:
+            key_config = self.KEY_MAPPINGS[config_key]
+            if key_config.required:
+                simple_key = config_key.split('_', 1)[1]
+                if simple_key not in config or not config[simple_key]:
+                    missing_keys.append(f"{simple_key} ({key_config.description})")
+        
+        return missing_keys
+    
+    def get_debug_info(self) -> Dict[str, Any]:
+        """Get debug information about environment loading."""
+        return {
+            "project_root": str(self.project_root),
+            "env_files_checked": [
+                str(self.project_root / ".env.local"),
+                str(self.project_root / ".env"),
+                str(Path.home() / ".mcp-ticketer" / ".env"),
+            ],
+            "loaded_keys": list(self._env_cache.keys()),
+            "available_configs": list(self.KEY_MAPPINGS.keys()),
+        }
+
+
+# Global instance
+_env_loader: Optional[UnifiedEnvLoader] = None
+
+
+def get_env_loader() -> UnifiedEnvLoader:
+    """Get the global environment loader instance."""
+    global _env_loader
+    if _env_loader is None:
+        _env_loader = UnifiedEnvLoader()
+    return _env_loader
+
+
+def load_adapter_config(adapter_name: str, base_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """
+    Convenience function to load adapter configuration with environment variables.
+    
+    Args:
+        adapter_name: Name of the adapter ('linear', 'jira', 'github')
+        base_config: Base configuration dictionary
+        
+    Returns:
+        Complete configuration with environment variables resolved
+    """
+    return get_env_loader().get_adapter_config(adapter_name, base_config)
+
+
+def validate_adapter_config(adapter_name: str, config: Dict[str, Any]) -> List[str]:
+    """
+    Convenience function to validate adapter configuration.
+    
+    Args:
+        adapter_name: Name of the adapter
+        config: Configuration dictionary
+        
+    Returns:
+        List of missing required keys (empty if all required keys are present)
+    """
+    return get_env_loader().validate_adapter_config(adapter_name, config)

mcp_ticketer/core/models.py

@@ -1,4 +1,26 @@
-"""Simplified Universal Ticket models using Pydantic."""
+"""Universal Ticket models using Pydantic.
+
+This module defines the core data models for the MCP Ticketer system, providing
+a unified interface across different ticket management platforms (Linear, JIRA,
+GitHub, etc.).
+
+The models follow a hierarchical structure:
+- Epic: Strategic level containers (Projects in Linear, Epics in JIRA)
+- Issue: Standard work items (Issues in GitHub, Stories in JIRA)
+- Task: Sub-work items (Sub-issues in Linear, Sub-tasks in JIRA)
+
+All models use Pydantic v2 for validation and serialization, ensuring type safety
+and consistent data handling across adapters.
+
+Example:
+    >>> from mcp_ticketer.core.models import Task, Priority, TicketState
+    >>> task = Task(
+    ...     title="Fix authentication bug",
+    ...     priority=Priority.HIGH,
+    ...     state=TicketState.IN_PROGRESS
+    ... )
+    >>> print(task.model_dump_json())
+"""
 
 from datetime import datetime
 from enum import Enum
@@ -8,7 +30,19 @@ from pydantic import BaseModel, ConfigDict, Field
 
 
 class Priority(str, Enum):
-    """Universal priority levels."""
+    """Universal priority levels for tickets.
+
+    These priority levels are mapped to platform-specific priorities:
+    - Linear: 1 (Critical), 2 (High), 3 (Medium), 4 (Low)
+    - JIRA: Highest, High, Medium, Low
+    - GitHub: P0/critical, P1/high, P2/medium, P3/low labels
+
+    Attributes:
+        LOW: Low priority, non-urgent work
+        MEDIUM: Standard priority, default for most work
+        HIGH: High priority, should be addressed soon
+        CRITICAL: Critical priority, urgent work requiring immediate attention
+    """
 
     LOW = "low"
     MEDIUM = "medium"
@@ -17,7 +51,22 @@ class Priority(str, Enum):
 
 
 class TicketType(str, Enum):
-    """Ticket type hierarchy."""
+    """Ticket type hierarchy for organizing work.
+
+    Defines the three-level hierarchy used across all platforms:
+
+    Platform Mappings:
+    - Linear: Project (Epic) → Issue (Issue) → Sub-issue (Task)
+    - JIRA: Epic (Epic) → Story/Task (Issue) → Sub-task (Task)
+    - GitHub: Milestone (Epic) → Issue (Issue) → Checklist item (Task)
+    - Aitrackdown: Epic file → Issue file → Task reference
+
+    Attributes:
+        EPIC: Strategic level containers for large features or initiatives
+        ISSUE: Standard work items, the primary unit of work
+        TASK: Sub-work items, smaller pieces of an issue
+        SUBTASK: Alias for TASK for backward compatibility
+    """
 
     EPIC = "epic"  # Strategic level (Projects in Linear, Milestones in GitHub)
     ISSUE = "issue"  # Work item level (standard issues/tasks)
@@ -26,7 +75,33 @@ class TicketType(str, Enum):
 
 
 class TicketState(str, Enum):
-    """Universal ticket states with state machine abstraction."""
+    """Universal ticket states with workflow state machine.
+
+    Implements a standardized workflow that maps to different platform states:
+
+    State Flow:
+        OPEN → IN_PROGRESS → READY → TESTED → DONE → CLOSED
+          ↓         ↓          ↓
+        CLOSED   WAITING    BLOCKED
+                    ↓          ↓
+                IN_PROGRESS ← IN_PROGRESS
+
+    Platform Mappings:
+    - Linear: Backlog (OPEN), Started (IN_PROGRESS), Completed (DONE), Canceled (CLOSED)
+    - JIRA: To Do (OPEN), In Progress (IN_PROGRESS), Done (DONE), etc.
+    - GitHub: open (OPEN), closed (CLOSED) + labels for extended states
+    - Aitrackdown: File-based state tracking
+
+    Attributes:
+        OPEN: Initial state, work not yet started
+        IN_PROGRESS: Work is actively being done
+        READY: Work is complete and ready for review/testing
+        TESTED: Work has been tested and verified
+        DONE: Work is complete and accepted
+        WAITING: Work is paused waiting for external dependency
+        BLOCKED: Work is blocked by an impediment
+        CLOSED: Final state, work is closed/archived
+    """
 
     OPEN = "open"
     IN_PROGRESS = "in_progress"
@@ -39,7 +114,14 @@ class TicketState(str, Enum):
 
     @classmethod
     def valid_transitions(cls) -> dict[str, list[str]]:
-        """Define valid state transitions."""
+        """Define valid state transitions for workflow enforcement.
+
+        Returns:
+            Dictionary mapping each state to list of valid target states
+
+        Note:
+            CLOSED is a terminal state with no valid transitions
+        """
         return {
             cls.OPEN: [cls.IN_PROGRESS, cls.WAITING, cls.BLOCKED, cls.CLOSED],
             cls.IN_PROGRESS: [cls.READY, cls.WAITING, cls.BLOCKED, cls.OPEN],
@@ -52,12 +134,56 @@ class TicketState(str, Enum):
         }
 
     def can_transition_to(self, target: "TicketState") -> bool:
-        """Check if transition to target state is valid."""
+        """Check if transition to target state is valid.
+
+        Validates state transitions according to the defined workflow rules.
+        This prevents invalid state changes and ensures workflow integrity.
+
+        Args:
+            target: The state to transition to
+
+        Returns:
+            True if the transition is valid, False otherwise
+
+        Example:
+            >>> state = TicketState.OPEN
+            >>> state.can_transition_to(TicketState.IN_PROGRESS)
+            True
+            >>> state.can_transition_to(TicketState.DONE)
+            False
+        """
         return target.value in self.valid_transitions().get(self, [])
 
 
 class BaseTicket(BaseModel):
-    """Base model for all ticket types."""
+    """Base model for all ticket types with universal field mapping.
+
+    Provides common fields and functionality shared across all ticket types
+    (Epic, Task, Comment). Uses Pydantic v2 for validation and serialization.
+
+    The metadata field allows adapters to store platform-specific information
+    while maintaining the universal interface.
+
+    Attributes:
+        id: Unique identifier assigned by the platform
+        title: Human-readable title (required, min 1 character)
+        description: Optional detailed description or body text
+        state: Current workflow state (defaults to OPEN)
+        priority: Priority level (defaults to MEDIUM)
+        tags: List of tags/labels for categorization
+        created_at: Timestamp when ticket was created
+        updated_at: Timestamp when ticket was last modified
+        metadata: Platform-specific data and field mappings
+
+    Example:
+        >>> ticket = BaseTicket(
+        ...     title="Fix login issue",
+        ...     description="Users cannot log in with SSO",
+        ...     priority=Priority.HIGH,
+        ...     tags=["bug", "authentication"]
+        ... )
+        >>> ticket.state = TicketState.IN_PROGRESS
+    """
 
     model_config = ConfigDict(use_enum_values=True)
 
@@ -77,7 +203,32 @@ class BaseTicket(BaseModel):
 
 
 class Epic(BaseTicket):
-    """Epic - highest level container for work (Projects in Linear, Milestones in GitHub)."""
+    """Epic - highest level container for strategic work initiatives.
+
+    Epics represent large features, projects, or initiatives that contain
+    multiple related issues. They map to different concepts across platforms:
+
+    Platform Mappings:
+    - Linear: Projects (with issues as children)
+    - JIRA: Epics (with stories/tasks as children)
+    - GitHub: Milestones (with issues as children)
+    - Aitrackdown: Epic files (with issue references)
+
+    Epics sit at the top of the hierarchy and cannot have parent epics.
+    They can contain multiple child issues, which in turn can contain tasks.
+
+    Attributes:
+        ticket_type: Always TicketType.EPIC (frozen field)
+        child_issues: List of issue IDs that belong to this epic
+
+    Example:
+        >>> epic = Epic(
+        ...     title="User Authentication System",
+        ...     description="Complete overhaul of authentication",
+        ...     priority=Priority.HIGH
+        ... )
+        >>> epic.child_issues = ["ISSUE-123", "ISSUE-124"]
+    """
 
     ticket_type: TicketType = Field(
         default=TicketType.EPIC, frozen=True, description="Always EPIC type"
@@ -89,9 +240,11 @@ class Epic(BaseTicket):
     def validate_hierarchy(self) -> list[str]:
         """Validate epic hierarchy rules.
 
-        Returns:
-            List of validation errors (empty if valid)
+        Epics are at the top of the hierarchy and have no parent constraints.
+        This method is provided for consistency with other ticket types.
 
+        Returns:
+            Empty list (epics have no hierarchy constraints)
         """
         # Epics don't have parents in our hierarchy
         return []

mcp_ticketer/mcp/server.py

@@ -1745,10 +1745,10 @@ async def _handle_system_health(self, arguments: dict[str, Any]) -> dict[str, An
 
         # Check queue system
         try:
-            from ..queue.manager import QueueManager
-            queue_manager = QueueManager()
-            worker_status = queue_manager.get_worker_status()
-            stats = queue_manager.get_queue_stats()
+            from ..queue.manager import WorkerManager
+            worker_manager = WorkerManager()
+            worker_status = worker_manager.get_status()
+            stats = worker_manager.queue.get_stats()
 
             total = stats.get("total", 0)
             failed = stats.get("failed", 0)

mcp_ticketer/queue/manager.py

@@ -99,8 +99,23 @@ class WorkerManager:
             return False
 
         try:
-            # Start worker in subprocess
-            cmd = [sys.executable, "-m", "mcp_ticketer.queue.run_worker"]
+            # Start worker in subprocess using the same Python executable as the CLI
+            # This ensures the worker can import mcp_ticketer modules
+            python_executable = self._get_python_executable()
+            cmd = [python_executable, "-m", "mcp_ticketer.queue.run_worker"]
+
+            # Prepare environment for subprocess
+            # Ensure the subprocess gets the same environment as the parent
+            subprocess_env = os.environ.copy()
+
+            # Explicitly load environment variables from .env.local if it exists
+            env_file = Path.cwd() / ".env.local"
+            if env_file.exists():
+                logger.debug(f"Loading environment from {env_file} for subprocess")
+                from dotenv import dotenv_values
+                env_vars = dotenv_values(env_file)
+                subprocess_env.update(env_vars)
+                logger.debug(f"Added {len(env_vars)} environment variables from .env.local")
 
             # Start as background process
             process = subprocess.Popen(
@@ -108,6 +123,8 @@ class WorkerManager:
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
                 start_new_session=True,
+                env=subprocess_env,  # Pass environment explicitly
+                cwd=str(Path.cwd()),  # Ensure correct working directory
             )
 
             # Save PID
@@ -256,6 +273,44 @@ class WorkerManager:
         except (OSError, ValueError):
             return None
 
+    def _get_python_executable(self) -> str:
+        """Get the correct Python executable for the worker subprocess.
+
+        This ensures the worker uses the same Python environment as the CLI,
+        which is critical for module imports to work correctly.
+
+        Returns:
+            Path to Python executable
+        """
+        # First, try to detect if we're running in a pipx environment
+        # by checking if the current executable is in a pipx venv
+        current_executable = sys.executable
+
+        # Check if we're in a pipx venv (path contains /pipx/venvs/)
+        if "/pipx/venvs/" in current_executable:
+            logger.debug(f"Using pipx Python executable: {current_executable}")
+            return current_executable
+
+        # Check if we can find the mcp-ticketer executable and extract its Python
+        import shutil
+        mcp_ticketer_path = shutil.which("mcp-ticketer")
+        if mcp_ticketer_path:
+            try:
+                # Read the shebang line to get the Python executable
+                with open(mcp_ticketer_path, 'r') as f:
+                    first_line = f.readline().strip()
+                    if first_line.startswith("#!") and "python" in first_line:
+                        python_path = first_line[2:].strip()
+                        if os.path.exists(python_path):
+                            logger.debug(f"Using Python from mcp-ticketer shebang: {python_path}")
+                            return python_path
+            except (OSError, IOError):
+                pass
+
+        # Fallback to sys.executable
+        logger.debug(f"Using sys.executable as fallback: {current_executable}")
+        return current_executable
+
     def _cleanup(self):
         """Clean up lock and PID files."""
         self._release_lock()

mcp_ticketer/queue/run_worker.py

@@ -15,7 +15,12 @@ logger = logging.getLogger(__name__)
 
 def main():
     """Run the worker process."""
+    import sys
+    import os
     logger.info("Starting standalone worker process")
+    logger.info(f"Worker Python executable: {sys.executable}")
+    logger.info(f"Worker working directory: {os.getcwd()}")
+    logger.info(f"Worker Python path: {sys.path[:3]}...")  # Show first 3 entries
 
     try:
         # Create queue and worker