titan-cli 0.1.0__py3-none-any.whl

titan_plugin_jira/plugin.py

@@ -0,0 +1,264 @@
+from pathlib import Path
+from typing import Optional, TypedDict, List
+from pydantic import ValidationError
+from titan_cli.core.plugins.models import JiraPluginConfig
+from titan_cli.core.plugins.plugin_base import TitanPlugin
+from titan_cli.core.config import TitanConfig
+from titan_cli.core.secrets import SecretManager
+from .clients.jira_client import JiraClient
+from .exceptions import JiraConfigurationError, JiraClientError
+from .messages import msg
+
+
+class TokenValidationResult(TypedDict):
+    """Result of token validation."""
+    valid: bool
+    error: Optional[str]
+    user: Optional[str]
+    email: Optional[str]
+    token_source: dict
+    warnings: List[str]
+
+
+class JiraPlugin(TitanPlugin):
+    """
+    Titan CLI Plugin for JIRA operations.
+    Provides a JiraClient for interacting with JIRA REST API.
+    """
+
+    @property
+    def name(self) -> str:
+        return "jira"
+
+    @property
+    def description(self) -> str:
+        return "Provides JIRA API integration with AI-powered issue management."
+
+    @property
+    def dependencies(self) -> list[str]:
+        return []
+
+    def initialize(self, config: TitanConfig, secrets: SecretManager) -> None:
+        """
+        Initialize with configuration.
+
+        Configuration cascade (project overrides global):
+            1. Global credentials (~/.titan/config.toml): base_url, email
+            2. Project settings (.titan/config.toml): default_project (optional)
+
+        Note: TitanConfig automatically merges global and project configs,
+        so _get_plugin_config() returns the already-merged configuration.
+
+        Reads API token from secrets:
+            JIRA_API_TOKEN or {email}_jira_api_token
+        """
+        # Get plugin-specific configuration data (already merged by TitanConfig)
+        plugin_config_data = self._get_plugin_config(config)
+
+        # Validate configuration using Pydantic model
+        # Pydantic validators will check base_url and email during construction
+        try:
+            validated_config = JiraPluginConfig(**plugin_config_data)
+        except ValidationError as e:
+            raise JiraConfigurationError(str(e)) from e
+
+        # Get API token from secrets
+        # Try multiple secret keys for backwards compatibility
+        # Priority: project-specific → plugin-specific → env var → email-specific
+        project_name = config.get_project_name()
+        project_key = f"{project_name}_jira_api_token" if project_name else None
+
+        api_token = (
+            (secrets.get(project_key) if project_key else None) or  # Project-specific keychain
+            secrets.get("jira_api_token") or  # Standard: plugin_fieldname
+            secrets.get("JIRA_API_TOKEN") or  # Environment variable
+            secrets.get(f"{validated_config.email}_jira_api_token")  # Email-specific
+        )
+
+        if not api_token:
+            raise JiraConfigurationError(
+                "JIRA API token not found in secrets. "
+                "Please configure the JIRA plugin to set the API token."
+            )
+
+        # Initialize client with validated configuration
+        self._client = JiraClient(
+            base_url=validated_config.base_url,
+            email=validated_config.email,
+            api_token=api_token,
+            project_key=validated_config.default_project,
+            timeout=validated_config.timeout,
+            enable_cache=validated_config.enable_cache,
+            cache_ttl=validated_config.cache_ttl
+        )
+
+        # Store token source info for diagnostics (without exposing token value)
+        self._token_source = self._identify_token_source(
+            secrets, project_name, validated_config.email, api_token
+        )
+
+    def _identify_token_source(
+        self, secrets: SecretManager, project_name: Optional[str],
+        email: str, token: str
+    ) -> dict:
+        """
+        Identify which source the token came from for diagnostics.
+
+        Returns:
+            Dict with source info (name, type, details)
+        """
+        project_key = f"{project_name}_jira_api_token" if project_name else None
+
+        if project_key and secrets.get(project_key) == token:
+            return {
+                "name": project_key,
+                "type": "project-specific",
+                "details": f"Token for project '{project_name}'"
+            }
+        elif secrets.get("jira_api_token") == token:
+            return {
+                "name": "jira_api_token",
+                "type": "global",
+                "details": "Global JIRA token (recommended)"
+            }
+        elif secrets.get("JIRA_API_TOKEN") == token:
+            return {
+                "name": "JIRA_API_TOKEN",
+                "type": "environment",
+                "details": "Environment variable"
+            }
+        elif secrets.get(f"{email}_jira_api_token") == token:
+            return {
+                "name": f"{email}_jira_api_token",
+                "type": "email-specific",
+                "details": f"Token for email '{email}'"
+            }
+        else:
+            return {
+                "name": "unknown",
+                "type": "unknown",
+                "details": "Token source could not be identified"
+            }
+
+    @property
+    def has_default_project(self) -> bool:
+        """Check if a default project is configured."""
+        return hasattr(self, '_client') and self._client.project_key is not None
+
+    def validate_token(self) -> TokenValidationResult:
+        """
+        Validate that the current token works by making a test API call.
+
+        Also checks configuration completeness and returns warnings.
+
+        Returns:
+            TokenValidationResult with validation results
+        """
+        warnings = []
+
+        # Check if default project is configured
+        if not self.has_default_project:
+            warnings.append(
+                "No default_project configured. "
+                "Some operations (like create_subtask) will fail without a project."
+            )
+
+        if not self.is_available():
+            return {
+                "valid": False,
+                "error": "JIRA client not initialized",
+                "user": None,
+                "email": None,
+                "token_source": getattr(self, '_token_source', {}),
+                "warnings": warnings
+            }
+
+        try:
+            # Test token with /rest/api/2/myself endpoint
+            myself = self._client.get_current_user()
+            return {
+                "valid": True,
+                "error": None,
+                "user": myself.get("displayName", "Unknown"),
+                "email": myself.get("emailAddress", "Unknown"),
+                "token_source": getattr(self, '_token_source', {}),
+                "warnings": warnings
+            }
+        except Exception as e:
+            return {
+                "valid": False,
+                "error": str(e),
+                "user": None,
+                "email": None,
+                "token_source": getattr(self, '_token_source', {}),
+                "warnings": warnings
+            }
+
+    def _get_plugin_config(self, config: TitanConfig) -> dict:
+        """
+        Extract plugin-specific configuration.
+
+        Args:
+            config: TitanConfig instance
+
+        Returns:
+            Plugin config dict (empty if not configured)
+        """
+        if "jira" not in config.config.plugins:
+            return {}
+
+        plugin_entry = config.config.plugins["jira"]
+        return plugin_entry.config if hasattr(plugin_entry, 'config') else {}
+
+    def get_config_schema(self) -> dict:
+        """
+        Return JSON schema for plugin configuration.
+
+        Returns:
+            JSON schema dict with api_token marked as required (even though it's stored in secrets)
+        """
+        schema = JiraPluginConfig.model_json_schema()
+        # Ensure api_token is in required list for interactive configuration
+        # (even though it's Optional in the model since it's stored in secrets)
+        if "api_token" not in schema.get("required", []):
+            schema.setdefault("required", []).append("api_token")
+        return schema
+
+    def is_available(self) -> bool:
+        """
+        Checks if the JIRA client is initialized and ready.
+        """
+        return hasattr(self, '_client') and self._client is not None
+
+    def get_client(self) -> JiraClient:
+        """
+        Returns the initialized JiraClient instance.
+        """
+        if not hasattr(self, '_client') or self._client is None:
+            raise JiraClientError(msg.Plugin.JIRA_CLIENT_NOT_AVAILABLE)
+        return self._client
+
+    def get_steps(self) -> dict:
+        """
+        Returns a dictionary of available workflow steps.
+        """
+        from .steps.search_saved_query_step import search_saved_query_step
+        from .steps.prompt_select_issue_step import prompt_select_issue_step
+        from .steps.get_issue_step import get_issue_step
+        from .steps.ai_analyze_issue_step import ai_analyze_issue_requirements_step
+        return {
+            "search_saved_query": search_saved_query_step,
+            "prompt_select_issue": prompt_select_issue_step,
+            "get_issue": get_issue_step,
+            "ai_analyze_issue_requirements": ai_analyze_issue_requirements_step,
+        }
+
+    @property
+    def workflows_path(self) -> Optional[Path]:
+        """
+        Returns the path to the workflows directory.
+
+        Returns:
+            Path to workflows directory containing YAML workflow definitions
+        """
+        return Path(__file__).parent / "workflows"

