Add full iOS build system: script, npm integration, and documentation

- Implement scripts/build-ios.sh with dev/test/prod, IPA, deploy, and Xcode support - Integrate all iOS build and legacy scripts into package.json (including deploy) - Update docs/ios-build-scripts.md: mark as complete, add usage and status - Update README.md: add iOS to quick start, platform builds, and docs links - Ensure iOS build system matches Android/Electron pattern for consistency
2025-07-11 08:56:12 +00:00
parent 4b79e3a36e
commit 62fb24b04a
11 changed files with 3249 additions and 213 deletions
--- a/docs/build-troubleshooting.md
+++ b/docs/build-troubleshooting.md
@@ -0,0 +1,723 @@
+# Build Systems Troubleshooting Guide
+
+**Author**: Matthew Raymer
+**Date**: 2025-07-11
+**Status**: ✅ **COMPLETE** - Comprehensive troubleshooting for all build systems
+
+## Overview
+
+This guide provides comprehensive troubleshooting for all TimeSafari build systems, including common issues, solutions, and debugging techniques for web, Android, iOS, and Electron builds.
+
+## Quick Diagnostic Commands
+
+### Environment Check
+```bash
+# Check Node.js and npm versions
+node --version
+npm --version
+
+# Check platform-specific tools
+npx cap --version
+npx vite --version
+
+# Check environment variables
+echo $VITE_PLATFORM
+echo $VITE_PWA_ENABLED
+```
+
+### Build System Status
+```bash
+# Check all build scripts exist
+ls -la scripts/build-*.sh
+
+# Check package.json scripts
+npm run | grep build:
+
+# Check build artifacts
+ls -la dist/
+ls -la android/app/build/
+ls -la electron/dist/
+```
+
+## Web Build Issues
+
+### Development Server Problems
+
+#### Port Already in Use
+```bash
+# Check what's using port 8080
+lsof -i :8080
+
+# Kill the process
+kill -9 <PID>
+
+# Or use different port
+npm run build:web:dev -- --port 8081
+```
+
+#### Hot Reload Not Working
+```bash
+# Clear browser cache
+# DevTools > Application > Storage > Clear site data
+
+# Restart dev server
+npm run build:web:dev
+
+# Check file watching
+# Ensure no file system watcher limits
+```
+
+#### PWA Issues in Development
+```bash
+# Clear service worker
+# DevTools > Application > Service Workers > Unregister
+
+# Clear browser cache
+# DevTools > Application > Storage > Clear site data
+
+# Restart with PWA disabled
+VITE_DISABLE_PWA=true npm run build:web:dev
+```
+
+### Production Build Issues
+
+#### Build Fails with Errors
+```bash
+# Clean build artifacts
+rm -rf dist/
+
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall dependencies
+rm -rf node_modules/
+npm install
+
+# Rebuild
+npm run build:web:prod
+```
+
+#### Large Bundle Size
+```bash
+# Analyze bundle
+npm run build:web:prod
+# Check dist/assets/ for large files
+
+# Enable bundle analysis
+npm install --save-dev vite-bundle-analyzer
+# Add to vite.config.web.mts
+```
+
+#### PWA Not Working in Production
+```bash
+# Check manifest generation
+ls -la dist/manifest.webmanifest
+
+# Check service worker
+ls -la dist/sw.js
+
+# Verify HTTPS (required for PWA)
+# Ensure site is served over HTTPS
+```
+
+### Docker Build Issues
+
+#### Docker Build Fails
+```bash
+# Check Docker is running
+docker --version
+docker ps
+
+# Clean Docker cache
+docker system prune -a
+
+# Rebuild without cache
+docker build --no-cache -t timesafari-web:production .
+```
+
+#### Docker Image Too Large
+```bash
+# Use multi-stage builds
+# Optimize base images
+# Remove unnecessary files
+
+# Analyze image layers
+docker history timesafari-web:production
+```
+
+## Android Build Issues
+
+### Build Process Failures
+
+#### Gradle Build Fails
+```bash
+# Clean Gradle cache
+cd android && ./gradlew clean && cd ..
+
+# Clear Android build cache
+rm -rf android/app/build/
+rm -rf android/.gradle/
+
+# Rebuild
+npm run build:android:dev
+```
+
+#### Capacitor Sync Issues
+```bash
+# Clean Capacitor
+npx cap clean android
+
+# Reinstall Android platform
+npx cap remove android
+npx cap add android
+
+# Sync manually
+npx cap sync android
+```
+
+#### Resource Generation Fails
+```bash
+# Check source assets
+ls -la assets/icon.png
+ls -la assets/splash.png
+
+# Regenerate assets
+npx capacitor-assets generate --android
+
+# Check generated resources
+ls -la android/app/src/main/res/
+```
+
+### Device Deployment Issues
+
+#### No Device Connected
+```bash
+# Check device connection
+adb devices
+
+# Enable USB debugging
+# Settings > Developer options > USB debugging
+
+# Install ADB drivers (Windows)
+# Download from Google USB drivers
+```
+
+#### Device Unauthorized
+```bash
+# Check device for authorization dialog
+# Tap "Allow USB debugging"
+
+# Reset ADB
+adb kill-server
+adb start-server
+
+# Check device again
+adb devices
+```
+
+#### APK Installation Fails
+```bash
+# Uninstall existing app
+adb uninstall app.timesafari.app
+
+# Install fresh APK
+adb install -r android/app/build/outputs/apk/debug/app-debug.apk
+
+# Check installation
+adb shell pm list packages | grep timesafari
+```
+
+### Performance Issues
+
+#### Slow Build Times
+```bash
+# Enable Gradle daemon
+# Add to ~/.gradle/gradle.properties:
+org.gradle.daemon=true
+org.gradle.parallel=true
+org.gradle.configureondemand=true
+
+# Use incremental builds
+# Only rebuild changed files
+```
+
+#### Large APK Size
+```bash
+# Enable APK splitting
+# Add to android/app/build.gradle:
+android {
+    splits {
+        abi {
+            enable true
+            reset()
+            include 'x86', 'x86_64', 'arm64-v8a', 'armeabi-v7a'
+        }
+    }
+}
+```
+
+## Electron Build Issues
+
+### Development Issues
+
+#### App Won't Start
+```bash
+# Check Electron installation
+npm list electron
+
+# Clear Electron cache
+rm -rf ~/.config/TimeSafari/
+rm -rf ~/Library/Application\ Support/TimeSafari/
+rm -rf %APPDATA%\TimeSafari
+
+# Reinstall Electron
+npm install electron
+```
+
+#### Single Instance Lock Issues
+```bash
+# Check lock file
+ls -la ~/.timesafari-lock
+
+# Remove lock file manually
+rm -f ~/.timesafari-lock
+
+# Restart app
+npm run build:electron:dev
+```
+
+#### Database Issues
+```bash
+# Clear database
+./scripts/clear-database.sh
+
+# Check database files
+ls -la ~/.config/TimeSafari/
+ls -la ~/Library/Application\ Support/TimeSafari/
+
+# Rebuild database
+npm run build:electron:dev
+```
+
+### Package Build Issues
+
+#### Package Creation Fails
+```bash
+# Check electron-builder
+npm list electron-builder
+
+# Clean package cache
+rm -rf electron/dist/
+rm -rf electron/node_modules/
+
+# Reinstall dependencies
+cd electron && npm install && cd ..
+
+# Rebuild package
+npm run build:electron:appimage:prod
+```
+
+#### Code Signing Issues
+```bash
+# Check certificates
+# macOS: Keychain Access
+# Windows: Certificate Manager
+# Linux: Check certificate files
+
+# Skip code signing for testing
+# Add to electron-builder.config.json:
+"forceCodeSigning": false
+```
+
+#### Platform-Specific Issues
+
+##### Linux AppImage Issues
+```bash
+# Check AppImage creation
+file electron/dist/*.AppImage
+
+# Make executable
+chmod +x electron/dist/*.AppImage
+
+# Test AppImage
+./electron/dist/*.AppImage
+```
+
+##### macOS DMG Issues
+```bash
+# Check DMG creation
+file electron/dist/*.dmg
+
+# Mount DMG
+hdiutil attach electron/dist/*.dmg
+
+# Check contents
+ls -la /Volumes/TimeSafari/
+```
+
+##### Windows EXE Issues
+```bash
+# Check EXE creation
+file electron/dist/*.exe
+
+# Test installer
+# Run the EXE file
+# Check installation directory
+```
+
+## iOS Build Issues (Future)
+
+### Xcode Issues
+```bash
+# Check Xcode installation
+xcode-select --print-path
+
+# Install command line tools
+xcode-select --install
+
+# Accept Xcode license
+sudo xcodebuild -license accept
+```
+
+### Simulator Issues
+```bash
+# List available simulators
+xcrun simctl list devices
+
+# Boot simulator
+xcrun simctl boot "iPhone 15 Pro"
+
+# Reset simulator
+xcrun simctl erase all
+```
+
+### Code Signing Issues
+```bash
+# Check certificates
+security find-identity -v -p codesigning
+
+# Check provisioning profiles
+ls ~/Library/MobileDevice/Provisioning\ Profiles/
+
+# Install certificate
+# Use Keychain Access or Xcode
+```
+
+## Environment Issues
+
+### Environment Variables
+
+#### Missing Environment Variables
+```bash
+# Check environment files
+ls -la .env*
+
+# Set required variables
+export VITE_PLATFORM=web
+export VITE_PWA_ENABLED=true
+
+# Check in build script
+echo $VITE_PLATFORM
+echo $VITE_PWA_ENABLED
+```
+
+#### Wrong Environment Loaded
+```bash
+# Check current environment
+echo $NODE_ENV
+
+# Force environment
+NODE_ENV=production npm run build:web:prod
+
+# Check environment file loading
+# Verify .env.production exists
+```
+
+### Dependency Issues
+
+#### Missing Dependencies
+```bash
+# Check package.json
+cat package.json | grep -A 10 "dependencies"
+
+# Install missing dependencies
+npm install
+
+# Check for peer dependencies
+npm ls
+```
+
+#### Version Conflicts
+```bash
+# Check for conflicts
+npm ls
+
+# Update dependencies
+npm update
+
+# Force resolution
+npm install --force
+```
+
+#### Platform-Specific Dependencies
+```bash
+# Check Capacitor plugins
+npx cap ls
+
+# Install missing plugins
+npm install @capacitor/core @capacitor/cli
+
+# Sync plugins
+npx cap sync
+```
+
+## Performance Issues
+
+### Build Performance
+
+#### Slow Build Times
+```bash
+# Enable parallel processing
+# Add to package.json scripts:
+"build:parallel": "npm run build:web:prod & npm run build:android:prod & wait"
+
+# Use incremental builds
+# Only rebuild changed files
+
+# Optimize file watching
+# Increase file watcher limits
+```
+
+#### Memory Issues
+```bash
+# Increase Node.js memory
+NODE_OPTIONS="--max-old-space-size=4096" npm run build:web:prod
+
+# Check memory usage
+top -p $(pgrep node)
+
+# Optimize build process
+# Use streaming builds
+# Minimize memory usage
+```
+
+### Runtime Performance
+
+#### App Performance Issues
+```bash
+# Profile application
+# Use browser DevTools > Performance
+# Use React/Vue DevTools
+
+# Check bundle size
+npm run build:web:prod
+# Analyze dist/assets/
+
+# Optimize code splitting
+# Implement lazy loading
+```
+
+## Debugging Techniques
+
+### Verbose Logging
+
+#### Enable Verbose Mode
+```bash
+# Web builds
+./scripts/build-web.sh --verbose
+
+# Android builds
+./scripts/build-android.sh --verbose
+
+# Electron builds
+./scripts/build-electron.sh --verbose
+```
+
+#### Debug Environment
+```bash
+# Enable debug logging
+DEBUG_MIGRATIONS=1 npm run build:web:dev
+
+# Check debug output
+# Look for detailed error messages
+# Check console output
+```
+
+### Log Analysis
+
+#### Build Logs
+```bash
+# Capture build logs
+npm run build:web:prod > build.log 2>&1
+
+# Analyze logs
+grep -i error build.log
+grep -i warning build.log
+
+# Check for specific issues
+grep -i "failed\|error\|exception" build.log
+```
+
+#### Runtime Logs
+
+##### Web Browser
+```bash
+# Open DevTools
+# Console tab for JavaScript errors
+# Network tab for API issues
+# Application tab for storage issues
+```
+
+##### Android
+```bash
+# View Android logs
+adb logcat | grep -i timesafari
+
+# Filter by app
+adb logcat | grep -i "app.timesafari.app"
+```
+
+##### Electron
+```bash
+# View Electron logs
+# Check console output
+# Check DevTools console
+# Check main process logs
+```
+
+## Common Error Messages
+
+### Web Build Errors
+
+#### "Module not found"
+```bash
+# Check import paths
+# Verify file exists
+# Check case sensitivity
+# Update import statements
+```
+
+#### "Port already in use"
+```bash
+# Kill existing process
+lsof -i :8080
+kill -9 <PID>
+
+# Use different port
+npm run build:web:dev -- --port 8081
+```
+
+### Android Build Errors
+
+#### "Gradle build failed"
+```bash
+# Clean Gradle cache
+cd android && ./gradlew clean && cd ..
+
+# Check Gradle version
+./android/gradlew --version
+
+# Update Gradle wrapper
+cd android && ./gradlew wrapper --gradle-version 8.13 && cd ..
+```
+
+#### "Device not found"
+```bash
+# Check device connection
+adb devices
+
+# Enable USB debugging
+# Settings > Developer options > USB debugging
+
+# Install drivers (Windows)
+# Download Google USB drivers
+```
+
+### Electron Build Errors
+
+#### "App already running"
+```bash
+# Remove lock file
+rm -f ~/.timesafari-lock
+
+# Kill existing processes
+pkill -f "TimeSafari"
+
+# Restart app
+npm run build:electron:dev
+```
+
+#### "Code signing failed"
+```bash
+# Check certificates
+# macOS: Keychain Access
+# Windows: Certificate Manager
+
+# Skip code signing for testing
+# Add to electron-builder.config.json:
+"forceCodeSigning": false
+```
+
+## Prevention Strategies
+
+### Best Practices
+
+#### Regular Maintenance
+```bash
+# Update dependencies regularly
+npm update
+
+# Clean build artifacts
+npm run clean:all
+
+# Check for security vulnerabilities
+npm audit
+
+# Update build tools
+npm update -g @capacitor/cli
+npm update -g electron-builder
+```
+
+#### Environment Management
+```bash
+# Use consistent environments
+# Separate dev/test/prod configurations
+# Version control environment files
+# Document environment requirements
+```
+
+#### Testing
+```bash
+# Test builds regularly
+npm run build:web:prod
+npm run build:android:prod
+npm run build:electron:prod
+
+# Test on different platforms
+# Verify all features work
+# Check performance metrics
+```
+
+### Monitoring
+
+#### Build Monitoring
+```bash
+# Track build times
+# Monitor build success rates
+# Check for performance regressions
+# Monitor bundle sizes
+```
+
+#### Runtime Monitoring
+```bash
+# Monitor app performance
+# Track error rates
+# Monitor user experience
+# Check platform-specific issues
+```
+
+---
+
+**Last Updated**: 2025-07-11
+**Version**: 1.0.3-beta
+**Status**: Production Ready