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

mcp_ticketer/mcp/server/tools/user_ticket_tools.py

@@ -0,0 +1,382 @@
+"""User-specific ticket management tools.
+
+This module provides tools for managing tickets from a user's perspective,
+including listing assigned tickets and transitioning tickets through workflow
+states with validation.
+
+Design Decision: Workflow State Validation
+------------------------------------------
+State transitions are validated using TicketState.can_transition_to() to ensure
+tickets follow the defined workflow. This prevents invalid state changes that
+could break integrations or confuse team members.
+
+Valid workflow transitions:
+- OPEN → IN_PROGRESS, WAITING, BLOCKED, CLOSED
+- IN_PROGRESS → READY, WAITING, BLOCKED, OPEN
+- READY → TESTED, IN_PROGRESS, BLOCKED
+- TESTED → DONE, IN_PROGRESS
+- DONE → CLOSED
+- WAITING/BLOCKED → OPEN, IN_PROGRESS, CLOSED
+- CLOSED → (no transitions, terminal state)
+
+Performance Considerations:
+- get_my_tickets uses adapter's native filtering when available
+- Falls back to client-side filtering for adapters without assignee filter
+- State transition validation is O(1) lookup in predefined state machine
+"""
+
+from pathlib import Path
+from typing import Any
+
+from ....core.models import TicketState
+from ....core.project_config import ConfigResolver, TicketerConfig
+from ..server_sdk import get_adapter, mcp
+
+
+def get_config_resolver() -> ConfigResolver:
+    """Get configuration resolver for current project.
+
+    Returns:
+        ConfigResolver instance for current working directory
+
+    """
+    return ConfigResolver(project_path=Path.cwd())
+
+
+@mcp.tool()
+async def get_my_tickets(
+    state: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Get tickets assigned to the configured default user.
+
+    Retrieves tickets assigned to the user specified in default_user configuration.
+    Requires default_user to be set via config_set_default_user().
+
+    Args:
+        state: Optional state filter - must be one of: open, in_progress, ready,
+            tested, done, closed, waiting, blocked
+        limit: Maximum number of tickets to return (default: 10, max: 100)
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - tickets: List of ticket objects assigned to user
+        - count: Number of tickets returned
+        - user: User ID that was queried
+        - state_filter: State filter applied (if any)
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await get_my_tickets(state="in_progress", limit=5)
+        >>> print(result)
+        {
+            "status": "completed",
+            "tickets": [
+                {"id": "TICKET-1", "title": "Fix bug", "state": "in_progress"},
+                {"id": "TICKET-2", "title": "Add feature", "state": "in_progress"}
+            ],
+            "count": 2,
+            "user": "user@example.com",
+            "state_filter": "in_progress"
+        }
+
+    Error Conditions:
+        - No default user configured: Returns error with setup instructions
+        - Invalid state: Returns error with valid state options
+        - Adapter query failure: Returns error with details
+
+    Usage Notes:
+        - Requires default_user to be set in configuration
+        - Use config_set_default_user() to configure the user first
+        - Limit is capped at 100 to prevent performance issues
+
+    """
+    try:
+        # Validate limit
+        if limit > 100:
+            limit = 100
+
+        # Load configuration to get default user
+        resolver = get_config_resolver()
+        config = resolver.load_project_config() or TicketerConfig()
+
+        if not config.default_user:
+            return {
+                "status": "error",
+                "error": "No default user configured. Use config_set_default_user() to set a default user first.",
+                "setup_command": "config_set_default_user",
+            }
+
+        # Validate state if provided
+        state_filter = None
+        if state is not None:
+            try:
+                state_filter = TicketState(state.lower())
+            except ValueError:
+                valid_states = [s.value for s in TicketState]
+                return {
+                    "status": "error",
+                    "error": f"Invalid state '{state}'. Must be one of: {', '.join(valid_states)}",
+                    "valid_states": valid_states,
+                }
+
+        # Build filters
+        filters: dict[str, Any] = {"assignee": config.default_user}
+        if state_filter:
+            filters["state"] = state_filter
+
+        # Query adapter
+        adapter = get_adapter()
+        tickets = await adapter.list(limit=limit, offset=0, filters=filters)
+
+        return {
+            "status": "completed",
+            "tickets": [ticket.model_dump() for ticket in tickets],
+            "count": len(tickets),
+            "user": config.default_user,
+            "state_filter": state if state else "all",
+            "limit": limit,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to retrieve tickets: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def get_available_transitions(ticket_id: str) -> dict[str, Any]:
+    """Get valid next states for a ticket based on workflow rules.
+
+    Retrieves the ticket's current state and returns all valid target states
+    according to the defined workflow state machine. This helps AI agents and
+    users understand which state transitions are allowed.
+
+    Args:
+        ticket_id: Unique identifier of the ticket
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - ticket_id: ID of the queried ticket
+        - current_state: Current workflow state
+        - available_transitions: List of valid target states
+        - transition_descriptions: Human-readable descriptions of each transition
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await get_available_transitions("TICKET-123")
+        >>> print(result)
+        {
+            "status": "completed",
+            "ticket_id": "TICKET-123",
+            "current_state": "in_progress",
+            "available_transitions": ["ready", "waiting", "blocked", "open"],
+            "transition_descriptions": {
+                "ready": "Mark work as complete and ready for review",
+                "waiting": "Pause work while waiting for external dependency",
+                "blocked": "Work is blocked by an impediment",
+                "open": "Move back to backlog"
+            }
+        }
+
+    Error Conditions:
+        - Ticket not found: Returns error with ticket ID
+        - Adapter query failure: Returns error with details
+        - Terminal state (CLOSED): Returns empty transitions list
+
+    Usage Notes:
+        - CLOSED is a terminal state with no valid transitions
+        - Use this before ticket_transition() to validate intended state change
+        - Transition validation prevents workflow violations
+
+    """
+    try:
+        # Get ticket from adapter
+        adapter = get_adapter()
+        ticket = await adapter.read(ticket_id)
+
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Get current state
+        current_state = ticket.state
+
+        # Get valid transitions from state machine
+        valid_transitions = TicketState.valid_transitions()
+        # Handle both TicketState enum and string values
+        if isinstance(current_state, str):
+            current_state = TicketState(current_state)
+        available = valid_transitions.get(current_state, [])
+
+        # Create human-readable descriptions
+        descriptions = {
+            TicketState.OPEN: "Move to backlog (not yet started)",
+            TicketState.IN_PROGRESS: "Begin active work on ticket",
+            TicketState.READY: "Mark as complete and ready for review/testing",
+            TicketState.TESTED: "Mark as tested and verified",
+            TicketState.DONE: "Mark as complete and accepted",
+            TicketState.WAITING: "Pause work while waiting for external dependency",
+            TicketState.BLOCKED: "Work is blocked by an impediment",
+            TicketState.CLOSED: "Close and archive ticket (final state)",
+        }
+
+        transition_descriptions = {
+            state.value: descriptions.get(state, "") for state in available
+        }
+
+        return {
+            "status": "completed",
+            "ticket_id": ticket_id,
+            "current_state": current_state.value,
+            "available_transitions": [state.value for state in available],
+            "transition_descriptions": transition_descriptions,
+            "is_terminal": len(available) == 0,
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to get available transitions: {str(e)}",
+        }
+
+
+@mcp.tool()
+async def ticket_transition(
+    ticket_id: str,
+    to_state: str,
+    comment: str | None = None,
+) -> dict[str, Any]:
+    """Move ticket through workflow with validation and optional comment.
+
+    Transitions a ticket to a new state, validating the transition against the
+    defined workflow rules. Optionally adds a comment explaining the transition.
+
+    Workflow State Machine:
+        OPEN → IN_PROGRESS, WAITING, BLOCKED, CLOSED
+        IN_PROGRESS → READY, WAITING, BLOCKED, OPEN
+        READY → TESTED, IN_PROGRESS, BLOCKED
+        TESTED → DONE, IN_PROGRESS
+        DONE → CLOSED
+        WAITING → OPEN, IN_PROGRESS, CLOSED
+        BLOCKED → OPEN, IN_PROGRESS, CLOSED
+        CLOSED → (no transitions)
+
+    Args:
+        ticket_id: Unique identifier of the ticket to transition
+        to_state: Target state - must be valid for current state
+        comment: Optional comment explaining the transition reason
+
+    Returns:
+        Dictionary containing:
+        - status: "completed" or "error"
+        - ticket: Updated ticket object with new state
+        - previous_state: State before transition
+        - new_state: State after transition
+        - comment_added: Whether a comment was added (if applicable)
+        - error: Error details (if failed)
+
+    Example:
+        >>> result = await ticket_transition(
+        ...     "TICKET-123",
+        ...     "ready",
+        ...     "Work complete, ready for code review"
+        ... )
+        >>> print(result)
+        {
+            "status": "completed",
+            "ticket": {"id": "TICKET-123", "state": "ready", ...},
+            "previous_state": "in_progress",
+            "new_state": "ready",
+            "comment_added": True
+        }
+
+    Error Conditions:
+        - Ticket not found: Returns error with ticket ID
+        - Invalid transition: Returns error with valid options
+        - Invalid state name: Returns error with valid states
+        - Adapter update failure: Returns error with details
+
+    Usage Notes:
+        - Use get_available_transitions() first to see valid options
+        - Comments are adapter-dependent (some may not support them)
+        - Validation prevents workflow violations
+        - Terminal state (CLOSED) has no valid transitions
+
+    """
+    try:
+        # Get ticket from adapter
+        adapter = get_adapter()
+        ticket = await adapter.read(ticket_id)
+
+        if ticket is None:
+            return {
+                "status": "error",
+                "error": f"Ticket {ticket_id} not found",
+            }
+
+        # Validate target state
+        try:
+            target_state = TicketState(to_state.lower())
+        except ValueError:
+            valid_states = [s.value for s in TicketState]
+            return {
+                "status": "error",
+                "error": f"Invalid state '{to_state}'. Must be one of: {', '.join(valid_states)}",
+                "valid_states": valid_states,
+            }
+
+        # Store current state for response
+        current_state = ticket.state
+        # Handle both TicketState enum and string values
+        if isinstance(current_state, str):
+            current_state = TicketState(current_state)
+
+        # Validate transition
+        if not current_state.can_transition_to(target_state):
+            valid_transitions = TicketState.valid_transitions().get(current_state, [])
+            valid_values = [s.value for s in valid_transitions]
+            return {
+                "status": "error",
+                "error": f"Invalid transition from '{current_state.value}' to '{target_state.value}'",
+                "current_state": current_state.value,
+                "valid_transitions": valid_values,
+                "message": f"Cannot transition from {current_state.value} to {target_state.value}. "
+                f"Valid transitions: {', '.join(valid_values) if valid_values else 'none (terminal state)'}",
+            }
+
+        # Update ticket state
+        updated = await adapter.update(ticket_id, {"state": target_state})
+
+        if updated is None:
+            return {
+                "status": "error",
+                "error": f"Failed to update ticket {ticket_id}",
+            }
+
+        # Add comment if provided and adapter supports it
+        comment_added = False
+        if comment and hasattr(adapter, "add_comment"):
+            try:
+                await adapter.add_comment(ticket_id, comment)
+                comment_added = True
+            except Exception:
+                # Log but don't fail the transition
+                comment_added = False
+
+        return {
+            "status": "completed",
+            "ticket": updated.model_dump(),
+            "previous_state": current_state.value,
+            "new_state": target_state.value,
+            "comment_added": comment_added,
+            "message": f"Ticket {ticket_id} transitioned from {current_state.value} to {target_state.value}",
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to transition ticket: {str(e)}",
+        }

mcp_ticketer/queue/__init__.py

@@ -1,5 +1,6 @@
 """Async queue system for mcp-ticketer."""
 
+# Import manager last to avoid circular import
 from .manager import WorkerManager
 from .queue import Queue, QueueItem, QueueStatus
 from .worker import Worker

mcp_ticketer/queue/health_monitor.py

@@ -4,7 +4,7 @@ import logging
 import time
 from datetime import datetime, timedelta
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 import psutil
 
@@ -30,8 +30,8 @@ class HealthAlert:
         self,
         level: HealthStatus,
         message: str,
-        details: Optional[dict[str, Any]] = None,
-        timestamp: Optional[datetime] = None,
+        details: dict[str, Any] | None = None,
+        timestamp: datetime | None = None,
     ):
         self.level = level
         self.message = message
@@ -39,6 +39,7 @@ class HealthAlert:
         self.timestamp = timestamp or datetime.now()
 
     def __str__(self) -> str:
+        """Return string representation of alert."""
         return f"[{self.level.upper()}] {self.message}"
 
 
@@ -52,7 +53,7 @@ class QueueHealthMonitor:
     QUEUE_BACKLOG_WARNING = 10  # Warn if more than 10 pending items
     QUEUE_BACKLOG_CRITICAL = 50  # Critical if more than 50 pending items
 
-    def __init__(self, queue: Optional[Queue] = None):
+    def __init__(self, queue: Queue | None = None):
         """Initialize health monitor.
 
         Args:

mcp_ticketer/queue/manager.py

@@ -4,14 +4,14 @@ import fcntl
 import logging
 import os
 import subprocess
-import sys
 import time
 from pathlib import Path
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any
 
 import psutil
 
-from .queue import Queue
+if TYPE_CHECKING:
+    pass
 
 logger = logging.getLogger(__name__)
 
@@ -19,8 +19,11 @@ logger = logging.getLogger(__name__)
 class WorkerManager:
     """Manages worker process with file-based locking."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         """Initialize worker manager."""
+        # Lazy import to avoid circular dependency
+        from .queue import Queue
+
         self.lock_file = Path.home() / ".mcp-ticketer" / "worker.lock"
         self.pid_file = Path.home() / ".mcp-ticketer" / "worker.pid"
         self.lock_file.parent.mkdir(parents=True, exist_ok=True)
@@ -51,7 +54,7 @@ class WorkerManager:
             # Lock already held
             return False
 
-    def _release_lock(self):
+    def _release_lock(self) -> None:
         """Release worker lock."""
         if hasattr(self, "lock_fd"):
             fcntl.lockf(self.lock_fd, fcntl.LOCK_UN)
@@ -123,7 +126,10 @@ class WorkerManager:
         try:
             # 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()
+            # Lazy import to avoid circular dependency
+            from ..cli.python_detection import get_mcp_ticketer_python
+
+            python_executable = get_mcp_ticketer_python()
             cmd = [python_executable, "-m", "mcp_ticketer.queue.run_worker"]
 
             # Prepare environment for subprocess
@@ -281,7 +287,7 @@ class WorkerManager:
         is_running = self.is_running()
         pid = self._get_pid() if is_running else None
 
-        status = {"running": is_running, "pid": pid}
+        status: dict[str, Any] = {"running": is_running, "pid": pid}
 
         # Add process info if running
         if is_running and pid:
@@ -304,7 +310,7 @@ class WorkerManager:
 
         return status
 
-    def _get_pid(self) -> Optional[int]:
+    def _get_pid(self) -> int | None:
         """Get worker PID from file.
 
         Returns:
@@ -320,49 +326,7 @@ 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) 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:
-                pass
-
-        # Fallback to sys.executable
-        logger.debug(f"Using sys.executable as fallback: {current_executable}")
-        return current_executable
-
-    def _cleanup(self):
+    def _cleanup(self) -> None:
         """Clean up lock and PID files."""
         self._release_lock()
         if self.pid_file.exists():

