bytelyst-devops-tools/docs/remove_user_interactive.md

# Interactive User Removal Tool

## Overview

`remove_user_interactive.sh` is a comprehensive command-line tool designed to remove users from GitHub repositories with advanced pattern matching and interactive confirmation features. The tool supports both individual user repositories and organization-wide operations.

## Features

### 🎯 Core Functionality
- **Interactive User Input**: Guides users through token, user, and pattern collection
- **Multi-Level Repository Discovery**: Handles both root account and organization repositories
- **Wildcard Pattern Matching**: Supports complex repository patterns
- **Batch Operations**: Process multiple repositories efficiently
- **Rich Visual Feedback**: Color-coded logging with progress indicators

### 🔐 Security Features
- **Token Validation**: Verifies GitHub API access before operations
- **Interactive Confirmations**: Prevents accidental bulk operations
- **Permission Checks**: Validates repository access permissions
- **Error Handling**: Comprehensive error reporting and recovery

### 🎨 User Experience
- **Progress Tracking**: Real-time progress indicators
- **Flexible Confirmation System**: Multiple response options
- **Summary Reports**: Detailed operation statistics
- **Color-Coded Output**: Enhanced readability with emojis

## Usage

### Basic Execution
```bash
./remove_user_interactive.sh
```

### Interactive Flow
1. **Dependency Check**: Validates required tools (`curl`, `jq`)
2. **Authentication**: Collects and validates GitHub token
3. **Root User Input**: Specifies the root account/organization
4. **Target User**: Defines the user to remove
5. **Pattern Matching**: Sets repository selection criteria
6. **Repository Discovery**: Finds all matching repositories
7. **Confirmation**: Reviews and confirms the operation
8. **Batch Processing**: Removes user from selected repositories
9. **Summary Report**: Displays operation results

## Pattern Matching

The tool supports sophisticated wildcard patterns for repository selection:

### Pattern Examples
- `*-go-api*` - Matches any repository containing "-go-api"
- `frontend-*` - Matches repositories starting with "frontend-"
- `*-service` - Matches repositories ending with "-service"
- `web-*-app` - Matches repositories with "web-" prefix and "-app" suffix
- `exact-repo-name` - Matches specific repository name

### Pattern Behavior
- Patterns are case-sensitive
- Wildcards (`*`) match any sequence of characters
- Patterns apply to repository names, not full paths
- Multiple patterns can be combined using shell globbing

## Interactive Confirmation System

During the removal process, users have multiple response options:

### Confirmation Options
- **`[y]es`** - Remove user from current repository
- **`[n]o`** - Skip current repository
- **`[a]ll yes`** - Remove user from all remaining repositories
- **`[s]kip all`** - Skip all remaining repositories
- **`[q]uit`** - Cancel entire operation

### Confirmation Modes
- **`ask`** - Default mode, prompts for each repository
- **`yes_all`** - Automatically confirm all operations
- **`no_all`** - Automatically skip all operations

## Repository Discovery

The tool performs comprehensive repository discovery:

### Discovery Process
1. **Root User Repositories**: Fetches all repositories owned by the root user
2. **Organization Discovery**: Identifies organizations the root user belongs to
3. **Organization Repositories**: Fetches repositories from each organization
4. **Pattern Filtering**: Applies wildcard patterns to repository names
5. **Deduplication**: Removes duplicate repositories from the final list

### API Endpoints Used
- `GET /users/{user}/repos` - User repositories
- `GET /users/{user}/orgs` - User organizations
- `GET /orgs/{org}/repos` - Organization repositories
- `DELETE /repos/{owner}/{repo}/collaborators/{username}` - Remove collaborator

## Error Handling

The tool includes comprehensive error handling:

### HTTP Status Codes
- **`204`** - Successful removal
- **`404`** - User not found or not a collaborator
- **`403`** - Insufficient permissions
- **`401`** - Invalid authentication

### Error Recovery
- **Network Failures**: Retry mechanisms for API calls
- **Rate Limiting**: Respects GitHub API rate limits
- **Permission Errors**: Clear error messages and suggestions
- **Invalid Input**: Input validation and correction prompts

## Logging and Output

### Log Levels
- **Info** (ℹ️): General information messages
- **Success** (✅): Successful operations
- **Warning** (⚠️): Non-critical issues
- **Error** (❌): Critical failures
- **Progress** (🔄): Operation progress updates

### Output Format
```
[EMOJI] [TIMESTAMP] [LEVEL] Message
```

### Summary Report
```
Operation Summary
=================
Total repositories processed: 15
Successful removals: 12
Failed removals: 1
Skipped removals: 2
Success rate: 80%
```

## Prerequisites

### Required Tools
- `curl` - HTTP client for API requests
- `jq` - JSON processor for API responses

### GitHub Token Permissions
- `repo` - Repository access (read/write)
- `admin:org` - Organization administration

### Environment Requirements
- Bash 4.0 or higher
- Internet connectivity for GitHub API access
- Valid GitHub Personal Access Token

## Security Considerations

### Token Security
- Tokens are not stored or logged
- Input is hidden during token entry
- Tokens are validated before use

### Operation Safety
- Interactive confirmations prevent accidental operations
- Detailed logging for audit trails
- Rollback information provided for manual recovery

### Access Control
- Respects GitHub repository permissions
- Validates user access before operations
- Handles permission errors gracefully

## Troubleshooting

### Common Issues
1. **Token Validation Fails**: Ensure token has correct permissions
2. **Repository Not Found**: Check repository name and access permissions
3. **User Not Found**: Verify username spelling and existence
4. **Rate Limiting**: Wait for rate limit reset or use token with higher limits

### Debug Mode
Enable verbose output by setting:
```bash
export DEBUG=1
./remove_user_interactive.sh
```

## Integration

The tool integrates seamlessly with other ByteLyst DevOps tools:
- Can be called from `bytelyst-cli.sh`
- Supports JSON configuration files
- Compatible with existing workflow scripts
- Follows established logging and error handling patterns

## Performance

### Optimization Features
- Paginated API requests for large datasets
- Parallel processing where possible
- Efficient pattern matching algorithms
- Minimal memory footprint

### Scale Considerations
- Handles hundreds of repositories efficiently
- Respects GitHub API rate limits
- Provides progress feedback for long operations
- Supports interruption and resumption