mcp-ticketer 0.2.0__py3-none-any.whl → 2.2.9__py3-none-any.whl

mcp_ticketer/core/project_config.py

@@ -14,7 +14,7 @@ import os
 from dataclasses import asdict, dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Optional
 
 if TYPE_CHECKING:
     from .env_discovery import DiscoveryResult
@@ -47,29 +47,29 @@ class AdapterConfig:
     enabled: bool = True
 
     # Common fields (not all adapters use all fields)
-    api_key: Optional[str] = None
-    token: Optional[str] = None
+    api_key: str | None = None
+    token: str | None = None
 
     # Linear-specific
-    team_id: Optional[str] = None
-    team_key: Optional[str] = None
-    workspace: Optional[str] = None
+    team_id: str | None = None
+    team_key: str | None = None
+    workspace: str | None = None
 
     # JIRA-specific
-    server: Optional[str] = None
-    email: Optional[str] = None
-    api_token: Optional[str] = None
-    project_key: Optional[str] = None
+    server: str | None = None
+    email: str | None = None
+    api_token: str | None = None
+    project_key: str | None = None
 
     # GitHub-specific
-    owner: Optional[str] = None
-    repo: Optional[str] = None
+    owner: str | None = None
+    repo: str | None = None
 
     # AITrackdown-specific
-    base_path: Optional[str] = None
+    base_path: str | None = None
 
     # Project ID (can be used by any adapter for scoping)
-    project_id: Optional[str] = None
+    project_id: str | None = None
 
     # Additional adapter-specific configuration
     additional_config: dict[str, Any] = field(default_factory=dict)
@@ -126,9 +126,9 @@ class ProjectConfig:
     """Configuration for a specific project."""
 
     adapter: str
-    api_key: Optional[str] = None
-    project_id: Optional[str] = None
-    team_id: Optional[str] = None
+    api_key: str | None = None
+    project_id: str | None = None
+    team_id: str | None = None
     additional_config: dict[str, Any] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
@@ -147,7 +147,7 @@ class HybridConfig:
 
     enabled: bool = False
     adapters: list[str] = field(default_factory=list)
-    primary_adapter: Optional[str] = None
+    primary_adapter: str | None = None
     sync_strategy: SyncStrategy = SyncStrategy.PRIMARY_SOURCE
 
     def to_dict(self) -> dict[str, Any]:
@@ -167,16 +167,76 @@ class HybridConfig:
 
 @dataclass
 class TicketerConfig:
-    """Complete ticketer configuration with hierarchical resolution."""
+    """Complete ticketer configuration with hierarchical resolution.
+
+    Supports URL parsing for default_project field:
+    - Linear URLs: https://linear.app/workspace/project/project-slug-abc123
+    - JIRA URLs: https://company.atlassian.net/browse/PROJ-123
+    - GitHub URLs: https://github.com/owner/repo/projects/1
+    - Plain IDs: PROJ-123, abc-123, 1 (backward compatible)
+    """
 
     default_adapter: str = "aitrackdown"
     project_configs: dict[str, ProjectConfig] = field(default_factory=dict)
     adapters: dict[str, AdapterConfig] = field(default_factory=dict)
