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

mcp_ticketer/mcp/server/tools/user_ticket_tools.py

@@ -0,0 +1,364 @@
+"""User-specific ticket management tools.
+
+This module provides tools for managing tickets from a user's perspective,
+including 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:
+- State transition validation is O(1) lookup in predefined state machine
+"""
+
+from typing import Any
+
+from ....core.adapter import BaseAdapter
+from ....core.models import TicketState
+from ....core.state_matcher import get_state_matcher
+from ..server_sdk import get_adapter, mcp
+
+
+def _build_adapter_metadata(
+    adapter: BaseAdapter,
+    ticket_id: str | None = None,
+) -> dict[str, Any]:
+    """Build adapter metadata for MCP responses."""
+    metadata = {
+        "adapter": adapter.adapter_type,
+        "adapter_name": adapter.adapter_display_name,
+    }
+    if ticket_id:
+        metadata["ticket_id"] = ticket_id
+    return metadata
+
+
+@mcp.tool()
+async def get_available_transitions(ticket_id: str) -> dict[str, Any]:
+    """Get valid next states for ticket based on workflow state machine.
+
+    Args: ticket_id (required)
+    Returns: TransitionResponse with current_state, available_transitions, transition_descriptions, is_terminal
+    See: docs/ticket-workflows.md#valid-state-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",
+            }
+
+        # 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",
+            **_build_adapter_metadata(adapter, 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,
+    auto_confirm: bool = True,
+) -> dict[str, Any]:
+    """Move ticket through workflow with validation and semantic matching (natural language support).
+
+    Args: ticket_id (required), to_state (supports natural language like "working on it"), comment (optional), auto_confirm (default: True)
+    Returns: TransitionResponse with status, ticket, previous_state, new_state, matched_state, confidence, suggestions (if ambiguous)
+    See: docs/ticket-workflows.md#semantic-state-matching, docs/ticket-workflows.md#valid-state-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",
+            }
+
+        # 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)
+
+        # Use semantic matcher to resolve target state
+        matcher = get_state_matcher()
+        match_result = matcher.match_state(to_state)
+
+        # Build response with semantic match info
+        response: dict[str, Any] = {
+            "ticket_id": ticket_id,
+            "original_input": to_state,
+            "matched_state": match_result.state.value,
+            "confidence": match_result.confidence,
+            "match_type": match_result.match_type,
+            "current_state": current_state.value,
+        }
+
+        # Handle low confidence - provide suggestions
+        if match_result.is_low_confidence():
+            suggestions = matcher.suggest_states(to_state, top_n=3)
+            return {
+                **response,
+                "status": "ambiguous",
+                "message": "Input is ambiguous. Please choose from suggestions.",
+                "suggestions": [
+                    {
+                        "state": s.state.value,
+                        "confidence": s.confidence,
+                        "description": _get_state_description(s.state),
+                    }
+                    for s in suggestions
+                ],
+            }
+
+        # Handle medium confidence - needs confirmation unless auto_confirm
+        if match_result.is_medium_confidence() and not auto_confirm:
+            return {
+                **response,
+                "status": "needs_confirmation",
+                "message": f"Matched '{to_state}' to '{match_result.state.value}' with {match_result.confidence:.0%} confidence. Please confirm.",
+                "confirm_required": True,
+            }
+
+        target_state = match_result.state
+
+        # Validate transition using adapter (includes parent/child state constraints)
+        is_valid = await adapter.validate_transition(ticket_id, target_state)
+        if not is_valid:
+            # Check if it's a workflow violation or parent constraint violation
+            workflow_valid = current_state.can_transition_to(target_state)
+            valid_transitions = TicketState.valid_transitions().get(current_state, [])
+            valid_values = [s.value for s in valid_transitions]
+
+            if workflow_valid:
+                # Workflow is valid, so this must be a parent constraint violation
+                # Get children to determine max child state
+                from ....core.models import Task
+
+                if isinstance(ticket, Task) and ticket.children:
+                    try:
+                        children = await adapter.list_tasks_by_issue(ticket_id)
+                        if children:
+                            max_child_state = None
+                            max_child_level = 0
+                            for child in children:
+                                child_state = child.state
+                                if isinstance(child_state, str):
+                                    try:
+                                        child_state = TicketState(child_state)
+                                    except ValueError:
+                                        continue
+                                child_level = child_state.completion_level()
+                                if child_level > max_child_level:
+                                    max_child_level = child_level
+                                    max_child_state = child_state
+
+                            return {
+                                **response,
+                                "status": "error",
+                                "error": f"Cannot transition to '{target_state.value}': parent issue has children in higher completion states",
+                                "reason": "parent_constraint_violation",
+                                "max_child_state": (
+                                    max_child_state.value if max_child_state else None
+                                ),
+                                "message": f"Cannot transition to {target_state.value}: "
+                                f"parent issue has children in higher completion states (max child state: {max_child_state.value if max_child_state else 'unknown'}). "
+                                f"Please update child states first.",
+                                "valid_transitions": valid_values,
+                            }
+                    except Exception:
+                        # Fallback to generic message if we can't determine child states
+                        pass
+
+                # Generic parent constraint violation message
+                return {
+                    **response,
+                    "status": "error",
+                    "error": f"Cannot transition to '{target_state.value}': parent/child state constraint violation",
+                    "reason": "parent_constraint_violation",
+                    "message": f"Cannot transition to {target_state.value}: "
+                    f"parent issue has children in higher completion states. Please update child states first.",
+                    "valid_transitions": valid_values,
+                }
+            else:
+                # Workflow violation
+                return {
+                    **response,
+                    "status": "error",
+                    "error": f"Invalid transition from '{current_state.value}' to '{target_state.value}'",
+                    "reason": "workflow_violation",
+                    "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 {
+                **response,
+                "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
+
+        # Auto project update hook (1M-315)
+        # Trigger automatic project update if enabled and ticket has parent epic
+        auto_update_result = None
+        try:
+            from pathlib import Path
+
+            from ....automation.project_updates import AutoProjectUpdateManager
+            from ....core.project_config import ConfigResolver
+
+            # Load config
+            resolver = ConfigResolver(project_path=Path.cwd())
+            config_obj = resolver.load_project_config()
+            config_dict = config_obj.to_dict() if config_obj else {}
+
+            # Check if auto updates enabled
+            auto_updates_mgr = AutoProjectUpdateManager(config_dict, adapter)
+            if auto_updates_mgr.is_enabled():
+                # Check if ticket has parent_epic
+                parent_epic = (
+                    updated.parent_epic if hasattr(updated, "parent_epic") else None
+                )
+
+                if parent_epic:
+                    # Only trigger on configured frequency
+                    update_frequency = auto_updates_mgr.get_update_frequency()
+                    should_trigger = update_frequency == "on_transition"
+
+                    # For "on_completion", only trigger if transitioned to done/closed
+                    if update_frequency == "on_completion":
+                        from ....core.models import TicketState as TSEnum
+
+                        should_trigger = target_state in (TSEnum.DONE, TSEnum.CLOSED)
+
+                    if should_trigger:
+                        auto_update_result = (
+                            await auto_updates_mgr.create_transition_update(
+                                ticket_id=ticket_id,
+                                ticket_title=updated.title or "",
+                                old_state=current_state.value,
+                                new_state=target_state.value,
+                                parent_epic=parent_epic,
+                            )
+                        )
+        except Exception as e:
+            # Log error but don't block the transition
+            import logging
+
+            logging.getLogger(__name__).warning(
+                f"Auto project update failed (non-blocking): {e}"
+            )
+
+        # Build final response
+        final_response = {
+            **response,
+            **_build_adapter_metadata(adapter, ticket_id),
+            "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}",
+        }
+
+        # Include auto update result if applicable
+        if auto_update_result:
+            final_response["auto_project_update"] = auto_update_result
+
+        return final_response
+    except Exception as e:
+        return {
+            "status": "error",
+            "error": f"Failed to transition ticket: {str(e)}",
+        }
+
+
+def _get_state_description(state: TicketState) -> str:
+    """Get human-readable description of a state.
+
+    Args:
+        state: TicketState to describe
+
+    Returns:
+        Description string
+
+    """
+    descriptions = {
+        TicketState.OPEN: "Work not yet started, in backlog",
+        TicketState.IN_PROGRESS: "Work is actively being done",
+        TicketState.READY: "Work complete, ready for review or testing",
+        TicketState.TESTED: "Work has been tested and verified",
+        TicketState.DONE: "Work is complete and accepted",
+        TicketState.WAITING: "Work paused, waiting for external dependency",
+        TicketState.BLOCKED: "Work blocked by an impediment",
+        TicketState.CLOSED: "Ticket closed or archived (final state)",
+    }
+    return descriptions.get(state, "")

mcp_ticketer/queue/health_monitor.py

@@ -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}"
 
 

