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

mcp_ticketer/mcp/server/tools/user_ticket_tools.py

@@ -1,8 +1,7 @@
 """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.
+including transitioning tickets through workflow states with validation.
 
 Design Decision: Workflow State Validation
 ------------------------------------------
@@ -20,177 +19,38 @@ Valid workflow transitions:
 - 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.adapter import BaseAdapter
 from ....core.models import TicketState
-from ....core.project_config import ConfigResolver, TicketerConfig
+from ....core.state_matcher import get_state_matcher
 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,
+def _build_adapter_metadata(
+    adapter: BaseAdapter,
+    ticket_id: str | None = None,
 ) -> 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)}",
-        }
+    """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 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
+    """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
@@ -231,7 +91,7 @@ async def get_available_transitions(ticket_id: str) -> dict[str, Any]:
 
         return {
             "status": "completed",
-            "ticket_id": ticket_id,
+            **_build_adapter_metadata(adapter, ticket_id),
             "current_state": current_state.value,
             "available_transitions": [state.value for state in available],
             "transition_descriptions": transition_descriptions,
@@ -249,63 +109,13 @@ 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 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
+    """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
@@ -318,41 +128,130 @@ async def ticket_transition(
                 "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]
+        # 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 {
-                "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)'}",
+                **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}",
             }
@@ -367,7 +266,61 @@ async def ticket_transition(
                 # Log but don't fail the transition
                 comment_added = False
 
-        return {
+        # 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,
@@ -375,8 +328,37 @@ async def ticket_transition(
             "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/worker.py

@@ -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] = []

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"]