titan-cli 0.1.0__py3-none-any.whl

titan_plugin_jira/config/jira_agent.toml

@@ -0,0 +1,92 @@
+[agent]
+name = "JiraAgent"
+description = "AI agent specialized in JIRA issue analysis for iOS, Android, and BFF development"
+version = "1.0.0"
+
+[agent.capabilities]
+issue_analysis = true
+requirements_extraction = true
+subtask_generation = true
+description_enhancement = true
+label_suggestion = true           
+risk_scoring = true               
+gherkin_generation = true         
+
+[agent.limits]
+max_description_length = 8000
+max_subtasks = 6
+max_comments_to_analyze = 8
+max_linked_issues = 5
+temperature = 0.3             
+max_tokens = 2000                      
+
+[agent.prompts.requirements_analysis]
+system = """You are a technical analyst. Extract requirements from JIRA issues.
+CRITICAL: You MUST follow the exact format specified in the user prompt.
+Do not add extra sections or change the format."""
+[agent.prompts.description_enhancement]
+system = """You are a Technical Writer and QA Specialist. 
+Structure:
+- **Overview**: What and Why.
+- **Technical Context**: Specifics for iOS, Android, or BFF.
+- **Acceptance Criteria**: Using [ ] checkboxes.
+- **Gherkin Scenarios**: 
+  Generate Given/When/Then scenarios for the main success path and at least one edge case.
+  Use code blocks:
+  Scenario: [Name]
+    Given [context]
+    When [action]
+    Then [outcome]
+"""
+
+[agent.prompts.subtask_suggestion]
+system = """You are a Tech Lead. Suggest subtasks ONLY for iOS, Android, or BFF.
+Include always:
+- 1 subtask for Implementation.
+- 1 subtask for QA/Gherkin validation.
+- 1 subtask for Documentation/Code Review.
+Complexity: (XS, S, M, L, XL).
+"""
+
+[agent.prompts.smart_labeling]
+system = """You are a classification bot. STRICTLY use only these labels. DO NOT create new ones:
+- Platforms: [iOS, Android, BFF]
+- Types: [bug, feature, tech-debt, spike, refactor]
+- Priority: [blocker, high-impact, low-priority]
+
+If the issue does not fit any platform, flag it as 'Needs Triage'.
+Output: comma-separated list only."""
+
+[agent.prompts.comment_generation]
+system = """You are an experienced software engineer providing technical guidance.
+Your task is to generate helpful comments for JIRA issues.
+
+Guidelines:
+1. Be constructive and helpful
+2. Provide technical insights specific to iOS, Android, or BFF
+3. Suggest solutions or alternatives
+4. Ask clarifying questions when needed
+5. Reference related issues when relevant
+6. Keep it concise but informative
+7. Consider multi-platform implications
+"""
+
+[agent.features]
+enable_requirement_extraction = true
+enable_subtasks = true
+enable_risk_analysis = true           # Enable risk and complexity analysis
+enable_dependency_detection = true    # Enable dependency detection
+enable_acceptance_criteria = true     # Enable acceptance criteria extraction
+enable_debug_output = true
+
+[agent.formatting]
+# Optional: Specify a Jinja2 template for formatting analysis output
+# If not set or template not found, uses built-in Python formatter
+# Template must be in config/templates/ directory
+template = "issue_analysis.md.j2"
+
+[agent.metadata]
+author = "Titan CLI Team"
+updated = "2024-12-22"
+stack = ["iOS", "Android", "BFF"]
+testing_framework = "Gherkin/Cucumber"

titan_plugin_jira/config/templates/issue_analysis.md.j2

