titan-cli 0.1.0__py3-none-any.whl

titan_plugin_github/config/pr_agent.toml

@@ -0,0 +1,85 @@
+# PR Agent Configuration
+# AI agent for analyzing code changes and generating PR descriptions
+
+[agent]
+name = "PRAgent"
+description = "AI agent specialized in PR analysis and generation"
+version = "1.0.0"
+
+[agent.capabilities]
+# What this agent can do
+code_analysis = true
+pr_generation = true
+commit_analysis = true
+architecture_review = true
+template_following = true
+
+[agent.prompts]
+# System prompts for different tasks
+
+[agent.prompts.pr_description]
+system = """You are an expert software engineer specialized in code review and documentation.
+Your task is to analyze git changes and generate professional pull request descriptions.
+
+Guidelines:
+1. Be concise but comprehensive
+2. Follow conventional commit formats for titles
+3. Use markdown formatting
+4. Highlight breaking changes
+5. Focus on WHY, not just WHAT
+6. Follow PR templates strictly when provided
+7. Adapt detail level based on PR size (small/medium/large/very large)
+
+Response format:
+TITLE: <conventional commit title max 72 chars>
+
+DESCRIPTION:
+<structured description following template or standard format>
+"""
+
+[agent.prompts.commit_message]
+system = """You are an expert software engineer specialized in writing clear commit messages.
+Your task is to analyze code changes and generate atomic commit messages.
+
+Guidelines:
+1. Follow conventional commits format: type(scope): description
+2. Be specific and descriptive
+3. Focus on WHY the change was made
+4. Keep title under 72 characters
+5. Group related changes logically
+
+Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build
+"""
+
+[agent.prompts.architecture_review]
+system = """You are a senior software architect reviewing code changes.
+Your task is to identify architectural patterns, potential issues, and improvements.
+
+Guidelines:
+1. Identify design patterns used
+2. Highlight potential issues (coupling, complexity, etc.)
+3. Suggest architectural improvements
+4. Consider scalability and maintainability
+5. Be constructive and actionable
+"""
+
+[agent.limits]
+# Diff analysis limits
+max_diff_size = 8000  # Characters
+max_files_in_diff = 50
+max_commits_to_analyze = 15
+
+[agent.features]
+# Feature flags
+enable_template_detection = true
+enable_dynamic_sizing = true
+enable_user_confirmation = true
+enable_fallback_prompts = true
+enable_debug_output = false  # Set to true for debugging
+
+[agent.metadata]
+# Agent metadata
+author = "Titan CLI Team"
+created = "2024-12-11"
+updated = "2024-12-11"
+tags = ["pr-generation", "code-analysis", "git", "ai", "github"]

titan_plugin_github/exceptions.py

@@ -0,0 +1,28 @@
+# plugins/titan-plugin-github/titan_plugin_github/exceptions.py
+class GitHubError(Exception):
+    """Base exception for all GitHub related errors."""
+    pass
+
+class GitHubAuthenticationError(GitHubError):
+    """Raised when GitHub authentication fails (e.g., gh CLI not authenticated)."""
+    pass
+
+class GitHubAPIError(GitHubError):
+    """Raised when a GitHub API call or gh CLI command fails."""
+    pass
+
+class PRNotFoundError(GitHubAPIError):
+    """Raised when a specified Pull Request is not found."""
+    pass
+
+class ReviewNotFoundError(GitHubAPIError):
+    """Raised when a specified Review is not found."""
+    pass
+
+class GitHubPermissionError(GitHubAPIError):
+    """Raised when the authenticated user does not have sufficient permissions."""
+    pass
+
+class GitHubConfigurationError(GitHubError):
+    """Raised when the GitHub plugin is misconfigured."""
+    pass

titan_plugin_github/messages.py

