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

mcp_ticketer/adapters/linear/client.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import asyncio
+import json
+import logging
 from typing import Any
 
 try:
@@ -19,6 +21,8 @@ except ImportError:
 
 from ...core.exceptions import AdapterError, AuthenticationError, RateLimitError
 
+logger = logging.getLogger(__name__)
+
 
 class LinearGraphQLClient:
     """GraphQL client for Linear API with error handling and retry logic."""
@@ -102,13 +106,42 @@ class LinearGraphQLClient:
         """
         query = gql(query_string)
 
+        # Extract operation name from query for logging
+        operation_name = "unknown"
+        try:
+            # Simple extraction - look for 'query' or 'mutation' keyword
+            query_lower = query_string.strip().lower()
+            if query_lower.startswith("mutation"):
+                operation_name = (
+                    query_string.split("{")[0].strip().replace("mutation", "").strip()
+                )
+            elif query_lower.startswith("query"):
+                operation_name = (
+                    query_string.split("{")[0].strip().replace("query", "").strip()
+                )
+        except Exception:
+            pass  # Use default 'unknown' if extraction fails
+
         for attempt in range(retries + 1):
             try:
+                # Log request details before execution
+                logger.debug(
+                    f"[Linear GraphQL] Executing operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}"
+                )
+
                 client = self.create_client()
                 async with client as session:
                     result = await session.execute(
                         query, variable_values=variables or {}
                     )
+
+                # Log successful response
+                logger.debug(
+                    f"[Linear GraphQL] Operation successful: {operation_name}\n"
+                    f"Response:\n{json.dumps(result, indent=2, default=str)}"
+                )
+
                 return result
 
             except TransportQueryError as e:
@@ -118,8 +151,46 @@ class LinearGraphQLClient:
 
                 Related: 1M-398 - Label duplicate error handling
                 """
+                # Log detailed error information
+                logger.error(
+                    f"[Linear GraphQL] TransportQueryError occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error: {e}\n"
+                    f"Error details: {e.errors if hasattr(e, 'errors') else 'No error details'}"
+                )
+
                 if e.errors:
