feat: implement repository transfer automation for migration to worlddriven org

[TooAngel]

Overview

Implement automated repository transfer functionality to enable migrating repositories from "powered by worlddriven" to "worlddriven project" status through REPOSITORIES.md.

Distinction

• Powered by worlddriven: Repository stays under owner's control, uses worlddriven for PR automation
• Worlddriven project: Repository lives in worlddriven org with full democratic governance, managed via REPOSITORIES.md

Progress

✅ Completed

1. Parser Support (scripts/parse-repositories.js)

   • Added Origin field parsing
   • Updated type definitions to include origin?: string
   • Added comprehensive tests for origin field parsing
   • All tests passing

2. Drift Detection (scripts/detect-drift.js)

   • Added pendingTransfer category to drift detection
   • Repositories with origin field are detected and reported separately
   • Clear warning messages when origin field is present
   • Exit code doesn't treat pending transfers as errors

3. Sync Script Warnings (scripts/sync-repositories.js)

   • Added warning when pending transfers detected
   • Lists all repositories awaiting transfer implementation
   • Prevents confusion about why repos with origin aren't being processed

4. Documentation (REPOSITORIES.md)

   • Documented Origin field in properties section
   • Added "Repository Migration (Coming Soon)" section
   • Explained planned workflow and current status

🚧 Remaining Work

1. Permission Verification

Add logic to check if worlddriven org has necessary permissions on origin repository:

// In detect-drift.js or new module
async function checkTransferPermissions(token, originRepo) {
  // Check if worlddriven has admin access to originRepo
  // Return { hasPermission: boolean, details: string }
}

GitHub API endpoint: GET /repos/{owner}/{repo}/collaborators/{username}/permission
Required permission: Admin access to origin repository
Consent mechanism: Owner granting admin permission = consent to transfer

2. Transfer API Implementation

Add transfer logic to scripts/sync-repositories.js:

async function transferRepository(token, originRepo, newName) {
  // POST /repos/{owner}/{repo}/transfer
  // Body: { new_owner: 'worlddriven', new_name: newName }
  // Returns: Transfer status (async operation)
}

Key details:

• Endpoint: POST /repos/{owner}/{repo}/transfer
• Required permission: Admin on source repo
• Transfer is asynchronous
• Secrets, variables, webhooks, deploy keys transfer automatically
• Org-level secrets don't transfer (repo-specific only)

3. Sync Plan Integration

Update generateSyncPlan() to handle pending transfers:

• Add transfer action type
• Check permissions before adding to plan
• Handle permission failures gracefully
• Skip transfer if permissions not granted

4. Error Handling

• Transfer in progress detection
• Permission denied handling
• Partial transfer failures
• Rollback strategy if needed

5. Testing

• Unit tests for permission checking
• Unit tests for transfer API calls
• Integration tests with test repositories
• Dry-run mode testing

6. Documentation

Create MIGRATION.md with:

• Complete migration guide for repository owners
• How to grant permissions
• What happens during migration
• Troubleshooting common issues
• Manual migration fallback instructions

Update AUTOMATION.md:

• Document transfer workflow
• Add transfer to automation workflow diagram
• Explain permission requirements

Technical Details

GitHub Transfer API

Endpoint: POST /repos/{owner}/{repo}/transfer

Required Permissions:

• Admin access to source repository
• Permission to create repos in target org

Request Body:

{
  "new_owner": "worlddriven",
  "new_name": "repository-name"
}

What Transfers:
✅ Repository secrets and variables
✅ Webhooks
✅ Deploy keys
✅ Git history and contributions
✅ Issues, PRs, releases, projects
✅ Repository settings

What Doesn't Transfer:
❌ Organization-level secrets (stay with source org)
❌ GitHub App installations (need reconfiguration)

Authentication

Use existing WORLDDRIVEN_GITHUB_TOKEN (already has admin:org permissions)

• Same token powering current REPOSITORIES.md sync
• Has necessary permissions for transfer API

Workflow

1. PR Phase:

   • User adds repository with Origin: owner/repo to REPOSITORIES.md
   • Drift detection checks if worlddriven has admin permission on origin
   • PR comment shows: "✅ Ready to transfer" or "❌ Missing admin permission"

2. Merge Phase:

   • Sync automation calls transfer API
   • Repository transfers to worlddriven org
   • Standard configs applied automatically
   • Commit comment confirms successful transfer

3. Post-Transfer:

   • Origin owner can fork back if desired (manual process)
   • Permissions cleanup (if needed, manual or automated)

First Migration: TooAngel/worlddriven → worlddriven/core

The worlddriven core repository itself will be the first migration test case:

• Dogfooding the feature
• Demonstrates commitment to democratic governance
• Provides real-world testing
• High visibility for community

Implementation Checklist

• Add permission verification function
• Implement transfer API call
• Integrate transfer into sync plan
• Add comprehensive error handling
• Write unit tests
• Write integration tests
• Create MIGRATION.md
• Update AUTOMATION.md
• Test with non-critical repository
• Execute TooAngel/worlddriven migration
• Document lessons learned

References

• GitHub REST API - Transfer Repository
• Transferring a Repository
• What Happens During Transfer