-    hybrid_mode: Optional[HybridConfig] = None
+    hybrid_mode: HybridConfig | None = None
+
+    # Default values for ticket operations
+    default_user: str | None = None  # Default assignee (user_id or email)
+    default_project: str | None = None  # Default project/epic ID (supports URLs)
+    default_epic: str | None = None  # Alias for default_project (backward compat)
+    default_tags: list[str] | None = None  # Default tags for new tickets
+    default_team: str | None = None  # Default team ID/key for multi-team platforms
+    default_cycle: str | None = None  # Default sprint/cycle ID for timeline scoping
+    assignment_labels: list[str] | None = None  # Labels indicating ticket assignment
+
+    # Automatic project updates configuration (1M-315)
+    auto_project_updates: dict[str, Any] | None = None  # Auto update settings
+
+    def __post_init__(self):
+        """Normalize default_project if it's a URL."""
+        if self.default_project:
+            self.default_project = self._normalize_project_id(self.default_project)
+        if self.default_epic:
+            self.default_epic = self._normalize_project_id(self.default_epic)
+
+    def _normalize_project_id(self, value: str) -> str:
+        """Normalize project ID by extracting from URL if needed.
+
+        Args:
+            value: Project ID or URL
+
+        Returns:
+            Normalized project ID (plain ID, not URL)
+
+        Examples:
+            >>> config._normalize_project_id("PROJ-123")
+            'PROJ-123'
+            >>> config._normalize_project_id("https://linear.app/team/project/abc-123")
+            'abc-123'
+
+        """
+        from .url_parser import is_url, normalize_project_id
+
+        try:
+            # If it's a URL, use auto-detection (don't rely on default_adapter)
+            # This allows users to paste URLs from any platform
+            if is_url(value):
+                normalized = normalize_project_id(value, adapter_type=None)
+            else:
+                # For plain IDs, just return as-is
+                normalized = normalize_project_id(value, self.default_adapter)
+
+            logger.debug(f"Normalized '{value}' to '{normalized}'")
+            return normalized
+        except Exception as e:
+            # If normalization fails, log warning but keep original value
+            logger.warning(f"Failed to normalize project ID '{value}': {e}")
+            return value
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
-        return {
+        result = {
             "default_adapter": self.default_adapter,
             "project_configs": {
                 path: config.to_dict() for path, config in self.project_configs.items()
@@ -186,6 +246,24 @@ class TicketerConfig:
             },
             "hybrid_mode": self.hybrid_mode.to_dict() if self.hybrid_mode else None,
         }
+        # Add optional fields if set
+        if self.default_user is not None:
+            result["default_user"] = self.default_user
+        if self.default_project is not None:
+            result["default_project"] = self.default_project
+        if self.default_epic is not None:
+            result["default_epic"] = self.default_epic
+        if self.default_tags is not None:
+            result["default_tags"] = self.default_tags
+        if self.default_team is not None:
+            result["default_team"] = self.default_team
+        if self.default_cycle is not None:
+            result["default_cycle"] = self.default_cycle
+        if self.assignment_labels is not None:
+            result["assignment_labels"] = self.assignment_labels
+        if self.auto_project_updates is not None:
+            result["auto_project_updates"] = self.auto_project_updates
+        return result
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "TicketerConfig":
@@ -212,6 +290,14 @@ class TicketerConfig:
             project_configs=project_configs,
             adapters=adapters,
             hybrid_mode=hybrid_mode,
+            default_user=data.get("default_user"),
+            default_project=data.get("default_project"),
+            default_epic=data.get("default_epic"),
+            default_tags=data.get("default_tags"),
+            default_team=data.get("default_team"),
+            default_cycle=data.get("default_cycle"),
+            assignment_labels=data.get("assignment_labels"),
+            auto_project_updates=data.get("auto_project_updates"),
         )
 
 
@@ -219,29 +305,77 @@ class ConfigValidator:
     """Validate adapter configurations."""
 
     @staticmethod
-    def validate_linear_config(config: dict[str, Any]) -> tuple[bool, Optional[str]]:
+    def validate_linear_config(config: dict[str, Any]) -> tuple[bool, str | None]:
         """Validate Linear adapter configuration.
 
+        Args:
+            config: Linear configuration dictionary
+
         Returns:
             Tuple of (is_valid, error_message)
 
         """