titan_plugin_jira/steps/ai_analyze_issue_step.py

@@ -0,0 +1,105 @@
+"""
+AI-powered JIRA issue analysis step
+"""
+
+from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error, Skip
+from titan_cli.ui.tui.widgets import Panel
+from ..messages import msg
+from ..agents import JiraAgent
+from ..formatters import IssueAnalysisMarkdownFormatter
+
+
+def ai_analyze_issue_requirements_step(ctx: WorkflowContext) -> WorkflowResult:
+    """
+    Analyze JIRA issue requirements using AI.
+
+    Provides intelligent analysis of:
+    - Summary and description breakdown
+    - Acceptance criteria extraction
+    - Technical requirements identification
+    - Potential challenges and risks
+    - Implementation suggestions
+    - Missing information detection
+
+    Inputs (from ctx.data):
+        jira_issue (JiraTicket): JIRA issue object to analyze
+        selected_issue (JiraTicket, optional): Alternative source
+
+    Outputs (saved to ctx.data):
+        ai_analysis (str): AI-generated analysis
+        analysis_sections (dict): Structured analysis breakdown
+    """
+    if not ctx.textual:
+        return Error("Textual UI context is not available for this step.")
+
+    # Check if AI is available
+    if not ctx.ai or not ctx.ai.is_available():
+        ctx.textual.mount(Panel(msg.Steps.AIIssue.AI_NOT_CONFIGURED_SKIP, panel_type="info"))
+        return Skip(msg.Steps.AIIssue.AI_NOT_CONFIGURED)
+
+    # Get issue to analyze
+    issue = ctx.get("jira_issue") or ctx.get("selected_issue")
+    if not issue:
+        ctx.textual.mount(Panel(msg.Steps.AIIssue.NO_ISSUE_FOUND, panel_type="error"))
+        return Error(msg.Steps.AIIssue.NO_ISSUE_FOUND)
+
+    # Create JiraAgent instance and analyze issue with loading indicator
+    with ctx.textual.loading(msg.Steps.AIIssue.ANALYZING):
+        jira_agent = JiraAgent(ctx.ai, ctx.jira)
+        analysis = jira_agent.analyze_issue(
+            issue_key=issue.key,
+            include_subtasks=True,
+            include_comments=False,
+            include_linked_issues=False
+        )
+
+    # Build formatted analysis for display
+    # Use template from config if specified, otherwise use built-in formatter
+    template_name = jira_agent.config.template if jira_agent.config.template else None
+    formatter = IssueAnalysisMarkdownFormatter(template_path=template_name)
+    ai_analysis = formatter.format(analysis)
+
+    # Display analysis
+    ctx.textual.text("")
+    ctx.textual.text("AI Analysis Results", markup="bold cyan")
+    ctx.textual.text("")
+
+    # Show issue header
+    ctx.textual.text(f"{issue.key}: {issue.summary}", markup="bold")
+    ctx.textual.text(f"Type: {issue.issue_type} | Status: {issue.status} | Priority: {issue.priority}", markup="dim")
+    ctx.textual.text("")
+
+    # Show AI analysis as markdown
+    ctx.textual.markdown(ai_analysis)
+
+    # Show token usage
+    if analysis.total_tokens_used > 0:
+        ctx.textual.text(f"Tokens used: {analysis.total_tokens_used}", markup="dim")
+
+    # Save structured analysis to context
+    ctx.set("ai_analysis_structured", {
+        "functional_requirements": analysis.functional_requirements,
+        "non_functional_requirements": analysis.non_functional_requirements,
+        "acceptance_criteria": analysis.acceptance_criteria,
+        "technical_approach": analysis.technical_approach,
+        "dependencies": analysis.dependencies,
+        "risks": analysis.risks,
+        "edge_cases": analysis.edge_cases,
+        "suggested_subtasks": analysis.suggested_subtasks,
+        "complexity_score": analysis.complexity_score,
+        "estimated_effort": analysis.estimated_effort
+    })
+
+    return Success(
+        "AI analysis completed",
+        metadata={
+            "ai_analysis": ai_analysis,
+            "analyzed_issue_key": issue.key,
+            "tokens_used": analysis.total_tokens_used,
+            "complexity": analysis.complexity_score,
+            "effort": analysis.estimated_effort
+        }
+    )
+
+
+__all__ = ["ai_analyze_issue_requirements_step"]

