# Auto-Run Guide

**Author**: Matthew Raymer  
**Date**: 2025-07-12  
**Status**: 🎯 **ACTIVE** - In Use

## Overview

The TimeSafari auto-run system intelligently detects available devices and
automatically builds and launches the app on the best available target. It
supports Android devices/emulators, iOS devices/simulators, and Electron
desktop apps.

## Features

### Smart Device Detection
- **Android**: Detects real devices vs emulators using ADB
- **iOS**: Detects real devices vs simulators using xcrun
- **Electron**: Checks for Electron availability
- **Priority**: Real devices preferred over simulators/emulators

### Build Mode Support
- **Development**: Default mode for daily development
- **Test**: Optimized for testing with test data
- **Production**: Production-ready builds

### Platform Targeting
- **All platforms**: Automatically detects and runs on all available
- **Specific platform**: Target only iOS, Android, or Electron
- **Cross-platform**: Works on macOS, Linux, and Windows

### Auto-Run Options
- **Build + Auto-Run**: Single command to build and launch
- **Smart Detection**: Automatically chooses best available target
- **Error Handling**: Graceful fallbacks when devices unavailable

## Usage

### Auto-Run Script (Recommended)

```bash
# Auto-detect and run on all available platforms (development mode)
npm run auto-run

# Run in test mode
npm run auto-run:test

# Run in production mode
npm run auto-run:prod

# Target specific platforms
npm run auto-run:ios
npm run auto-run:android
npm run auto-run:electron
```

### Build Script Auto-Run

#### iOS Auto-Run Commands

```bash
# Test build + auto-run
npm run build:ios:test:run

# Production build + auto-run
npm run build:ios:prod:run

# Debug build + auto-run
npm run build:ios:debug:run

# Release build + auto-run
npm run build:ios:release:run
```

#### Android Auto-Run Commands

```bash
# Test build + auto-run
npm run build:android:test:run

# Production build + auto-run
npm run build:android:prod:run

# Debug build + auto-run
npm run build:android:debug:run

# Release build + auto-run
npm run build:android:release:run
```

#### Electron Auto-Run Commands

```bash
# Development build + auto-run
npm run build:electron:dev:run

# Test build + auto-run
npm run build:electron:test:run

# Production build + auto-run
npm run build:electron:prod:run
```

### Advanced Usage

```bash
# Direct script usage with options
./scripts/auto-run.sh --test --platform=ios
./scripts/auto-run.sh --prod --platform=android
./scripts/auto-run.sh --auto  # Skip confirmation prompts

# Build script with auto-run flag
./scripts/build-ios.sh --test --auto-run
./scripts/build-android.sh --prod --auto-run
./scripts/build-electron.sh --test --auto-run

# Combine options
./scripts/auto-run.sh --test --platform=all --auto
```

### Command Line Options

| Option | Description | Example |
|--------|-------------|---------|
| `--test` | Build and run in test mode | `--test` |
| `--prod` | Build and run in production mode | `--prod` |
| `--platform=PLATFORM` | Target specific platform | `--platform=ios` |
| `--auto` | Skip confirmation prompts | `--auto` |
| `--auto-run` | Auto-run after build | `--auto-run` |
| `--help` | Show help message | `--help` |

**Platform Options:**
- `ios` - iOS devices/simulators only
- `android` - Android devices/emulators only
- `electron` - Electron desktop app only
- `all` - All available platforms (default)

## How It Works

### 1. Device Detection

**Android Detection:**
```bash
# Uses ADB to list devices
adb devices

# Parses output to distinguish:
# - Real devices: Physical Android phones/tablets
# - Emulators: Android emulator instances
```

**iOS Detection:**
```bash
# Uses xcrun to list devices
xcrun xctrace list devices

# Parses output to distinguish:
# - Real devices: Physical iPhones/iPads
# - Simulators: iOS Simulator instances
```

### 2. Build Process

The script automatically calls the appropriate build commands:

```bash
# Development mode
npm run build:ios:dev
npm run build:android:dev
npm run build:electron:dev

# Test mode
npm run build:ios:test
npm run build:android:test
npm run build:electron:test

# Production mode
npm run build:ios:prod
npm run build:android:prod
npm run build:electron:prod
```

### 3. Launch Process

**Android:**
- Real devices: Install APK and launch via ADB
- Emulators: Use `npx cap run android`

**iOS:**
- Real devices: Build release version (requires Xcode setup)
- Simulators: Use `npx cap run ios`

**Electron:**
- Launch via `npm run electron:start`

## Examples

### Development Workflow

