@papi-ai/skills 0.1.0

package/skills/pr-reviewer/references/scenarios.md

@@ -0,0 +1,71 @@
+# Common Review Scenarios
+
+Detailed workflows for specific review use cases.
+
+## Scenario 1: Quick Review Request
+
+**Trigger**: User provides PR URL and requests review.
+
+**Workflow**:
+1. Run `fetch_pr_data.py` to collect data
+2. Read `SUMMARY.txt` and `metadata.json`
+3. Scan `diff.patch` for obvious issues
+4. Apply critical criteria (security, bugs, tests)
+5. Create findings JSON with analysis
+6. Run `generate_review_files.py` to create review files
+7. Direct user to review `pr/review.md` and `pr/human.md`
+8. Remind user to use `/show` to edit, then `/send` or `/send-decline`
+
+## Scenario 2: Thorough Review with Inline Comments
+
+**Trigger**: User requests comprehensive review with inline comments.
+
+**Workflow**:
+1. Run `fetch_pr_data.py` with cloning enabled
+2. Read all collected files (metadata, diff, comments, commits)
+3. Apply full `review_criteria.md` checklist
+4. Identify critical issues, important issues, and nits
+5. Create findings JSON with `inline_comments` array
+6. Run `generate_review_files.py` to create all files
+7. Direct user to:
+   - Review `pr/review.md` for detailed analysis
+   - Edit `pr/human.md` if needed
+   - Check `pr/inline.md` for proposed comments
+   - Use `/show` to open in VS Code
+   - Use `/send` or `/send-decline` when ready
+   - Optionally post inline comments from `pr/inline.md`
+
+## Scenario 3: Security-Focused Review
+
+**Trigger**: User requests security-specific review.
+
+**Workflow**:
+1. Fetch PR data
+2. Focus on `review_criteria.md` Section 5 (Security)
+3. Check for: SQL injection, XSS, CSRF, secrets exposure
+4. Examine dependencies in metadata
+5. Review authentication/authorization changes
+6. Report security findings with severity ratings
+
+## Scenario 4: Review with Related Tickets
+
+**Trigger**: User requests review against linked JIRA/GitHub ticket.
+
+**Workflow**:
+1. Fetch PR data (captures ticket references)
+2. Read `related_issues.json`
+3. Compare PR changes against ticket requirements
+4. Verify all acceptance criteria met
+5. Note any missing functionality
+6. Suggest additional tests if needed
+
+## Scenario 5: Large PR Review (>400 lines)
+
+**Trigger**: PR contains more than 400 lines of changes.
+
+**Workflow**:
+1. Suggest splitting into smaller PRs if feasible
+2. Review in logical chunks by file or feature
+3. Focus on architecture and design first
+4. Document structural concerns before line-level issues
+5. Prioritize security and correctness over style

package/skills/pr-reviewer/references/troubleshooting.md

@@ -0,0 +1,55 @@
+# Troubleshooting Guide
+
+Common issues and solutions for the PR Reviewer skill.
+
+## gh CLI Not Found
+
+Install GitHub CLI: https://cli.github.com/
+
+```bash
+# macOS
+brew install gh
+
+# Linux
+sudo apt install gh  # or yum, dnf, etc.
+
+# Authenticate
+gh auth login
+```
+
+## Permission Denied Errors
+
+Check authentication:
+
+```bash
+gh auth status
+gh auth refresh -s repo
+```
+
+## Invalid PR URL
+
+Ensure URL format: `https://github.com/owner/repo/pull/NUMBER`
+
+## Line Number Mismatch in Diff
+
+Inline comment line numbers are **relative to the diff**, not absolute file positions.
+Use `gh pr diff <number>` to see diff line numbers.
+
+## Rate Limit Errors
+
+```bash
+# Check rate limit
+gh api /rate_limit
+
+# Authenticated users get higher limits
+gh auth login
+```
+
+## Common Error Patterns
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 401 Unauthorized | Token expired | Run `gh auth refresh` |
+| 403 Forbidden | Missing scope | Run `gh auth refresh -s repo` |
+| 404 Not Found | Private repo access | Verify repo permissions |
+| 422 Unprocessable | Invalid request | Check command arguments |