titan_plugin_jira/steps/get_issue_step.py

@@ -0,0 +1,82 @@
+"""
+Get JIRA issue details step
+"""
+
+from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error
+from titan_cli.ui.tui.widgets import Panel
+from ..exceptions import JiraAPIError
+from ..messages import msg
+
+
+def get_issue_step(ctx: WorkflowContext) -> WorkflowResult:
+    """
+    Get JIRA issue details by key.
+
+    Inputs (from ctx.data):
+        jira_issue_key (str): JIRA issue key (e.g., "PROJ-123")
+        expand (list[str], optional): Additional fields to expand
+
+    Outputs (saved to ctx.data):
+        jira_issue (JiraTicket): Issue details
+
+    Returns:
+        Success: Issue retrieved
+        Error: Failed to get issue
+    """
+    if not ctx.textual:
+        return Error("Textual UI context is not available for this step.")
+
+    # Check if JIRA client is available
+    if not ctx.jira:
+        ctx.textual.mount(Panel(msg.Plugin.CLIENT_NOT_AVAILABLE_IN_CONTEXT, panel_type="error"))
+        return Error(msg.Plugin.CLIENT_NOT_AVAILABLE_IN_CONTEXT)
+
+    # Get issue key
+    issue_key = ctx.get("jira_issue_key")
+    if not issue_key:
+        ctx.textual.mount(Panel("JIRA issue key is required", panel_type="error"))
+        return Error("JIRA issue key is required")
+
+    # Get optional expand fields
+    expand = ctx.get("expand")
+
+    try:
+        # Get issue with loading indicator
+        with ctx.textual.loading(msg.Steps.GetIssue.GETTING_ISSUE.format(issue_key=issue_key)):
+            issue = ctx.jira.get_ticket(ticket_key=issue_key, expand=expand)
+
+        # Show success
+        ctx.textual.mount(
+            Panel(
+                text=msg.Steps.GetIssue.GET_SUCCESS.format(issue_key=issue_key),
+                panel_type="success"
+            )
+        )
+
+        # Show issue details
+        ctx.textual.text(f"  Title: {issue.summary}", markup="cyan")
+        ctx.textual.text(f"  Status: {issue.status}")
+        ctx.textual.text(f"  Type: {issue.issue_type}")
+        ctx.textual.text(f"  Assignee: {issue.assignee or 'Unassigned'}")
+        ctx.textual.text("")
+
+        return Success(
+            msg.Steps.GetIssue.GET_SUCCESS.format(issue_key=issue_key),
+            metadata={"jira_issue": issue}
+        )
+
+    except JiraAPIError as e:
+        if e.status_code == 404:
+            error_msg = msg.Steps.GetIssue.ISSUE_NOT_FOUND.format(issue_key=issue_key)
+            ctx.textual.mount(Panel(error_msg, panel_type="error"))
+            return Error(error_msg)
+        error_msg = msg.Steps.GetIssue.GET_FAILED.format(e=e)
+        ctx.textual.mount(Panel(error_msg, panel_type="error"))
+        return Error(error_msg)
+    except Exception as e:
+        error_msg = f"Unexpected error getting issue: {e}"
+        ctx.textual.mount(Panel(error_msg, panel_type="error"))
+        return Error(error_msg)
+
+
+__all__ = ["get_issue_step"]