@@ -0,0 +1,78 @@
+# JIRA Issue Analysis
+
+{% if functional_requirements or non_functional_requirements %}
+## 1. Requirements Breakdown
+
+{% if functional_requirements %}
+**Functional Requirements:**
+{% for req in functional_requirements %}
+- {{ req }}
+{% endfor %}
+{% endif %}
+
+{% if non_functional_requirements %}
+**Non-Functional Requirements:**
+{% for req in non_functional_requirements %}
+- {{ req }}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if acceptance_criteria %}
+## 2. Acceptance Criteria
+
+{% for criterion in acceptance_criteria %}
+- [ ] {{ criterion }}
+{% endfor %}
+{% endif %}
+
+{% if technical_approach %}
+## 3. Technical Approach
+
+{{ technical_approach }}
+{% endif %}
+
+{% if dependencies %}
+## 4. Dependencies
+
+{% for dep in dependencies %}
+- {{ dep }}
+{% endfor %}
+{% endif %}
+
+{% if risks %}
+## 5. Potential Risks
+
+{% for risk in risks %}
+- ⚠️ {{ risk }}
+{% endfor %}
+{% endif %}
+
+{% if edge_cases %}
+## 6. Edge Cases to Consider
+
+{% for edge_case in edge_cases %}
+- {{ edge_case }}
+{% endfor %}
+{% endif %}
+
+{% if suggested_subtasks %}
+## 7. Suggested Subtasks
+
+{% for subtask in suggested_subtasks %}
+**{{ loop.index }}. {{ subtask.summary }}**
+{{ subtask.description }}
+
+{% endfor %}
+{% endif %}
+
+{% if complexity_score or estimated_effort %}
+## 8. Complexity Assessment
+
+{% if complexity_score %}
+**Complexity:** {{ complexity_score|title }}
+{% endif %}
+{% if estimated_effort %}
+**Estimated Effort:** {{ estimated_effort }}
+{% endif %}
+{% endif %}

titan_plugin_jira/exceptions.py

@@ -0,0 +1,37 @@
+# plugins/titan-plugin-jira/titan_plugin_jira/exceptions.py
+"""Custom exceptions for JIRA plugin."""
+
+from typing import Dict, Optional
+
+
+class JiraPluginError(Exception):
+    """Base exception for JIRA plugin errors."""
+    pass
+
+
+class JiraConfigurationError(JiraPluginError):
+    """Raised when JIRA plugin configuration is invalid or missing."""
+    pass
+
+
+class JiraClientError(JiraPluginError):
+    """Raised when JIRA client operations fail."""
+    pass
+
+
+class JiraAPIError(Exception):
+    """Exception raised for JIRA API errors"""
+
+    def __init__(self, message: str, status_code: Optional[int] = None, response: Optional[Dict] = None):
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        super().__init__(self.message)
+
+
+__all__ = [
+    "JiraPluginError",
+    "JiraConfigurationError",
+    "JiraClientError",
+    "JiraAPIError",
+]

titan_plugin_jira/formatters/__init__.py

@@ -0,0 +1,6 @@
+# plugins/titan-plugin-jira/titan_plugin_jira/formatters/__init__.py
+"""Formatters for JIRA analysis output."""
+
+from .markdown_formatter import IssueAnalysisMarkdownFormatter
+
+__all__ = ["IssueAnalysisMarkdownFormatter"]

titan_plugin_jira/formatters/markdown_formatter.py

