learning_ai_common_plat/AI.dev/SKILLS/desktop-release.md

# Desktop Release Skill

**Description**: Build and release cross-platform desktop applications (macOS, Windows, Linux).

## When to Use

- Preparing for public release
- Creating distributable packages
- Setting up CI/CD for desktop builds
- Code signing and notarization for distribution

## Prerequisites

### macOS Setup

```bash
# Install system tools
xcode-select --install                          # Xcode Command Line Tools
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  # Homebrew
brew install python@3.13 portaudio              # Python + audio lib for PyAudio
```

### Project Setup

```bash
git clone https://github.com/your-org/your-repo.git
cd your-repo
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Azure Credentials

```bash
cp .env ~/.lysnrai/.env     # Create config dir + env file
```

Edit `~/.lysnrai/.env` with real values:

- `AZURE_SPEECH_KEY` - Azure Portal → Speech Service → Keys
- `AZURE_SPEECH_REGION` - e.g. `eastus`
- `AZURE_OPENAI_ENDPOINT` - Azure Portal → OpenAI → Endpoint
- `AZURE_OPENAI_KEY` - Azure Portal → OpenAI → Keys
- `AZURE_OPENAI_DEPLOYMENT` - e.g. `gpt-4o-mini`

## macOS Build and Release

### Step 1 - Build the .app Bundle

```bash
# From project root
bash scripts/build.sh
```

**Output**: `dist/LysnrAI.app` (ad-hoc signed, ready for local use)

### Step 2 - Optional Code Signing and Notarization

#### Set up Apple Developer Account

1. Create "Developer ID Application" certificate:
   - Go to [developer.apple.com/account/resources/certificates](https://developer.apple.com/account/resources/certificates/list)
   - Click **+** → select **Developer ID Application**
   - Create CSR: Keychain Access → Certificate Assistant → Request a Certificate
   - Upload CSR → download `.cer` → install in Keychain
   - Verify: `security find-identity -v -p codesigning | grep "Developer ID"`

2. Generate app-specific password:
   - Go to [appleid.apple.com](https://appleid.apple.com)
   - Sign-In and Security → App-Specific Passwords
   - Generate new password, label "App Notarization"

#### Code Sign and Notarize

```bash
export APPLE_DEVELOPER_ID="Developer ID Application: Your Name (TEAM_ID)"
bash scripts/codesign_macos.sh dist/LysnrAI.app
```

The script prompts for:

- Apple ID (default: your@email.com)
- Team ID (default: from certificate)
- App-specific password (secure input, not stored)

### Step 3 - Install Locally

```bash
bash scripts/install_macos.sh
```

Installs to `/Applications/LysnrAI.app`, creates config, and adds desktop launcher.

### Step 4 - Package for Distribution

```bash
# Create DMG installer
bash scripts/create_dmg.sh dist/LysnrAI.app

# Output: dist/LysnrAI-1.0.0.dmg (ready for distribution)
```

## Windows Build

### Prerequisites

```bash
# On Windows or via GitHub Actions
# Install Visual Studio Build Tools
# Install WiX Toolset for MSI creation
```

### Build Process

```bash
# Activate virtual environment
.venv\Scripts\activate

# Build executable
python scripts/build_windows.py

# Create installer
python scripts/create_installer.py
```

**Output**:

- `dist/LysnrAI.exe` - Portable executable
- `dist/LysnrAI-Setup-1.0.0.msi` - Windows installer

## Linux Build

### Prerequisites

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev python3-pyqt5 python3-venv

# For AppImage
sudo apt-get install appimagetool
```

### Build Process

```bash
# Build executable
python scripts/build_linux.py

# Create AppImage
python scripts/create_appimage.py
```

**Output**: `dist/LysnrAI.AppImage` - Portable Linux app

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Build Desktop App
on: [push, release]

jobs:
  build-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.13'
      - name: Build and sign
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
        run: |
          bash scripts/build.sh
          bash scripts/codesign_macos.sh dist/LysnrAI.app          
      - name: Create DMG
        run: bash scripts/create_dmg.sh dist/LysnrAI.app
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: macos-build
          path: dist/*.dmg
```

## Code Signing Best Practices

### macOS

```bash
# Verify signing
codesign -dv --verbose=4 dist/LysnrAI.app

# Verify notarization (after upload)
xcrun altool --notarization-info <request-uuid> -u your@email.com -p @keychain:AC_PASSWORD

# Staple notarization
xcrun stapler staple dist/LysnrAI.app
```

### Windows

```bash
# Sign with certificate (if you have one)
signtool sign /f certificate.p12 /p password /t http://timestamp.digicert.com dist/LysnrAI.exe
```

## Distribution Checklist

### Before Release

- [ ] All tests pass locally
- [ ] Version number updated in all places
- [ ] Release notes prepared
- [ ] Dependencies audited for security
- [ ] EULA/license included

### After Build

- [ ] Test installation on clean machine
- [ ] Verify auto-update works
- [ ] Test all major features
- [ ] Check file size is reasonable
- [ ] Virus scan executables

### Release Assets

| Platform | File        | Description           |
| -------- | ----------- | --------------------- |
| macOS    | `.dmg`      | Disk image installer  |
| Windows  | `.msi`      | Windows installer     |
| Windows  | `.zip`      | Portable version      |
| Linux    | `.AppImage` | Portable Linux app    |
| Linux    | `.deb`      | Debian/Ubuntu package |
| Linux    | `.rpm`      | RedHat/Fedora package |

## Common Issues

### Build Failures

1. **Missing dependencies**: Check `requirements.txt` and system packages
2. **Python version mismatch**: Use exactly Python 3.13
3. **Audio library issues**: Install portaudio (macOS) or appropriate Windows equivalent

### Code Signing Issues

1. **Certificate expired**: Renew from Apple Developer portal
2. **Team ID mismatch**: Verify in certificate and script
3. **Notarization pending**: Wait 5-15 minutes for Apple processing

### Platform-Specific Issues

- **macOS**: "App is damaged" - run `xattr -cr LysnrAI.app`
- **Windows**: "DLL not found" - install Visual C++ redistributable
- **Linux**: Permission denied - run `chmod +x LysnrAI.AppImage`

## Version Management

```bash
# Update version in all places
# 1. pyproject.toml
# 2. src/__init__.py
# 3. scripts/build.sh
# 4. Package.json (if applicable)

# Tag release
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
```

## Notes

- **Build on target platform** for best results (especially for code signing)
- **Keep certificates secure** - never commit them to repo
- **Test on clean machines** to ensure distribution works
- **Document requirements** clearly for users

## Related Skills

- [Production Readiness](./production-readiness.md) - Before releasing
- [Docker Compose](./docker-compose.md) - For backend services
- [Mobile Code Quality](./mobile-code-quality.md) - For mobile releases