feat(dev): enhance development environment and dependency management

- Add comprehensive environment setup documentation to README.md
- Add check:dependencies npm script for environment validation
- Update build scripts to use npx for local dependencies
- Enhance Android build script with dependency validation
- Add new check-dependencies.sh script for environment diagnostics

scripts/build-android.sh

@@ -49,6 +49,31 @@ set -e
 # Source common utilities
 source "$(dirname "$0")/common.sh"
 
+# Function to validate critical dependencies
+validate_dependencies() {
+    log_info "Validating critical dependencies..."
+    
+    # Check if node_modules exists
+    if [ ! -d "node_modules" ]; then
+        log_error "node_modules directory not found. Please run 'npm install' first."
+        exit 1
+    fi
+    
+    # Check if tsx is available
+    if [ ! -f "node_modules/.bin/tsx" ]; then
+        log_error "tsx dependency not found. Please run 'npm install' first."
+        exit 1
+    fi
+    
+    # Check if capacitor-assets is available
+    if [ ! -f "node_modules/.bin/capacitor-assets" ]; then
+        log_error "capacitor-assets dependency not found. Please run 'npm install' first."
+        exit 1
+    fi
+    
+    log_success "All critical dependencies validated successfully"
+}
+
 # Default values
 BUILD_MODE="development"
 BUILD_TYPE="debug"
@@ -179,6 +204,11 @@ parse_android_args "$@"
 
 # Print build header
 print_header "TimeSafari Android Build Process"
+
+# Validate dependencies before proceeding
+validate_dependencies
+
+# Log build start
 log_info "Starting Android build process at $(date)"
 log_info "Build mode: $BUILD_MODE"
 log_info "Build type: $BUILD_TYPE"
@@ -257,6 +287,7 @@ fi
 # Step 1: Validate asset configuration
 safe_execute "Validating asset configuration" "npm run assets:validate" || {
     log_warn "Asset validation found issues, but continuing with build..."
+    log_info "If you encounter build failures, please run 'npm install' first to ensure all dependencies are available."
 }
 
 # Step 2: Clean Android app
@@ -337,6 +368,9 @@ if [ "$OPEN_STUDIO" = true ]; then
     log_info "Android Studio: opened"
 fi
 
+# Reminder about dependency management
+log_info "💡 Tip: If you encounter dependency issues, run 'npm install' to ensure all packages are up to date."
+
 print_footer "Android Build"
 
 # Exit with success

scripts/check-dependencies.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# check-dependencies.sh
+# Author: Matthew Raymer
+# Date: 2025-08-19
+# Description: Dependency validation script for TimeSafari development environment
+# This script checks for critical dependencies required for building the application.
+
+# Exit on any error
+set -e
+
+# Source common utilities
+source "$(dirname "$0")/common.sh"
+
+print_header "TimeSafari Dependency Validation"
+
+log_info "Checking development environment dependencies..."
+
+# Check Node.js version
+if command -v node &> /dev/null; then
+    NODE_VERSION=$(node --version)
+    log_info "Node.js version: $NODE_VERSION"
+    
+    # Extract major version number
+    MAJOR_VERSION=$(echo $NODE_VERSION | sed 's/v\([0-9]*\)\..*/\1/')
+    if [ "$MAJOR_VERSION" -lt 18 ]; then
+        log_error "Node.js version $NODE_VERSION is too old. Please upgrade to Node.js 18 or later."
+        exit 1
+    fi
+else
+    log_error "Node.js is not installed. Please install Node.js 18 or later."
+    exit 1
+fi
+
+# Check npm version
+if command -v npm &> /dev/null; then
+    NPM_VERSION=$(npm --version)
+    log_info "npm version: $NPM_VERSION"
+else
+    log_error "npm is not installed. Please install npm."
+    exit 1
+fi
+
+# Check if node_modules exists
+if [ ! -d "node_modules" ]; then
+    log_error "node_modules directory not found."
+    log_info "Please run: npm install"
+    exit 1
+fi
+
+# Check critical dependencies
+log_info "Validating critical packages..."
+
+CRITICAL_DEPS=("tsx" "capacitor-assets" "vite")
+
+for dep in "${CRITICAL_DEPS[@]}"; do
+    if [ -f "node_modules/.bin/$dep" ]; then
+        log_success "✓ $dep found"
+    else
+        log_error "✗ $dep not found in node_modules/.bin"
+        log_info "This usually means the package wasn't installed properly."
+        log_info "Try running: npm install"
+        exit 1
+    fi
+done
+
+# Check TypeScript via npx
+if npx tsc --version &> /dev/null; then
+    TSC_VERSION=$(npx tsc --version)
+    log_success "✓ TypeScript found: $TSC_VERSION"
+else
+    log_error "✗ TypeScript not accessible via npx"
+    log_info "Try running: npm install"
+    exit 1
+fi
+
+# Check Capacitor CLI
+if command -v npx &> /dev/null; then
+    if npx cap --version &> /dev/null; then
+        CAP_VERSION=$(npx cap --version)
+        log_success "✓ Capacitor CLI version: $CAP_VERSION"
+    else
+        log_error "✗ Capacitor CLI not accessible via npx"
+        log_info "Try running: npm install @capacitor/cli"
+        exit 1
+    fi
+else
+    log_error "npx is not available. Please ensure npm is properly installed."
+    exit 1
+fi
+
+# Check Android development tools
+if command -v adb &> /dev/null; then
+    log_success "✓ Android Debug Bridge (adb) found"
+else
+    log_warn "⚠ Android Debug Bridge (adb) not found"
+    log_info "This is only needed for Android development and testing."
+fi
+
+if command -v gradle &> /dev/null; then
+    GRADLE_VERSION=$(gradle --version | head -n 1)
+    log_success "✓ Gradle found: $GRADLE_VERSION"
+else
+    log_warn "⚠ Gradle not found in PATH"
+    log_info "This is only needed if building outside of Android Studio."
+fi
+
+log_success "Dependency validation completed successfully!"
+log_info "Your development environment is ready for TimeSafari development."
+
+print_footer "Dependency Validation"