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

mcp_ticketer/core/mappers.py

@@ -98,13 +98,13 @@ class StateMapper(BaseMapper):
         self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
-    def get_mapping(self) -> BiDirectionalDict:
+    def get_mapping(self) -> BiDirectionalDict[TicketState, str]:
         """Get cached bidirectional state mapping."""
         if self._mapping is not None:
             return self._mapping
 
         # Default mappings by adapter type
-        default_mappings = {
+        default_mappings: dict[str, dict[TicketState, str]] = {
             "github": {
                 TicketState.OPEN: "open",
                 TicketState.IN_PROGRESS: "open",  # Uses labels
@@ -147,13 +147,16 @@ class StateMapper(BaseMapper):
             },
         }
 
-        mapping = default_mappings.get(self.adapter_type, {})
+        mapping: dict[TicketState, str] = default_mappings.get(self.adapter_type, {})
 
-        # Apply custom mappings
+        # Apply custom mappings (cast to proper type)
         if self.custom_mappings:
-            mapping.update(self.custom_mappings)
+            # custom_mappings might have str keys, need to convert to TicketState
+            for key, value in self.custom_mappings.items():
+                if isinstance(key, TicketState):
+                    mapping[key] = value
 
-        self._mapping = BiDirectionalDict(mapping)
+        self._mapping = BiDirectionalDict[TicketState, str](mapping)
         return self._mapping
 
     def to_system_state(self, adapter_state: str) -> TicketState:
@@ -168,7 +171,9 @@ class StateMapper(BaseMapper):
         """
         cache_key = f"to_system_{adapter_state}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, TicketState):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_reverse(adapter_state)
@@ -205,7 +210,9 @@ class StateMapper(BaseMapper):
         """
         cache_key = f"from_system_{system_state.value}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, str):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_forward(system_state)
@@ -273,13 +280,13 @@ class PriorityMapper(BaseMapper):
         self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
-    def get_mapping(self) -> BiDirectionalDict:
+    def get_mapping(self) -> BiDirectionalDict[Priority, Any]:
         """Get cached bidirectional priority mapping."""
         if self._mapping is not None:
             return self._mapping
 
         # Default mappings by adapter type
-        default_mappings = {
+        default_mappings: dict[str, dict[Priority, Any]] = {
             "github": {
                 Priority.CRITICAL: "P0",
                 Priority.HIGH: "P1",
@@ -306,13 +313,16 @@ class PriorityMapper(BaseMapper):
             },
         }
 
-        mapping = default_mappings.get(self.adapter_type, {})
+        mapping: dict[Priority, Any] = default_mappings.get(self.adapter_type, {})
 
-        # Apply custom mappings
+        # Apply custom mappings (cast to proper type)
         if self.custom_mappings:
-            mapping.update(self.custom_mappings)
+            # custom_mappings might have str keys, need to convert to Priority
+            for key, value in self.custom_mappings.items():
+                if isinstance(key, Priority):
+                    mapping[key] = value
 
-        self._mapping = BiDirectionalDict(mapping)
+        self._mapping = BiDirectionalDict[Priority, Any](mapping)
         return self._mapping
 
     def to_system_priority(self, adapter_priority: Any) -> Priority:
@@ -327,7 +337,9 @@ class PriorityMapper(BaseMapper):
         """
         cache_key = f"to_system_{adapter_priority}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, Priority):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_reverse(adapter_priority)
@@ -365,7 +377,7 @@ class PriorityMapper(BaseMapper):
                     ]:
                         result = Priority.LOW
                         break
-            elif isinstance(adapter_priority, (int, float)):
+            elif isinstance(adapter_priority, int | float):
                 # Handle numeric priorities (Linear-style)
                 if adapter_priority <= 1:
                     result = Priority.CRITICAL
@@ -524,10 +536,10 @@ class MapperRegistry:
     @classmethod
     def clear_cache(cls) -> None:
         """Clear all mapper caches."""
-        for mapper in cls._state_mappers.values():
-            mapper.clear_cache()
-        for mapper in cls._priority_mappers.values():
-            mapper.clear_cache()
+        for state_mapper in cls._state_mappers.values():
+            state_mapper.clear_cache()
+        for priority_mapper in cls._priority_mappers.values():
+            priority_mapper.clear_cache()
 
     @classmethod
     def reset(cls) -> None:

mcp_ticketer/core/models.py

@@ -160,6 +160,37 @@ class TicketState(str, Enum):
         """
         return target.value in self.valid_transitions().get(self, [])
 
+    def completion_level(self) -> int:
+        """Get numeric completion level for state ordering.
+
+        Higher numbers indicate more complete states. Used for parent/child
+        state constraints where parents must be at least as complete as
+        their most complete child.
+
+        Returns:
+            Completion level (0-7)
+
+        Example:
+            >>> TicketState.OPEN.completion_level()
+            0
+            >>> TicketState.DONE.completion_level()
+            6
+            >>> TicketState.DONE.completion_level() > TicketState.IN_PROGRESS.completion_level()
+            True
+
+        """
+        levels = {
+            TicketState.OPEN: 0,  # Not started
+            TicketState.BLOCKED: 1,  # Blocked
+            TicketState.WAITING: 2,  # Waiting
+            TicketState.IN_PROGRESS: 3,  # In progress
+            TicketState.READY: 4,  # Ready for review
+            TicketState.TESTED: 5,  # Tested
+            TicketState.DONE: 6,  # Done
+            TicketState.CLOSED: 7,  # Closed (terminal)
+        }
+        return levels.get(self, 0)
+
 
 class BaseTicket(BaseModel):
     """Base model for all ticket types with universal field mapping.
@@ -380,11 +411,114 @@ class Attachment(BaseModel):
     )
 
     def __str__(self) -> str:
-        """String representation showing filename and size."""
+        """Return string representation showing filename and size."""
         size_str = f" ({self.size_bytes} bytes)" if self.size_bytes else ""
         return f"Attachment({self.filename}{size_str})"
 
 
+class ProjectUpdateHealth(str, Enum):
+    """Project health status indicator for status updates.
+
+    Represents the health/status of a project at the time of an update.
+    These states map to different platform-specific health indicators:
+
+    Platform Mappings:
+    - Linear: on_track, at_risk, off_track (1:1 mapping)
+    - GitHub V2: Uses ProjectV2StatusOptionConfiguration
+      - complete: Project is finished
+      - inactive: Project is not actively being worked on
+    - Asana: On Track, At Risk, Off Track (1:1 mapping)
+    - JIRA: Not directly supported (workaround via status comments)
+
+    Attributes:
+        ON_TRACK: Project is progressing as planned
+        AT_RISK: Project has some issues but recoverable
+        OFF_TRACK: Project is significantly behind or blocked
+        COMPLETE: Project is finished (GitHub-specific)
+        INACTIVE: Project is not actively being worked on (GitHub-specific)
+
+    Note:
+        Related to ticket 1M-238: Add project updates support with flexible
+        project identification.
+
+    """
+
+    ON_TRACK = "on_track"  # Linear, Asana
+    AT_RISK = "at_risk"  # Linear, Asana
+    OFF_TRACK = "off_track"  # Linear, Asana
+    COMPLETE = "complete"  # GitHub only
+    INACTIVE = "inactive"  # GitHub only
+
+
+class ProjectUpdate(BaseModel):
+    """Represents a project status update across different platforms.
+
+    ProjectUpdate provides a unified interface for creating and retrieving
+    project status updates with health indicators, supporting Linear, GitHub V2,
+    Asana, and JIRA (via workaround).
+
+    Platform Mappings:
+    - Linear: ProjectUpdate entity with health, diff_markdown, staleness
+    - GitHub V2: ProjectV2StatusUpdate with status options
+    - Asana: Project Status Updates with color-coded health
+    - JIRA: Comments with custom formatting (workaround)
+
+    The model includes platform-specific optional fields to support features
+    like Linear's auto-generated diffs and staleness indicators.
+
+    Attributes:
+        id: Unique identifier for the update
+        project_id: ID of the project this update belongs to
+        project_name: Optional human-readable project name
+        body: Markdown-formatted update content (required)
+        health: Optional health status indicator
+        created_at: Timestamp when update was created
+        updated_at: Timestamp when update was last modified
+        author_id: Optional ID of the user who created the update
+        author_name: Optional human-readable author name
+        url: Optional direct URL to the update
+        diff_markdown: Linear-specific auto-generated diff of project changes
+        is_stale: Linear-specific indicator if update is outdated
+
+    Example:
+        >>> update = ProjectUpdate(
+        ...     project_id="PROJ-123",
+        ...     body="Sprint completed with 15/20 stories done",
+        ...     health=ProjectUpdateHealth.AT_RISK,
+        ...     created_at=datetime.now()
+        ... )
+        >>> print(update.model_dump_json())
+
+    Note:
+        Related to ticket 1M-238: Add project updates support with flexible
+        project identification.
+
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str = Field(..., description="Unique update identifier")
+    project_id: str = Field(..., description="Parent project identifier")
+    project_name: str | None = Field(None, description="Human-readable project name")
+    body: str = Field(..., min_length=1, description="Markdown update content")
+    health: ProjectUpdateHealth | None = Field(
+        None, description="Project health status"
+    )
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
+    author_id: str | None = Field(None, description="Update author identifier")
+    author_name: str | None = Field(None, description="Update author name")
+    url: str | None = Field(None, description="Direct URL to update")
+
+    # Platform-specific fields
+    diff_markdown: str | None = Field(
+        None, description="Linear: Auto-generated diff of project changes"
+    )
+    is_stale: bool | None = Field(
+        None, description="Linear: Indicator if update is outdated"
+    )
+
+
 class SearchQuery(BaseModel):
     """Search query parameters."""
 
@@ -393,5 +527,6 @@ class SearchQuery(BaseModel):
     priority: Priority | None = Field(None, description="Filter by priority")
     tags: list[str] | None = Field(None, description="Filter by tags")
     assignee: str | None = Field(None, description="Filter by assignee")
+    project: str | None = Field(None, description="Filter by project/epic ID or name")
     limit: int = Field(10, gt=0, le=100, description="Maximum results")
     offset: int = Field(0, ge=0, description="Result offset for pagination")

mcp_ticketer/core/onepassword_secrets.py

@@ -0,0 +1,379 @@
+"""1Password CLI integration for secure secret management.
+
+This module provides automatic secret loading from 1Password using the op CLI,
+supporting:
+- Detection of op:// secret references in .env files
+- Automatic resolution using `op run` or `op inject`
+- Fallback to regular .env values if 1Password CLI is not available
+- Support for .env.1password template files
+"""
+
+import logging
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class OnePasswordConfig:
+    """Configuration for 1Password integration."""
+
+    enabled: bool = True
+    vault: str | None = None  # Default vault for secret references
+    service_account_token: str | None = None  # For CI/CD environments
+    fallback_to_env: bool = True  # Fall back to regular .env if op CLI unavailable
+
+
+class OnePasswordSecretsLoader:
+    """Load secrets from 1Password using the op CLI.
+
+    This class provides methods to:
+    1. Check if 1Password CLI is installed and authenticated
+    2. Resolve op:// secret references in .env files
+    3. Load secrets into environment variables
+    4. Create .env templates with op:// references
+    """
+
+    def __init__(self, config: OnePasswordConfig | None = None) -> None:
+        """Initialize the 1Password secrets loader.
+
+        Args:
+            config: Configuration for 1Password integration
+
+        """
+        self.config = config or OnePasswordConfig()
+        self._op_available: bool | None = None
+        self._op_authenticated: bool | None = None
+
+    def is_op_available(self) -> bool:
+        """Check if 1Password CLI is installed.
+
+        Returns:
+            True if op CLI is available, False otherwise
+
+        """
+        if self._op_available is None:
+            self._op_available = shutil.which("op") is not None
+            if not self._op_available:
+                logger.debug("1Password CLI (op) not found in PATH")
+        return self._op_available
+
+    def is_authenticated(self) -> bool:
+        """Check if user is authenticated with 1Password.
+
+        Returns:
+            True if authenticated, False otherwise
+
+        """
+        if not self.is_op_available():
+            return False
+
+        if self._op_authenticated is None:
+            try:
+                # Try to list accounts to check authentication
+                result = subprocess.run(
+                    ["op", "account", "list"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                self._op_authenticated = result.returncode == 0
+                if not self._op_authenticated:
+                    logger.debug(
+                        "1Password CLI not authenticated. Run 'op signin' first."
+                    )
+            except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+                logger.debug(f"Error checking 1Password authentication: {e}")
+                self._op_authenticated = False
+
+        return self._op_authenticated
+
+    def load_secrets_from_env_file(
+        self, env_file: Path, output_dict: dict[str, str] | None = None
+    ) -> dict[str, str]:
+        """Load secrets from .env file, resolving 1Password references.
+
+        This method:
+        1. Checks if the .env file contains op:// references
+        2. If yes and op CLI is available, uses op inject to resolve them
+        3. If no op references or CLI unavailable, returns regular dotenv values
+
+        Args:
+            env_file: Path to .env file (may contain op:// references)
+            output_dict: Optional dict to update with loaded secrets
+
+        Returns:
+            Dictionary of environment variables with secrets resolved
+
+        """
+        if not env_file.exists():
+            logger.warning(f"Environment file not found: {env_file}")
+            return output_dict or {}
+
+        # Read the file to check for op:// references
+        content = env_file.read_text(encoding="utf-8")
+        has_op_references = "op://" in content
+
+        if has_op_references and self.is_authenticated():
+            # Use op inject to resolve references
+            return self._inject_secrets(env_file, output_dict)
+        else:
+            # Fall back to regular dotenv parsing
+            if has_op_references and not self.is_authenticated():
+                logger.warning(
+                    f"File {env_file} contains 1Password references but op CLI "
+                    "is not authenticated. Using fallback values."
+                )
+            return self._load_regular_env(env_file, output_dict)
+
+    def _inject_secrets(
+        self, env_file: Path, output_dict: dict[str, str] | None = None
+    ) -> dict[str, str]:
+        """Use op inject to resolve secret references in .env file.
+
+        Args:
+            env_file: Path to .env file with op:// references
+            output_dict: Optional dict to update
+
+        Returns:
+            Dictionary with resolved secrets
+
+        """
+        try:
+            # Use op inject to resolve references
+            cmd = ["op", "inject", "--in-file", str(env_file)]
+
+            # Add service account token if provided
+            env = None
+            if self.config.service_account_token:
+                env = {"OP_SERVICE_ACCOUNT_TOKEN": self.config.service_account_token}
+
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=True,
+                env=env,
+            )
+
+            # Parse the injected output
+            secrets = self._parse_env_output(result.stdout)
+
+            if output_dict is not None:
+                output_dict.update(secrets)
+                return output_dict
+            return secrets
+
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Error injecting 1Password secrets: {e.stderr}")
+            if self.config.fallback_to_env:
+                logger.info("Falling back to regular .env parsing")
+                return self._load_regular_env(env_file, output_dict)
+            raise
+        except subprocess.TimeoutExpired:
+            logger.error("Timeout while injecting 1Password secrets")
+            if self.config.fallback_to_env:
+                return self._load_regular_env(env_file, output_dict)
+            raise
+
+    def _load_regular_env(
+        self, env_file: Path, output_dict: dict[str, str] | None = None
+    ) -> dict[str, str]:
+        """Load environment variables without 1Password resolution.
+
+        Args:
+            env_file: Path to .env file
+            output_dict: Optional dict to update
+
+        Returns:
+            Dictionary of environment variables
+
+        """
+        from dotenv import dotenv_values
+
+        values = dotenv_values(env_file)
+
+        if output_dict is not None:
+            output_dict.update(values)
+            return output_dict
+        return dict(values)
+
+    def _parse_env_output(self, output: str) -> dict[str, str]:
+        """Parse environment variable output from op inject.
+
+        Args:
+            output: String output from op inject
+
+        Returns:
+            Dictionary of parsed environment variables
+
+        """
+        env_vars = {}
+        for line in output.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            # Split on first = only
+            if "=" in line:
+                key, value = line.split("=", 1)
+                key = key.strip()
+                value = value.strip()
+
+                # Remove quotes if present
+                if value.startswith('"') and value.endswith('"'):
+                    value = value[1:-1]
+                elif value.startswith("'") and value.endswith("'"):
+                    value = value[1:-1]
+
+                env_vars[key] = value
+
+        return env_vars
+
+    def create_template_file(
+        self,
+        output_path: Path,
+        adapter_type: str,
+        vault_name: str = "Development",
+        item_name: str | None = None,
+    ) -> None:
+        """Create a .env template file with 1Password secret references.
+
+        Args:
+            output_path: Path where to create the template file
+            adapter_type: Type of adapter (linear, github, jira, aitrackdown)
+            vault_name: Name of 1Password vault to use
+            item_name: Name of 1Password item (defaults to adapter name)
+
+        """
+        if item_name is None:
+            item_name = adapter_type.upper()
+
+        templates = {
+            "linear": f"""# Linear Configuration with 1Password
+# This file contains secret references that will be resolved by 1Password CLI
+# Run: op run --env-file=.env.1password -- mcp-ticketer discover
+
+LINEAR_API_KEY="op://{vault_name}/{item_name}/api_key"
+LINEAR_TEAM_ID="op://{vault_name}/{item_name}/team_id"
+LINEAR_TEAM_KEY="op://{vault_name}/{item_name}/team_key"
+LINEAR_PROJECT_ID="op://{vault_name}/{item_name}/project_id"
+""",
+            "github": f"""# GitHub Configuration with 1Password
+# This file contains secret references that will be resolved by 1Password CLI
+# Run: op run --env-file=.env.1password -- mcp-ticketer discover
+
+GITHUB_TOKEN="op://{vault_name}/{item_name}/token"
+GITHUB_OWNER="op://{vault_name}/{item_name}/owner"
+GITHUB_REPO="op://{vault_name}/{item_name}/repo"
+""",
+            "jira": f"""# JIRA Configuration with 1Password
+# This file contains secret references that will be resolved by 1Password CLI
+# Run: op run --env-file=.env.1password -- mcp-ticketer discover
+
+JIRA_SERVER="op://{vault_name}/{item_name}/server"
+JIRA_EMAIL="op://{vault_name}/{item_name}/email"
+JIRA_API_TOKEN="op://{vault_name}/{item_name}/api_token"
+JIRA_PROJECT_KEY="op://{vault_name}/{item_name}/project_key"
+""",
+            "aitrackdown": """# AITrackdown Configuration
+# AITrackdown doesn't use API keys, but you can store the base path
+
+AITRACKDOWN_PATH=".aitrackdown"
+""",
+        }
+
+        template = templates.get(adapter_type.lower(), "")
+        if template:
+            output_path.write_text(template, encoding="utf-8")
+            logger.info(f"Created 1Password template file: {output_path}")
+        else:
+            logger.error(f"Unknown adapter type: {adapter_type}")
+
+    def run_with_secrets(
+        self, command: list[str], env_file: Path | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        """Run a command with secrets loaded from 1Password.
+
+        Args:
+            command: Command and arguments to run
+            env_file: Optional .env file with secret references
+
+        Returns:
+            CompletedProcess result
+
+        """
+        if not self.is_authenticated():
+            raise RuntimeError(
+                "1Password CLI not authenticated. Run 'op signin' first."
+            )
+
+        cmd = ["op", "run"]
+
+        if env_file:
+            cmd.extend(["--env-file", str(env_file)])
+
+        cmd.append("--")
+        cmd.extend(command)
+
+        return subprocess.run(cmd, capture_output=True, text=True, check=True)
+
+
+def check_op_cli_status() -> dict[str, Any]:
+    """Check the status of 1Password CLI installation and authentication.
+
+    Returns:
+        Dictionary with status information
+
+    """
+    loader = OnePasswordSecretsLoader()
+
+    status: dict[str, Any] = {
+        "installed": loader.is_op_available(),
+        "authenticated": False,
+        "version": None,
+        "accounts": [],
+    }
+
+    if status["installed"]:
+        # Get version
+        try:
+            result = subprocess.run(
+                ["op", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+            if result.returncode == 0:
+                status["version"] = result.stdout.strip()
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            pass
+
+        # Check authentication
+        status["authenticated"] = loader.is_authenticated()
+
+        # Get accounts if authenticated
+        if status["authenticated"]:
+            try:
+                result = subprocess.run(
+                    ["op", "account", "list", "--format=json"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    import json
+
+                    status["accounts"] = json.loads(result.stdout)
+            except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+                pass
+
+    return status