@techwavedev/agi-agent-kit 1.1.7 → 1.2.1

package/templates/skills/ec/jira/scripts/jira_client.py

@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+"""
+Jira API Client Utility
+
+Provides a reusable client for Jira REST API operations.
+Handles authentication, error handling, and common operations.
+
+This module is used by all other Jira scripts.
+
+Usage:
+    from jira_client import JiraClient
+    
+    client = JiraClient()
+    issue = client.get_issue("PROJ-123")
+
+Environment Variables Required:
+    JIRA_URL - Base URL (e.g., https://company.atlassian.net)
+    JIRA_EMAIL - User email
+    JIRA_API_TOKEN - API token
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urljoin
+
+try:
+    import requests
+except ImportError:
+    print("❌ Error: requests library required. Install with: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+# Try to load dotenv if available
+try:
+    from dotenv import load_dotenv
+    # Look for .env in common locations
+    for env_path in ['.env', '../.env', '../../.env', Path.home() / '.env']:
+        if Path(env_path).exists():
+            load_dotenv(env_path)
+            break
+except ImportError:
+    pass
+
+
+class JiraClient:
+    """
+    Jira REST API client with authentication and error handling.
+    """
+    
+    def __init__(self, url: str = None, email: str = None, token: str = None):
+        """
+        Initialize the Jira client.
+        
+        Args:
+            url: Jira instance URL (or JIRA_URL env var)
+            email: User email (or JIRA_EMAIL env var)
+            token: API token (or JIRA_API_TOKEN env var)
+        """
+        self.base_url = (url or os.getenv('JIRA_URL', '')).rstrip('/')
+        self.email = email or os.getenv('JIRA_EMAIL', '')
+        self.token = token or os.getenv('JIRA_API_TOKEN', '')
+        
+        if not all([self.base_url, self.token]):
+            missing = []
+            if not self.base_url:
+                missing.append('JIRA_URL')
+            if not self.token:
+                missing.append('JIRA_API_TOKEN')
+            raise ValueError(f"Missing required environment variables: {', '.join(missing)}")
+        
+        # Detect Jira Server vs Cloud and set appropriate API version
+        # Jira Server uses /rest/api/2, Jira Cloud uses /rest/api/3
+        self.is_server = 'atlassian.net' not in self.base_url.lower()
+        api_version = '2' if self.is_server else '3'
+        
+        # Clean base URL (remove /secure/Dashboard.jspa or similar paths)
+        import re
+        self.base_url = re.sub(r'/secure/.*$', '', self.base_url)
+        self.base_url = re.sub(r'/browse/.*$', '', self.base_url)
+        self.base_url = self.base_url.rstrip('/')
+        
+        self.api_url = f"{self.base_url}/rest/api/{api_version}"
+        self.session = requests.Session()
+        
+        # Jira Server can use token directly as Bearer or basic auth
+        # Try Bearer token first for server, basic auth for cloud
+        if self.is_server:
+            self.session.headers.update({
+                'Authorization': f'Bearer {self.token}'
+            })
+        else:
+            if self.email:
+                self.session.auth = (self.email, self.token)
+            else:
+                self.session.headers.update({
+                    'Authorization': f'Bearer {self.token}'
+                })
+        
+        self.session.headers.update({
+            'Accept': 'application/json',
+            'Content-Type': 'application/json'
+        })
+    
+    def _request(self, method: str, endpoint: str, **kwargs) -> Tuple[bool, Any]:
+        """
+        Make an API request.
+        
+        Returns:
+            (success, data_or_error)
+        """
+        url = f"{self.api_url}/{endpoint.lstrip('/')}"
+        
+        try:
+            response = self.session.request(method, url, **kwargs)
+            
+            if response.status_code == 204:
+                return True, None
+            
+            if response.status_code >= 400:
+                error_data = response.json() if response.content else {}
+                error_msg = self._parse_error(error_data, response.status_code)
+                return False, error_msg
+            
+            return True, response.json() if response.content else None
+            
+        except requests.exceptions.RequestException as e:
+            return False, f"Request failed: {str(e)}"
+        except json.JSONDecodeError:
+            return False, f"Invalid JSON response: {response.text[:200]}"
+    
+    def _parse_error(self, error_data: Dict, status_code: int) -> str:
+        """Parse Jira error response into readable message."""
+        if 'errorMessages' in error_data and error_data['errorMessages']:
+            return '; '.join(error_data['errorMessages'])
+        if 'errors' in error_data:
+            return '; '.join(f"{k}: {v}" for k, v in error_data['errors'].items())
+        return f"HTTP {status_code} error"
+    
+    # ========== Issue Operations ==========
+    
+    def get_issue(self, key: str, fields: List[str] = None, expand: List[str] = None) -> Tuple[bool, Any]:
+        """Get issue by key."""
+        params = {}
+        if fields:
+            params['fields'] = ','.join(fields)
+        if expand:
+            params['expand'] = ','.join(expand)
+        
+        return self._request('GET', f'issue/{key}', params=params)
+    
+    def create_issue(self, fields: Dict) -> Tuple[bool, Any]:
+        """Create a new issue."""
+        return self._request('POST', 'issue', json={'fields': fields})
+    
+    def update_issue(self, key: str, fields: Dict = None, update: Dict = None) -> Tuple[bool, Any]:
+        """Update an existing issue."""
+        data = {}
+        if fields:
+            data['fields'] = fields
+        if update:
+            data['update'] = update
+        
+        return self._request('PUT', f'issue/{key}', json=data)
+    
+    def delete_issue(self, key: str) -> Tuple[bool, Any]:
+        """Delete an issue."""
+        return self._request('DELETE', f'issue/{key}')
+    
+    def search_issues(self, jql: str, fields: List[str] = None, 
+                      max_results: int = 50, start_at: int = 0) -> Tuple[bool, Any]:
+        """Search issues using JQL."""
+        data = {
+            'jql': jql,
+            'maxResults': max_results,
+            'startAt': start_at
+        }
+        if fields:
+            data['fields'] = fields
+        
+        return self._request('POST', 'search', json=data)
+    
+    # ========== Transitions ==========
+    
+    def get_transitions(self, key: str) -> Tuple[bool, Any]:
+        """Get available transitions for an issue."""
+        return self._request('GET', f'issue/{key}/transitions')
+    
+    def transition_issue(self, key: str, transition_id: str, 
+                         fields: Dict = None, comment: str = None) -> Tuple[bool, Any]:
+        """Transition an issue to a new status."""
+        data = {
+            'transition': {'id': transition_id}
+        }
+        if fields:
+            data['fields'] = fields
+        if comment:
+            data['update'] = {
+                'comment': [{
+                    'add': {'body': self._format_body(comment)}
+                }]
+            }
+        
+        return self._request('POST', f'issue/{key}/transitions', json=data)
+    
+    def find_transition_by_name(self, key: str, status_name: str) -> Optional[str]:
+        """Find transition ID by target status name."""
+        success, transitions = self.get_transitions(key)
+        if not success:
+            return None
+        
+        status_lower = status_name.lower()
+        for t in transitions.get('transitions', []):
+            if t.get('to', {}).get('name', '').lower() == status_lower:
+                return t['id']
+            if t.get('name', '').lower() == status_lower:
+                return t['id']
+        
+        return None
+    
+    # ========== Comments ==========
+    
+    def get_comments(self, key: str) -> Tuple[bool, Any]:
+        """Get all comments for an issue."""
+        return self._request('GET', f'issue/{key}/comment')
+    
+    def add_comment(self, key: str, body: str, visibility: Dict = None) -> Tuple[bool, Any]:
+        """Add a comment to an issue."""
+        data = {
+            'body': self._format_body(body)
+        }
+        if visibility:
+            data['visibility'] = visibility
+        
+        return self._request('POST', f'issue/{key}/comment', json=data)
+    
+    def update_comment(self, key: str, comment_id: str, body: str) -> Tuple[bool, Any]:
+        """Update an existing comment."""
+        data = {
+            'body': self._format_body(body)
+        }
+        return self._request('PUT', f'issue/{key}/comment/{comment_id}', json=data)
+    
+    def delete_comment(self, key: str, comment_id: str) -> Tuple[bool, Any]:
+        """Delete a comment."""
+        return self._request('DELETE', f'issue/{key}/comment/{comment_id}')
+    
+    # ========== Worklog ==========
+    
+    def get_worklogs(self, key: str) -> Tuple[bool, Any]:
+        """Get all worklogs for an issue."""
+        return self._request('GET', f'issue/{key}/worklog')
+    
+    def add_worklog(self, key: str, time_spent: str, 
+                    comment: str = None, started: str = None,
+                    adjust_estimate: str = None, new_estimate: str = None) -> Tuple[bool, Any]:
+        """
+        Add a worklog entry.
+        
+        Args:
+            key: Issue key
+            time_spent: Time in Jira format (e.g., "2h", "1d", "30m")
+            comment: Work description
+            started: Start datetime in ISO format
+            adjust_estimate: How to adjust estimate (new, manual, leave, auto)
+            new_estimate: New estimate if adjust_estimate is 'new'
+        """
+        data = {
+            'timeSpent': time_spent
+        }
+        if comment:
+            data['comment'] = self._format_body(comment)
+        if started:
+            data['started'] = started
+        
+        params = {}
+        if adjust_estimate:
+            params['adjustEstimate'] = adjust_estimate
+        if new_estimate:
+            params['newEstimate'] = new_estimate
+        
+        return self._request('POST', f'issue/{key}/worklog', json=data, params=params)
+    
+    # ========== Projects ==========
+    
+    def get_projects(self) -> Tuple[bool, Any]:
+        """Get all accessible projects."""
+        return self._request('GET', 'project')
+    
+    def get_project(self, key: str) -> Tuple[bool, Any]:
+        """Get project details."""
+        return self._request('GET', f'project/{key}')
+    
+    # ========== Users ==========
+    
+    def search_users(self, query: str, max_results: int = 50) -> Tuple[bool, Any]:
+        """Search for users."""
+        return self._request('GET', 'user/search', params={
+            'query': query,
+            'maxResults': max_results
+        })
+    
+    def get_myself(self) -> Tuple[bool, Any]:
+        """Get current user info."""
+        return self._request('GET', 'myself')
+    
+    # ========== Helpers ==========
+    
+    def _format_body(self, text: str) -> Any:
+        """
+        Format text for the appropriate Jira version.
+        Jira Server (v2) expects plain string.
+        Jira Cloud (v3) expects ADF (Atlassian Document Format).
+        """
+        if self.is_server:
+            return text
+            
+        # Atlassian Document Format (ADF) for Jira Cloud
+        paragraphs = []
+        for para in text.split('\n\n'):
+            if para.strip():
+                paragraphs.append({
+                    'type': 'paragraph',
+                    'content': [{'type': 'text', 'text': para.strip()}]
+                })
+        
+        return {
+            'type': 'doc',
+            'version': 1,
+            'content': paragraphs if paragraphs else [
+                {'type': 'paragraph', 'content': [{'type': 'text', 'text': text}]}
+            ]
+        }
+    
+    def parse_time_to_seconds(self, time_str: str) -> int:
+        """
+        Parse Jira time format to seconds.
+        
+        Supports: 1w, 2d, 3h, 30m (and combinations like "2h 30m")
+        """
+        total = 0
+        patterns = {
+            'w': 5 * 8 * 60 * 60,  # 1 week = 5 days
+            'd': 8 * 60 * 60,      # 1 day = 8 hours
+            'h': 60 * 60,
+            'm': 60,
+            's': 1
+        }
+        
+        for match in re.finditer(r'(\d+)\s*([wdhms])', time_str.lower()):
+            value, unit = int(match.group(1)), match.group(2)
+            total += value * patterns.get(unit, 0)
+        
+        return total
+
+
+def get_client() -> JiraClient:
+    """Get a configured Jira client instance."""
+    try:
+        return JiraClient()
+    except ValueError as e:
+        print(f"❌ Configuration Error: {e}", file=sys.stderr)
+        print("\nEnsure these environment variables are set:", file=sys.stderr)
+        print("  JIRA_URL=https://your-domain.atlassian.net", file=sys.stderr)
+        print("  JIRA_EMAIL=your-email@example.com", file=sys.stderr)
+        print("  JIRA_API_TOKEN=your-api-token", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    # Test connection when run directly
+    print("Testing Jira connection...")
+    client = get_client()
+    
+    success, result = client.get_myself()
+    if success:
+        print(f"✅ Connected as: {result.get('displayName', 'Unknown')}")
+        print(f"   Email: {result.get('emailAddress', 'N/A')}")
+    else:
+        print(f"❌ Connection failed: {result}")
+        sys.exit(1)

package/templates/skills/ec/jira/scripts/log_work.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Log Work Time to Jira Ticket
+
+Logs work time against an existing Jira issue.
+
+Usage:
+    python log_work.py --ticket <key> --time <duration> [options]
+
+Arguments:
+    --ticket        Ticket key (required)
+    --time          Time spent: "2h", "30m", "1d", "2h 30m" (required)
+    --comment       Work description (optional)
+    --started       Start time in ISO format (optional)
+    --remaining     New remaining estimate (optional)
+
+Exit Codes:
+    0 - Success
+    1 - Invalid arguments
+    2 - Ticket not found
+    3 - Worklog error
+"""
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from jira_client import get_client
+
+
+def round_to_15min_blocks(time_str: str) -> str:
+    """
+    Round time to 15-minute blocks (EC Jira requirement).
+    
+    Args:
+        time_str: Time string like "2h", "25m", "1h 20m"
+    
+    Returns:
+        Rounded time string using 15m/30m/45m/1h increments
+    """
+    # Parse time to total minutes
+    total_minutes = 0
+    patterns = {
+        'w': 5 * 8 * 60,  # 1 week = 5 days = 40 hours
+        'd': 8 * 60,      # 1 day = 8 hours
+        'h': 60,
+        'm': 1
+    }
+    
+    for match in re.finditer(r'(\d+)\s*([wdhm])', time_str.lower()):
+        value, unit = int(match.group(1)), match.group(2)
+        total_minutes += value * patterns.get(unit, 0)
+    
+    if total_minutes == 0:
+        return time_str  # Return original if parsing failed
+    
+    # Round to nearest 15 minutes (minimum 15 min)
+    rounded_minutes = max(15, round(total_minutes / 15) * 15)
+    
+    # Convert back to Jira format
+    hours = rounded_minutes // 60
+    mins = rounded_minutes % 60
+    
+    if hours > 0 and mins > 0:
+        return f"{hours}h {mins}m"
+    elif hours > 0:
+        return f"{hours}h"
+    else:
+        return f"{mins}m"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Log work time to a Jira ticket',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument('--ticket', required=True, help='Ticket key')
+    parser.add_argument('--time', required=True, help='Time spent (e.g., "2h", "1d")')
+    parser.add_argument('--comment', help='Work description')
+    parser.add_argument('--started', help='Start time (ISO format)')
+    parser.add_argument('--remaining', help='New remaining estimate')
+    args = parser.parse_args()
+    
+    client = get_client()
+    ticket = args.ticket.upper()
+    
+    # Round to 15-minute blocks (EC requirement)
+    original_time = args.time
+    rounded_time = round_to_15min_blocks(original_time)
+    
+    if original_time != rounded_time:
+        print(f"⏱️  Rounding {original_time} → {rounded_time} (15-min blocks)", file=sys.stderr)
+    
+    print(f"⏱️  Logging {rounded_time} to {ticket}...", file=sys.stderr)
+    
+    # Verify ticket exists
+    success, issue = client.get_issue(ticket)
+    if not success:
+        print(f"❌ Error: Could not find ticket {ticket}: {issue}", file=sys.stderr)
+        sys.exit(2)
+    
+    # Parse started time or use now
+    started = args.started
+    if not started:
+        # Jira expects format: 2026-01-23T14:00:00.000+0100
+        started = datetime.now().strftime('%Y-%m-%dT%H:%M:%S.000%z')
+        if not started.endswith('+') and len(started) < 30:
+            # Add timezone if missing
+            started = datetime.now().astimezone().strftime('%Y-%m-%dT%H:%M:%S.000%z')
+    
+    # Determine estimate adjustment
+    adjust_estimate = None
+    new_estimate = None
+    if args.remaining:
+        adjust_estimate = 'new'
+        new_estimate = args.remaining
+    
+    # Add worklog with rounded time
+    success, result = client.add_worklog(
+        ticket,
+        time_spent=rounded_time,
+        comment=args.comment,
+        started=started,
+        adjust_estimate=adjust_estimate,
+        new_estimate=new_estimate
+    )
+    
+    if not success:
+        print(f"❌ Error logging work: {result}", file=sys.stderr)
+        sys.exit(3)
+    
+    worklog_id = result.get('id', 'Unknown')
+    time_logged = result.get('timeSpent', args.time)
+    
+    output = {
+        'success': True,
+        'ticket': ticket,
+        'worklog_id': worklog_id,
+        'time_logged': time_logged,
+        'started': started
+    }
+    print(json.dumps(output, indent=2))
+    
+    print(f"✅ Logged {time_logged} to {ticket}", file=sys.stderr)
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/templates/skills/ec/jira/scripts/search_tickets.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Search Jira Tickets
+
+Search and filter Jira issues using JQL.
+
+Usage:
+    python search_tickets.py --jql <query> [options]
+
+Arguments:
+    --jql           JQL query string (required)
+    --fields        Comma-separated fields to return
+    --max-results   Maximum results (default: 50)
+    --output        Output format: json, table, keys (default: table)
+
+Exit Codes:
+    0 - Success
+    1 - Invalid arguments
+    2 - Search error
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from jira_client import get_client
+
+
+def format_table(issues: list) -> str:
+    """Format issues as a simple table."""
+    if not issues:
+        return "No issues found."
+    
+    lines = []
+    lines.append(f"{'Key':<12} {'Type':<10} {'Priority':<10} {'Status':<15} {'Summary'}")
+    lines.append("-" * 80)
+    
+    for issue in issues:
+        key = issue.get('key', '')
+        fields = issue.get('fields', {})
+        
+        issue_type = fields.get('issuetype', {}).get('name', '-')[:10]
+        priority = fields.get('priority', {}).get('name', '-')[:10] if fields.get('priority') else '-'
+        status = fields.get('status', {}).get('name', '-')[:15]
+        summary = fields.get('summary', '')[:50]
+        
+        lines.append(f"{key:<12} {issue_type:<10} {priority:<10} {status:<15} {summary}")
+    
+    return '\n'.join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Search Jira tickets with JQL',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument('--jql', required=True, help='JQL query')
+    parser.add_argument('--fields', help='Comma-separated fields')
+    parser.add_argument('--max-results', type=int, default=50, help='Max results')
+    parser.add_argument('--output', choices=['json', 'table', 'keys'], default='table',
+                        help='Output format')
+    args = parser.parse_args()
+    
+    client = get_client()
+    
+    print(f"🔍 Searching: {args.jql}", file=sys.stderr)
+    
+    # Parse fields
+    fields = None
+    if args.fields:
+        fields = [f.strip() for f in args.fields.split(',')]
+    else:
+        # Default useful fields
+        fields = ['summary', 'status', 'priority', 'issuetype', 'assignee', 'created', 'updated']
+    
+    # Search
+    success, result = client.search_issues(args.jql, fields=fields, max_results=args.max_results)
+    
+    if not success:
+        print(f"❌ Search error: {result}", file=sys.stderr)
+        sys.exit(2)
+    
+    issues = result.get('issues', [])
+    total = result.get('total', len(issues))
+    
+    print(f"   Found {total} issue(s) (showing {len(issues)})", file=sys.stderr)
+    
+    # Output based on format
+    if args.output == 'keys':
+        for issue in issues:
+            print(issue.get('key'))
+    elif args.output == 'json':
+        print(json.dumps(issues, indent=2))
+    else:
+        print(format_table(issues))
+    
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()