feat: add multi-token support for fine-grained PATs (#11)

* feat: add multi-token support for fine-grained PATs

Add REVIEW_ROADMAP_GITHUB_TOKENS environment variable that accepts a
comma-separated list of GitHub tokens. When --post is used, each token
is tested for write access until one with the correct permissions is
found.

This is useful when working with multiple repositories that each have
their own fine-grained PAT, eliminating the need to change .env when
switching between projects.

Changes:
- config.py: Add REVIEW_ROADMAP_GITHUB_TOKENS setting with helper methods
- client.py: Add find_working_token() function to search for working token
- main.py: Use multi-token search when --post flag is provided
- env.example: Document new environment variable
- tests: Add comprehensive tests for new functionality

* fix: use monkeypatch in config tests to isolate from CI env vars

The CI environment sets GITHUB_TOKEN as an env var, which pydantic-settings
picks up even with _env_file=None. Use monkeypatch.delenv() to ensure tests
are isolated from any environment variables.

Author: jwm4

env.example

@@ -1,8 +1,15 @@
 # Note: If you have these environment variables set in your own environment, the ones in your environment will take precedence over any you put here.
 
 # GitHub Configuration
+# Option 1: Single token (simplest)
 GITHUB_TOKEN=your_github_token_here
 
+# Option 2: Multiple tokens (for working across multiple projects with fine-grained PATs)
+# Comma-separated list of tokens. When --post is used, each token is tested for write access
+# and the first one that works is used. This is useful if you have separate fine-grained PATs
+# for different repositories. Takes precedence over GITHUB_TOKEN for write operations.
+# REVIEW_ROADMAP_GITHUB_TOKENS=ghp_token1,ghp_token2,ghp_token3
+
 # Application Settings
 
 REVIEW_ROADMAP_LOG_LEVEL=INFO

review_roadmap/config.py

@@ -7,7 +7,8 @@
 
 import os
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
+from pydantic import model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -21,6 +22,9 @@ class Settings(BaseSettings):
 
     Attributes:
         GITHUB_TOKEN: GitHub API token for fetching PR data.
+        REVIEW_ROADMAP_GITHUB_TOKENS: Comma-separated list of GitHub tokens.
+            When set, these are tried in order during write access checks.
+            Takes precedence over GITHUB_TOKEN for write operations.
         REVIEW_ROADMAP_LLM_PROVIDER: LLM provider to use. Options:
             'anthropic', 'anthropic-vertex', 'openai', 'google'.
         REVIEW_ROADMAP_MODEL_NAME: Model name (e.g., 'claude-opus-4-5', 'gpt-4o').
@@ -39,7 +43,60 @@ class Settings(BaseSettings):
     )
 
     # GitHub
-    GITHUB_TOKEN: str
+    GITHUB_TOKEN: Optional[str] = None
+    REVIEW_ROADMAP_GITHUB_TOKENS: Optional[str] = None
+    
+    @model_validator(mode="after")
+    def validate_github_token(self) -> "Settings":
+        """Ensure at least one GitHub token is configured."""
+        if not self.GITHUB_TOKEN and not self.REVIEW_ROADMAP_GITHUB_TOKENS:
+            raise ValueError(
+                "Either GITHUB_TOKEN or REVIEW_ROADMAP_GITHUB_TOKENS must be set"
+            )
+        return self
+    
+    def get_github_tokens(self) -> List[str]:
+        """Get the list of GitHub tokens to try, in order of precedence.
+        
+        When REVIEW_ROADMAP_GITHUB_TOKENS is set, those tokens take precedence
+        and are returned first. GITHUB_TOKEN (if set and not already in the list)
+        is appended as a fallback.
+        
+        Returns:
+            List of unique, non-empty GitHub tokens to try.
+        """
+        tokens: List[str] = []
+        
+        # REVIEW_ROADMAP_GITHUB_TOKENS takes precedence
+        if self.REVIEW_ROADMAP_GITHUB_TOKENS:
+            tokens.extend(
+                t.strip() 
+                for t in self.REVIEW_ROADMAP_GITHUB_TOKENS.split(",") 
+                if t.strip()
+            )
+        
+        # Add GITHUB_TOKEN as fallback if not already included
+        if self.GITHUB_TOKEN and self.GITHUB_TOKEN not in tokens:
+            tokens.append(self.GITHUB_TOKEN)
+        
+        return tokens
+    
+    def get_default_github_token(self) -> str:
+        """Get the default GitHub token for read operations.
+        
+        Returns the first available token (REVIEW_ROADMAP_GITHUB_TOKENS
+        takes precedence over GITHUB_TOKEN).
+        
+        Returns:
+            The first available GitHub token.
+        
+        Raises:
+            ValueError: If no tokens are configured.
+        """
+        tokens = self.get_github_tokens()
+        if not tokens:
+            raise ValueError("No GitHub tokens configured")
+        return tokens[0]
 
     # LLM Configuration (prefixed to avoid conflicts with shell environment)
     REVIEW_ROADMAP_LLM_PROVIDER: str = "anthropic"