mcp_ticketer/queue/manager.py

@@ -19,7 +19,7 @@ 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
@@ -54,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)
@@ -287,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:
@@ -326,7 +326,7 @@ class WorkerManager:
         except (OSError, ValueError):
             return None
 
-    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

@@ -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(
@@ -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
 

mcp_ticketer/queue/ticket_registry.py

@@ -27,7 +27,7 @@ class TicketRegistry:
         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:
             # Ticket registry table
@@ -149,7 +149,7 @@ class TicketRegistry:
         with self._lock:
             with sqlite3.connect(self.db_path) as conn:
                 update_fields = ["status = ?", "updated_at = ?"]
-                values = [status, datetime.now().isoformat()]
+                values: list[Any] = [status, datetime.now().isoformat()]
 
                 if ticket_id is not None:
                     update_fields.append("ticket_id = ?")

mcp_ticketer/queue/worker.py

@@ -97,12 +97,12 @@ class Worker:
             f"Worker initialized with batch_size={batch_size}, max_concurrent={max_concurrent}"
         )
 
-    def _signal_handler(self, signum, frame):
+    def _signal_handler(self, signum: int, frame: Any) -> None:
         """Handle shutdown signals."""
         logger.info(f"Received signal {signum}, shutting down...")
         self.stop()
 
