gh-legacy/README.md

A powerful GitHub CLI tool for automatic repository ownership transfer to trusted beneficiaries after periods of inactivity

# gh-legacy

A powerful GitHub CLI tool for automatic repository ownership transfer to trusted beneficiaries after periods of inactivity.

[![npm version](https://badge.fury.io/js/gh-legacy.svg)](https://badge.fury.io/js/gh-legacy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Features

- **Automatic Repository Transfer**: Seamlessly transfer repository ownership to trusted users
- **Flexible Inactivity Periods**: Support for minutes, hours, days, weeks, months, and years
- **Secure Token Management**: Encrypted GitHub token storage with AES-256-CBC
- **Email Notifications**: Automated HTML email notifications with detailed instructions
- **Heartbeat System**: Reset inactivity timers with simple heartbeat commands
- **Status Tracking**: Comprehensive monitoring of all beneficiaries and transfer status
- **Automated Scheduling**: Set up automated access checking with cron jobs or task schedulers

## 📦 Installation

```bash
npm install -g gh-legacy
```

## 🔧 Quick Setup

### 1. Initialize the System
```bash
gh-legacy init
```

### 2. Configure GitHub Token
```bash
gh-legacy token
```

### 3. Add Beneficiaries
```bash
gh-legacy add-beneficiary <owner/repo> <email> <github-username> "<time-period>"
```

## 📖 Usage

### Basic Commands

```bash
# Initialize the system
gh-legacy init

# Add a beneficiary (transfer after 6 months of inactivity)
gh-legacy add-beneficiary myusername/myproject user@email.com newowner "6 months"

# Send a heartbeat (reset inactivity timer)
gh-legacy heartbeat

# Check status of all beneficiaries
gh-legacy status

# Trigger access transfers manually
gh-legacy trigger-access

# Automatic trigger (for scheduling)
gh-legacy auto-trigger
```

### Time Periods Supported

| Unit | Examples |
|------|----------|
| Minutes | `"5 minutes"`, `"30 minutes"` |
| Hours | `"2 hours"`, `"12 hours"` |
| Days | `"7 days"`, `"30 days"` |
| Weeks | `"2 weeks"`, `"4 weeks"` |
| Months | `"3 months"`, `"6 months"` |
| Years | `"1 year"`, `"2 years"` |

## 🤖 Automation

### Windows Task Scheduler
```batch
# Create a scheduled task to run daily at 9 AM
schtasks /create /tn "GH-Legacy Auto Trigger" /tr "C:\path\to\gh-legacy\run-auto-trigger.bat" /sc daily /st 09:00
```

### Linux/Mac Cron Job
```bash
# Add to crontab (check daily at 9 AM)
0 9 * * * cd /path/to/gh-legacy && gh-legacy auto-trigger
```

### PowerShell Scheduled Task
```powershell
$action = New-ScheduledTaskAction -Execute "gh-legacy" -Argument "auto-trigger"
$trigger = New-ScheduledTaskTrigger -Daily -At 9AM
Register-ScheduledTask -TaskName "GH-Legacy Auto Trigger" -Action $action -Trigger $trigger
```

## 🔐 Security Features

- **Encrypted Token Storage**: GitHub tokens encrypted with AES-256-CBC
- **Environment Variables**: Email credentials stored securely
- **No Plain Text**: All sensitive data encrypted at rest
- **Permission Validation**: Ensures proper GitHub permissions before operations

## 📧 Email Notifications

Beneficiaries receive detailed HTML emails containing:
- Repository information and access details
- Step-by-step ownership transfer instructions
- Security considerations and best practices
- Contact information for support

## 🔄 How It Works

1. **Setup Phase**: Add trusted beneficiaries with their GitHub usernames and desired inactivity periods
2. **Monitoring Phase**: System tracks your last heartbeat (activity signal)
3. **Transfer Phase**: When inactivity threshold is reached, ownership transfer is initiated
4. **Notification Phase**: Beneficiaries receive detailed email notifications with transfer instructions

## 📋 Example Workflow

```bash
# 1. Install and initialize
npm install -g gh-legacy
gh-legacy init

# 2. Configure GitHub token
# Run the following command and enter your token when prompted:
gh-legacy token

# 3. Add trusted colleague as beneficiary
gh-legacy add-beneficiary myusername/important-project colleague@company.com colleague-username "6 months"

# 4. Send regular heartbeats
gh-legacy heartbeat

# 5. Monitor status
gh-legacy status

# 6. Set up automation (optional)
# Schedule gh-legacy auto-trigger to run daily

# 7. Automatic transfer occurs after 6 months of inactivity
```

## 🗃️ Transferred Repositories Archive

- When a repository is successfully transferred (ownership or admin access), it is removed from the main configuration and archived in a separate `transferred.json` file in your `.gh-legacy` directory.
- This archive includes the transfer status, timestamp, and a message log for each repo.
- You can view your transfer history and details by opening `~/.gh-legacy/transferred.json`.

## ⚙️ Configuration

### GitHub Token Setup
1. Generate a token at https://github.com/settings/tokens
2. Ensure it has `repo` permissions
3. Run `gh-legacy token` and enter your token when prompted

### Email Notifications (Optional)
```bash
export GMAIL_USER="your-email@gmail.com"
export GMAIL_PASS="your-app-password"
```

## 🚨 Important Notes

- **GitHub Permissions**: Your token needs repository admin permissions
- **Ownership Transfer**: May require manual approval in some cases
- **Regular Heartbeats**: Send heartbeats regularly to prevent unwanted transfers
- **Backup Strategy**: Consider backing up your configuration regularly

## 🔧 Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| "Could not transfer ownership" | GitHub requires manual approval. Beneficiary can request transfer manually |
| "Failed to send email" | Check Gmail credentials and app password setup |
| "No configuration found" | Run `gh-legacy init` first |
| "Token not found" | Run `gh-legacy token` and enter your token |

### Debug Commands

```bash
# Check current status
gh-legacy status

# Force trigger access (with confirmation)
gh-legacy trigger-access

# Automatic trigger (no confirmation)
gh-legacy auto-trigger

# List all beneficiaries
gh-legacy list

# Resend emails with updated template
gh-legacy resend-email
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Octokit](https://github.com/octokit/octokit.js) for GitHub API integration
- Uses [Commander.js](https://github.com/tj/commander.js) for CLI functionality
- Email notifications powered by [Nodemailer](https://nodemailer.com/)

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/dtechoracle/gh-legacy/issues)
- **Documentation**: [GitHub Wiki](https://github.com/dtechoracle/gh-legacy/wiki)
- **Email**: iamezekieljeremiah@gmail.com

---

**Made with ❤️ for the GitHub community**