feat: implement permission verification for repository transfers

[TooAngel]

Summary

Implements automated permission verification for repository transfers, completing step 1 of issue #9. This PR adds the infrastructure to check if worlddriven org has admin access to origin repositories before attempting transfer.

Changes

New Module: Permission Verification

• scripts/check-transfer-permissions.js: Core module for checking GitHub permissions
  • checkTransferPermission(token, originRepo) - Check single repository
  • checkMultipleTransferPermissions(token, originRepos) - Batch checking
  • Uses GitHub API: GET /repos/{owner}/{repo}/collaborators/worlddriven/permission
  • Returns: {hasPermission, permissionLevel, details}
  • CLI tool: node scripts/check-transfer-permissions.js owner/repo

Tests

• scripts/check-transfer-permissions.test.js: Unit tests for validation logic
  • Tests error handling (missing token, invalid format)
  • Documents expected behavior for integration tests
  • All tests passing ✅

Enhanced Drift Detection

• scripts/detect-drift.js: Integrated permission checking
  • Automatically checks permissions for repositories with Origin field
  • Stores permission results in drift object
  • Enhanced report formatting to show permission status:
    • ✅ "Ready to transfer" when admin permission granted
    • ❌ "Missing admin permission" with actionable feedback
    • ⚠️ "Could not verify" for errors
  • Summary shows ready vs. blocked count

Enhanced Sync Planning

• scripts/sync-repositories.js: Transfer action support
  • New action type: transfer (added to plan when permissions verified)
  • New summary fields: transfer and transferBlocked
  • Permission checking integrated into workflow
  • Clear console output showing permission status
  • Transfer actions marked as "not yet implemented" in reports

Updated Documentation

• REPOSITORIES.md: Comprehensive migration guide
  • Changed status from "Coming Soon" to "Partially Implemented"
  • Step-by-step instructions for granting admin permissions
  • Explanation of permission verification process
  • Example usage with Origin field
  • Clear expectations about what's implemented vs. pending

Permission Verification Flow

How It Works

1. User adds repository to REPOSITORIES.md with Origin: owner/repo-name
2. Drift detection automatically calls permission check API
3. GitHub API returns permission level ("admin", "write", "read", or "none")
4. System determines if transfer is ready:
   • Admin: ✅ Transfer ready (once API implemented)
   • Write/Read: ❌ Insufficient permissions
   • None/404: ❌ No access or repo doesn't exist
5. PR comments show clear status and next steps

GitHub API Details

• Endpoint: GET /repos/{owner}/{repo}/collaborators/worlddriven/permission
• Authentication: Uses existing WORLDDRIVEN_GITHUB_TOKEN
• Required: Read access to origin repository (public repos work)
• Response: JSON with permission field
• Rate Limits: Standard GitHub API limits apply

User Experience

PR Comments

When a PR includes a repository with Origin field:

## 🚧 Repository Transfer Pending (1)

⚠️ TRANSFER FEATURE IN DEVELOPMENT

- **my-project** ← `myusername/my-project`
  - Description: My awesome project
  - ✅ Permission Status: worlddriven has admin access to myusername/my-project
  - Ready for transfer (once transfer automation is complete)

Or if permission is missing:

- **my-project** ← `myusername/my-project`
  - Description: My awesome project
  - ❌ Permission Status: worlddriven has "write" access (admin required)
  - Action required: Grant worlddriven admin access to myusername/my-project
  - See REPOSITORIES.md for instructions on granting permissions

Sync Plan Output

Summary: 5 total actions
- Create: 2
- Update descriptions: 1
- Transfer (ready): 1
- Transfer (blocked): 0
- Ensure settings: 1

Testing

Manual Testing

# Check permission for a repository
export WORLDDRIVEN_GITHUB_TOKEN=your_token
node scripts/check-transfer-permissions.js TooAngel/worlddriven

# Run drift detection (will check permissions automatically)
node scripts/detect-drift.js

# Run sync plan (dry-run)
node scripts/sync-repositories.js

Unit Tests

node --test scripts/*.test.js

All tests passing ✅ (19 tests, 2 suites)

Implementation Status

✅ Completed (This PR)

• Permission verification module
• GitHub API integration
• Unit tests
• Drift detection integration
• Enhanced reporting
• Sync plan updates
• User documentation

🚧 Remaining (Future PRs)

• Transfer API implementation (POST /repos/{owner}/{repo}/transfer)
• Actual repository transfer execution
• Post-transfer configuration
• Error handling for transfer failures
• Integration tests with test repositories

Breaking Changes

None - this PR is fully backward compatible. Existing functionality unchanged.

Related Issue

Closes #9 (partial - completes permission verification step)

Next Steps

1. Merge this PR to enable permission verification
2. Users can start granting permissions to prepare for transfer
3. Next PR will implement actual transfer API call
4. Transfer automation will be complete after API implementation

Notes

• Transfer actions appear in sync plan but throw error if executed
• This is intentional - sets up infrastructure for next step
• Clear error message references issue feat: implement repository transfer automation for migration to worlddriven org #9 for implementation progress

[worlddriven]

🤖 Worlddriven Status

📊 Live Status Dashboard

🗓️ Merge Date: 2025-11-24 at 07:18:07 UTC (today)
📅 Started: 2025-11-22 at 07:18:07 UTC
⚡ Speed Factor: 0.20 (80% faster due to reviews)
✅ Positive votes: 8/10 contribution weight (coefficient: 0.80)
📈 Base Merge Time: 10 days → Current: 2 days

🎯 Want to influence when this merges?

Your review matters! As a contributor to this project, your voice helps determine the merge timeline.

How to review:

1. Check the changes
   

2. Leave your review
   

Your options:

• ✅ Agree & Speed Up: Approving makes this merge faster
• ❌ Disagree & Slow Down: Requesting changes delays the merge

💡 Pro tip: The more contributors who agree, the faster this gets merged!

📊 View detailed stats on the dashboard

📋 Recent Activity

• 2025-11-22, 07:04:49 - Pull request opened
• 2025-11-22, 07:04:51 - Pull request opened
• 2025-11-22, 07:18:14 - Branch synchronized (merge timer reset)
• 2025-11-22, 07:18:15 - Branch synchronized (merge timer reset)
• 2025-11-24, 07:52:02 - Pull request merged by worlddriven ✅

---

This comment is automatically updated by worlddriven