+        import logging
+        import re
+
+        logger = logging.getLogger(__name__)
+
         required = ["api_key"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"Linear config missing required field: {field}"
+        missing_fields = []
+
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                missing_fields.append(field_name)
 
-        # Require either team_key or team_id (team_id is preferred)
-        if not config.get("team_key") and not config.get("team_id"):
+        if missing_fields:
             return (
                 False,
-                "Linear config requires either team_key (short key like 'BTA') or team_id (UUID)",
+                f"Linear config missing required fields: {', '.join(missing_fields)}",
+            )
+
+        # Require either team_key or team_id (team_key is preferred)
+        has_team_key = config.get("team_key") and config["team_key"].strip()
+        has_team_id = config.get("team_id") and config["team_id"].strip()
+
+        if not has_team_key and not has_team_id:
+            return (
+                False,
+                "Linear config requires either team_key (short key like 'ENG') or team_id (UUID)",
+            )
+
+        # Validate team_id format if provided (should be UUID)
+        if has_team_id:
+            team_id = config["team_id"]
+            uuid_pattern = re.compile(
+                r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+                re.IGNORECASE,
+            )
+
+            if not uuid_pattern.match(team_id):
+                # Not a UUID - could be a team_key mistakenly stored as team_id
+                logger.warning(
+                    f"team_id '{team_id}' is not a UUID format. "
+                    f"It will be treated as team_key and resolved at runtime."
+                )
+                # Move it to team_key if team_key is empty
+                if not has_team_key:
+                    config["team_key"] = team_id
+                    del config["team_id"]
+                    logger.info(f"Moved non-UUID team_id to team_key: {team_id}")
+
+        # Validate user_email format if provided
+        if config.get("user_email"):
+            email = config["user_email"]
+            email_pattern = re.compile(
+                r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
             )
+            if not email_pattern.match(email):
+                return False, f"Invalid email format for user_email: {email}"
 
         return True, None
 
     @staticmethod
-    def validate_github_config(config: dict[str, Any]) -> tuple[bool, Optional[str]]:
+    def validate_github_config(config: dict[str, Any]) -> tuple[bool, str | None]:
         """Validate GitHub adapter configuration.
 
         Returns:
@@ -263,14 +397,14 @@ class ConfigValidator:
 
         # Otherwise need explicit owner and repo
         required = ["owner", "repo"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"GitHub config missing required field: {field}"
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                return False, f"GitHub config missing required field: {field_name}"
 
         return True, None
 
     @staticmethod
-    def validate_jira_config(config: dict[str, Any]) -> tuple[bool, Optional[str]]:
+    def validate_jira_config(config: dict[str, Any]) -> tuple[bool, str | None]:
         """Validate JIRA adapter configuration.
 
         Returns:
@@ -278,9 +412,9 @@ class ConfigValidator:
 
         """
         required = ["server", "email", "api_token"]
-        for field in required:
-            if field not in config or not config[field]:
-                return False, f"JIRA config missing required field: {field}"
+        for field_name in required:
+            if field_name not in config or not config[field_name]:
+                return False, f"JIRA config missing required field: {field_name}"
 
         # Validate server URL format
         server = config["server"]
@@ -292,7 +426,7 @@ class ConfigValidator:
     @staticmethod
     def validate_aitrackdown_config(
         config: dict[str, Any],
-    ) -> tuple[bool, Optional[str]]:
+    ) -> tuple[bool, str | None]:
         """Validate AITrackdown adapter configuration.
 
         Returns:
@@ -306,7 +440,7 @@ class ConfigValidator:
     @classmethod
     def validate(
         cls, adapter_type: str, config: dict[str, Any]
-    ) -> tuple[bool, Optional[str]]:
+    ) -> tuple[bool, str | None]:
         """Validate configuration for any adapter type.
 
         Args:
@@ -350,7 +484,7 @@ class ConfigResolver:
     PROJECT_CONFIG_SUBPATH = ".mcp-ticketer" / Path("config.json")
 
     def __init__(
-        self, project_path: Optional[Path] = None, enable_env_discovery: bool = True
+        self, project_path: Path | None = None, enable_env_discovery: bool = True
     ):
         """Initialize config resolver.
 
@@ -361,8 +495,8 @@ class ConfigResolver:
         """
         self.project_path = project_path or Path.cwd()
         self.enable_env_discovery = enable_env_discovery
-        self._project_config: Optional[TicketerConfig] = None
-        self._discovered_config: Optional[DiscoveryResult] = None
+        self._project_config: TicketerConfig | None = None
+        self._discovered_config: DiscoveryResult | None = None
 
     def load_global_config(self) -> TicketerConfig:
         """Load default configuration (global config loading removed for security).