@@ -0,0 +1,245 @@
+# plugins/titan-plugin-jira/titan_plugin_jira/formatters/markdown_formatter.py
+"""Markdown formatter for JIRA issue analysis."""
+
+from typing import List, Optional
+from pathlib import Path
+from dataclasses import asdict
+from ..agents.jira_agent import IssueAnalysis
+
+
+class IssueAnalysisMarkdownFormatter:
+    """
+    Formats IssueAnalysis into markdown for display.
+
+    This class separates presentation logic from business logic,
+    making it easy to:
+    - Modify output format without touching agent code
+    - Test formatting independently
+    - Add other formatters (HTML, JSON, etc.) in the future
+    - Optionally use Jinja2 templates for custom formatting
+
+    Example:
+        >>> # Use built-in formatter (default)
+        >>> formatter = IssueAnalysisMarkdownFormatter()
+        >>> markdown = formatter.format(analysis)
+
+        >>> # Use custom Jinja2 template
+        >>> formatter = IssueAnalysisMarkdownFormatter(template_path="custom.md.j2")
+        >>> markdown = formatter.format(analysis)
+    """
+
+    def __init__(self, template_path: Optional[str] = None):
+        """
+        Initialize the formatter.
+
+        Args:
+            template_path: Optional path to Jinja2 template file.
+                          If None, uses built-in Python formatter.
+                          If provided, must be relative to config/templates/
+        """
+        self.template = None
+        if template_path:
+            self.template = self._load_template(template_path)
+
+    def _load_template(self, template_name: str):
+        """
+        Load Jinja2 template from config/templates/.
+
+        Args:
+            template_name: Template filename (e.g., "issue_analysis.md.j2")
+
+        Returns:
+            Jinja2 Template object or None if Jinja2 not available
+        """
+        try:
+            from jinja2 import Environment, FileSystemLoader
+        except ImportError:
+            # Jinja2 not installed, fall back to built-in formatter
+            return None
+
+        try:
+            # Templates directory is relative to this file
+            # This works both in development and when installed
+            templates_dir = Path(__file__).parent.parent / "config" / "templates"
+
+            if not templates_dir.exists():
+                return None
+
+            # Enable autoescape to prevent XSS vulnerabilities (CWE-116)
+            # This ensures all template variables are HTML-escaped by default
+            env = Environment(
+                loader=FileSystemLoader(str(templates_dir)),
+                autoescape=False
+            )
+            return env.get_template(template_name)
+        except Exception:
+            # Template not found or other error, fall back to built-in formatter
+            # Silently fail and use built-in formatter
+            return None
+
+    def format(self, analysis: IssueAnalysis) -> str:
+        """
+        Format IssueAnalysis into markdown.
+
+        Args:
+            analysis: IssueAnalysis object from JiraAgent
+
+        Returns:
+            Formatted markdown string
+        """
+        if self.template:
+            # Use Jinja2 template
+            return self._format_with_template(analysis)
+        else:
+            # Use built-in Python formatter
+            return self._format_builtin(analysis)
+
+    def _format_with_template(self, analysis: IssueAnalysis) -> str:
+        """
+        Format using Jinja2 template.
+
+        Args:
+            analysis: IssueAnalysis object
+
+        Returns:
+            Rendered markdown string
+        """
+        # Convert dataclass to dict for template
+        analysis_dict = asdict(analysis)
+        return self.template.render(**analysis_dict)
+
+    def _format_builtin(self, analysis: IssueAnalysis) -> str:
+        """
+        Format using built-in Python methods.
+
+        Args:
+            analysis: IssueAnalysis object
+
+        Returns:
+            Formatted markdown string
+        """
+        sections = []
+
+        # 1. Requirements Breakdown
+        if analysis.functional_requirements or analysis.non_functional_requirements:
+            sections.extend(self._format_requirements(analysis))
+
+        # 2. Acceptance Criteria
+        if analysis.acceptance_criteria:
+            sections.extend(self._format_acceptance_criteria(analysis))
+
+        # 3. Technical Approach
+        if analysis.technical_approach:
+            sections.extend(self._format_technical_approach(analysis))
+
+        # 4. Dependencies
+        if analysis.dependencies:
+            sections.extend(self._format_dependencies(analysis))
+
+        # 5. Potential Risks
+        if analysis.risks:
+            sections.extend(self._format_risks(analysis))
+
+        # 6. Edge Cases
+        if analysis.edge_cases:
+            sections.extend(self._format_edge_cases(analysis))
+
+        # 7. Suggested Subtasks
+        if analysis.suggested_subtasks:
+            sections.extend(self._format_subtasks(analysis))
+
+        # 8. Complexity & Effort
+        if analysis.complexity_score or analysis.estimated_effort:
+            sections.extend(self._format_complexity(analysis))
+
+        return "\n".join(sections)
+
+    def _format_requirements(self, analysis: IssueAnalysis) -> List[str]:
+        """Format requirements section."""
+        sections = ["## 1. Requirements Breakdown"]
+
+        if analysis.functional_requirements:
+            sections.append("\n**Functional Requirements:**")
+            for req in analysis.functional_requirements:
+                sections.append(f"- {req}")
+
+        if analysis.non_functional_requirements:
+            sections.append("\n**Non-Functional Requirements:**")
+            for req in analysis.non_functional_requirements:
+                sections.append(f"- {req}")
+
+        sections.append("")
+        return sections
+
+    def _format_acceptance_criteria(self, analysis: IssueAnalysis) -> List[str]:
+        """Format acceptance criteria section."""
+        sections = ["## 2. Acceptance Criteria"]
+
+        for criterion in analysis.acceptance_criteria:
+            sections.append(f"- [ ] {criterion}")
+
+        sections.append("")
+        return sections
+
+    def _format_technical_approach(self, analysis: IssueAnalysis) -> List[str]:
+        """Format technical approach section."""
+        sections = [
+            "## 3. Technical Approach",
+            analysis.technical_approach,
+            ""
+        ]
+        return sections
+
+    def _format_dependencies(self, analysis: IssueAnalysis) -> List[str]:
+        """Format dependencies section."""
+        sections = ["## 4. Dependencies"]
+
+        for dep in analysis.dependencies:
+            sections.append(f"- {dep}")
+
+        sections.append("")
+        return sections
+
+    def _format_risks(self, analysis: IssueAnalysis) -> List[str]:
+        """Format risks section."""
+        sections = ["## 5. Potential Risks"]
+
+        for risk in analysis.risks:
+            sections.append(f"- ⚠️ {risk}")
+
+        sections.append("")
+        return sections
+
+    def _format_edge_cases(self, analysis: IssueAnalysis) -> List[str]:
+        """Format edge cases section."""
+        sections = ["## 6. Edge Cases to Consider"]
+
+        for edge_case in analysis.edge_cases:
+            sections.append(f"- {edge_case}")
+
+        sections.append("")
+        return sections
+
+    def _format_subtasks(self, analysis: IssueAnalysis) -> List[str]:
+        """Format subtasks section."""
+        sections = ["## 7. Suggested Subtasks"]
+
+        for i, subtask in enumerate(analysis.suggested_subtasks, 1):
+            sections.append(f"\n**{i}. {subtask.get('summary', 'Subtask')}**")
+            sections.append(f"{subtask.get('description', '')}")
+
+        sections.append("")
+        return sections
+
+    def _format_complexity(self, analysis: IssueAnalysis) -> List[str]:
+        """Format complexity assessment section."""
+        sections = ["## 8. Complexity Assessment"]
+
+        if analysis.complexity_score:
+            sections.append(f"**Complexity:** {analysis.complexity_score.title()}")
+
+        if analysis.estimated_effort:
+            sections.append(f"**Estimated Effort:** {analysis.estimated_effort}")
+
+        sections.append("")
+        return sections

