# Build Process Quick Reference

**Author**: Matthew Raymer  
**Date**: October 17, 2025  
**Last Updated**: November 19, 2025

## ⚡ Quick Start

**Easiest way to build and run:**

```bash
# Build and run both platforms
./scripts/build.sh --run

# Or build only
./scripts/build.sh
```

This script handles everything automatically! See [Unified Build Script](#-unified-build-script-recommended) section for all options.

---

## 🚨 Critical Build Steps

### Prerequisites

**Required for All Platforms:**
- Node.js 20.19.0+ or 22.12.0+
- npm (comes with Node.js)
- Plugin must be built (`npm run build` in plugin root directory)
  - The build script will automatically build the plugin if `dist/` doesn't exist

**For Android:**
- Java JDK 22.12 or later
- Android SDK (with `adb` in PATH)
- Gradle (comes with Android project)

**For iOS:**
- macOS with Xcode (xcodebuild must be in PATH)
- CocoaPods (`pod --version` to check)
  - Can be installed via rbenv (script handles this automatically)
- iOS deployment target: iOS 13.0+

**Plugin Requirements:**
- Plugin podspec must exist at: `node_modules/@timesafari/daily-notification-plugin/ios/DailyNotificationPlugin.podspec`
- Plugin must be installed: `npm install` (uses `file:../../` reference)
- Plugin must be built: `npm run build` in plugin root (creates `dist/` directory)

### Initial Setup (One-Time)

```bash
# 1. Install dependencies (includes @capacitor/ios)
npm install

# 2. Add iOS platform (if not already added)
npx cap add ios

# 3. Install iOS dependencies
cd ios/App
pod install
cd ../..
```

### Build for Both Platforms

```bash
# 1. Build web assets (required for both platforms)
npm run build

# 2. Sync with native projects (syncs both Android and iOS)
npm run cap:sync

# OR sync platforms individually:
# npm run cap:sync:android  # Android only
# npm run cap:sync:ios      # iOS only
```

### Android Build

```bash
# Build Android APK
cd android
./gradlew :app:assembleDebug

# Install on device/emulator
adb install -r app/build/outputs/apk/debug/app-debug.apk

# Launch app
adb shell am start -n org.timesafari.dailynotification.test/.MainActivity
```

### iOS Build

```bash
# Open in Xcode
cd ios/App
open App.xcworkspace

# Or build from command line
xcodebuild -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

# Or use Capacitor CLI
npx cap run ios
```

## ⚠️ Why `npm run cap:sync` is Important

**Problem**: `npx cap sync` overwrites `capacitor.plugins.json` and `capacitor.settings.gradle` with incorrect paths.

**Solution**: The `cap:sync` script automatically:
1. Runs `npx cap sync` (syncs both Android and iOS)
2. Fixes `capacitor.settings.gradle` (corrects plugin path from `android/` to `android/plugin/`)
3. Restores the DailyNotification plugin entry in `capacitor.plugins.json`

**Platform-specific sync:**
- `npm run cap:sync:android` - Syncs Android only (includes fix script)
- `npm run cap:sync:ios` - Syncs iOS only (no fix needed for iOS)

**Without the fix**: Plugin detection fails, build errors occur, "simplified dialog" appears.

## 🔍 Verification Checklist

### Android Verification

After Android build, verify:

- [ ] `android/app/src/main/assets/capacitor.plugins.json` contains DailyNotification entry
- [ ] System Status shows "Plugin: Available" (green)  
- [ ] Plugin Diagnostics shows all 4 plugins
- [ ] Click events work on ActionCard components
- [ ] No "simplified dialog" appears

### iOS Verification

After iOS build, verify:

- [ ] iOS project exists at `ios/App/App.xcworkspace`
- [ ] CocoaPods installed (`pod install` completed successfully)
- [ ] Plugin framework linked in Xcode project
- [ ] App builds without errors in Xcode
- [ ] Plugin methods accessible from JavaScript
- [ ] System Status shows "Plugin: Available" (green)

## 🛠️ Automated Build Scripts

### Unified Build Script (Recommended)

The project includes a comprehensive build script that handles both platforms:

```bash
# Build both platforms
./scripts/build.sh

# Build Android only
./scripts/build.sh --android

# Build iOS only
./scripts/build.sh --ios

# Build and run Android on emulator
./scripts/build.sh --run-android

# Build and run iOS on simulator
./scripts/build.sh --run-ios

# Build and run both platforms
./scripts/build.sh --run

# Show help
./scripts/build.sh --help
```

**Features:**
- ✅ Automatically builds web assets
- ✅ Syncs Capacitor with both platforms
- ✅ Builds Android APK
- ✅ Builds iOS app for simulator
- ✅ Automatically finds and uses available emulator/simulator
- ✅ Installs and launches apps when using `--run` flags
- ✅ Color-coded output for easy reading
- ✅ Comprehensive error handling

### Manual Build Scripts

#### Build for Android

Create `scripts/build-android.sh`:

```bash
#!/bin/bash
set -e

echo "🔨 Building web assets..."
npm run build

echo "🔄 Syncing with native projects..."
npm run cap:sync:android
# This automatically syncs and fixes plugin paths

echo "🏗️ Building Android app..."
cd android
./gradlew :app:assembleDebug

echo "📱 Installing and launching..."
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n org.timesafari.dailynotification.test/.MainActivity

echo "✅ Android build and deploy complete!"
```

### Build for iOS

Create `scripts/build-ios.sh`:

```bash
#!/bin/bash
set -e

echo "🔨 Building web assets..."
npm run build

echo "🔄 Syncing with iOS..."
npm run cap:sync:ios

echo "🍎 Building iOS app..."
cd ios/App
pod install
xcodebuild -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

echo "✅ iOS build complete!"
echo "📱 Open Xcode to run on simulator: open App.xcworkspace"
```

### Build for Both Platforms

Create `scripts/build-all.sh`:

```bash
#!/bin/bash
set -e

echo "🔨 Building web assets..."
npm run build

echo "🔄 Syncing with all native projects..."
npm run cap:sync

echo "🏗️ Building Android..."
cd android && ./gradlew :app:assembleDebug && cd ..

echo "🍎 Building iOS..."
cd ios/App && pod install && cd ../..
xcodebuild -workspace ios/App/App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

echo "✅ All platforms built successfully!"
```

## 🐛 Common Issues

| Issue | Symptom | Solution |
|-------|---------|----------|
| Empty plugin registry | `capacitor.plugins.json` is `[]` | Run `npm run cap:sync` or `node scripts/fix-capacitor-plugins.js` |
| Plugin not detected | "Plugin: Not Available" (red) | Check plugin registry, rebuild |
| Click events not working | Buttons don't respond | Check Vue 3 compatibility, router config |
| Inconsistent status | Different status in different cards | Use consistent detection logic |
| **No podspec found** | `[!] No podspec found for 'TimesafariDailyNotificationPlugin'` | Run `node scripts/fix-capacitor-plugins.js` to fix Podfile, then `pod install` |
| **Plugin not built** | Vite build fails: "Failed to resolve entry" | Run `npm run build` in plugin root directory (`../../`) |
| **CocoaPods not found** | `pod: command not found` | Install CocoaPods: `sudo gem install cocoapods` or via rbenv |
| **Xcode not found** | `xcodebuild: command not found` | Install Xcode from App Store, run `xcode-select --install` |

## 📱 Testing Commands

### Android Testing

```bash
# Check plugin registry
cat android/app/src/main/assets/capacitor.plugins.json

# Monitor native logs
adb logcat | grep -i "dailynotification\|capacitor\|plugin"

# Check app installation
adb shell pm list packages | grep dailynotification

# View app logs
adb logcat -s DailyNotification
```

### iOS Testing

```bash
# Check if iOS project exists
ls -la ios/App/App.xcworkspace

# Check CocoaPods installation
cd ios/App && pod install && cd ../..

# Monitor iOS logs (simulator)
xcrun simctl spawn booted log stream | grep -i "dailynotification\|capacitor\|plugin"

# Check plugin in Xcode
# Open ios/App/App.xcworkspace in Xcode
# Check: Project Navigator → Frameworks → DailyNotificationPlugin.framework

# View device logs (physical device)
# Xcode → Window → Devices and Simulators → Select device → Open Console
```

---

## 📝 Important Notes

**Remember**: 
- Use `npm run cap:sync` to sync both platforms (automatically fixes Android configuration files)
- Use `npm run cap:sync:android` for Android-only sync (includes fix script)
- Use `npm run cap:sync:ios` for iOS-only sync
- Always run `npm run build` before syncing to ensure latest web assets are copied
- For iOS: Run `pod install` in `ios/App/` after first sync or when dependencies change
