Create universal installation script for Linux and macOS

[jbrinkman]

Overview

To provide an alternative installation method for users who cannot or prefer not to use package managers (Chocolatey/Homebrew), we should create a universal shell script that automatically downloads and installs the appropriate DotNetApiDiff binary from GitHub Releases for any Linux distribution or macOS system.

Goals

• Universal Compatibility: Single script that works across all Linux distributions and macOS
• Automatic Detection: Detect OS, architecture, and choose appropriate release binary
• Smart Installation: Install to appropriate directory based on user permissions and system conventions
• Version Management: Support installing specific versions or latest release
• Safe Installation: Verify checksums and handle installation failures gracefully

Scope

Script Features

• Auto-detect operating system (Linux distributions, macOS)
• Auto-detect CPU architecture (x64, ARM64, etc.)
• Download appropriate binary from GitHub Releases
• Verify download integrity (checksums/signatures)
• Install to appropriate directory with proper permissions
• Add installed location to PATH if needed
• Support version selection (latest, specific version, upgrade)
• Provide clear installation feedback and error messages

Installation Locations

The script should intelligently choose installation directories:

User Installation (no sudo required):

• ~/.local/bin/ (preferred for most Linux distributions)
• ~/bin/ (fallback for systems without ~/.local/bin)

System Installation (requires sudo):

• /usr/local/bin/ (standard location for user-installed binaries)
• /opt/dotnetapidiff/bin/ (alternative system location)

Supported Platforms

• Linux: All major distributions (Ubuntu, Debian, CentOS, RHEL, Fedora, Alpine, Arch, etc.)
• macOS: Intel and Apple Silicon Macs
• Architecture: x64, ARM64 (and others as needed)

Implementation Details

Script Name and Location

• File: install.sh
• Location: Repository root or scripts/ directory
• URL: https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh

Usage Examples

# Install latest version to user directory
curl -fsSL https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh | bash

# Install specific version
curl -fsSL https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh | bash -s -- v1.2.3

# Install to system directory (requires sudo)
curl -fsSL https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh | sudo bash -s -- --system

# Install with custom directory
curl -fsSL https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh | bash -s -- --prefix /custom/path

# Download script first (more secure)
wget https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh
chmod +x install.sh
./install.sh

Script Architecture Detection

# Detect OS
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $OS in
    linux*) OS="linux" ;;
    darwin*) OS="osx" ;;
    *) echo "Unsupported OS: $OS"; exit 1 ;;
esac

# Detect Architecture  
ARCH=$(uname -m)
case $ARCH in
    x86_64) ARCH="x64" ;;
    aarch64|arm64) ARCH="arm64" ;;
    *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
esac

Installation Logic

1. Detect Environment: OS, architecture, available directories
2. Choose Version: Latest release or user-specified version
3. Download Binary: From GitHub Releases with progress indicator
4. Verify Integrity: Check file size, checksums if available
5. Install Binary: Copy to appropriate directory with correct permissions
6. Update PATH: Add directory to PATH if not already present
7. Verify Installation: Test that dotnetapidiff --version works
8. Cleanup: Remove temporary files

Error Handling

• Network connectivity issues
• Invalid versions or missing releases
• Insufficient permissions
• Disk space problems
• Checksum verification failures
• PATH update failures

Security Considerations

• Verify SSL certificates for downloads
• Support checksum verification (SHA256)
• Avoid executing downloaded code without verification
• Clear error messages for security-related failures
• Optional: Support GPG signature verification

User Experience

Successful Installation Output

DotNetApiDiff Installer
=======================
Detected: Linux x64
Version: Latest (v1.2.3)
Download: ✓ dotnetapidiff-linux-x64-v1.2.3.tar.gz
Verify:   ✓ Checksum matches
Install:  ✓ Installed to ~/.local/bin/dotnetapidiff
PATH:     ✓ ~/.local/bin is in PATH

Installation complete! 
Run 'dotnetapidiff --version' to verify installation.

Script Options

Options:
  -v, --version <version>    Install specific version (default: latest)
  -p, --prefix <path>        Install to custom directory
  -s, --system              Install system-wide (requires sudo)
  -f, --force               Overwrite existing installation
  -h, --help                Show this help message
  --verify-checksum         Verify download checksums (default: enabled)
  --no-path-update          Don't modify PATH automatically

Testing Strategy

Test Matrix

• Linux Distributions: Ubuntu, Debian, CentOS, Alpine, Arch
• macOS Versions: Intel and Apple Silicon Macs
• Installation Types: User vs system installation
• Permission Scenarios: With and without sudo access
• Network Conditions: Slow connections, interrupted downloads
• Version Scenarios: Latest, specific versions, invalid versions

Integration with CI

• Add automated testing of install script in GitHub Actions
• Test script against multiple OS/architecture combinations
• Verify script works with actual GitHub Releases

Documentation

README.md Updates

Add installation section:

## Installation

### Quick Install (Linux/macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/jbrinkman/dotnet-api-diff/main/install.sh | bash

Manual Install

Download the latest release from GitHub Releases

### Complementary to Package Managers
This script provides an alternative to package manager installation (issue #44) for users who:
- Don't have package managers installed
- Need specific versions not yet in package repositories  
- Prefer manual control over installation process
- Work in environments where package managers are restricted

## Acceptance Criteria

- [ ] Single shell script works on all major Linux distributions
- [ ] Script works on both Intel and Apple Silicon Macs
- [ ] Automatically detects OS and architecture
- [ ] Downloads and installs appropriate binary from GitHub Releases
- [ ] Handles both user and system-wide installation
- [ ] Provides clear feedback and error messages
- [ ] Includes comprehensive error handling
- [ ] Updates PATH appropriately
- [ ] Includes help documentation and usage examples
- [ ] Tested across multiple platforms in CI
- [ ] Documentation updated with installation instructions

## Priority

**Medium** - Provides important alternative installation method that complements package manager approach.