@@ -382,8 +516,8 @@ class ConfigResolver:
         return default_config
 
     def load_project_config(
-        self, project_path: Optional[Path] = None
-    ) -> Optional[TicketerConfig]:
+        self, project_path: Path | None = None
+    ) -> TicketerConfig | None:
         """Load project-specific configuration.
 
         Args:
@@ -424,7 +558,7 @@ class ConfigResolver:
         self.save_project_config(config)
 
     def save_project_config(
-        self, config: TicketerConfig, project_path: Optional[Path] = None
+        self, config: TicketerConfig, project_path: Path | None = None
     ) -> None:
         """Save project-specific configuration.
 
@@ -461,8 +595,8 @@ class ConfigResolver:
 
     def resolve_adapter_config(
         self,
-        adapter_name: Optional[str] = None,
-        cli_overrides: Optional[dict[str, Any]] = None,
+        adapter_name: str | None = None,
+        cli_overrides: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Resolve adapter configuration with hierarchical precedence.
 
@@ -582,6 +716,12 @@ class ConfigResolver:
                 overrides["team_id"] = os.getenv("MCP_TICKETER_LINEAR_TEAM_ID")
             if os.getenv("LINEAR_API_KEY"):
                 overrides["api_key"] = os.getenv("LINEAR_API_KEY")
+            if os.getenv("LINEAR_TEAM_ID"):
+                overrides["team_id"] = os.getenv("LINEAR_TEAM_ID")
+            if os.getenv("LINEAR_TEAM_KEY"):
+                overrides["team_key"] = os.getenv("LINEAR_TEAM_KEY")
+            if os.getenv("MCP_TICKETER_LINEAR_TEAM_KEY"):
+                overrides["team_key"] = os.getenv("MCP_TICKETER_LINEAR_TEAM_KEY")
 
         elif adapter_type == AdapterType.GITHUB.value:
             if os.getenv("MCP_TICKETER_GITHUB_TOKEN"):
@@ -623,7 +763,7 @@ class ConfigResolver:
 
         return overrides
 
-    def get_hybrid_config(self) -> Optional[HybridConfig]:
+    def get_hybrid_config(self) -> HybridConfig | None:
         """Get hybrid mode configuration if enabled.
 
         Returns:
@@ -655,10 +795,10 @@ class ConfigResolver:
 
 
 # Singleton instance for global access
-_default_resolver: Optional[ConfigResolver] = None
+_default_resolver: ConfigResolver | None = None
 
 
-def get_config_resolver(project_path: Optional[Path] = None) -> ConfigResolver:
+def get_config_resolver(project_path: Path | None = None) -> ConfigResolver:
     """Get the global config resolver instance.
 
     Args:

mcp_ticketer/core/project_utils.py

@@ -0,0 +1,281 @@
+"""Utilities for project conversion and backwards compatibility.
+
+This module provides conversion functions between the legacy Epic model and
+the new Project model, ensuring backward compatibility during the migration
+to unified project support.
+
+The conversions maintain semantic equivalence while mapping between the
+simpler Epic structure and the richer Project model with additional fields
+for visibility, scope, ownership, and statistics.
+
+Example:
+    >>> from mcp_ticketer.core.models import Epic, Priority
+    >>> from mcp_ticketer.core.project_utils import epic_to_project
+    >>>
+    >>> epic = Epic(
+    ...     epic_id="epic-123",
+    ...     title="User Authentication",
+    ...     priority=Priority.HIGH
+    ... )
+    >>> project = epic_to_project(epic)
+    >>> print(project.scope)  # ProjectScope.TEAM (default)
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import Epic, Project
+
+from .models import ProjectScope, ProjectState, TicketState
+
+
+def epic_to_project(epic: Epic) -> Project:
+    """Convert Epic model to Project model for backwards compatibility.
+
+    Maps legacy Epic fields to the new Project structure with sensible defaults
+    for new fields not present in Epic.
+
+    Field Mappings:
+        - epic.id -> project.id
+        - epic.id -> project.platform_id
+        - epic.title -> project.name
+        - epic.description -> project.description
+        - epic.state -> project.state (via state mapping)
+        - epic.url -> project.url
+        - epic.created_at -> project.created_at
+        - epic.updated_at -> project.updated_at
+        - epic.target_date -> project.target_date
+        - epic.child_issues -> project.child_issues
+
+    New fields receive defaults:
+        - scope: ProjectScope.TEAM (epics are team-level by convention)
+        - visibility: ProjectVisibility.TEAM
+        - platform: Extracted from epic.metadata or "unknown"
+
+    Args:
+        epic: Epic instance to convert
+
+    Returns:
+        Project instance with equivalent data
+
+    Example:
+        >>> epic = Epic(
+        ...     epic_id="linear-epic-123",
+        ...     title="Q4 Features",
+        ...     state="in_progress",
+        ...     child_issues=["issue-1", "issue-2"]
+        ... )
+        >>> project = epic_to_project(epic)
+        >>> project.name == epic.title
+        True
+        >>> project.scope == ProjectScope.TEAM
+        True
+
+    """
+    from .models import Project, ProjectVisibility
+
+    # Extract platform from metadata if available
+    platform = epic.metadata.get("platform", "unknown") if epic.metadata else "unknown"
+
+    # Map epic state to project state
+    state = _map_epic_state_to_project(epic.state)
+
+    return Project(
+        id=epic.id or "",
+        platform=platform,
+        platform_id=epic.id or "",
+        scope=ProjectScope.TEAM,  # Default for epics
+        name=epic.title,
+        description=epic.description,
+        state=state,
+        visibility=ProjectVisibility.TEAM,  # Default visibility
+        url=getattr(epic.metadata, "url", None) if epic.metadata else None,
+        created_at=epic.created_at,
+        updated_at=epic.updated_at,
+        target_date=(
+            getattr(epic.metadata, "target_date", None) if epic.metadata else None
+        ),
+        completed_at=(
+            getattr(epic.metadata, "completed_at", None) if epic.metadata else None
+        ),
+        child_issues=epic.child_issues or [],
+        extra_data={"original_type": "epic", **epic.metadata} if epic.metadata else {},
+    )
+
+
+def project_to_epic(project: Project) -> Epic:
+    """Convert Project model back to Epic for backwards compatibility.
+
+    Maps Project fields back to the simpler Epic structure, preserving data
+    in metadata where Epic doesn't have direct field equivalents.
+
+    Field Mappings:
+        - project.id -> epic.id
+        - project.name -> epic.title
+        - project.description -> epic.description
+        - project.state -> epic.state (via state mapping)
+        - project.child_issues -> epic.child_issues
+
+    Additional project data stored in metadata:
+        - platform, scope, visibility, ownership fields
+        - Stored under metadata["project_data"]
+
+    Args:
+        project: Project instance to convert
+
+    Returns:
+        Epic instance with equivalent core data
+
+    Example:
+        >>> from .models import ProjectScope, ProjectState
+        >>> project = Project(
+        ...     id="proj-123",
+        ...     platform="linear",
+        ...     platform_id="abc123",
+        ...     scope=ProjectScope.TEAM,
+        ...     name="Q4 Features",
+        ...     state=ProjectState.ACTIVE
+        ... )
+        >>> epic = project_to_epic(project)
+        >>> epic.title == project.name
+        True
+        >>> epic.metadata["project_data"]["platform"] == "linear"
+        True
+
+    """
+    from .models import Epic
+
+    # Map project state back to epic state string
+    state = _map_project_state_to_epic(project.state)
+
+    # Build metadata with project-specific data
+    metadata = {
+        "platform": project.platform,
+        "url": project.url,
+        "target_date": project.target_date,
+        "completed_at": project.completed_at,
+        "project_data": {
+            "scope": project.scope,
+            "visibility": project.visibility,
+            "owner_id": project.owner_id,
+            "owner_name": project.owner_name,
+            "team_id": project.team_id,
+            "team_name": project.team_name,
+            "platform_id": project.platform_id,
+        },
+        **project.extra_data,
+    }
+
+    return Epic(
+        id=project.id,
+        title=project.name,
+        description=project.description,
+        state=state,
+        created_at=project.created_at,
+        updated_at=project.updated_at,
+        child_issues=project.child_issues,
+        metadata=metadata,
+    )
+
+
+def _map_epic_state_to_project(epic_state: str | None) -> ProjectState:
+    """Map epic state string to ProjectState enum.
+
+    Provides flexible mapping from various platform-specific epic states
+    to the standardized ProjectState values.
+
+    State Mappings:
+        - "planned", "backlog" -> PLANNED
+        - "in_progress", "active", "started" -> ACTIVE
+        - "completed", "done" -> COMPLETED
+        - "archived" -> ARCHIVED
+        - "cancelled", "canceled" -> CANCELLED
+
+    Args:
+        epic_state: Epic state string (case-insensitive)
+
+    Returns:
+        Corresponding ProjectState, defaults to PLANNED if unknown
+
+    Example:
+        >>> _map_epic_state_to_project("in_progress")
+        <ProjectState.ACTIVE: 'active'>
+        >>> _map_epic_state_to_project("Done")
+        <ProjectState.COMPLETED: 'completed'>
+        >>> _map_epic_state_to_project(None)
+        <ProjectState.PLANNED: 'planned'>
+
+    """
+    if not epic_state:
+        return ProjectState.PLANNED
+
+    # Normalize to lowercase for case-insensitive matching
+    normalized = epic_state.lower().strip()
+
+    # State mapping dictionary
+    mapping = {
+        # Planned states
+        "planned": ProjectState.PLANNED,
+        "backlog": ProjectState.PLANNED,
+        "todo": ProjectState.PLANNED,
+        # Active states
+        "in_progress": ProjectState.ACTIVE,
+        "active": ProjectState.ACTIVE,
+        "started": ProjectState.ACTIVE,
+        "in progress": ProjectState.ACTIVE,
+        # Completed states
+        "completed": ProjectState.COMPLETED,
+        "done": ProjectState.COMPLETED,
+        "finished": ProjectState.COMPLETED,
+        # Archived states
+        "archived": ProjectState.ARCHIVED,
+        "archive": ProjectState.ARCHIVED,
+        # Cancelled states
+        "cancelled": ProjectState.CANCELLED,
+        "canceled": ProjectState.CANCELLED,
+        "dropped": ProjectState.CANCELLED,
+    }
+
+    return mapping.get(normalized, ProjectState.PLANNED)
+
+
+def _map_project_state_to_epic(project_state: ProjectState | str) -> TicketState:
+    """Map ProjectState back to TicketState enum for Epic.
+
+    Converts ProjectState enum values to TicketState enum values
+    suitable for Epic model which uses TicketState.
+
+    Args:
+        project_state: ProjectState enum or string value
+
+    Returns:
+        TicketState enum value compatible with Epic model
+
+    Example:
+        >>> _map_project_state_to_epic(ProjectState.ACTIVE)
+        <TicketState.IN_PROGRESS: 'in_progress'>
+        >>> _map_project_state_to_epic(ProjectState.COMPLETED)
+        <TicketState.DONE: 'done'>
+
+    """
+    # Handle both enum and string inputs
+    if isinstance(project_state, str):
+        try:
+            project_state = ProjectState(project_state)
+        except ValueError:
+            # If invalid string, return default
+            return TicketState.OPEN
+
+    # Map ProjectState to TicketState
+    mapping = {
+        ProjectState.PLANNED: TicketState.OPEN,
+        ProjectState.ACTIVE: TicketState.IN_PROGRESS,
+        ProjectState.COMPLETED: TicketState.DONE,
+        ProjectState.ARCHIVED: TicketState.CLOSED,
+        ProjectState.CANCELLED: TicketState.CLOSED,
+    }
+
+    return mapping.get(project_state, TicketState.OPEN)