#!/bin/bash
# script-name.sh - Brief description of what this script does
#
# Usage: script-name.sh <param1> <param2> [optional-param]
#
# Example:
#   script-name.sh value1 value2
#   script-name.sh value1 value2 optional-value
#
# Exit codes:
#   0 - Success
#   1 - Invalid arguments or general error
#   2 - Specific error condition (document what)

set -e  # Exit immediately on error
# set -x  # Uncomment for debugging

# Color output for better visibility
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Helper functions
error() {
    echo -e "${RED}ERROR: $1${NC}" >&2
    exit 1
}

success() {
    echo -e "${GREEN}SUCCESS: $1${NC}"
}

warn() {
    echo -e "${YELLOW}WARNING: $1${NC}"
}

# Input validation
if [ $# -lt 2 ]; then
    echo "Usage: $0 <param1> <param2> [optional-param]"
    echo ""
    echo "Description: Brief description of what this does"
    echo ""
    echo "Arguments:"
    echo "  param1        Description of param1"
    echo "  param2        Description of param2"
    echo "  optional-param  Description of optional param (default: value)"
    exit 1
fi

# Parse arguments
PARAM1=$1
PARAM2=$2
OPTIONAL_PARAM=${3:-"default-value"}

# Validate inputs
if [ -z "$PARAM1" ]; then
    error "param1 cannot be empty"
fi

# Main logic
main() {
    echo "Processing with param1=$PARAM1, param2=$PARAM2..."

    # Step 1: Describe what this step does
    if ! some_command "$PARAM1"; then
        error "Failed to process param1"
    fi

    # Step 2: Another operation with error handling
    result=$(another_command "$PARAM2" 2>&1)
    if [ $? -ne 0 ]; then
        error "Failed to process param2: $result"
    fi

    # Step 3: Validation
    if [ ! -f "$result" ]; then
        error "Expected file not found: $result"
    fi

    success "Operation completed successfully"
    echo "$result"  # Output for caller to parse
}

# Execute main function
main