@@ -0,0 +1,88 @@
+# plugins/titan-plugin-github/titan_plugin_github/messages.py
+class Messages:
+    class Prompts:
+        """Prompts specific to the GitHub plugin"""
+        ENTER_PR_TITLE: str = "Enter Pull Request title:"
+        ENTER_PR_BODY: str = "Enter PR body/description (press Meta+Enter or Esc then Enter to finish):"
+        ENTER_ISSUE_BODY: str = "Enter issue body/description (press Meta+Enter or Esc then Enter to finish):"
+        ASSIGN_TO_SELF: str = "Assign this issue to yourself?"
+        SELECT_LABELS: str = "Select labels for this issue:"
+        ENTER_PR_BODY_INFO: str = "Enter a description for your pull request. When you are finished, press Meta+Enter (or Esc followed by Enter)."
+
+    class GitHub:
+        """GitHub operations messages"""
+        # Client errors
+        CLI_NOT_FOUND: str = "GitHub CLI ('gh') not found. Please install it and ensure it's in your PATH."
+        NOT_AUTHENTICATED: str = "GitHub CLI is not authenticated. Run: gh auth login"
+        CONFIG_REPO_MISSING: str = "GitHub repository owner and name must be configured in [plugins.github.config]."
+        API_ERROR: str = "GitHub API error: {error_msg}"
+        PERMISSION_ERROR: str = "Permission denied for GitHub operation: {error_msg}"
+        UNEXPECTED_ERROR: str = "An unexpected GitHub error occurred: {error}"
+
+        # Pull Requests
+        PR_NOT_FOUND: str = "Pull Request #{pr_number} not found."
+        PR_CREATING: str = "Creating pull request..."
+        PR_CREATED: str = "PR #{number} created: {url}"
+        PR_UPDATED: str = "PR #{number} updated"
+        PR_MERGED: str = "PR #{number} merged"
+        PR_CLOSED: str = "PR #{number} closed"
+        PR_FAILED: str = "Failed to create PR: {error}"
+        PR_CREATION_FAILED: str = "Failed to create pull request: {error}"
+        FAILED_TO_PARSE_PR_NUMBER: str = "Failed to parse PR number from URL: {url}"
+
+        # Merge
+        INVALID_MERGE_METHOD: str = "Invalid merge method: {method}. Must be one of: {valid_methods}"
+
+        # Reviews
+        REVIEW_NOT_FOUND: str = "Review ID #{review_id} for Pull Request #{pr_number} not found."
+        REVIEW_CREATING: str = "Creating review..."
+        REVIEW_CREATED: str = "Review submitted"
+        REVIEW_FAILED: str = "Failed to submit review: {error}"
+
+        # Comments
+        COMMENT_CREATING: str = "Adding comment..."
+        COMMENT_CREATED: str = "Comment added"
+        COMMENT_FAILED: str = "Failed to add comment: {error}"
+
+        # Repository
+        REPO_NOT_FOUND: str = "Repository not found"
+        REPO_ACCESS_DENIED: str = "Access denied to repository"
+
+        # Authentication
+        AUTH_MISSING: str = "GitHub token not found. Set GITHUB_TOKEN environment variable."
+        AUTH_INVALID: str = "Invalid GitHub token"
+
+        class AI:
+            AI_NOT_CONFIGURED: str = "AI not configured. Run 'titan ai configure' to enable AI features."
+            GITHUB_CLIENT_NOT_AVAILABLE: str = "GitHub client is not available in the workflow context."
+            GIT_CLIENT_NOT_AVAILABLE: str = "Git client is not available in the workflow context."
+            MISSING_PR_HEAD_BRANCH: str = "Missing pr_head_branch in context"
+            ANALYZING_BRANCH_DIFF: str = "Analyzing branch diff: {head_branch} vs {base_branch}..."
+            FAILED_TO_GET_BRANCH_DIFF: str = "Failed to get branch diff: {e}"
+            NO_CHANGES_FOUND: str = "No changes found between branches"
+            COMMITS_TRUNCATED: str = "\n  ... and {count} more commits"
+            NO_DIFF_AVAILABLE: str = "No diff available"
+            DIFF_TRUNCATED: str = "\n\n... (diff truncated for brevity)"
+            PR_SIZE_INFO: str = "PR Size: {pr_size} ({files_changed} files, {diff_lines} lines) → Max description: {max_chars} chars"
+            FAILED_TO_READ_PR_TEMPLATE: str = "Failed to read PR template: {e}"
+            GENERATING_PR_DESCRIPTION: str = "Generating PR description with AI..."
+            AI_RESPONSE_FORMAT_INCORRECT: str = "AI response format incorrect. Expected 'TITLE:' and 'DESCRIPTION:' sections.\nGot: {response_preview}..."
+            AI_GENERATED_TRUNCATING: str = "AI generated {actual_len} chars, truncating to {max_chars}"
+            AI_GENERATED_EMPTY_SHORT: str = "AI generated an empty or very short description."
+            FULL_AI_RESPONSE: str = "Full AI response:"
+            AI_GENERATED_INCOMPLETE: str = "AI generated an empty or incomplete PR description"
+            AI_GENERATED_COMMIT_MESSAGE: str = "AI Generated Commit Message"
+            COMMIT_MESSAGE_LABEL: str = "Commit Message:"
+            CONFIRM_USE_AI_COMMIT: str = "Use this AI-generated commit message?"
+            AI_COMMIT_REJECTED: str = "AI-generated commit message rejected"
+            AI_GENERATED_PR_TITLE: str = "AI Generated PR:"
+            TITLE_LABEL: str = "Title:"
+            TITLE_TOO_LONG_WARNING: str = "Title is {length} chars (recommended: ≤72)"
+            DESCRIPTION_LABEL: str = "Description:"
+            CONFIRM_USE_AI_PR: str = "Use this AI-generated PR?"
+            AI_SUGGESTION_REJECTED: str = "AI suggestion rejected. Will prompt for manual input."
+            AI_GENERATED_PR_DESCRIPTION_SUCCESS: str = "AI generated PR description"
+            AI_GENERATION_FAILED: str = "AI generation failed: {e}"
+            FALLBACK_TO_MANUAL: str = "Falling back to manual PR creation..."
+
+msg = Messages()

