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

# 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

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

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

# 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
   • 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
   • Sign-In and Security → App-Specific Passwords
   • Generate new password, label "App Notarization"

Code Sign and Notarize

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 scripts/install_macos.sh

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

Step 4 - Package for Distribution

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

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

Windows Build

Prerequisites

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

Build Process

# 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

# 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

# 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

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

# 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

# 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

# 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 - Before releasing
• Docker Compose - For backend services
• Mobile Code Quality - For mobile releases