review_roadmap/github/client.py

@@ -5,6 +5,7 @@
 generate review roadmaps.
 """
 
+from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Tuple
 
 import httpx
@@ -16,6 +17,21 @@
 )
 
 
+@dataclass
+class TokenSearchResult:
+    """Result of searching for a token with write access.
+    
+    Attributes:
+        token: The token that was found with write access, or None if no token worked.
+        access_result: The WriteAccessResult from checking the successful token,
+            or the last failed result if no token worked.
+        tokens_tried: Number of tokens that were tested.
+    """
+    token: Optional[str]
+    access_result: WriteAccessResult
+    tokens_tried: int
+
+
 class GitHubClient:
     """Synchronous GitHub API client for PR data retrieval.
 
@@ -37,9 +53,10 @@ def __init__(self, token: Optional[str] = None):
         """Initialize the GitHub client.
 
         Args:
-            token: GitHub API token. If not provided, uses GITHUB_TOKEN from settings.
+            token: GitHub API token. If not provided, uses the first available
+                token from settings (REVIEW_ROADMAP_GITHUB_TOKENS takes precedence).
         """
-        self.token = token or settings.GITHUB_TOKEN
+        self.token = token or settings.get_default_github_token()
         self.headers = {
             "Authorization": f"Bearer {self.token}",
             "Accept": "application/vnd.github.v3+json",
@@ -471,3 +488,79 @@ def post_pr_comment(self, owner: str, repo: str, pr_number: int, body: str) -> D
         )
         resp.raise_for_status()
         return resp.json()
+
+
+def find_working_token(
+    owner: str, repo: str, pr_number: int
+) -> TokenSearchResult:
+    """Find a GitHub token with write access from the configured tokens.
+    
+    Iterates through all configured tokens (from REVIEW_ROADMAP_GITHUB_TOKENS
+    and GITHUB_TOKEN) and tests each one for write access using the
+    check_write_access method with a live reaction test.
+    
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        pr_number: PR number for live write testing.
+    
+    Returns:
+        TokenSearchResult containing:
+        - token: The first token with GRANTED status, or None if none worked
+        - access_result: The WriteAccessResult from the successful check,
+          or the last failed result if no token worked
+        - tokens_tried: Number of tokens that were tested
+    
+    Example:
+        >>> result = find_working_token("owner", "repo", 123)
+        >>> if result.token:
+        ...     client = GitHubClient(token=result.token)
+        ...     client.post_pr_comment(owner, repo, 123, "Hello!")
+    """
+    tokens = settings.get_github_tokens()
+    
+    if not tokens:
+        return TokenSearchResult(
+            token=None,
+            access_result=WriteAccessResult(
+                status=WriteAccessStatus.DENIED,
+                is_fine_grained_pat=False,
+                message="No GitHub tokens configured."
+            ),
+            tokens_tried=0
+        )
+    
+    last_result: Optional[WriteAccessResult] = None
+    
+    for i, token in enumerate(tokens, start=1):
+        client = GitHubClient(token=token)
+        try:
+            result = client.check_write_access(owner, repo, pr_number)
+            last_result = result
+            
+            if result.status == WriteAccessStatus.GRANTED:
+                return TokenSearchResult(
+                    token=token,
+                    access_result=result,
+                    tokens_tried=i
+                )
+        except Exception:
+            # Token failed to even check access (e.g., network error, invalid token)
+            # Continue to next token
+            last_result = WriteAccessResult(
+                status=WriteAccessStatus.DENIED,
+                is_fine_grained_pat=False,
+                message=f"Token failed basic validation (may be invalid or revoked)."
+            )
+            continue
+    
+    # No token worked - return the last result
+    return TokenSearchResult(
+        token=None,
+        access_result=last_result or WriteAccessResult(
+            status=WriteAccessStatus.DENIED,
+            is_fine_grained_pat=False,
+            message="No tokens were successfully tested."
+        ),
+        tokens_tried=len(tokens)
+    )

