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

[jwm4]

Summary

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 (get_github_tokens(), get_default_github_token())
• client.py: Add find_working_token() function to search through tokens for write access
• main.py: Use multi-token search when --post flag is provided
• env.example: Document new environment variable
• tests: Add comprehensive tests for new functionality (13 new tests)

Usage

# In .env - list multiple fine-grained PATs
REVIEW_ROADMAP_GITHUB_TOKENS=ghp_token_for_repo1,ghp_token_for_repo2,ghp_token_for_repo3

When running with --post, tokens are tried in order until one with write access is found:

$ review_roadmap owner/repo/123 --post
Searching 3 tokens for write access to owner/repo...
Write access confirmed (token 2 of 3).
...

Precedence

• REVIEW_ROADMAP_GITHUB_TOKENS takes precedence over GITHUB_TOKEN for write operations
• GITHUB_TOKEN is appended as a fallback if not already in the list
• At least one token must be configured (either variable)

Test Results

All 89 tests pass with 84% coverage.

[jwm4]

🗺️ Auto-Generated Review Roadmap

This roadmap was automatically generated by review-roadmap.
Model: anthropic-vertex/claude-opus-4-5

---

Review Roadmap: Multi-Token Support for Fine-Grained PATs

High-Level Summary

This PR introduces the ability to configure multiple GitHub Personal Access Tokens (PATs) via a new REVIEW_ROADMAP_GITHUB_TOKENS environment variable. When the --post flag is used, the system iterates through configured tokens until it finds one with write access to the target repository. This solves a real workflow pain point: developers working across multiple repos with fine-grained PATs no longer need to swap tokens in their .env file.

The change touches configuration, the GitHub client layer, and CLI orchestration, with comprehensive test coverage.

---

Recommended Review Order

1. Configuration Layer (Start Here)

Why first: Understanding the token management API is foundational—everything else depends on it.

File	Focus Areas
env.example	Quick read—verify the user-facing documentation is clear
review_roadmap/config.py	Core logic—get_github_tokens(), get_default_github_token(), and the model_validator

2. GitHub Client Additions

Why second: Contains the find_working_token() function that orchestrates token testing.

File	Focus Areas
review_roadmap/github/client.py	New TokenSearchResult dataclass and find_working_token() function

3. CLI Integration

Why third: See how the pieces are wired together in the user-facing command.

File	Focus Areas
review_roadmap/main.py	Conditional logic around --post, token selection, and GitHubClient instantiation with write_token

4. Test Suite (Validation Pass)

Why last: Confirm edge cases are covered and assertions match expected behavior.

File	Focus Areas
tests/test_config.py	New file—token list parsing, precedence, deduplication, validation
tests/test_github_client.py	find_working_token tests—first token works, fallback, all fail scenarios
tests/test_main.py	Updated mocks for find_working_token integration

---

Watch Outs

Security & Credential Handling

• Token logging: Verify that tokens are never printed to console or logs. Check main.py console output—it shows "token 2 of 3" but not the actual token value. Confirm find_working_token in client.py doesn't log tokens either.
• Error messages: Ensure failed token attempts don't leak credential prefixes in error strings.

Logic & Edge Cases

• Empty string tokens: In config.py, get_github_tokens() filters via if t.strip(). Confirm this handles "token1,,token3" (empty middle entry) gracefully.
• Deduplication order: The code appends GITHUB_TOKEN as fallback "if not already in the list." Verify the dedup preserves order (first occurrence wins).
• Validator timing: The @model_validator raises if neither token source is set. Confirm tests in test_config.py cover this validation error path.

API & Rate Limiting

• Multiple API calls: find_working_token() tests each token by calling check_write_access(). If there are many tokens, this could hit rate limits. Check if there's any short-circuit or caching consideration mentioned.
• Client re-instantiation: In main.py, after finding write_token, a new GitHubClient(token=write_token) is created. Confirm this doesn't leave the original client's connection dangling (httpx handles this, but worth a glance).

Test Coverage

• Mock isolation: Tests in test_main.py now patch find_working_token instead of check_write_access. Verify the existing --post test scenarios still exercise the right code paths.
• Partial failures: Is there a test for "first N tokens fail, then one succeeds"? Check test_github_client.py for test_find_working_token_second_token_works.

---

Existing Discussions

No comments have been posted on this PR yet. You're the first reviewer! 🎉

---

Quick Checklist for Your Review

• Token precedence logic matches documentation in env.example
• TokenSearchResult dataclass is used consistently
• Console output mentions token position but not token values
• All new tests pass locally (author claims 89 tests, 84% coverage)
• No breaking changes to existing single-token workflow