titan_plugin_github/models.py

@@ -0,0 +1,330 @@
+# plugins/titan-plugin-github/titan_plugin_github/models.py
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+# Import PRSizeEstimation from utils
+
+
+@dataclass
+class User:
+    """GitHub user representation"""
+    login: str
+    name: Optional[str] = None
+    email: Optional[str] = None
+    avatar_url: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'User':
+        """
+        Create User from API response
+
+        Args:
+            data: User data from GitHub API
+
+        Returns:
+            User instance
+
+        Examples:
+            >>> data = {"login": "john", "name": "John Doe"}
+            >>> user = User.from_dict(data)
+        """
+        if not data:
+            return cls(login="unknown")
+
+        return cls(
+            login=data.get("login", "unknown"),
+            name=data.get("name"),
+            email=data.get("email"),
+            avatar_url=data.get("avatar_url")
+        )
+
+
+@dataclass
+class ReviewComment:
+    """GitHub PR review comment"""
+    id: int
+    path: str
+    line: int
+    body: str
+    user: User
+    created_at: str
+    side: str = "RIGHT"  # RIGHT or LEFT
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'ReviewComment':
+        """Create ReviewComment from API response"""
+        return cls(
+            id=data.get("id", 0),
+            path=data.get("path", ""),
+            line=data.get("line", 0),
+            body=data.get("body", ""),
+            user=User.from_dict(data.get("user", {})),
+            created_at=data.get("created_at", ""),
+            side=data.get("side", "RIGHT")
+        )
+
+
+@dataclass
+class Review:
+    """GitHub PR review"""
+    id: int
+    user: User
+    body: str
+    state: str  # PENDING, APPROVED, CHANGES_REQUESTED, COMMENTED
+    submitted_at: Optional[str] = None
+    commit_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Review':
+        """Create Review from API response"""
+        return cls(
+            id=data.get("id", 0),
+            user=User.from_dict(data.get("user", {})),
+            body=data.get("body", ""),
+            state=data.get("state", "PENDING"),
+            submitted_at=data.get("submitted_at"),
+            commit_id=data.get("commit_id")
+        )
+
+
+@dataclass
+class PullRequest:
+    """
+    GitHub Pull Request representation
+
+    Attributes:
+        number: PR number
+        title: PR title
+        body: PR description
+        state: open, closed, merged
+        author: PR author
+        base_ref: Base branch (e.g., develop)
+        head_ref: Head branch (e.g., feature/xyz)
+        additions: Lines added
+        deletions: Lines deleted
+        changed_files: Number of files changed
+        mergeable: Can be merged
+        draft: Is draft PR
+        created_at: ISO date string
+        updated_at: ISO date string
+        merged_at: ISO date string (if merged)
+        reviews: List of reviews
+        labels: List of label names
+    """
+    number: int
+    title: str
+    body: str
+    state: str
+    author: User
+    base_ref: str
+    head_ref: str
+    additions: int = 0
+    deletions: int = 0
+    changed_files: int = 0
+    mergeable: bool = True
+    draft: bool = False
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    merged_at: Optional[str] = None
+    reviews: List[Review] = field(default_factory=list)
+    labels: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'PullRequest':
+        """
+        Create PullRequest from GitHub API response
+
+        Args:
+            data: PR data from GitHub API (gh pr view --json format)
+
+        Returns:
+            PullRequest instance
+
+        Examples:
+            >>> data = gh_api_response
+            >>> pr = PullRequest.from_dict(data)
+        """
+        # Parse author
+        author_data = data.get("author", {})
+        author = User.from_dict(author_data)
+
+        # Parse reviews
+        reviews_data = data.get("reviews", [])
+        reviews = [Review.from_dict(r) for r in reviews_data]
+
+        # Parse labels
+        labels_data = data.get("labels", [])
+        labels = [label.get("name", "") for label in labels_data]
+
+        return cls(
+            number=data.get("number", 0),
+            title=data.get("title", ""),
+            body=data.get("body", ""),
+            state=data.get("state", "OPEN"),
+            author=author,
+            base_ref=data.get("baseRefName", ""),
+            head_ref=data.get("headRefName", ""),
+            additions=data.get("additions", 0),
+            deletions=data.get("deletions", 0),
+            changed_files=data.get("changedFiles", 0),
+            mergeable=data.get("mergeable", "MERGEABLE") == "MERGEABLE",
+            draft=data.get("isDraft", False),
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+            merged_at=data.get("mergedAt"),
+            reviews=reviews,
+            labels=labels
+        )
+
+    def get_status_emoji(self) -> str:
+        """Get emoji for PR state"""
+        if self.state == "MERGED":
+            return "🟣"
+        elif self.state == "CLOSED":
+            return "🔴"
+        elif self.draft:
+            return "📝"
+        elif self.state == "OPEN":
+            return "🟢"
+        return "⚪"
+
+    def get_review_status(self) -> str:
+        """Get review status summary"""
+        if not self.reviews:
+            return "No reviews"
+
+        approved = sum(1 for r in self.reviews if r.state == "APPROVED")
+        changes = sum(1 for r in self.reviews if r.state == "CHANGES_REQUESTED")
+
+        if approved > 0 and changes == 0:
+            return f"✅ {approved} approved"
+        elif changes > 0:
+            return f"❌ {changes} changes requested"
+        else:
+            return f"💬 {len(self.reviews)} comments"
+
+
+@dataclass
+class PRSearchResult:
+    """Result of searching pull requests"""
+    prs: List[PullRequest]
+    total: int
+
+    @classmethod
+    def from_list(cls, data: List[dict]) -> 'PRSearchResult':
+        """
+        Create PRSearchResult from list of PR data
+
+        Args:
+            data: List of PR dictionaries from GitHub API
+
+        Returns:
+            PRSearchResult instance
+        """
+        prs = [PullRequest.from_dict(pr_data) for pr_data in data]
+        return cls(prs=prs, total=len(prs))
+
+
+@dataclass
+class PRComment:
+    """
+    Pull request comment (review comment or issue comment)
+
+    Attributes:
+        id: Comment ID
+        body: Comment text
+        user: User who created the comment
+        created_at: Creation timestamp
+        path: File path (for review comments)
+        line: Line number (for review comments)
+        diff_hunk: Diff context (for review comments)
+        pull_request_review_id: Review ID (for review comments)
+        in_reply_to_id: ID of parent comment (if it's a reply)
+        is_review_comment: True if inline review comment, False if issue comment
+    """
+    id: int
+    body: str
+    user: User
+    created_at: str
+    path: Optional[str] = None
+    line: Optional[int] = None
+    diff_hunk: Optional[str] = None
+    pull_request_review_id: Optional[int] = None
+    in_reply_to_id: Optional[int] = None
+    is_review_comment: bool = True
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any], is_review: bool = True) -> 'PRComment':
+        """Create from API response"""
+        user_data = data.get("user", {})
+        user = User(
+            login=user_data.get("login", ""),
+            name=user_data.get("name"),
+            email=user_data.get("email"),
+            avatar_url=user_data.get("avatar_url")
+        )
+
+        return cls(
+            id=data.get("id", 0),
+            body=data.get("body", ""),
+            user=user,
+            created_at=data.get("created_at", ""),
+            path=data.get("path"),
+            line=data.get("line"),
+            diff_hunk=data.get("diff_hunk"),
+            pull_request_review_id=data.get("pull_request_review_id"),
+            in_reply_to_id=data.get("in_reply_to_id"),
+            is_review_comment=is_review
+        )
+
+
+@dataclass
+class PRMergeResult:
+    """
+    Result of merging a pull request
+
+    Attributes:
+        merged: Whether the PR was successfully merged
+        sha: Commit SHA of the merge (if successful)
+        message: Success or error message
+    """
+    merged: bool
+    sha: Optional[str] = None
+    message: str = ""
+
+
+@dataclass
+class Issue:
+    """
+    GitHub Issue representation.
+    """
+    number: int
+    title: str
+    body: str
+    state: str
+    author: User
+    labels: List[str] = field(default_factory=list)
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'Issue':
+        """
+        Create Issue from GitHub API response.
+        """
+        author_data = data.get("author", {})
+        author = User.from_dict(author_data)
+
+        labels_data = data.get("labels", [])
+        labels = [label.get("name", "") for label in labels_data]
+
+        return cls(
+            number=data.get("number", 0),
+            title=data.get("title", ""),
+            body=data.get("body", ""),
+            state=data.get("state", "OPEN"),
+            author=author,
+            labels=labels,
+            created_at=data.get("createdAt"),
+            updated_at=data.get("updatedAt"),
+        )