review_roadmap/main.py

@@ -1,7 +1,7 @@
 import typer
 from rich.console import Console
 from rich.markdown import Markdown
-from review_roadmap.github.client import GitHubClient
+from review_roadmap.github.client import GitHubClient, find_working_token
 from review_roadmap.agent.graph import build_graph
 from review_roadmap.config import settings
 from review_roadmap.logging import configure_logging
@@ -59,27 +59,49 @@ def generate(
         console.print("[red]Invalid PR format. Use 'owner/repo/number' or a full URL.[/red]")
         raise typer.Exit(code=1)
 
-    # Initialize GitHub client
+    # Initialize GitHub client (default token for read operations)
     gh_client = GitHubClient()
+    
+    # Token with write access (may differ from default if using multi-token)
+    write_token = None
 
     # Check write access early if posting is requested (fail fast before LLM generation)
     if post:
-        console.print(f"[bold blue]Checking write access for {owner}/{repo}...[/bold blue]")
+        tokens = settings.get_github_tokens()
+        
+        if len(tokens) > 1:
+            console.print(f"[bold blue]Searching {len(tokens)} tokens for write access to {owner}/{repo}...[/bold blue]")
+        else:
+            console.print(f"[bold blue]Checking write access for {owner}/{repo}...[/bold blue]")
+        
         try:
-            # Pass pr_number to enable live write test for fine-grained PATs
-            access_result = gh_client.check_write_access(owner, repo, pr_number)
+            # Search through available tokens for one with write access
+            search_result = find_working_token(owner, repo, pr_number)
 
-            if access_result.status == WriteAccessStatus.DENIED:
-                console.print(
-                    f"[red]Error: {access_result.message}[/red]\n"
-                    "[yellow]To use --post, your token needs 'Pull requests: Read and write' permission.[/yellow]"
-                )
-                raise typer.Exit(code=1)
-            elif access_result.status == WriteAccessStatus.UNCERTAIN:
-                console.print(f"[yellow]Warning: {access_result.message}[/yellow]")
+            if search_result.token:
+                write_token = search_result.token
+                if search_result.tokens_tried > 1:
+                    console.print(f"[green]Write access confirmed (token {search_result.tokens_tried} of {len(tokens)}).[/green]")
+                else:
+                    console.print("[green]Write access confirmed.[/green]")
+                # Update client to use the working token for subsequent operations
+                gh_client = GitHubClient(token=write_token)
+            elif search_result.access_result.status == WriteAccessStatus.UNCERTAIN:
+                console.print(f"[yellow]Warning: {search_result.access_result.message}[/yellow]")
                 console.print("[yellow]Proceeding, but posting may fail...[/yellow]")
             else:
-                console.print("[green]Write access confirmed.[/green]")
+                if search_result.tokens_tried > 1:
+                    console.print(
+                        f"[red]Error: None of the {search_result.tokens_tried} configured tokens have write access.[/red]\n"
+                        f"[red]Last error: {search_result.access_result.message}[/red]\n"
+                        "[yellow]To use --post, at least one token needs 'Pull requests: Read and write' permission.[/yellow]"
+                    )
+                else:
+                    console.print(
+                        f"[red]Error: {search_result.access_result.message}[/red]\n"
+                        "[yellow]To use --post, your token needs 'Pull requests: Read and write' permission.[/yellow]"
+                    )
+                raise typer.Exit(code=1)
         except typer.Exit:
             raise
         except Exception as e: