# Tea CLI Installer - Advanced Version Management

## Enhanced Installation Strategy

The Tea CLI installer now implements sophisticated version management with user-specific installations:

### Installation Priority Order

1. **User Bin Directory** (`~/bin`) - Preferred
   - Checks if `~/bin` exists and is in PATH
   - Installs binaries with version-specific names
   - Creates symlinks for easy version switching
   - Allows multiple versions side-by-side

2. **System Installation** (`/usr/local/bin`) - Fallback
   - Used when user bin is not available
   - Requires sudo for system-wide installation
   - Single version installation

### Version Management Features

#### Symlink-Based Version Control
```bash
~/bin/
├── tea -> tea-v0.11.1    # Active version symlink
├── tea-v0.11.0           # Previous version
├── tea-v0.11.1           # Current version
└── tea-v0.12.0           # Future version (when available)
```

#### Automatic Updates
- Detects current version via symlink
- Downloads newer versions with version suffix
- Updates symlink to point to latest version
- Preserves old versions for rollback

### Installation Strategies

#### `user_install` - Fresh User Installation
- When Tea CLI not found in user bin
- Creates versioned binary and symlink
- No sudo required

#### `user_update` - User Version Update
- When newer version available
- Downloads new version with suffix
- Updates symlink to new version
- Keeps old versions

#### `user_upgrade` - User Upgrade (No Symlink)
- When existing binary found but no symlink
- Creates versioned structure
- Adds symlink management

#### `system_install` - System Installation
- When user bin not available/in PATH
- Installs to `/usr/local/bin`
- Requires sudo privileges

### Usage Examples

#### Normal Usage (Auto-detects strategy)
```bash
./install-tea-cli.sh
# Detects user bin, checks versions, updates if needed
```

#### Force Binary Installation
```bash
./install-tea-cli.sh --force --binary
# Forces binary download regardless of current version
```

#### Check Current Status
```bash
./install-tea-cli.sh
# Shows current version and installation type
# Exits if no update needed
```

### Version Detection Logic

1. **Check PATH**: Finds `tea` command location
2. **Installation Type**: Determines user vs system installation
3. **Symlink Check**: Detects version-specific symlinks
4. **Version Comparison**: Compares with latest release
5. **Strategy Selection**: Chooses appropriate installation method

### Benefits

✅ **User Isolation**: Installations don't affect other users  
✅ **Version Control**: Multiple versions can coexist  
✅ **Easy Updates**: Symlinks automatically point to latest  
✅ **Rollback Support**: Old versions preserved  
✅ **No Sudo Required**: User installations don't need root  
✅ **System Fallback**: Falls back to system installation when needed  

### Directory Structure

#### User Installation
```
~/bin/
├── tea -> tea-v0.11.1
├── tea-v0.11.0
└── tea-v0.11.1
```

#### System Installation
```
/usr/local/bin/
├── tea -> tea-v0.11.1
├── tea-v0.11.0
└── tea-v0.11.1
```

### PATH Requirements

For user installations, ensure `~/bin` is in PATH:
```bash
# Add to ~/.bashrc or ~/.profile
export PATH="$HOME/bin:$PATH"
```

### Troubleshooting

#### Version Not Updating
```bash
# Check current symlink
ls -la ~/bin/tea

# Force reinstall
./install-tea-cli.sh --force
```

#### PATH Issues
```bash
# Check if user bin is in PATH
echo $PATH | grep -q "$HOME/bin" && echo "OK" || echo "Add to PATH"

# Test tea command
which tea
tea --version
```

#### Permission Issues
```bash
# For system installation
sudo ./install-tea-cli.sh --binary
```

### Integration with Setup Script

The installer integrates seamlessly with the main setup script:
- Automatically called when Tea CLI is needed
- Respects user preferences for installation location
- Provides clear feedback on installation strategy
- Handles both new installations and updates