-                    error_msg = e.errors[0].get("message", "Unknown GraphQL error")
+                    error = e.errors[0]
+                    error_msg = error.get("message", "Unknown GraphQL error")
+
+                    # Parse extensions for field-specific details (enhanced debugging)
+                    extensions = error.get("extensions", {})
+
+                    # Check for user-presentable message (clearer error for users)
+                    user_message = extensions.get("userPresentableMessage")
+                    if user_message:
+                        error_msg = user_message
+
+                    # Check for argument path (which field failed validation)
+                    arg_path = extensions.get("argumentPath")
+                    if arg_path:
+                        field_path = ".".join(str(p) for p in arg_path)
+                        error_msg = f"{error_msg} (field: {field_path})"
+
+                    # Check for validation errors (additional context)
+                    validation_errors = extensions.get("validationErrors")
+                    if validation_errors:
+                        error_msg = (
+                            f"{error_msg}\nValidation errors: {validation_errors}"
+                        )
+
+                    # Log full error context for debugging
+                    logger.error(
+                        "Linear GraphQL error: %s (extensions: %s)",
+                        error_msg,
+                        extensions,
+                    )
 
                     # Check for duplicate label errors specifically
                     if (
@@ -139,6 +210,15 @@ class LinearGraphQLClient:
                 raise AdapterError(f"Linear GraphQL error: {e}", "linear") from e
 
             except TransportError as e:
+                # Log transport error details
+                logger.error(
+                    f"[Linear GraphQL] TransportError occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error: {e}\n"
+                    f"Status code: {e.response.status if hasattr(e, 'response') and e.response else 'N/A'}"
+                )
+
                 # Handle HTTP errors
                 if hasattr(e, "response") and e.response:
                     status_code = e.response.status
@@ -173,6 +253,16 @@ class LinearGraphQLClient:
                 raise AdapterError(f"Linear API transport error: {e}", "linear") from e
 
             except Exception as e:
+                # Log generic error details
+                logger.error(
+                    f"[Linear GraphQL] Unexpected error occurred\n"
+                    f"Operation: {operation_name}\n"
+                    f"Variables:\n{json.dumps(variables or {}, indent=2, default=str)}\n"
+                    f"Error type: {type(e).__name__}\n"
+                    f"Error: {e}",
+                    exc_info=True,
+                )
+
                 # GraphQL or other errors
                 error_msg = str(e)
 

mcp_ticketer/adapters/linear/mappers.py

@@ -418,3 +418,110 @@ def map_linear_attachment_to_attachment(
         description=subtitle,
         metadata=metadata,
     )
+
+
+def task_to_compact_format(task: Task) -> dict[str, Any]:
+    """Convert Task to compact format for efficient token usage.
+
+    Compact format includes only essential fields, reducing token usage by ~70-80%
+    compared to full Task serialization.
+
+    Args:
+    ----
+        task: Universal Task model
+
+    Returns:
+    -------
+        Compact dictionary with minimal essential fields
+
+    Design Decision: Compact Format Fields (1M-554)
+    -----------------------------------------------
+    Rationale: Selected fields based on token efficiency analysis and user needs.
+    Full Task serialization averages ~600 tokens per item. Compact format targets
+    ~120 tokens per item (80% reduction).
+
+    Essential fields included:
+    - id: Required for all operations (identifier)
+    - title: Primary user-facing information
+    - state: Critical for workflow understanding
+    - priority: Important for triage and filtering
+    - assignee: Key for task assignment visibility
+
+    Fields excluded:
+    - description: Often large (100-500 tokens), available via get()
+    - creator: Less critical for list views
+    - tags: Available in full format, not essential for scanning
+    - children: Hierarchy details available via dedicated queries
+    - created_at/updated_at: Not essential for list scanning
+    - metadata: Platform-specific, not needed in compact view
+
+    Performance: Reduces typical 50-item list from ~30,000 to ~6,000 tokens.
+
+    """
+    # Handle state - can be TicketState enum or string
+    state_value = None
+    if task.state:
+        state_value = task.state.value if hasattr(task.state, "value") else task.state
+
+    # Handle priority - can be Priority enum or string
+    priority_value = None
+    if task.priority:
+        priority_value = (
+            task.priority.value if hasattr(task.priority, "value") else task.priority
+        )
+
+    return {
+        "id": task.id,
+        "title": task.title,
+        "state": state_value,
+        "priority": priority_value,
+        "assignee": task.assignee,
+    }
+
+
+def epic_to_compact_format(epic: Epic) -> dict[str, Any]:
+    """Convert Epic to compact format for efficient token usage.
+
+    Compact format includes only essential fields, reducing token usage by ~70-80%
+    compared to full Epic serialization.
+
+    Args:
+    ----
+        epic: Universal Epic model
+
+    Returns:
+    -------
+        Compact dictionary with minimal essential fields
+
+    Design Decision: Epic Compact Format (1M-554)
+    ---------------------------------------------
+    Rationale: Epics typically have less metadata than tasks, but descriptions
+    can still be large. Compact format focuses on overview information.
+
+    Essential fields:
+    - id: Required for all operations
+    - title: Primary identifier
+    - state: Project status
+    - child_count: Useful for project overview (if available)
+
+    Performance: Similar token reduction to task compact format.
+
+    """
+    # Handle state - can be TicketState enum or string
+    state_value = None
+    if epic.state:
+        state_value = epic.state.value if hasattr(epic.state, "value") else epic.state
+
+    compact = {
+        "id": epic.id,
+        "title": epic.title,
+        "state": state_value,
+    }
+
+    # Include child count if available in metadata
+    if epic.metadata and "linear" in epic.metadata:
+        linear_meta = epic.metadata["linear"]
+        if "issue_count" in linear_meta:
+            compact["child_count"] = linear_meta["issue_count"]
+
+    return compact

mcp_ticketer/adapters/linear/queries.py

@@ -354,11 +354,15 @@ LIST_PROJECTS_QUERY = (
     TEAM_FRAGMENT  # Required by PROJECT_FRAGMENT which uses ...TeamFields
     + PROJECT_FRAGMENT
     + """
-    query ListProjects($filter: ProjectFilter, $first: Int!) {
-        projects(filter: $filter, first: $first, orderBy: updatedAt) {
+    query ListProjects($filter: ProjectFilter, $first: Int!, $after: String) {
+        projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt) {
             nodes {
                 ...ProjectFields
             }
+            pageInfo {
+                hasNextPage
+                endCursor
+            }
         }
     }
 """
@@ -554,3 +558,109 @@ GET_PROJECT_UPDATE_QUERY = (
     }
 """
 )
+
+# Milestone/Cycle Operations (1M-607 Phase 2)
+
+CREATE_CYCLE_MUTATION = """
+    mutation CycleCreate($input: CycleCreateInput!) {
+        cycleCreate(input: $input) {
+            success
+            cycle {
+                id
+                name
+                description
+                startsAt
+                endsAt
+                completedAt
+                progress
+                completedIssueCount
+                issueCount
+                team {
+                    id
+                    name
+                }
+            }
+        }
+    }
+"""
+
+GET_CYCLE_QUERY = """
+    query Cycle($id: String!) {
+        cycle(id: $id) {
+            id
+            name
+            description
+            startsAt
+            endsAt
+            completedAt
+            progress
+            completedIssueCount
+            issueCount
+            team {
+                id
+                name
+            }
+        }
+    }
+"""
+
+UPDATE_CYCLE_MUTATION = """
+    mutation CycleUpdate($id: String!, $input: CycleUpdateInput!) {
+        cycleUpdate(id: $id, input: $input) {
+            success
+            cycle {
+                id
+                name
+                description
+                startsAt
+                endsAt
+                completedAt
+                progress
+                completedIssueCount
+                issueCount
+            }
+        }
+    }
+"""
+
+ARCHIVE_CYCLE_MUTATION = """
+    mutation CycleArchive($id: String!) {
+        cycleArchive(id: $id) {
+            success
+        }
+    }
+"""
+
+GET_CYCLE_ISSUES_QUERY = """
+    query CycleIssues($cycleId: String!, $first: Int!) {
+        cycle(id: $cycleId) {
+            issues(first: $first) {
+                nodes {
+                    id
+                    identifier
+                    title
+                    description
+                    state {
+                        id
+                        name
+                        type
+                    }
+                    priority
+                    assignee {
+                        id
+                        email
+                        name
+                    }
+                    labels {
+                        nodes {
+                            id
+                            name
+                        }
+                    }
+                    createdAt
+                    updatedAt
+                }
+            }
+        }
+    }
+"""

mcp_ticketer/adapters/linear/types.py

@@ -51,6 +51,34 @@ class LinearStateMapping:
         "canceled": TicketState.CLOSED,
     }
 
+    # Semantic state name mappings for flexible workflow matching (1M-552)
+    # Maps universal states to common Linear state names (case-insensitive)
+    SEMANTIC_NAMES: dict[TicketState, list[str]] = {
+        TicketState.OPEN: ["todo", "to do", "open", "new", "backlog"],
+        TicketState.READY: ["ready", "triage", "ready for dev", "ready to start"],
+        TicketState.TESTED: [
+            "tested",
+            "in review",
+            "review",
+            "qa",
+            "testing",
+            "ready for review",
+        ],
+        TicketState.WAITING: ["waiting", "on hold", "paused"],
+        TicketState.BLOCKED: ["blocked"],
+        TicketState.IN_PROGRESS: [
+            "in progress",
+            "in-progress",
+            "started",
+            "doing",
+            "active",
+            "in development",
+            "in dev",
+        ],
+        TicketState.DONE: ["done", "completed", "finished"],
+        TicketState.CLOSED: ["closed", "canceled", "cancelled", "won't do", "wont do"],
+    }
+
 
 class LinearWorkflowStateType(Enum):
     """Linear workflow state types."""
@@ -138,8 +166,9 @@ def get_universal_state(
     2. Try synonym matching on state name (ToDo, In Review, Testing, etc.)
     3. Default to OPEN for unknown states
 
-    Synonym Matching Rules (ticket 1M-164):
-    - "Done", "Closed", "Cancelled", "Completed", "Won't Do" → CLOSED
+    Synonym Matching Rules (ticket 1M-164, fixed in v2.0.4):
+    - "done", "completed", "finished", "resolved" → DONE
+    - "closed", "canceled", "cancelled", "won't do" → CLOSED
     - Everything else → OPEN
 
     Args:
@@ -158,24 +187,35 @@ def get_universal_state(
     if state_name:
         state_name_lower = state_name.lower().strip()
 
-        # Check for "done/closed" synonyms - these become CLOSED
-        closed_synonyms = [
+        # DONE states: Work successfully completed
+        # - User finished the work
+        # - Requirements met
+        # - Quality verified
+        done_synonyms = [
             "done",
+            "completed",
+            "finished",
+            "resolved",
+        ]
+
+        if any(synonym in state_name_lower for synonym in done_synonyms):
+            return TicketState.DONE
+
+        # CLOSED states: Work terminated without completion
+        # - User decided not to do it
+        # - Requirements changed
+        # - Duplicate/invalid ticket
+        closed_synonyms = [
             "closed",
             "cancelled",
             "canceled",
-            "completed",
             "won't do",
             "wont do",
             "rejected",
-            "resolved",
-            "finished",
         ]
 
         if any(synonym in state_name_lower for synonym in closed_synonyms):
-            return (
-                TicketState.DONE if state_name_lower == "done" else TicketState.CLOSED
-            )
+            return TicketState.CLOSED
 
         # Check for "in progress" synonyms
         in_progress_synonyms = [