crowd-funder-for-time-pwa/scripts/README.md

# TimeSafari Build Scripts

This directory contains unified build and test scripts for the TimeSafari application. All scripts use a common utilities library to eliminate redundancy and provide consistent logging, error handling, timing, and environment variable management.

## Architecture

### Common Utilities (`common.sh`)

The `common.sh` script provides shared functionality used by all build scripts:

- **Logging Functions**: `log_info`, `log_success`, `log_warn`, `log_error`, `log_debug`, `log_step`
- **Timing**: `measure_time` for execution time tracking
- **Headers/Footers**: `print_header`, `print_footer` for consistent output formatting
- **Validation**: `check_command`, `check_directory`, `check_file`, `check_venv`
- **Execution**: `safe_execute` for error-handled command execution
- **Utilities**: `get_git_hash`, `clean_build_artifacts`, `validate_env_vars`
- **Environment Management**: `setup_build_env`, `setup_app_directories`, `load_env_file`, `print_env_vars`
- **CLI**: `parse_args`, `print_usage` for command-line argument handling

### Environment Variable Management

All scripts automatically handle environment variables for different build types:

#### Build Types and Environment Variables

| Platform | Mode | PWA Enabled | Native Features | Build Script |
|----------|------|-------------|-----------------|--------------|
| `web` | web | true | false | `build-web.sh` |
| `capacitor` | capacitor | false | true | `build-capacitor.sh` |

#### Automatic Environment Setup

Each script automatically:

1. **Sets platform-specific variables** based on build type
2. **Gets git hash** for versioning (`VITE_GIT_HASH`)
3. **Creates application directories** (`~/.local/share/TimeSafari/timesafari`)
4. **Loads .env file** if it exists
5. **Validates required variables** when needed

#### Environment Functions

- `setup_build_env(build_type, production)` - Sets environment for specific build type
- `setup_app_directories()` - Creates necessary application directories
- `load_env_file(filename)` - Loads variables from .env file
- `print_env_vars(prefix)` - Displays current environment variables
- `validate_env_vars(var1, var2, ...)` - Validates required variables exist

### Script Structure

All scripts follow this unified pattern:

```bash
#!/bin/bash
# script-name.sh
# Author: Matthew Raymer
# Description: Brief description of what the script does
#
# Exit Codes: List of exit codes and their meanings
# Usage: ./scripts/script-name.sh [options]

# Exit on any error
set -e

# Source common utilities
source "$(dirname "$0")/common.sh"

# Parse command line arguments
parse_args "$@"

# Print header
print_header "Script Title"
log_info "Starting process at $(date)"

# Setup environment (automatic)
setup_build_env "build_type"
setup_app_directories
load_env_file ".env"

# Execute steps with safe_execute
safe_execute "Step description" "command to execute" || exit 1

# Print footer
print_footer "Script Title"
exit 0
```

## Available Scripts

### Test Scripts

- **`test-all.sh`**: Comprehensive test suite (prerequisites, build, web tests, mobile tests)
- **`test-mobile.sh`**: Mobile test suite (Capacitor build, Android tests, iOS tests)
- **`test-common.sh`**: Test script to verify common utilities work correctly
- **`test-env.sh`**: Test script to verify environment variable handling

### Build Scripts

- **`build-android.sh`**: Complete Android build process

### Development Scripts

- **`electron-dev.sh`**: Electron development workflow

## Benefits of Unification

### Before (Redundant)

```bash
# Each script had 50+ lines of duplicate code:
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
# ... 40+ more lines of duplicate logging functions
log_info "Step 1/4: Doing something..."
if ! measure_time some_command; then
    log_error "Step failed!"
    exit 1
fi
# Manual environment variable setup
export VITE_PLATFORM=electron
export VITE_PWA_ENABLED=false
# ... more manual exports
```

### After (Unified)

```bash
# Each script is now ~20 lines of focused logic:
source "$(dirname "$0")/common.sh"
print_header "Script Title"
setup_build_env "electron"  # Automatic environment setup
safe_execute "Step description" "some_command" || exit 1
print_footer "Script Title"
```

## Usage Examples

### Running Tests

```bash
# Run all tests
./scripts/test-all.sh

# Run mobile tests only
./scripts/test-mobile.sh

# Run with verbose logging
./scripts/test-all.sh --verbose

# Show environment variables
./scripts/test-env.sh --env
```

### Building Applications

```bash
# Build Android
./scripts/build-android.sh

# Build Linux package
./scripts/build-electron-linux.sh deb

# Build universal Mac package
./scripts/build-electron-mac.sh universal

# Show environment variables for build
./scripts/build-electron.sh --env
```

### Development Workflows

```bash
# Start development
npm run dev
```

## Environment Variable Features

### Automatic Setup

All scripts automatically configure the correct environment variables for their build type:

```bash
# Capacitor builds automatically get:
export VITE_PLATFORM=capacitor
export VITE_PWA_ENABLED=false
export VITE_DISABLE_PWA=true
export DEBUG_MIGRATIONS=0
export VITE_GIT_HASH=<git-hash>

# Production builds also get:
export NODE_ENV=production
```

### .env File Support

Scripts automatically load variables from `.env` files if they exist:

```bash
# .env file example:
VITE_API_URL=https://api.example.com
VITE_DEBUG=true
CUSTOM_VAR=value
```

### Environment Validation

Required environment variables can be validated:

```bash
# In your script
validate_env_vars "VITE_API_URL" "VITE_DEBUG" || exit 1
```

### Environment Inspection

View current environment variables with the `--env` flag:

```bash
./scripts/test-env.sh --env
```

## Error Handling

All scripts use consistent error handling:

- **Exit Codes**: Each script documents specific exit codes
- **Safe Execution**: `safe_execute` provides timing and error handling
- **Graceful Failure**: Scripts stop on first error with clear messages
- **Logging**: All operations are logged with timestamps and colors
- **Environment Validation**: Required variables are checked before execution

## Testing

To verify the common utilities work correctly:

```bash
# Test all common functions
./scripts/test-common.sh

# Test environment variable handling
./scripts/test-env.sh

# Test with verbose logging
./scripts/test-env.sh --verbose
```

## Maintenance

### Adding New Scripts

1. Create new script following the unified pattern
2. Source `common.sh` at the top
3. Use `setup_build_env()` for environment setup
4. Use `safe_execute` for command execution
5. Document exit codes and usage
6. Make executable: `chmod +x scripts/new-script.sh`

### Modifying Common Utilities

1. Update `common.sh` with new functions
2. Export new functions with `export -f function_name`
3. Update this README if adding new categories
4. Test with `test-common.sh` and `test-env.sh`

### Adding New Build Types

1. Add new case to `setup_build_env()` function
2. Define appropriate environment variables
3. Update this README with new build type
4. Test with `test-env.sh`

## Security Considerations

- All scripts use `set -e` for immediate failure on errors
- Commands are executed through `safe_execute` for consistent error handling
- No direct execution of user input without validation
- Environment variables are validated when required
- .env files are loaded safely with proper parsing

## Performance

- Common utilities are sourced once per script execution
- Timing information is automatically collected for all operations
- Build artifacts are cleaned up automatically
- No redundant command execution or file operations
- Environment variables are set efficiently with minimal overhead