package/skills/pr-reviewer/scripts/add_inline_comment.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Add inline code review comments to a GitHub PR.
+
+Usage:
+    python add_inline_comment.py <owner> <repo> <pr_number> <commit_id> <file_path> <line> <comment> [--side RIGHT|LEFT]
+
+Example:
+    python add_inline_comment.py owner repo 123 abc123def "src/main.py" 42 "Consider refactoring this logic"
+    python add_inline_comment.py owner repo 123 abc123def "src/main.py" 42 "Check edge cases" --side LEFT
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from typing import Optional
+
+
+def add_inline_comment(
+    owner: str,
+    repo: str,
+    pr_number: str,
+    commit_id: str,
+    path: str,
+    line: int,
+    body: str,
+    side: str = "RIGHT",
+    start_line: Optional[int] = None,
+    start_side: Optional[str] = None
+) -> dict:
+    """
+    Add an inline comment to a PR using gh CLI.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        pr_number: Pull request number
+        commit_id: SHA of the commit to comment on
+        path: File path relative to repo root
+        line: Line number in the diff
+        body: Comment text
+        side: "RIGHT" (new version) or "LEFT" (old version)
+        start_line: For multi-line comments, the starting line
+        start_side: For multi-line comments, the starting side
+
+    Returns:
+        API response as dict
+
+    Raises:
+        RuntimeError: If gh command fails
+    """
+    # Build the API request body
+    request_body = {
+        "body": body,
+        "commit_id": commit_id,
+        "path": path,
+        "side": side,
+        "line": line
+    }
+
+    # Add multi-line comment fields if provided
+    if start_line is not None:
+        request_body["start_line"] = start_line
+        if start_side is not None:
+            request_body["start_side"] = start_side
+
+    # Convert to JSON string for gh CLI
+    request_json = json.dumps(request_body)
+
+    # Build gh api command
+    cmd = [
+        'gh', 'api',
+        '-X', 'POST',
+        '-H', 'Accept: application/vnd.github+json',
+        f'/repos/{owner}/{repo}/pulls/{pr_number}/comments',
+        '--input', '-'
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            input=request_json,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return json.loads(result.stdout)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Failed to add comment: {e.stderr}")
+    except FileNotFoundError:
+        raise RuntimeError("gh CLI not found. Please install: https://cli.github.com/")
+
+
+def get_latest_commit(owner: str, repo: str, pr_number: str) -> str:
+    """Get the latest commit SHA for a PR."""
+    try:
+        result = subprocess.run([
+            'gh', 'api',
+            f'/repos/{owner}/{repo}/pulls/{pr_number}/commits',
+            '--jq', '.[-1].sha'
+        ], capture_output=True, text=True, check=True)
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Failed to get commits: {e.stderr}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Add inline code review comment to GitHub PR',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument('owner', help='Repository owner')
+    parser.add_argument('repo', help='Repository name')
+    parser.add_argument('pr_number', help='Pull request number')
+    parser.add_argument('commit_id', help='Commit SHA (use "latest" to auto-fetch)')
+    parser.add_argument('path', help='File path relative to repo root')
+    parser.add_argument('line', type=int, help='Line number in the diff')
+    parser.add_argument('body', help='Comment text')
+    parser.add_argument('--side', choices=['RIGHT', 'LEFT'], default='RIGHT',
+                       help='Side of the diff (RIGHT=new, LEFT=old)')
+    parser.add_argument('--start-line', type=int,
+                       help='Starting line for multi-line comment')
+    parser.add_argument('--start-side', choices=['RIGHT', 'LEFT'],
+                       help='Starting side for multi-line comment')
+
+    args = parser.parse_args()
+
+    try:
+        # Get latest commit if requested
+        commit_id = args.commit_id
+        if commit_id.lower() == 'latest':
+            print(f"Fetching latest commit for PR #{args.pr_number}...")
+            commit_id = get_latest_commit(args.owner, args.repo, args.pr_number)
+            print(f"Latest commit: {commit_id}")
+
+        # Add the inline comment
+        print(f"Adding comment to {args.path}:{args.line}...")
+        response = add_inline_comment(
+            owner=args.owner,
+            repo=args.repo,
+            pr_number=args.pr_number,
+            commit_id=commit_id,
+            path=args.path,
+            line=args.line,
+            body=args.body,
+            side=args.side,
+            start_line=args.start_line,
+            start_side=args.start_side
+        )
+
+        print(f"\n✅ Comment added successfully!")
+        print(f"Comment ID: {response.get('id')}")
+        print(f"URL: {response.get('html_url')}")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/pr-reviewer/scripts/fetch_pr_data.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""
+Fetch GitHub PR data using gh CLI and organize it for review.
+
+Usage:
+    python fetch_pr_data.py <pr_url> [--output-dir <dir>]
+
+Example:
+    python fetch_pr_data.py https://github.com/owner/repo/pull/123
+    python fetch_pr_data.py https://github.com/owner/repo/pull/123 --output-dir /tmp/custom
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+def parse_pr_url(pr_url: str) -> Tuple[str, str, str]:
+    """
+    Parse GitHub PR URL to extract owner, repo, and PR number.
+
+    Args:
+        pr_url: GitHub PR URL (e.g., https://github.com/owner/repo/pull/123)
+
+    Returns:
+        Tuple of (owner, repo, pr_number)
+
+    Raises:
+        ValueError: If URL format is invalid
+    """
+    pattern = r'github\.com/([^/]+)/([^/]+)/pull/(\d+)'
+    match = re.search(pattern, pr_url)
+
+    if not match:
+        raise ValueError(f"Invalid GitHub PR URL: {pr_url}")
+
+    return match.group(1), match.group(2), match.group(3)
+
+
+def run_gh_command(args: List[str]) -> str:
+    """
+    Run gh CLI command and return output.
+
+    Args:
+        args: Command arguments to pass to gh
+
+    Returns:
+        Command output as string
+
+    Raises:
+        RuntimeError: If gh command fails
+    """
+    try:
+        result = subprocess.run(
+            ['gh'] + args,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"gh command failed: {e.stderr}")
+    except FileNotFoundError:
+        raise RuntimeError("gh CLI not found. Please install: https://cli.github.com/")
+
+
+def fetch_pr_metadata(owner: str, repo: str, pr_number: str) -> Dict:
+    """Fetch PR metadata using gh pr view."""
+    repo_spec = f"{owner}/{repo}"
+    output = run_gh_command([
+        'pr', 'view', pr_number,
+        '--repo', repo_spec,
+        '--json', 'number,title,body,state,author,headRefName,baseRefName,commits,reviews,comments,files,labels,assignees,milestone,createdAt,updatedAt,mergedAt,closedAt,url,isDraft'
+    ])
+    return json.loads(output)
+
+
+def fetch_pr_diff(owner: str, repo: str, pr_number: str) -> str:
+    """Fetch PR diff using gh pr diff."""
+    repo_spec = f"{owner}/{repo}"
+    return run_gh_command(['pr', 'diff', pr_number, '--repo', repo_spec])
+
+
+def fetch_pr_comments(owner: str, repo: str, pr_number: str) -> List[Dict]:
+    """Fetch PR review comments."""
+    repo_spec = f"{owner}/{repo}"
+    output = run_gh_command([
+        'api',
+        f'/repos/{owner}/{repo}/pulls/{pr_number}/comments',
+        '--paginate'
+    ])
+    return json.loads(output)
+
+
+def fetch_commits(owner: str, repo: str, pr_number: str) -> List[Dict]:
+    """Fetch commit details for the PR."""
+    repo_spec = f"{owner}/{repo}"
+    output = run_gh_command([
+        'api',
+        f'/repos/{owner}/{repo}/pulls/{pr_number}/commits',
+        '--paginate'
+    ])
+    return json.loads(output)
+
+
+def extract_ticket_numbers(text: str) -> List[str]:
+    """
+    Extract ticket/issue numbers from text.
+    Looks for patterns like: JIRA-123, #123, PROJ-456, etc.
+    """
+    patterns = [
+        r'#(\d+)',  # GitHub issues: #123
+        r'([A-Z]+-\d+)',  # JIRA style: PROJ-123
+        r'([A-Z]{2,}-\d+)',  # Generic ticket: ABC-123
+    ]
+
+    tickets = []
+    for pattern in patterns:
+        matches = re.findall(pattern, text)
+        tickets.extend(matches)
+
+    return list(set(tickets))  # Remove duplicates
+
+
+def fetch_github_issue(owner: str, repo: str, issue_number: str) -> Optional[Dict]:
+    """Fetch GitHub issue details if it exists."""
+    try:
+        output = run_gh_command([
+            'api',
+            f'/repos/{owner}/{repo}/issues/{issue_number.lstrip("#")}'
+        ])
+        return json.loads(output)
+    except RuntimeError:
+        return None
+
+
+def setup_pr_review_dir(base_dir: str, repo: str, pr_number: str) -> Path:
+    """Create and return the PR review directory."""
+    pr_review_dir = Path(base_dir) / 'PRs' / repo / pr_number
+    pr_review_dir.mkdir(parents=True, exist_ok=True)
+    return pr_review_dir
+
+
+def clone_pr_branch(owner: str, repo: str, branch: str, target_dir: Path) -> None:
+    """Clone the PR source branch into target directory."""
+    repo_url = f"https://github.com/{owner}/{repo}.git"
+    clone_dir = target_dir / "source"
+
+    if clone_dir.exists():
+        print(f"Repository already cloned at {clone_dir}, pulling latest...")
+        subprocess.run(['git', '-C', str(clone_dir), 'pull'], check=True)
+    else:
+        print(f"Cloning {repo_url} branch {branch}...")
+        subprocess.run([
+            'git', 'clone',
+            '--branch', branch,
+            '--single-branch',
+            repo_url,
+            str(clone_dir)
+        ], check=True)
+
+
+def get_branch_diff(clone_dir: Path, base_branch: str, head_branch: str) -> str:
+    """Get git diff between base and head branches."""
+    # Fetch base branch if not already present
+    subprocess.run([
+        'git', '-C', str(clone_dir),
+        'fetch', 'origin', f'{base_branch}:{base_branch}'
+    ], check=False)  # Don't fail if branch exists
+
+    result = subprocess.run([
+        'git', '-C', str(clone_dir),
+        'diff', f'origin/{base_branch}...{head_branch}'
+    ], capture_output=True, text=True, check=True)
+
+    return result.stdout
+
+
+def save_data(pr_review_dir: Path, data: Dict) -> None:
+    """Save all fetched data to JSON files in the PR review directory."""
+    for filename, content in data.items():
+        filepath = pr_review_dir / filename
+
+        if filename.endswith('.json'):
+            with open(filepath, 'w') as f:
+                json.dump(content, f, indent=2)
+        else:
+            with open(filepath, 'w') as f:
+                f.write(content)
+
+        print(f"Saved: {filepath}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Fetch GitHub PR data for code review',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument('pr_url', help='GitHub PR URL')
+    parser.add_argument('--output-dir', default='/tmp',
+                       help='Base output directory (default: /tmp)')
+    parser.add_argument('--no-clone', action='store_true',
+                       help='Skip cloning the repository')
+
+    args = parser.parse_args()
+
+    try:
+        # Parse PR URL
+        owner, repo, pr_number = parse_pr_url(args.pr_url)
+        print(f"Fetching PR #{pr_number} from {owner}/{repo}...")
+
+        # Setup review directory
+        pr_review_dir = setup_pr_review_dir(args.output_dir, repo, pr_number)
+        print(f"PR review directory: {pr_review_dir}")
+
+        # Fetch PR metadata
+        print("Fetching PR metadata...")
+        metadata = fetch_pr_metadata(owner, repo, pr_number)
+
+        # Fetch PR diff
+        print("Fetching PR diff...")
+        diff = fetch_pr_diff(owner, repo, pr_number)
+
+        # Fetch comments
+        print("Fetching PR comments...")
+        comments = fetch_pr_comments(owner, repo, pr_number)
+
+        # Fetch commits
+        print("Fetching commit history...")
+        commits = fetch_commits(owner, repo, pr_number)
+
+        # Extract and fetch ticket information
+        print("Extracting ticket references...")
+        all_text = f"{metadata.get('title', '')} {metadata.get('body', '')}"
+        for commit in commits:
+            all_text += f" {commit.get('commit', {}).get('message', '')}"
+
+        ticket_numbers = extract_ticket_numbers(all_text)
+        related_issues = {}
+
+        for ticket in ticket_numbers:
+            if ticket.startswith('#') or ticket.isdigit():
+                issue_num = ticket.lstrip('#')
+                print(f"Fetching GitHub issue #{issue_num}...")
+                issue = fetch_github_issue(owner, repo, issue_num)
+                if issue:
+                    related_issues[ticket] = issue
+
+        # Clone repository and get diff (optional)
+        git_diff = ""
+        if not args.no_clone:
+            try:
+                print("Cloning repository...")
+                clone_pr_branch(owner, repo, metadata['headRefName'], pr_review_dir)
+
+                print("Generating git diff...")
+                clone_dir = pr_review_dir / "source"
+                git_diff = get_branch_diff(
+                    clone_dir,
+                    metadata['baseRefName'],
+                    metadata['headRefName']
+                )
+            except Exception as e:
+                print(f"Warning: Could not clone repository: {e}")
+
+        # Save all data
+        print("\nSaving data...")
+        data = {
+            'metadata.json': metadata,
+            'diff.patch': diff,
+            'comments.json': comments,
+            'commits.json': commits,
+            'related_issues.json': related_issues,
+            'ticket_numbers.json': ticket_numbers,
+        }
+
+        if git_diff:
+            data['git_diff.patch'] = git_diff
+
+        save_data(pr_review_dir, data)
+
+        # Create summary file
+        summary = f"""PR Review Summary
+==================
+
+Repository: {owner}/{repo}
+PR Number: #{pr_number}
+Title: {metadata.get('title', 'N/A')}
+Author: {metadata.get('author', {}).get('login', 'N/A')}
+State: {metadata.get('state', 'N/A')}
+Draft: {metadata.get('isDraft', False)}
+
+Branches:
+  Source: {metadata.get('headRefName', 'N/A')}
+  Target: {metadata.get('baseRefName', 'N/A')}
+
+Files Changed: {len(metadata.get('files', []))}
+Commits: {len(commits)}
+Comments: {len(comments)}
+Reviews: {len(metadata.get('reviews', []))}
+
+Related Tickets:
+{chr(10).join(f"  - {ticket}" for ticket in ticket_numbers) if ticket_numbers else "  None found"}
+
+Review Directory: {pr_review_dir}
+"""
+
+        summary_file = pr_review_dir / 'SUMMARY.txt'
+        with open(summary_file, 'w') as f:
+            f.write(summary)
+
+        print(f"\n{summary}")
+        print(f"\nAll data saved to: {pr_review_dir}")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()