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

### 2. Store Token Securely

Choose one of these methods:

**Option A: Environment Variable (Simplest)**
```powershell
# Windows PowerShell
$env:FORGEJO_TOKEN = "your_token_here"
```

**Option B: Credential Manager (Windows - Most Secure)**
```powershell
.\build\scripts\upload_to_packages.ps1 -SaveToken -ForgejoToken "your_token_here"
# Token is encrypted and stored for future use
```

**Option C: Config File**
```bash
# macOS/Linux - Save to home directory
bash build/scripts/upload_to_packages.sh --save-token -t "your_token_here"
# Saved to ~/.config/webdrop-bridge/.env (chmod 600)
```

**Option D: Project .env (Development Only)**
Create `.env` in project root and add to `.gitignore`:
```
FORGEJO_TOKEN=your_token_here
```

### 3. 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

After storing your token (see Setup Requirements above), uploading is simple:

**Windows Upload:**
```powershell
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0
```

**macOS Upload:**
```bash
bash build/scripts/upload_to_packages.sh -v 1.0.0
```

The scripts will automatically find your token from:
1. `-ForgejoToken` / `-t` parameter (if provided)
2. `$env:FORGEJO_TOKEN` / `$FORGEJO_TOKEN` environment variable
3. Windows Credential Manager / `~/.config/webdrop-bridge/.env`
4. Project `.env` file

### 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`)

**Basic Usage:**
```powershell
# After storing token (see Setup Requirements)
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0
```

**First time setup - Save token to Credential Manager:**
```powershell
.\build\scripts\upload_to_packages.ps1 -SaveToken -ForgejoToken "your_token"
# Then future uploads just need version
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0
```

**Parameters:**
- `-Version` - Version number (required, e.g., "1.0.0")
- `-ForgejoToken` - Personal access token (optional if stored)
- `-SaveToken` - Save token to Credential Manager
- `-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

**Script flow:**
1. Check for token in: parameter → environment → Credential Manager
2. Verify exe and checksum files exist
3. Upload exe to Packages API
4. Upload checksum to Packages API
5. Show success message with package URL

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

**Basic Usage:**
```bash
# After storing token (see Setup Requirements)
bash build/scripts/upload_to_packages.sh -v 1.0.0
```

**First time setup - Save token to config:**
```bash
bash build/scripts/upload_to_packages.sh --save-token -t "your_token"
# Then future uploads just need version
bash build/scripts/upload_to_packages.sh -v 1.0.0
```

**Options:**
- `-v, --version` - Version number (required, e.g., "1.0.0")
- `-t, --token` - Personal access token (optional if stored)
- `--save-token` - Save token to ~/.config/webdrop-bridge/.env
- `-u, --url` - Forgejo server URL (default: https://git.him-tools.de)

**Script flow:**
1. Check for token in: parameter → environment → ~/.config/webdrop-bridge/.env → project .env
2. Verify dmg and checksum files exist
3. Upload dmg to Packages API
4. Upload checksum to Packages API
5. Show success message with package URL

### Token Resolution Order

Both scripts check for tokens in this priority:
1. **Parameter**: `-ForgejoToken "token"` (PowerShell) or `-t "token"` (Bash)
2. **Environment**: `$env:FORGEJO_TOKEN` (PowerShell) or `$FORGEJO_TOKEN` (Bash)
3. **Stored Config**:
   - Windows: Credential Manager (via `-SaveToken` flag)
   - macOS/Linux: `~/.config/webdrop-bridge/.env`
4. **Project File**: `.env` in project root (if exists)

This design matches how git handles credentials!

## 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