-    def start(self, daemon: bool = True):
+    def start(self, daemon: bool = True) -> None:
         """Start the worker.
 
         Args:
@@ -126,14 +126,14 @@ class Worker:
             # Run in main thread
             self._run_loop()
 
-    def stop(self):
+    def stop(self) -> None:
         """Stop the worker."""
         logger.info("Stopping worker...")
         self.running = False
         self.stop_event.set()
 
-    def _run_loop(self):
-        """Main worker loop with batch processing."""
+    def _run_loop(self) -> None:
+        """Run main worker loop with batch processing."""
         logger.info("Worker loop started")
 
         # Reset any stuck items on startup
@@ -174,7 +174,7 @@ class Worker:
                 break
         return batch
 
-    async def _process_batch(self, batch: list[QueueItem]):
+    async def _process_batch(self, batch: list[QueueItem]) -> None:
         """Process a batch of queue items with concurrency control.
 
         Args:
@@ -184,7 +184,7 @@ class Worker:
         logger.info(f"Processing batch of {len(batch)} items")
 
         # Group items by adapter for concurrent processing
-        adapter_groups = {}
+        adapter_groups: dict[str, list[Any]] = {}
         for item in batch:
             if item.adapter not in adapter_groups:
                 adapter_groups[item.adapter] = []
@@ -199,7 +199,9 @@ class Worker:
         # Wait for all adapter groups to complete
         await asyncio.gather(*tasks, return_exceptions=True)
 
-    async def _process_adapter_group(self, adapter: str, items: list[QueueItem]):
+    async def _process_adapter_group(
+        self, adapter: str, items: list[QueueItem]
+    ) -> None:
         """Process items for a specific adapter with concurrency control.
 
         Args:
@@ -216,7 +218,7 @@ class Worker:
         semaphore = self.adapter_semaphores[adapter]
 
         # Process items with concurrency control
-        async def process_with_semaphore(item):
+        async def process_with_semaphore(item: QueueItem) -> None:
             async with semaphore:
                 await self._process_item(item)
 
@@ -226,7 +228,7 @@ class Worker:
         # Process with concurrency control
         await asyncio.gather(*tasks, return_exceptions=True)
 
-    async def _process_item(self, item: QueueItem):
+    async def _process_item(self, item: QueueItem) -> None:
         """Process a single queue item.
 
         Args:
@@ -333,7 +335,7 @@ class Worker:
                 self.stats["items_failed"] += 1
                 logger.error(f"Max retries exceeded for {item.id}, marking as failed")
 
-    async def _check_rate_limit(self, adapter: str):
+    async def _check_rate_limit(self, adapter: str) -> None:
         """Check and enforce rate limits.
 
         Args:
@@ -357,7 +359,7 @@ class Worker:
 
         self.last_request_times[adapter] = datetime.now()
 
-    def _get_adapter(self, item: QueueItem):
+    def _get_adapter(self, item: QueueItem) -> Any:
         """Get adapter instance for item.
 
         Args:
@@ -442,7 +444,7 @@ class Worker:
 
         return adapter
 
-    async def _execute_operation(self, adapter, item: QueueItem) -> dict[str, Any]:
+    async def _execute_operation(self, adapter: Any, item: QueueItem) -> dict[str, Any]:
         """Execute the queued operation.
 
         Args:

mcp_ticketer/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules for mcp-ticketer."""
+
+from .token_utils import estimate_json_tokens, estimate_tokens, paginate_response
+
+__all__ = ["estimate_tokens", "estimate_json_tokens", "paginate_response"]