Phase 2: Automatic Update Implementation

Implement the complete automatic update functionality for the CLI tool, building on top of Phase 1 infrastructure. The implementation must be safe, reliable, and include proper rollback mechanisms.

Requirements

1. Download Module (src/update/download.rs)

• Download binary files from GitHub releases with progress reporting
• Download and parse SHA256SUMS.txt file
• Support resumable downloads (if connection is interrupted)
• Proper error handling for network failures
• Display progress bar or percentage during download

2. Checksum Verification Module (src/update/checksum.rs)

• Parse SHA256SUMS.txt format (standard format: <hash> <filename>)
• Calculate SHA256 hash of downloaded binary
• Verify downloaded binary matches published checksum
• Clear error messages if verification fails

3. Safe Installation Module (src/update/installer.rs)

• CRITICAL SAFETY REQUIREMENTS:
  • Create backup of current binary before any modifications (.bak extension)
  • Use atomic file operations where possible (rename vs copy)
  • Handle platform-specific concerns:
    • Unix/Linux/macOS: Preserve executable permissions, handle running binary replacement
    • Windows: Handle file locking issues (running .exe cannot be replaced directly)
  • Rollback on failure: If update fails at ANY step, automatically restore from backup
  • Cleanup on success: Delete backup file ONLY after successful update and verification
  • Verify the new binary is actually executable after installation
  • Optional: Spawn new binary to verify it works before committing the update

4. Update Error Types

Add new error variants to src/update/error.rs:

• DownloadFailed
• ChecksumMismatch
• ChecksumFileNotFound
• InstallationFailed
• BackupFailed
• RollbackFailed
• PermissionDenied

5. Integration with Existing Code

• Extend src/update/mod.rs to add pub async fn perform_update(release: Release) -> Result<(), UpdateError>
• Update the Commands::Update handler in src/main.rs to actually perform the update (not just check)
• Add confirmation prompt before downloading (show download size)
• Add --force flag to skip confirmation
• Show clear messages at each step (downloading, verifying, installing, cleaning up)

6. Safety & Rollback Logic

// Pseudo-code of the safety flow:
// 1. Create backup: current_binary -> current_binary.bak
// 2. Download new binary to temp location
// 3. Verify checksum of downloaded binary
// 4. If checksum OK:
//    - Replace current binary with new binary (atomic if possible)
//    - Test that new binary is executable
//    - If test OK: delete backup
//    - If test FAILS: rollback from backup, return error
// 5. If checksum FAILS or any error:
//    - Delete downloaded temp file
//    - Keep backup intact
//    - Return error (no changes made)
// 6. If installation fails:
//    - Restore from backup immediately
//    - Return error with rollback message

7. Platform-Specific Handling

Unix/Linux/macOS:

• Use std::fs::rename() for atomic replacement when possible
• Preserve chmod +x permissions (0o755)
• Handle the case where the binary is currently running (may need to replace on next launch)

Windows:

• Running .exe files are locked and cannot be replaced
• Use self-replace techniques:
  • Rename current binary to .bak
  • Write new binary with original name
  • Schedule .bak deletion on next run or after successful restart
• Alternatively, guide user to restart the application after download completes

8. Testing Requirements

• Add unit tests for checksum parsing and verification
• Add unit tests for backup/rollback logic (use temp directories)
• Add integration test that simulates:
  • Successful update flow
  • Failed checksum verification (rollback triggered)
  • Failed installation (rollback triggered)
• Test on all supported platforms in CI

9. User Experience

When user runs zy update:

Checking for updates on Stable channel...
Current version: 1.0.2
Latest version: 1.0.3 available!

Download size: 8.5 MB
Proceed with update? [y/N]: y

[1/4] Downloading binary... ████████████████████ 100% (8.5 MB)
[2/4] Verifying checksum... ✓
[3/4] Installing update... ✓
[4/4] Cleaning up... ✓

Successfully updated to version 1.0.3!
Please restart the CLI or run 'zy --version' to confirm.

If update fails:

[1/4] Downloading binary... ████████████████████ 100% (8.5 MB)
[2/4] Verifying checksum... ✗ FAILED
Error: Checksum mismatch! 
  Expected: abc123...
  Got:      def456...

Update cancelled. Your current version (1.0.2) is unchanged.

10. Dependencies

Add to Cargo.toml if needed:

• sha2 - for SHA256 hashing (likely already in dependencies)
• indicatif - for progress bars (optional, can use simple percentage)
• tempfile - for safe temporary file handling

11. Documentation

• Update README.md with automatic update instructions...