MovieMapper/BUILD-DISTRIBUTION.md

# MovieMapper iOS - Build & Distribution (Phase 6)

## Overview

This document describes the build system, CI/CD automation, and distribution tools for the MovieMapper iOS app.

## Directory Structure

```
MovieMapper/
├── build.sh              # Build for simulator and device
├── archive.sh            # Create Xcode archive
├── export-ipa.sh         # Export IPA from archive (optional)
├── run-tests.sh          # Run all tests
├── ExportOptions.plist   # Export configuration
├── build-settings.xcconfig  # Build settings
├── .github/
│   └── workflows/
│       ├── build.yml     # Build automation
│       └── test.yml      # Test automation
└── MovieMapper-iOS/      # Xcode project
```

## Build Scripts

### 1. build.sh - Build for Simulator and Device

**Usage:**
```bash
./build.sh [simulator|device] [Debug|Release]
```

**Examples:**
```bash
# Build for simulator (Debug)
./build.sh simulator

# Build for device (Release)
./build.sh device Release

# Build for simulator (Debug)
./build.sh simulator Debug
```

**What it does:**
- Builds the Xcode project for the specified target
- Uses iPad Pro (12.9-inch) simulator as default
- Sets appropriate SDK and destination
- Validates build configuration

**Environment Variables:**
- `TVDB_API_KEY` - TheTVDB API key (from `.env` file)

---

### 2. archive.sh - Create Xcode Archive

**Usage:**
```bash
./archive.sh [Debug|Release] [ArchiveName]
```

**Examples:**
```bash
# Create release archive
./archive.sh Release MovieMapper-iOS

# Create debug archive with custom name
./archive.sh Debug MovieMapper-iOS-Debug
```

**What it does:**
- Creates an `.xcarchive` file
- Stores archives in `archives/` directory
- Uses Release configuration for App Store deployment
- Lists available archives after creation

**Output:**
```
archives/
└── MovieMapper-iOS.xcarchive/
    ├── Info.plist
    ├── Products/
    ├── dSYMs/
    └── ...
```

---

### 3. export-ipa.sh - Export IPA from Archive

**Usage:**
```bash
./export-ipa.sh [ArchivePath] [ExportOptionsPlist] [OutputDirectory]
```

**Examples:**
```bash
# Export with App Store options
./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions.plist

# Export with Ad Hoc options
./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions-AdHoc.plist ./output
```

**What it does:**
- Exports IPA from `.xcarchive`
- Uses ExportOptions.plist for configuration
- Supports App Store, Ad Hoc, and Enterprise distribution

---

### 4. run-tests.sh - Run All Tests

**Usage:**
```bash
./run-tests.sh [unit|ui|all]
```

**Examples:**
```bash
# Run only unit tests
./run-tests.sh unit

# Run only UI tests
./run-tests.sh ui

# Run all tests
./run-tests.sh all
```

**What it does:**
- Loads environment variables from `.env`
- Runs Swift unit tests with `swift test`
- Runs UI tests with `xcodebuild`
- Generates test summary reports
- Saves logs to `test-results/` directory

**Test Results:**
```
test-results/
├── unit-test.log         # Unit test output
├── ui-test.log           # UI test output
├── unit-test.xml         # Unit test summary
└── ui-test.xml           # UI test summary
```

---

## Configuration Files

### ExportOptions.plist

**Purpose:** Configure IPA export for different distribution methods.

**Key Settings:**
- `method`: Distribution method (app-store, ad-hoc, enterprise, development)
- `teamID`: Apple Developer Team ID
- `bundleIdentifier`: App bundle ID
- `codeSignIdentity`: Code signing identity
- `provisioningProfiles`: Provisioning profile mapping

**Example Methods:**

**App Store Distribution:**
```xml
<key>method</key>
<string>app-store</string>
```

**Ad Hoc Distribution:**
```xml
<key>method</key>
<string>ad-hoc</string>
```

**Enterprise Distribution:**
```xml
<key>method</key>
<string>enterprise</string>
```

### build-settings.xcconfig

**Purpose:** Centralize build settings for Debug and Release configurations.

**Key Settings:**

**Debug Configuration:**
- `CODE_SIGN_IDENTITY = iPhone Developer`
- `GCC_OPTIMIZATION_LEVEL = 0` (no optimization)
- `ENABLE_TESTABILITY = YES`
- `DEBUG_INFORMATION_FORMAT = dwarf`

**Release Configuration:**
- `CODE_SIGN_IDENTITY = iPhone Distribution`
- `GCC_OPTIMIZATION_LEVEL = s` (optimize for size)
- `ENABLE_TESTABILITY = NO`
- `DEVELOPMENT_TEAM = YourTeamID`

**Common Settings:**
- `IPHONEOS_DEPLOYMENT_TARGET = 17.0`
- `SDKROOT = iphoneos`
- `ARCHS = arm64`
- `ENABLE_BITCODE = NO`

---

## CI/CD Automation

### GitHub Actions Workflows

#### build.yml - Build Workflow

**Triggers:**
- Push to `main`, `develop`, `feature/*` branches
- Pull requests to `main`, `develop`

