HereIAm/DISTRIBUTION.md

# HereIAm Distribution Guide

## Building for macOS Distribution

### Quick Start
```bash
# 1. Build the .app
./build_app.sh

# 2. Create distributable DMG
./create_dmg.sh

# 3. Your app is ready at: dist/HereIAm-1.0.0.dmg
```

### Detailed Build Process

#### Prerequisites
- macOS 10.14+ (for building)
- Python 3.8+
- Xcode Command Line Tools: `xcode-select --install`

#### Step 1: Environment Setup
```bash
# Clone and setup
git clone <your-repo>
cd HereIAm

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-build.txt
```

#### Step 2: Build the Application
```bash
# Build .app bundle
./build_app.sh
```

This creates `dist/HereIAm.app` with:
- All dependencies bundled
- Icons and assets included
- Menu bar-only app (no dock icon)
- Ready to run on any macOS 10.14+ system

#### Step 3: Create Distribution Package
```bash
# Create DMG for distribution
./create_dmg.sh
```

This creates `dist/HereIAm-1.0.0.dmg` with:
- Drag-to-Applications installer
- Professional DMG layout
- README instructions
- Compressed for smaller download

### Code Signing (Recommended for Distribution)

#### For Developer ID Distribution:
```bash
# Sign the app
codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name (TEAM_ID)" \
  dist/HereIAm.app

# Verify signing
codesign --verify --verbose dist/HereIAm.app
spctl --assess --verbose dist/HereIAm.app
```

#### For Mac App Store:
```bash
# Sign for App Store
codesign --deep --force --verify --verbose \
  --sign "3rd Party Mac Developer Application: Your Name (TEAM_ID)" \
  dist/HereIAm.app

# Create installer package
productbuild --component dist/HereIAm.app /Applications \
  --sign "3rd Party Mac Developer Installer: Your Name (TEAM_ID)" \
  HereIAm.pkg
```

### Notarization (Required for Gatekeeper)

#### Setup (one-time):
```bash
# Store credentials
xcrun notarytool store-credentials "AC_PASSWORD" \
  --apple-id "your-email@example.com" \
  --team-id "YOUR_TEAM_ID" \
  --password "app-specific-password"
```

#### Notarize DMG:
```bash
# Submit for notarization
xcrun notarytool submit dist/HereIAm-1.0.0.dmg \
  --keychain-profile "AC_PASSWORD" --wait

# Staple the notarization
xcrun stapler staple dist/HereIAm-1.0.0.dmg
```

### Distribution Options

#### 1. Direct Download
- Upload DMG to your website
- Users download and install manually
- Requires code signing for smooth installation

#### 2. Mac App Store
- Most secure distribution
- Apple handles updates
- Requires App Store review process
- Need to modify app for sandboxing requirements

#### 3. Package Managers
```bash
# Homebrew Cask (example)
brew install --cask hereiam
```

### Testing the Build

#### Local Testing:
```bash
# Test the app bundle
open dist/HereIAm.app

# Test the DMG
open dist/HereIAm-1.0.0.dmg
```

#### Distribution Testing:
1. Test on clean macOS system
2. Verify all dependencies are bundled
3. Check accessibility permissions prompt
4. Test menu bar functionality
5. Verify icon changes with system theme

### Troubleshooting

#### Common Build Issues:

**PyInstaller import errors:**
```bash
# Add missing imports to HereIAm.spec hiddenimports
hiddenimports=[
    'PyQt5.QtCore',
    'PyQt5.QtGui', 
    'PyQt5.QtWidgets',
    'pyautogui',
    'missing_module_name',
]
```

**Missing assets:**
- Verify all `.icns` files are in `assets/`
- Check file permissions
- Ensure assets are copied in spec file

**Large bundle size:**
- Review excludes in spec file
- Remove unused dependencies
- Use UPX compression (enabled by default)

**Gatekeeper issues:**
- Code sign the application
- Notarize with Apple
- Test with: `spctl --assess --verbose dist/HereIAm.app`

#### Performance Optimization:

**Reduce bundle size:**
```python
# In HereIAm.spec, add to excludes:
excludes=[
    'tkinter', 'unittest', 'email', 'http', 'urllib', 'xml',
    'pydoc', 'doctest', 'argparse', 'difflib', 'inspect',
    'calendar', 'pprint', 'pdb', 'bdb', 'cmd', 'pstats',
]
```

**Faster startup:**
- Minimize imports in main.py
- Use lazy imports where possible
- Optimize icon loading

### Continuous Integration

#### GitHub Actions Example:
```yaml
name: Build macOS App

on: [push, release]

jobs:
  build:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    - name: Install dependencies
      run: |
        pip install -r requirements.txt
        pip install -r requirements-build.txt
    - name: Build app
      run: ./build_app.sh
    - name: Create DMG
      run: ./create_dmg.sh
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: HereIAm-macOS
        path: dist/HereIAm-*.dmg
```

### Version Management

Update version in `src/__init__.py`:
```python
__version__ = "1.1.0"  # Update this for new releases
```

### Support and Maintenance

#### User Support:
- Provide clear installation instructions
- Document accessibility permission requirements
- Include troubleshooting in README
- Offer support email (jerico@tekop.net)

#### Updates:
- Use semantic versioning (1.0.0 → 1.0.1 → 1.1.0)
- Test on multiple macOS versions
- Consider auto-update mechanism for future versions