mcp_ticketer/queue/queue.py

@@ -8,7 +8,7 @@ from dataclasses import asdict, dataclass
 from datetime import datetime, timedelta
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 
 class QueueStatus(str, Enum):
@@ -30,12 +30,12 @@ class QueueItem:
     operation: str
     status: QueueStatus
     created_at: datetime
-    processed_at: Optional[datetime] = None
-    error_message: Optional[str] = None
+    processed_at: datetime | None = None
+    error_message: str | None = None
     retry_count: int = 0
-    result: Optional[dict[str, Any]] = None
-    project_dir: Optional[str] = None
-    adapter_config: Optional[dict[str, Any]] = None  # Adapter configuration
+    result: dict[str, Any] | None = None
+    project_dir: str | None = None
+    adapter_config: dict[str, Any] | None = None  # Adapter configuration
 
     def to_dict(self) -> dict:
         """Convert to dictionary for storage."""
@@ -67,7 +67,7 @@ class QueueItem:
 class Queue:
     """Thread-safe SQLite queue for ticket operations."""
 
-    def __init__(self, db_path: Optional[Path] = None):
+    def __init__(self, db_path: Path | None = None):
         """Initialize queue with database connection.
 
         Args:
@@ -83,7 +83,7 @@ class Queue:
         self._lock = threading.Lock()
         self._init_database()
 
-    def _init_database(self):
+    def _init_database(self) -> None:
         """Initialize database schema."""
         with sqlite3.connect(self.db_path) as conn:
             conn.execute(
@@ -139,8 +139,8 @@ class Queue:
         ticket_data: dict[str, Any],
         adapter: str,
         operation: str,
-        project_dir: Optional[str] = None,
-        adapter_config: Optional[dict[str, Any]] = None,
+        project_dir: str | None = None,
+        adapter_config: dict[str, Any] | None = None,
     ) -> str:
         """Add item to queue.
 