titan_plugin_jira/messages.py

@@ -0,0 +1,115 @@
+"""
+User-facing messages for JIRA plugin
+"""
+
+
+class Messages:
+    """Container for all user-facing messages"""
+
+    class Plugin:
+        """Plugin-level messages"""
+        CLIENT_INIT_WARNING: str = "Warning: JiraPlugin could not initialize JiraClient: {e}"
+        CLIENT_NOT_AVAILABLE: str = "JiraPlugin not initialized or JIRA API not available."
+        CLIENT_NOT_AVAILABLE_IN_CONTEXT: str = "JIRA client is not available in the workflow context."
+        JIRA_CLIENT_NOT_AVAILABLE: str = "JIRA client not initialized. Please configure the plugin first."
+
+    class Steps:
+        """Step-level messages"""
+
+        class Search:
+            """Search issues step messages"""
+            SEARCHING: str = "Searching JIRA issues with JQL: {jql}"
+            SEARCH_SUCCESS: str = "Found {count} JIRA issue(s)"
+            NO_RESULTS: str = "No JIRA issues found matching the query"
+            SEARCH_FAILED: str = "Failed to search JIRA issues: {e}"
+            QUERY_NOT_FOUND: str = "Saved query '{query_name}' not found."
+            AVAILABLE_PREDEFINED: str = "Available predefined queries (first 15):"
+            MORE_QUERIES: str = "  ... and {count} more"
+            CUSTOM_QUERIES_HEADER: str = "Custom queries from config:"
+            ADD_CUSTOM_HINT: str = "💡 Add custom queries to .titan/config.toml:"
+            CUSTOM_QUERY_EXAMPLE: str = "[jira.saved_queries]\nmy_custom = \"assignee = currentUser() AND status != Done\""
+            QUERY_NAME_REQUIRED: str = "query_name parameter is required"
+            PROJECT_REQUIRED: str = (
+                "Query '{query_name}' requires a 'project' parameter.\n"
+                "JQL template: {jql}\n\n"
+                "Provide it in workflow:\n"
+                "  params:\n"
+                "    query_name: \"{query_name}\"\n"
+                "    project: \"PROJ\""
+            )
+
+        class GetIssue:
+            """Get issue step messages"""
+            GETTING_ISSUE: str = "Fetching JIRA issue: {issue_key}"
+            GET_SUCCESS: str = "Retrieved JIRA issue: {issue_key}"
+            GET_FAILED: str = "Failed to get JIRA issue: {e}"
+            ISSUE_NOT_FOUND: str = "JIRA issue not found: {issue_key}"
+
+        class CreateIssue:
+            """Create issue step messages"""
+            CREATING_ISSUE: str = "Creating JIRA issue: {summary}"
+            CREATE_SUCCESS: str = "Created JIRA issue: {issue_key}"
+            CREATE_FAILED: str = "Failed to create JIRA issue: {e}"
+            MISSING_SUMMARY: str = "Issue summary is required"
+
+        class UpdateStatus:
+            """Update status step messages"""
+            UPDATING_STATUS: str = "Updating JIRA issue {issue_key} to status: {status}"
+            UPDATE_SUCCESS: str = "Updated JIRA issue {issue_key} to {status}"
+            UPDATE_FAILED: str = "Failed to update JIRA issue status: {e}"
+            INVALID_TRANSITION: str = "Cannot transition to '{status}'. Available: {transitions}"
+
+        class AddComment:
+            """Add comment step messages"""
+            ADDING_COMMENT: str = "Adding comment to JIRA issue: {issue_key}"
+            COMMENT_SUCCESS: str = "Added comment to JIRA issue {issue_key}"
+            COMMENT_FAILED: str = "Failed to add comment: {e}"
+
+        class LinkPR:
+            """Link PR step messages"""
+            LINKING_PR: str = "Linking PR to JIRA issue: {issue_key}"
+            LINK_SUCCESS: str = "Linked PR to JIRA issue {issue_key}"
+            LINK_FAILED: str = "Failed to link PR: {e}"
+
+        class AIIssue:
+            """AI issue generation step messages"""
+            AI_NOT_CONFIGURED: str = "AI not configured. Run 'titan ai configure' to enable AI features."
+            AI_NOT_CONFIGURED_SKIP: str = "AI not configured - skipping analysis"
+            GENERATING_ISSUE: str = "Generating JIRA issue with AI..."
+            GENERATION_SUCCESS: str = "AI generated JIRA issue successfully"
+            GENERATION_FAILED: str = "AI generation failed: {e}"
+            INVALID_ISSUE_TYPE: str = "Invalid issue type: {issue_type}. Use: bug, feature, or task"
+            USER_REJECTED: str = "User rejected AI-generated issue"
+            CONFIRM_USE_AI: str = "Use this AI-generated issue?"
+            NO_ISSUE_FOUND: str = "No issue found to analyze"
+            ANALYZING: str = "Analyzing issue with AI..."
+
+        class ExtractKey:
+            """Extract issue key step messages"""
+            EXTRACTING_KEY: str = "Extracting JIRA key from branch: {branch}"
+            KEY_FOUND: str = "Found JIRA key: {issue_key}"
+            KEY_NOT_FOUND: str = "No JIRA key found in branch name: {branch}"
+            INVALID_BRANCH_FORMAT: str = "Branch name doesn't follow pattern: feature/PROJ-123-description"
+
+        class PromptSelectIssue:
+            """Prompt select issue step messages"""
+            NO_ISSUES_AVAILABLE: str = "No JIRA issues available to select from"
+            NO_ISSUE_SELECTED: str = "No issue selected"
+            UI_NOT_AVAILABLE: str = "UI not available for prompting"
+            ASK_ISSUE_NUMBER: str = "Enter issue number to analyze"
+            ISSUE_SELECTED: str = "Selected: {key} - {summary}"
+            ISSUE_SELECTION_CONFIRM: str = "Selected: {key} - {summary}"
+            SELECT_SUCCESS: str = "Selected issue: {key}"
+
+    class JIRA:
+        """JIRA-specific messages"""
+        AUTHENTICATION_FAILED: str = "JIRA authentication failed. Check your API token."
+        RATE_LIMIT_EXCEEDED: str = "JIRA API rate limit exceeded. Please wait and try again."
+        NETWORK_ERROR: str = "Network error connecting to JIRA: {e}"
+        INVALID_PROJECT: str = "Invalid JIRA project: {project}"
+        INVALID_JQL: str = "Invalid JQL query: {jql}"
+
+
+msg = Messages()
+
+__all__ = ["msg", "Messages"]

