webdrop-bridge/FORGEJO_PACKAGES_SETUP.md

# Forgejo Packages Distribution Guide

This guide explains how to distribute WebDrop Bridge builds using **Forgejo Packages** instead of runners.

## Overview

**Forgejo Packages** is a package repository system that lets you upload and distribute binaries. It's simpler than setting up CI/CD runners and works perfectly for manual releases.

```
1. Build locally (Windows & macOS)
2. Upload exe + dmg to Forgejo Packages
3. UpdateManager downloads from Packages
4. Users verify with SHA256 checksums
```

## Setup Requirements

### 1. Forgejo Personal Access Token

Create a token with package write permissions:

1. Go to: https://git.him-tools.de/user/settings/applications
2. Click "Generate New Token"
3. Name: `BUILD_UPLOAD_TOKEN`
4. Scopes: Check `write:package`, `api`
5. Click "Generate Token"
6. Copy the token (you'll use it for uploads)

**Store securely** - this token grants upload access!

### 2. Build Scripts

Upload scripts are already created:
- Windows: `build/scripts/upload_to_packages.ps1`
- macOS: `build/scripts/upload_to_packages.sh`

## Release Workflow

### Step 1: Build Executables

**On Windows:**
```powershell
cd C:\Development\VS Code Projects\webdrop_bridge
python build/scripts/build_windows.py
# Output: build/dist/windows/WebDropBridge.exe
#         build/dist/windows/WebDropBridge.exe.sha256
```

**On macOS:**
```bash
cd ~/webdrop_bridge
bash build/scripts/build_macos.sh
# Output: build/dist/macos/WebDropBridge.dmg
#         build/dist/macos/WebDropBridge.dmg.sha256
```

### Step 2: Upload to Packages

**Windows Upload:**
```powershell
$token = "your_token_from_settings"
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token
```

**macOS Upload:**
```bash
token="your_token_from_settings"
bash build/scripts/upload_to_packages.sh -v 1.0.0 -t $token
```

### Step 3: Tag and Commit

Once both are uploaded:
```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push upstream v1.0.0
```

## Forgejo Packages API

### Package Structure

```
https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages
```

### Get Latest Version

```bash
curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages
```

Response:
```json
[
  {
    "id": 123,
    "name": "webdrop-bridge",
    "version": "1.0.0",
    "created_at": "2026-01-28T...",
    "files": [
      {
        "name": "WebDropBridge.exe",
        "size": 204840960,
        "file_name": "WebDropBridge.exe",
        "id": 456
      },
      {
        "name": "WebDropBridge.exe.sha256",
        "size": 65,
        "file_name": "WebDropBridge.exe.sha256",
        "id": 457
      }
    ]
  }
]
```

### Download URL

```
https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe
```

### Direct Package Page

```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

## UpdateManager Integration (Phase 4.1)

The auto-update system will query the Packages API:

```python
async def check_for_updates(self) -> Optional[UpdateInfo]:
    """Query Forgejo Packages for new version."""
    url = "https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages"
    response = await session.get(url)
    packages = response.json()
    
    # Get latest package
    latest = packages[0]  # Sorted by date
    latest_version = latest['version']
    
    # Compare versions
    if parse_version(latest_version) > parse_version(self.current_version):
        return UpdateInfo(
            version=latest_version,
            download_url=f".../{latest_version}/WebDropBridge.exe",
            checksum_url=f".../{latest_version}/WebDropBridge.exe.sha256"
        )
    
    return None
```

## Upload Script Details

### Windows Script (`upload_to_packages.ps1`)

```powershell
Usage: .\upload_to_packages.ps1 -Version 1.0.0 -ForgejoToken $token

Parameters:
  -Version          Version number (required, e.g., "1.0.0")
  -ForgejoToken     Personal access token (required)
  -ForgejoUrl       Forgejo server URL (default: https://git.him-tools.de)
  -Repo             Repository (default: HIM-public/webdrop-bridge)
  -ExePath          Path to exe file (default: build\dist\windows\WebDropBridge.exe)
  -ChecksumPath     Path to checksum file

What it does:
  1. Verifies exe and checksum files exist
  2. Uploads exe to Packages
  3. Uploads checksum to Packages
  4. Shows success/error messages
```

### macOS Script (`upload_to_packages.sh`)

```bash
Usage: ./upload_to_packages.sh -v 1.0.0 -t $token

Options:
  -v, --version     Version number (required)
  -t, --token       Personal access token (required)
  -u, --url         Forgejo server URL (default: https://git.him-tools.de)

What it does:
  1. Verifies dmg and checksum files exist
  2. Uploads dmg to Packages
  3. Uploads checksum to Packages
  4. Shows success/error messages
```

## Complete Release Checklist

```
[ ] Update version in src/webdrop_bridge/config.py
[ ] Update CHANGELOG.md with release notes
[ ] Build Windows executable
[ ] Verify WebDropBridge.exe exists
[ ] Verify WebDropBridge.exe.sha256 exists
[ ] Build macOS DMG
[ ] Verify WebDropBridge.dmg exists
[ ] Verify WebDropBridge.dmg.sha256 exists
[ ] Upload Windows to Packages
[ ] Upload macOS to Packages
[ ] Verify both on Packages page
[ ] Create git tag: git tag -a v1.0.0
[ ] Push tag: git push upstream v1.0.0
[ ] Announce release
```

## Troubleshooting

### Upload fails with "401 Unauthorized"

- Verify token is correct
- Check token has `write:package` scope
- Token may have expired - create new one

### Upload fails with "404 Not Found"

- Verify repository name is correct (`HIM-public/webdrop-bridge`)
- Verify version format (e.g., `1.0.0`, not `v1.0.0`)

### Checksum verification fails

- Regenerate checksums:
  ```powershell
  # Windows
  $file = "build\dist\windows\WebDropBridge.exe"
  $hash = (Get-FileHash -Path $file -Algorithm SHA256).Hash
  $hash | Out-File -FilePath "${file}.sha256" -NoNewline
  ```
  
  ```bash
  # macOS
  shasum -a 256 build/dist/macos/WebDropBridge.dmg > build/dist/macos/WebDropBridge.dmg.sha256
  ```

- Upload again

### Where are my packages?

View all uploads at:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

Each version shows:
- Files (exe/dmg + checksums)
- Upload date
- Download links

## Manual Download

Users can download directly:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe
https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.dmg
```

Or via Packages page UI:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

## Benefits of Packages

✅ **Simple**: No CI/CD runners needed  
✅ **Flexible**: Build when you want  
✅ **Reliable**: Forgejo handles storage  
✅ **Secure**: Token-based auth  
✅ **Integrated**: UpdateManager ready  
✅ **Free**: Built-in to Forgejo  

---

**Status**: Ready to use  
**Last Updated**: January 2026