titan_plugin_jira/steps/prompt_select_issue_step.py

@@ -0,0 +1,80 @@
+"""
+Prompt user to select an issue from search results
+"""
+
+from titan_cli.engine import WorkflowContext, WorkflowResult, Success, Error
+from titan_cli.ui.tui.widgets import Panel
+from ..messages import msg
+
+
+def prompt_select_issue_step(ctx: WorkflowContext) -> WorkflowResult:
+    """
+    Prompt user to select a JIRA issue from search results.
+
+    Inputs (from ctx.data):
+        jira_issues (List[JiraTicket]): List of issues from search
+
+    Outputs (saved to ctx.data):
+        jira_issue_key (str): Selected issue key
+        selected_issue (JiraTicket): Selected issue object
+    """
+    if not ctx.textual:
+        return Error("Textual UI context is not available for this step.")
+
+    # Get issues from previous search
+    issues = ctx.get("jira_issues")
+    if not issues:
+        return Error(msg.Steps.PromptSelectIssue.NO_ISSUES_AVAILABLE)
+
+    if len(issues) == 0:
+        return Error(msg.Steps.PromptSelectIssue.NO_ISSUES_AVAILABLE)
+
+    # Prompt user to select issue (issues already displayed in table from previous step)
+    ctx.textual.text("")
+
+    try:
+        # Ask for selection using text input and validate
+        response = ctx.textual.ask_text(
+            msg.Steps.PromptSelectIssue.ASK_ISSUE_NUMBER,
+            default=""
+        )
+
+        if not response or not response.strip():
+            return Error(msg.Steps.PromptSelectIssue.NO_ISSUE_SELECTED)
+
+        # Validate it's a number
+        try:
+            selected_index = int(response.strip())
+        except ValueError:
+            return Error(f"Invalid input: '{response}' is not a number")
+
+        # Validate it's in range
+        if selected_index < 1 or selected_index > len(issues):
+            return Error(f"Invalid selection: must be between 1 and {len(issues)}")
+
+        # Convert to 0-based index
+        selected_issue = issues[selected_index - 1]
+
+        ctx.textual.text("")
+        ctx.textual.mount(
+            Panel(
+                text=msg.Steps.PromptSelectIssue.ISSUE_SELECTION_CONFIRM.format(
+                    key=selected_issue.key,
+                    summary=selected_issue.summary
+                ),
+                panel_type="success"
+            )
+        )
+
+        return Success(
+            msg.Steps.PromptSelectIssue.SELECT_SUCCESS.format(key=selected_issue.key),
+            metadata={
+                "jira_issue_key": selected_issue.key,
+                "selected_issue": selected_issue
+            }
+        )
+    except (KeyboardInterrupt, EOFError):
+        return Error("User cancelled issue selection")
+
+
+__all__ = ["prompt_select_issue_step"]