@@ -186,7 +186,7 @@ class Queue:
 
         return queue_id
 
-    def get_next_pending(self) -> Optional[QueueItem]:
+    def get_next_pending(self) -> QueueItem | None:
         """Get next pending item from queue atomically.
 
         Returns:
@@ -251,9 +251,9 @@ class Queue:
         self,
         queue_id: str,
         status: QueueStatus,
-        error_message: Optional[str] = None,
-        result: Optional[dict[str, Any]] = None,
-        expected_status: Optional[QueueStatus] = None,
+        error_message: str | None = None,
+        result: dict[str, Any] | None = None,
+        expected_status: QueueStatus | None = None,
     ) -> bool:
         """Update queue item status atomically.
 
@@ -328,7 +328,7 @@ class Queue:
                     raise
 
     def increment_retry(
-        self, queue_id: str, expected_status: Optional[QueueStatus] = None
+        self, queue_id: str, expected_status: QueueStatus | None = None
     ) -> int:
         """Increment retry count and reset to pending atomically.
 
@@ -387,7 +387,7 @@ class Queue:
                     conn.rollback()
                     raise
 
-    def get_item(self, queue_id: str) -> Optional[QueueItem]:
+    def get_item(self, queue_id: str) -> QueueItem | None:
         """Get specific queue item by ID.
 
         Args:
@@ -409,7 +409,7 @@ class Queue:
             return QueueItem.from_row(row) if row else None
 
     def list_items(
-        self, status: Optional[QueueStatus] = None, limit: int = 50
+        self, status: QueueStatus | None = None, limit: int = 50
     ) -> list[QueueItem]:
         """List queue items.
 
@@ -462,7 +462,7 @@ class Queue:
 
             return cursor.fetchone()[0]
 
-    def cleanup_old(self, days: int = 7):
+    def cleanup_old(self, days: int = 7) -> None:
         """Clean up old completed/failed items.
 
         Args:
@@ -487,7 +487,7 @@ class Queue:
                 )
                 conn.commit()
 
-    def reset_stuck_items(self, timeout_minutes: int = 30):
+    def reset_stuck_items(self, timeout_minutes: int = 30) -> None:
         """Reset items stuck in processing state.
 
         Args:

mcp_ticketer/queue/run_worker.py

@@ -13,7 +13,7 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-def main():
+def main() -> None:
     """Run the worker process."""
     import os