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:

#!/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)

# 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)

# 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

# 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

# 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

# Start development
npm run dev

Environment Variable Features

Automatic Setup

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

# 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:

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

Environment Validation

Required environment variables can be validated:

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

Environment Inspection

View current environment variables with the --env flag:

./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:

# 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