webdrop-bridge/build/scripts/README.md

# Build Scripts

Automation scripts for building, releasing, and downloading WebDrop Bridge.

## Scripts Overview

| Script | Purpose | OS |
|--------|---------|-----|
| `download_release.ps1` | Download installer from Forgejo via wget | Windows |
| `download_release.sh` | Download installer from Forgejo via wget | macOS/Linux |
| `build_windows.py` | Build Windows MSI installer | Windows |
| `build_macos.sh` | Build macOS DMG installer | macOS |
| `create_release.ps1` | Create GitHub/Forgejo release | Windows |
| `create_release.sh` | Create GitHub/Forgejo release | macOS/Linux |
| `sync_remotes.ps1` | Sync git remotes | Windows |
| `sync_version.py` | Manage version synchronization | All |

## Download Scripts

### Purpose

The `download_release.ps1` (Windows) and `download_release.sh` (macOS/Linux) scripts download pre-built WebDrop Bridge installers from the Forgejo repository using **wget**. This is the recommended way to:

- **Initial Installation**: First-time users can bootstrap without building from source
- **Enterprise Deployments**: Automated setup scripts in larger organizations  
- **Offline/Air-Gapped Systems**: Download on one machine, transfer to another
- **Proxy Environments**: Works with corporate proxies (via wget)
- **CI/CD Automation**: Internal deployment pipelines
- **Command-Line Preference**: Admins who prefer CLI tools over GUIs

### Features

✅ **Automatic platform detection** - Prefers .dmg on macOS, .msi on Windows
✅ **SHA256 checksum verification** - Ensures integrity of downloaded files
✅ **Progress indication** - Shows download progress with wget
✅ **Error handling** - Clear error messages for common issues
✅ **Version selection** - Download specific releases or latest
✅ **Offline-friendly** - Works in environments with limited connectivity

### Prerequisites

- **wget** (required)
  - Windows: `choco install wget` or `winget install GNU.Wget`
  - macOS: `brew install wget`
  - Linux: `apt-get install wget` (Ubuntu/Debian) or equivalent

### Direct wget Commands (No Script Needed)

**Simplest: If you know the version**

```bash
# Download directly by version tag
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
```

**If you need to auto-detect latest (with grep/cut, no jq needed)**

```bash
# Get latest release and download MSI/DMG
wget -qO- https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest | \
  grep -o '"browser_download_url":"[^"]*\.\(msi\|dmg\)"' | head -1 | cut -d'"' -f4 | \
  xargs wget -O installer.msi
```

**With checksum verification**

```bash
# Download installer and checksum
INSTALLER=$(wget -qO- https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest | \
  grep -o '"browser_download_url":"[^"]*\.\(msi\|dmg\)"' | head -1 | cut -d'"' -f4)

wget -O installer.msi "$INSTALLER"
wget -O installer.sha256 "${INSTALLER}.sha256"

# Verify (macOS: shasum -a 256 -c installer.sha256)
sha256sum -c installer.sha256
```

### Script-Based Usage (Recommended for Automation)

#### Windows PowerShell

```powershell
# Latest release to current directory
.\download_release.ps1

# Specific version to Downloads folder
.\download_release.ps1 -Version "0.8.0" -OutputDir "$env:USERPROFILE\Downloads"

# Skip checksum verification
.\download_release.ps1 -Verify $false
```

#### macOS / Linux Bash

```bash
# Latest release
./build/scripts/download_release.sh

# Specific version to Downloads
./build/scripts/download_release.sh 0.8.0 ~/Downloads

# Skip checksum verification
./build/scripts/download_release.sh latest --no-verify
```

## Build Scripts

### build_windows.py
Builds Windows MSI installer using PyInstaller and WIX toolset.

```bash
python build/scripts/build_windows.py --msi
```

### build_macos.sh
Builds macOS DMG installer with code signing and notarization.

```bash
bash build/scripts/build_macos.sh
```

## Release Scripts

### create_release.ps1 / create_release.sh
Automated release creation with versioning and asset uploads.

```bash
# Windows
.\build\scripts\create_release.ps1

# macOS/Linux
./build/scripts/create_release.sh
```

## Version Management

### sync_version.py
Manages consistent versioning across the project.

```bash
python build/scripts/sync_version.py --version 0.8.0
```

## Integration Flow

```
download_release.ps1/sh
    ↓
Fetches release from Forgejo API
    ↓
Downloads installer (.msi or .dmg)
    ↓
Verifies SHA256 checksum
    ↓
Installer ready for execution
    ↓
(Application auto-update handles future updates)
```

## Testing Scripts Locally

```bash
# Test download script (dry-run)
.\build\scripts\download_release.ps1 -Version "0.7.1"

# Test with different output directory
.\build\scripts\download_release.ps1 -OutputDir ".\test_download"
```

## Troubleshooting

### wget not found
- **Windows**: Install via `winget install GNU.Wget` or Chocolatey
- **macOS**: `brew install wget`
- **Linux**: `apt-get install wget` (or equivalent)

### Checksum verification failed
- File may be corrupted in transit
- Retry download: `.\download_release.ps1 -Verify $false` then manually verify
- Report issue with download URL and Forgejo release info

### Network timeouts
- Check connectivity to `https://git.him-tools.de`
- May indicate temporary Forgejo API unavailability
- Retry after a few minutes

### Permission denied (macOS/Linux)
```bash
chmod +x build/scripts/download_release.sh
chmod +x build/scripts/build_macos.sh
```

---

For user-facing documentation, see [QUICKSTART.md](../../QUICKSTART.md) and [README.md](../../README.md)