claude-mpm 4.1.4__py3-none-any.whl → 4.1.6__py3-none-any.whl

claude_mpm/services/ticket_services/validation_service.py

@@ -0,0 +1,303 @@
+"""
+Input validation service for tickets.
+
+WHY: Centralizes all validation logic to ensure data integrity and
+provide consistent error messages across the ticket system.
+
+DESIGN DECISIONS:
+- Returns validation results with detailed error messages
+- Validates ticket IDs, types, statuses, priorities
+- Handles pagination parameter validation
+- Provides sanitization for user inputs
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class TicketValidationService:
+    """Service for validating ticket inputs."""
+
+    # Valid ticket types
+    VALID_TYPES = ["task", "issue", "epic", "bug", "feature", "story"]
+
+    # Valid ticket statuses
+    VALID_STATUSES = [
+        "open",
+        "in_progress",
+        "ready",
+        "tested",
+        "done",
+        "waiting",
+        "closed",
+        "blocked",
+        "all",
+    ]
+
+    # Valid priorities
+    VALID_PRIORITIES = ["low", "medium", "high", "critical"]
+
+    # Valid workflow states
+    VALID_WORKFLOW_STATES = [
+        "todo",
+        "in_progress",
+        "ready",
+        "tested",
+        "done",
+        "blocked",
+    ]
+
+    def validate_ticket_id(self, ticket_id: Any) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket ID.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not ticket_id:
+            return False, "No ticket ID provided"
+
+        if not isinstance(ticket_id, str):
+            return False, "Ticket ID must be a string"
+
+        if len(ticket_id) < 3:
+            return False, "Invalid ticket ID format"
+
+        return True, None
+
+    def validate_ticket_type(self, ticket_type: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket type.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not ticket_type:
+            return True, None  # Type is optional, default will be used
+
+        if ticket_type not in self.VALID_TYPES:
+            return (
+                False,
+                f"Invalid ticket type: {ticket_type}. Valid types: {', '.join(self.VALID_TYPES)}",
+            )
+
+        return True, None
+
+    def validate_status(self, status: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket status.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not status:
+            return True, None  # Status is optional
+
+        if status not in self.VALID_STATUSES:
+            return (
+                False,
+                f"Invalid status: {status}. Valid statuses: {', '.join(self.VALID_STATUSES)}",
+            )
+
+        return True, None
+
+    def validate_priority(self, priority: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket priority.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not priority:
+            return True, None  # Priority is optional, default will be used
+
+        if priority not in self.VALID_PRIORITIES:
+            return (
+                False,
+                f"Invalid priority: {priority}. Valid priorities: {', '.join(self.VALID_PRIORITIES)}",
+            )
+
+        return True, None
+
+    def validate_workflow_state(self, state: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a workflow state.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not state:
+            return False, "No workflow state provided"
+
+        if state not in self.VALID_WORKFLOW_STATES:
+            return (
+                False,
+                f"Invalid workflow state: {state}. Valid states: {', '.join(self.VALID_WORKFLOW_STATES)}",
+            )
+
+        return True, None
+
+    def validate_pagination(
+        self, page: int, page_size: int
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate pagination parameters.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if page < 1:
+            return False, "Page number must be 1 or greater"
+
+        if page_size < 1:
+            return False, "Page size must be 1 or greater"
+
+        if page_size > 100:
+            return False, "Page size cannot exceed 100"
+
+        return True, None
+
+    def validate_create_params(
+        self, params: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate parameters for ticket creation.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Title is required
+        if not params.get("title"):
+            return False, "Title is required for ticket creation"
+
+        if len(params["title"]) < 3:
+            return False, "Title must be at least 3 characters long"
+
+        if len(params["title"]) > 200:
+            return False, "Title cannot exceed 200 characters"
+
+        # Validate optional fields if provided
+        if "type" in params:
+            valid, error = self.validate_ticket_type(params["type"])
+            if not valid:
+                return False, error
+
+        if "priority" in params:
+            valid, error = self.validate_priority(params["priority"])
+            if not valid:
+                return False, error
+
+        # Validate parent references
+        if params.get("parent_epic"):
+            valid, error = self.validate_ticket_id(params["parent_epic"])
+            if not valid:
+                return False, f"Invalid parent epic: {error}"
+
+        if params.get("parent_issue"):
+            valid, error = self.validate_ticket_id(params["parent_issue"])
+            if not valid:
+                return False, f"Invalid parent issue: {error}"
+
+        return True, None
+
+    def validate_update_params(
+        self, params: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate parameters for ticket update.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # At least one update field must be provided
+        update_fields = ["status", "priority", "description", "tags", "assign"]
+        if not any(field in params for field in update_fields):
+            return False, "No update fields specified"
+
+        # Validate status if provided
+        if "status" in params:
+            valid, error = self.validate_status(params["status"])
+            if not valid:
+                return False, error
+
+        # Validate priority if provided
+        if "priority" in params:
+            valid, error = self.validate_priority(params["priority"])
+            if not valid:
+                return False, error
+
+        return True, None
+
+    def sanitize_tags(self, tags: Any) -> List[str]:
+        """
+        Sanitize and parse tags input.
+
+        Returns:
+            List of sanitized tags
+        """
+        if not tags:
+            return []
+
+        if isinstance(tags, str):
+            # Split comma-separated tags
+            tag_list = [tag.strip() for tag in tags.split(",")]
+        elif isinstance(tags, list):
+            tag_list = [str(tag).strip() for tag in tags]
+        else:
+            return []
+
+        # Remove empty tags and duplicates
+        return list(filter(None, dict.fromkeys(tag_list)))
+
+    def sanitize_description(self, description: Any) -> str:
+        """
+        Sanitize description input.
+
+        Returns:
+            Sanitized description string
+        """
+        if not description:
+            return ""
+
+        if isinstance(description, list):
+            # Join list elements with spaces
+            return " ".join(str(item) for item in description)
+
+        return str(description).strip()
+
+    def validate_search_query(self, query: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a search query.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not query:
+            return False, "Search query cannot be empty"
+
+        if len(query) < 2:
+            return False, "Search query must be at least 2 characters"
+
+        if len(query) > 100:
+            return False, "Search query cannot exceed 100 characters"
+
+        return True, None
+
+    def validate_comment(self, comment: Any) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a comment.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not comment:
+            return False, "Comment cannot be empty"
+
+        comment_str = self.sanitize_description(comment)
+
+        if len(comment_str) < 1:
+            return False, "Comment cannot be empty"
+
+        if len(comment_str) > 5000:
+            return False, "Comment cannot exceed 5000 characters"
+
+        return True, None

claude_mpm/services/ticket_services/workflow_service.py

@@ -0,0 +1,244 @@
+"""
+Workflow service for ticket state transitions.
+
+WHY: Manages ticket workflow states and transitions, ensuring valid
+state changes and maintaining workflow integrity.
+
+DESIGN DECISIONS:
+- Enforces valid state transitions
+- Handles workflow-specific operations (comments, notifications)
+- Provides workflow history tracking
+- Abstracts aitrackdown workflow commands
+"""
+
+import subprocess
+from typing import Any, Dict, List, Optional, Tuple
+
+from ...core.logger import get_logger
+
+
+class TicketWorkflowService:
+    """Service for managing ticket workflow states."""
+
+    # Valid workflow transitions
+    WORKFLOW_TRANSITIONS = {
+        "todo": ["in_progress", "blocked"],
+        "in_progress": ["ready", "blocked", "todo"],
+        "ready": ["tested", "in_progress", "blocked"],
+        "tested": ["done", "ready", "blocked"],
+        "done": ["tested", "ready"],  # Can reopen
+        "blocked": ["todo", "in_progress", "ready"],
+    }
+
+    # Status to workflow state mapping
+    STATUS_TO_WORKFLOW = {
+        "open": "todo",
+        "in_progress": "in_progress",
+        "ready": "ready",
+        "tested": "tested",
+        "done": "done",
+        "closed": "done",
+        "blocked": "blocked",
+        "waiting": "blocked",
+    }
+
+    def __init__(self):
+        """Initialize the workflow service."""
+        self.logger = get_logger("services.ticket_workflow")
+
+    def transition_ticket(
+        self,
+        ticket_id: str,
+        new_state: str,
+        comment: Optional[str] = None,
+        force: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Transition a ticket to a new workflow state.
+
+        Args:
+            ticket_id: ID of the ticket
+            new_state: Target workflow state
+            comment: Optional comment for the transition
+            force: Force transition even if not normally allowed
+
+        Returns:
+            Dict with success status and message
+        """
+        try:
+            # Validate the transition if not forced
+            if not force:
+                valid, error = self.validate_transition(ticket_id, new_state)
+                if not valid:
+                    return {"success": False, "error": error}
+
+            # Use aitrackdown CLI for the transition
+            result = self._transition_via_aitrackdown(ticket_id, new_state, comment)
+
+            if result["success"]:
+                # Log successful transition
+                self.logger.info(f"Transitioned {ticket_id} to {new_state}")
+
+            return result
+
+        except Exception as e:
+            self.logger.error(f"Error transitioning ticket {ticket_id}: {e}")
+            return {"success": False, "error": str(e)}
+
+    def _transition_via_aitrackdown(
+        self, ticket_id: str, state: str, comment: Optional[str]
+    ) -> Dict[str, Any]:
+        """Transition ticket using aitrackdown CLI."""
+        try:
+            cmd = ["aitrackdown", "transition", ticket_id, state]
+
+            if comment:
+                cmd.extend(["--comment", comment])
+
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+
+            return {
+                "success": True,
+                "message": f"Updated workflow state for {ticket_id} to: {state}",
+            }
+        except subprocess.CalledProcessError as e:
+            self.logger.error(f"Failed to transition via CLI: {e}")
+            return {
+                "success": False,
+                "error": f"Failed to update workflow state for ticket: {ticket_id}",
+            }
+
+    def validate_transition(
+        self, ticket_id: str, new_state: str
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate if a workflow transition is allowed.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # For now, we assume all transitions are valid since we don't
+        # have access to current state without fetching the ticket
+        # In a real implementation, this would check current state
+
+        if new_state not in self.WORKFLOW_TRANSITIONS:
+            return False, f"Invalid workflow state: {new_state}"
+
+        # TODO: Fetch current state and validate transition
+        # current_state = self._get_current_state(ticket_id)
+        # if new_state not in self.WORKFLOW_TRANSITIONS.get(current_state, []):
+        #     return False, f"Cannot transition from {current_state} to {new_state}"
+
+        return True, None
+
+    def add_comment(self, ticket_id: str, comment: str) -> Dict[str, Any]:
+        """
+        Add a comment to a ticket.
+
+        Args:
+            ticket_id: ID of the ticket
+            comment: Comment text
+
+        Returns:
+            Dict with success status and message
+        """
+        try:
+            cmd = ["aitrackdown", "comment", ticket_id, comment]
+
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+
+            return {"success": True, "message": f"Added comment to ticket: {ticket_id}"}
+        except subprocess.CalledProcessError as e:
+            self.logger.error(f"Failed to add comment: {e}")
+            return {
+                "success": False,
+                "error": f"Failed to add comment to ticket: {ticket_id}",
+            }
+
+    def get_workflow_states(self) -> List[str]:
+        """
+        Get list of all valid workflow states.
+
+        Returns:
+            List of workflow state names
+        """
+        return list(self.WORKFLOW_TRANSITIONS.keys())
+
+    def get_valid_transitions(self, current_state: str) -> List[str]:
+        """
+        Get valid transitions from a given state.
+
+        Args:
+            current_state: Current workflow state
+
+        Returns:
+            List of valid target states
+        """
+        return self.WORKFLOW_TRANSITIONS.get(current_state, [])
+
+    def map_status_to_workflow(self, status: str) -> str:
+        """
+        Map a ticket status to a workflow state.
+
+        Args:
+            status: Ticket status
+
+        Returns:
+            Corresponding workflow state
+        """
+        return self.STATUS_TO_WORKFLOW.get(status, "todo")
+
+    def bulk_transition(
+        self, ticket_ids: List[str], new_state: str, comment: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Transition multiple tickets to a new state.
+
+        Args:
+            ticket_ids: List of ticket IDs
+            new_state: Target workflow state
+            comment: Optional comment for all transitions
+
+        Returns:
+            Dict with results for each ticket
+        """
+        results = {"succeeded": [], "failed": [], "total": len(ticket_ids)}
+
+        for ticket_id in ticket_ids:
+            result = self.transition_ticket(ticket_id, new_state, comment)
+
+            if result["success"]:
+                results["succeeded"].append(ticket_id)
+            else:
+                results["failed"].append(
+                    {
+                        "ticket_id": ticket_id,
+                        "error": result.get("error", "Unknown error"),
+                    }
+                )
+
+        return {"success": len(results["failed"]) == 0, "results": results}
+
+    def get_workflow_summary(self, tickets: List[Dict[str, Any]]) -> Dict[str, int]:
+        """
+        Get summary of tickets by workflow state.
+
+        Args:
+            tickets: List of ticket dictionaries
+
+        Returns:
+            Dict mapping workflow states to counts
+        """
+        summary = dict.fromkeys(self.WORKFLOW_TRANSITIONS.keys(), 0)
+        summary["unknown"] = 0
+
+        for ticket in tickets:
+            status = ticket.get("status", "unknown")
+            workflow_state = self.map_status_to_workflow(status)
+
+            if workflow_state in summary:
+                summary[workflow_state] += 1
+            else:
+                summary["unknown"] += 1
+
+        return summary

{claude_mpm-4.1.4.dist-info → claude_mpm-4.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.1.4
+Version: 4.1.6
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -46,6 +46,8 @@ Requires-Dist: toml>=0.10.2
 Requires-Dist: packaging>=21.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: textual>=0.47.0
+Requires-Dist: rich>=13.0.0
 Requires-Dist: pyee>=13.0.0
 Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
 Provides-Extra: dev