titan_plugin_github/plugin.py

@@ -0,0 +1,131 @@
+# plugins/titan-plugin-github/titan_plugin_github/plugin.py
+from pathlib import Path
+from typing import Optional
+
+from titan_cli.core.plugins.plugin_base import TitanPlugin
+from titan_cli.core.config import TitanConfig
+from titan_cli.core.secrets import SecretManager
+from titan_cli.core.plugins.models import GitHubPluginConfig
+from .clients.github_client import GitHubClient, GitHubError
+
+
+class GitHubPlugin(TitanPlugin):
+    """
+    Titan CLI Plugin for GitHub operations.
+    """
+
+    @property
+    def name(self) -> str:
+        return "github"
+
+    @property
+    def description(self) -> str:
+        return "Provides GitHub integration for PRs, issues, and more."
+
+    @property
+    def dependencies(self) -> list[str]:
+        return ["git"]
+
+    def initialize(self, config: TitanConfig, secrets: SecretManager) -> None:
+        """
+        Initializes the GitHubClient.
+        """
+        # Get plugin-specific configuration data
+        plugin_config_data = self._get_plugin_config(config)
+
+        # Validate configuration using Pydantic model
+        validated_config = GitHubPluginConfig(**plugin_config_data)
+
+        repo_owner = validated_config.repo_owner
+        repo_name = validated_config.repo_name
+
+        # Get the git client from the registry
+        git_plugin = config.registry.get_plugin("git")
+        if not git_plugin or not git_plugin.is_available():
+            raise GitHubError("The 'git' plugin is a required dependency and is not available.")
+        git_client = git_plugin.get_client()
+
+        # Attempt to auto-detect if not explicitly configured
+        if not repo_owner or not repo_name:
+            detected_owner, detected_name = git_client.get_github_repo_info()
+            if detected_owner and detected_name:
+                repo_owner = repo_owner or detected_owner
+                repo_name = repo_name or detected_name
+        
+        # If still missing, raise an error
+        if not repo_owner or not repo_name:
+            raise GitHubError("GitHub repository owner and name must be configured or auto-detected from git remote.")
+
+        # Initialize client with validated configuration and git_client
+        self._client = GitHubClient(
+            config=validated_config,
+            secrets=secrets,
+            git_client=git_client,
+            repo_owner=repo_owner, # Pass detected/configured owner
+            repo_name=repo_name # Pass detected/configured name
+        )
+
+    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 "github" not in config.config.plugins:
+            return {}
+
+        plugin_entry = config.config.plugins["github"]
+        return plugin_entry.config if hasattr(plugin_entry, 'config') else {}
+
+    def get_config_schema(self) -> dict:
+        """Returns the JSON schema for the plugin's configuration."""
+        return GitHubPluginConfig.model_json_schema()
+
+    def is_available(self) -> bool:
+        """
+        Checks if the GitHub CLI is installed and available.
+        """
+        import shutil
+        return shutil.which("gh") is not None and hasattr(self, '_client') and self._client is not None
+
+    @property
+    def workflows_path(self) -> Optional[Path]:
+        """
+        Returns the path to the workflows directory for this plugin.
+        """
+        return Path(__file__).parent / "workflows"
+
+    def get_client(self) -> GitHubClient:
+        """
+        Returns the initialized GitHubClient instance.
+        """
+        # Ensure the client is initialized, potentially adding a check here
+        if not hasattr(self, '_client') or self._client is None:
+            raise GitHubError("GitHubPlugin not initialized. GitHub client may not be available.")
+        return self._client
+
+    def get_steps(self) -> dict:
+        """
+        Returns a dictionary of available workflow steps.
+        """
+        from .steps.create_pr_step import create_pr_step
+        from .steps.github_prompt_steps import prompt_for_pr_title_step, prompt_for_pr_body_step, prompt_for_issue_body_step, prompt_for_self_assign_step, prompt_for_labels_step
+        from .steps.ai_pr_step import ai_suggest_pr_description_step
+        from .steps.issue_steps import ai_suggest_issue_title_and_body_step, create_issue_steps
+        from .steps.preview_step import preview_and_confirm_issue_step
+        return {
+            "create_pr": create_pr_step,
+            "prompt_for_pr_title": prompt_for_pr_title_step,
+            "prompt_for_pr_body": prompt_for_pr_body_step,
+            "prompt_for_issue_body_step": prompt_for_issue_body_step,
+            "prompt_for_self_assign": prompt_for_self_assign_step,
+            "prompt_for_labels": prompt_for_labels_step,
+            "ai_suggest_pr_description": ai_suggest_pr_description_step,
+            "ai_suggest_issue_title_and_body": ai_suggest_issue_title_and_body_step,
+            "create_issue": create_issue_steps,
+            "preview_and_confirm_issue": preview_and_confirm_issue_step,
+        }

titan_plugin_github/steps/__init__.py

@@ -0,0 +1,12 @@
+# plugins/titan-plugin-github/titan_plugin_github/steps/__init__.py
+"""
+Workflow steps for GitHub operations
+"""
+
+from .create_pr_step import create_pr_step
+from .ai_pr_step import ai_suggest_pr_description_step
+
+__all__ = [
+    "create_pr_step",
+    "ai_suggest_pr_description_step",
+]