**Jobs:**
1. **Checkout code** - Clone repository
2. **Set up Xcode** - Install Xcode 15.2
3. **Load environment variables** - Read `.env` file
4. **Build for Simulator** - Debug build
5. **Build for Device** - Release build
6. **Archive App** - Create `.xcarchive`
7. **Upload Build Artifacts** - Save build outputs
8. **Upload Test Results** - Save test logs
9. **Upload Debug Logs** - Save debug logs on failure

**Artifacts:**
- `iOS-App-Build` - Archives and IPA files (7 days retention)
- `test-results` - Test reports (7 days retention)
- `debug-logs` - Debug logs on failure (7 days retention)

---

#### test.yml - Test Workflow

**Triggers:**
- Push to `main`, `develop`, `feature/*` branches
- Pull requests to `main`, `develop`

**Jobs:**
1. **Checkout code** - Clone repository
2. **Set up Xcode** - Install Xcode 15.2
3. **Load environment variables** - Read `.env` file
4. **Run Unit Tests** - Execute Swift tests
5. **Run UI Tests** - Execute UI automation tests
6. **Upload Test Results** - Save test reports

**Test Coverage:**
- Unit tests: All service classes
- UI tests: Main views and navigation
- TVDB API tests: Authentication and search

---

## Environment Variables

### Required Variables

**TVDB_API_KEY**
- Location: `.env` file at project root
- Format: `TVDB_API_KEY=your-api-key-here`
- Usage: Authentication for TheTVDB API

**Example .env:**
```bash
TVDB_API_KEY=aa3699a9-01ac-49a9-836e-3b6123e00140
APP_NAME=MovieMapper
APP_VERSION=1.0.0
```

### CI/CD Environment Variables

GitHub Actions automatically loads `.env` file:
```yaml
- name: Load environment variables
  run: |
    if [[ -f .env ]]; then
      export $(grep -v '^#' .env | xargs)
    fi
```

---

## Testing Strategy

### Unit Tests

**Location:** `MovieMapper-iOS/Tests/`

**Test Files:**
- `FileScannerTests.swift` - Directory scanning
- `MetadataExtractorTests.swift` - FFmpeg metadata extraction
- `TVDBClientTests.swift` - API integration
- `FileMapperTests.swift` - File mapping logic
- `AuditLoggerTests.swift` - Audit logging

**Run Unit Tests:**
```bash
./run-tests.sh unit
swift test -v
```

### UI Tests

**Location:** `MovieMapper-iOS/`

**Test Features:**
- Directory picker
- File list navigation
- Tagging system
- Search functionality
- Episode management

**Run UI Tests:**
```bash
./run-tests.sh ui
xcodebuild test -project MovieMapper-iOS.xcodeproj ...
```

---

## Distribution

### App Store Distribution

1. **Build Release Archive:**
   ```bash
   ./archive.sh Release MovieMapper-iOS
   ```

2. **Export IPA:**
   ```bash
   ./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions.plist
   ```

3. **Upload to App Store:**
   - Use Xcode Organizer
   - Or use `xcrun altool` command

### Ad Hoc Distribution

1. **Update ExportOptions.plist:**
   ```xml
   <key>method</key>
   <string>ad-hoc</string>
   ```

2. **Archive and Export:**
   ```bash
   ./archive.sh Release MovieMapper-iOS-AdHoc
   ./export-ipa.sh archives/MovieMapper-iOS-AdHoc.xcarchive ExportOptions-AdHoc.plist
   ```

3. **Distribute to Testers:**
   - Upload to TestFlight
   - Or share IPA directly

---

## Troubleshooting

### Common Issues

**1. Build fails with "No such module"**
```bash
# Clean build directory
./build.sh simulator Debug clean
```

**2. Archive fails**
```bash
# Check Xcode version
xcodebuild -version

# Verify team ID in ExportOptions.plist
```

**3. Tests fail with API errors**
```bash
# Verify TVDB_API_KEY is set
echo $TVDB_API_KEY

# Check .env file exists
cat .env
```

**4. Code signing errors**
```bash
# Check provisioning profiles in Xcode
# Update CODE_SIGN_IDENTITY in build-settings.xcconfig
```

---

## Quick Reference

| Task | Command |
|------|---------|
| Build for simulator | `./build.sh simulator` |
| Build for device | `./build.sh device Release` |
| Create archive | `./archive.sh Release` |
| Run all tests | `./run-tests.sh all` |
| Run unit tests only | `./run-tests.sh unit` |
| Run UI tests only | `./run-tests.sh ui` |

---

## Next Steps

1. **Update ExportOptions.plist** with your Team ID
2. **Configure Xcode signing** in project settings
3. **Set up App Store Connect** metadata
4. **Configure TestFlight** for beta testing
5. **Set up GitHub Secrets** for CI/CD (if needed)

---

## Documentation References

- [Phase 1](./MovieMapper-iOS/README.md) - Project Setup
- [Phase 3](./MovieMapper-iOS/QUICK_REFERENCE.md) - UI Implementation
- [Phase 4](./MovieMapper-iOS/TESTING.md) - Testing Strategy
- [iOS_PLAN.md](./iOS_PLAN.md) - Complete Implementation Plan