```bash
# Quick development run
npm run auto-run

# Output:
# ✅ Found 1 real Android device: ABC123DEF456
# ✅ Found 1 iOS simulator: iPhone 15 Pro
# ✅ Electron: available
# 
# Available targets:
#   Android: real:ABC123DEF456
#   iOS: simulator:iPhone 15 Pro
#   Electron: available
# 
# Continue with auto-run? (y/N): y
# 
# 🔄 Building and running Android (real: ABC123DEF456)...
# 🔄 Building and running iOS (simulator: iPhone 15 Pro)...
# 🔄 Building and running Electron...
# 
# ✅ Auto-run completed successfully! 3 platform(s) launched.
```

### Test Mode with Build Scripts

```bash
# iOS test build + auto-run
npm run build:ios:test:run

# Android test build + auto-run
npm run build:android:test:run

# Electron test build + auto-run
npm run build:electron:test:run

# Output:
# === TimeSafari iOS Build Process ===
# 🔄 Building Capacitor version (test)...
# 🔄 Syncing with Capacitor...
# 🔄 Building iOS app...
# 🔄 Auto-running iOS app...
# ✅ iOS app launched successfully!
# ✅ iOS build completed successfully!
```

### Production Mode

```bash
# Production build and run
npm run auto-run:prod

# Output:
# 🔄 Building Android (production)...
# 🔄 Building iOS (production)...
# 🔄 Building Electron (production)...
# 
# ✅ Auto-run completed successfully! 3 platform(s) launched.
```

## Comparison: Auto-Run Script vs Build Scripts

### Auto-Run Script (`auto-run.sh`)
**Best for:**
- Multi-platform development
- Quick testing across devices
- Automated workflows
- CI/CD integration

**Features:**
- Smart device detection
- Multi-platform support
- Interactive confirmation
- Error recovery

### Build Scripts with `--auto-run`
**Best for:**
- Single platform development
- Specific build configurations
- Non-interactive workflows
- Build customization

**Features:**
- Platform-specific optimization
- Build customization options
- Direct control over build process
- Integration with existing workflows

## Troubleshooting

### Common Issues

**No devices detected:**
```bash
# Check Android devices
adb devices

# Check iOS devices (macOS only)
xcrun xctrace list devices

# Check Electron availability
which electron
```

**Build failures:**
```bash
# Clean and rebuild
npm run clean:android
npm run clean:ios
npm run clean:electron

# Then retry auto-run
npm run auto-run
```

**Permission issues:**
```bash
# Make script executable
chmod +x scripts/auto-run.sh

# Check ADB permissions (Android)
adb kill-server
adb start-server
```

### Platform-Specific Issues

**Android:**
- Ensure ADB is in PATH
- Enable USB debugging on device
- Accept device authorization prompt
- Check device is in "device" state (not "unauthorized")

**iOS:**
- Requires macOS with Xcode
- Ensure Xcode command line tools installed
- Check iOS Simulator is available
- For real devices: Requires proper certificates

**Electron:**
- Ensure Electron is installed globally or locally
- Check Node.js version compatibility
- Verify build dependencies are installed

### Debug Mode

Enable verbose logging by modifying the script:

```bash
# Add debug logging to auto-run.sh
set -x  # Enable debug mode
```

## Integration with CI/CD

The auto-run script can be integrated into CI/CD pipelines:

```yaml
# Example GitHub Actions workflow
- name: Auto-run tests
  run: |
    npm run auto-run:test --auto
  env:
    # Set environment variables for CI
    CI: true
```

## Best Practices

### Development Workflow
1. **Daily development**: Use `npm run auto-run` for quick testing
2. **Testing**: Use `npm run auto-run:test` before commits
3. **Production**: Use `npm run auto-run:prod` for final testing
4. **Single platform**: Use `npm run build:ios:test:run` for focused work

### Device Management
1. **Keep devices connected**: Reduces detection time
2. **Use consistent device names**: Helps with identification
3. **Regular cleanup**: Clear old builds and caches

### Performance Tips
1. **Use --auto flag**: Skip prompts in automated workflows
2. **Target specific platforms**: Use `--platform=ios` for faster runs
3. **Parallel execution**: Script runs platforms in sequence (can be optimized)

## Future Enhancements

### Planned Features
- **Parallel execution**: Run multiple platforms simultaneously
- **Device selection**: Choose specific devices when multiple available
- **Custom build configurations**: Support for custom build modes
- **Integration with IDEs**: VS Code and other IDE integration
- **Performance monitoring**: Track build and launch times

### Contributing
To add new features or fix issues:
1. Modify `scripts/auto-run.sh`
2. Update this documentation
3. Test on multiple platforms
4. Submit pull request

## Related Documentation

- [iOS Simulator Build and Icons](./ios-simulator-build-and-icons.md)
- [Android Build Guide](./android-build-guide.md)
- [Electron Build Guide](./electron-build-guide.md)
- [Testing Guide](./testing-guide.md)