titan_plugin_jira/models.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+JIRA Plugin Data Models
+
+All Pydantic models and dataclasses for the JIRA plugin.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Any
+
+
+class IssueStatus(str, Enum):
+    """Common JIRA issue statuses"""
+    TODO = "To Do"
+    IN_PROGRESS = "In Progress"
+    IN_REVIEW = "In Review"
+    READY_FOR_QA = "Ready for QA"
+    IN_QA = "In QA"
+    DONE = "Done"
+    BLOCKED = "Blocked"
+
+
+@dataclass
+class JiraProject:
+    """Represents a JIRA project"""
+    id: str
+    key: str
+    name: str
+    description: Optional[str] = None
+    project_type: Optional[str] = None
+    lead: Optional[str] = None
+
+
+@dataclass
+class JiraIssueType:
+    """Represents a JIRA issue type"""
+    id: str
+    name: str
+    description: Optional[str] = None
+    subtask: bool = False
+
+
+@dataclass
+class JiraTransition:
+    """Represents a JIRA workflow transition"""
+    id: str
+    name: str
+    to_status: str
+
+
+@dataclass
+class JiraComment:
+    """Represents a JIRA comment"""
+    id: str
+    author: str
+    body: str
+    created: str
+    updated: Optional[str] = None
+
+
+@dataclass
+class JiraTicket:
+    """Represents a JIRA ticket/issue"""
+    key: str
+    id: str
+    summary: str
+    description: Optional[str]
+    status: str
+    issue_type: str
+    assignee: Optional[str]
+    reporter: str
+    priority: str
+    created: str
+    updated: str
+    labels: List[str]
+    components: List[str]
+    fix_versions: List[str]
+    raw: Dict[str, Any]  # Original API response
+
+
+__all__ = [
+    "IssueStatus",
+    "JiraProject",
+    "JiraIssueType",
+    "JiraTransition",
+    "JiraComment",
+    "JiraTicket",
+]