icrn_manager

#!/bin/bash

# This script manages the checkout of kernels from a configured central repository
# this script leverages 'update_r_libs.sh'

# [[ $_ != $0 ]] && return

# check for existence of needed tools
if [ -z $(type -p jq) ]; then
    echo "Need tool jq installed to proceed."
    exit 1
fi

icrn_base=".icrn"
icrn_kernels="icrn_kernels"
APP_FOLDER=$(dirname $0)
KERNEL_FOLDER=${KERNEL_FOLDER:-${APP_FOLDER}/../kernels}
if [ ! -d ${KERNEL_FOLDER} ]; then echo "Could not determine location of kernel respository - contact administrator"; exit -1 ; fi
central_catalog_default=${KERNEL_FOLDER}

ICRN_USER_BASE=${ICRN_USER_BASE:-${HOME}/${icrn_base}}
ICRN_MANAGER_CONFIG=${ICRN_MANAGER_CONFIG:-${ICRN_USER_BASE}/manager_config.json}
ICRN_USER_KERNEL_BASE=${ICRN_USER_KERNEL_BASE:-${ICRN_USER_BASE}/${icrn_kernels}}
ICRN_USER_CATALOG=${ICRN_USER_CATALOG:-${ICRN_USER_KERNEL_BASE}/user_catalog.json}

if [ ! -e ${ICRN_MANAGER_CONFIG} ]; then
    # Note: Auto-initialization will be handled in kernels() function
    # This section sets up default paths for when config doesn't exist yet
    ICRN_KERNEL_REPOSITORY=$central_catalog_default
    ICRN_R_KERNELS=${ICRN_KERNEL_REPOSITORY}"/R"
    ICRN_PYTHON_KERNELS=${ICRN_KERNEL_REPOSITORY}"/Python"
    ICRN_KERNEL_CATALOG=${ICRN_KERNEL_REPOSITORY}"/icrn_kernel_catalog.json"
else
    ICRN_KERNEL_REPOSITORY=$(jq -r ".\"icrn_central_catalog_path\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_R_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_r_kernels\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_PYTHON_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_python_kernels\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_KERNEL_CATALOG=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_kernel_catalog\"" "${ICRN_MANAGER_CONFIG}")
    if [ -z ${ICRN_KERNEL_REPOSITORY} ] || [ -z ${ICRN_R_KERNELS} ] || [ -z ${ICRN_PYTHON_KERNELS} ] || [ -z ${ICRN_KERNEL_CATALOG} ] ; then
        echo "Problem with determining central kernel information - please check user manager config at ${ICRN_MANAGER_CONFIG}"
        echo "ICRN Kernel base: ${ICRN_KERNEL_REPOSITORY}"
        echo "ICRN R Kernels location:  ${ICRN_R_KERNELS}"
        echo "ICRN Python Kernels location:  ${ICRN_PYTHON_KERNELS}"
        echo "ICRN catalog location: ${ICRN_KERNEL_CATALOG}"
        exit 1
    fi
fi



# Prompt the user for confirmation before proceeding with a potentially destructive operation.
#
# Parameters:
#   $1 - challenge: Optional prompt string to display to the user. If not provided,
#        defaults to "Are you sure? [y/N]"
#
# Returns:
#   0 if user confirms (y/yes), exits with status 0 if user declines
#
# Side effects:
#   Exits the script with status 0 if user does not confirm
confirm() {
    local challenge=$1; shift
    # call with a prompt string or use a default
    # function much less needed after we have stopped unpacking kernels to the users local dir; retaining in case its needed
    # https://stackoverflow.com/questions/3231804/in-bash-how-to-add-are-you-sure-y-n-to-any-command-or-alias
    read -r -p "${challenge:-Are you sure? [y/N]} " response
    if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]
    then
        return 0
    else
        echo "Exiting..."
        exit 0
    fi
}

last_check=-1
# Check if a kernel entry exists in the specified catalog.
#
# This function searches for a kernel entry in a catalog (either central or user catalog)
# and sets the global variable 'last_check' to indicate success (1) or failure (0).
#
# Parameters:
#   $1 - catalog: Path to the JSON catalog file to search
#   $2 - language: Language of the kernel (e.g., "R", "Python")
#   $3 - targetname: Name of the kernel to search for
#   $4 - targetversion: Optional version number to check for
#
# Global variables:
#   last_check: Set to 1 if entry found, 0 if not found. Initialized to -1.
#
# Returns:
#   No return value. Results are stored in the global 'last_check' variable.
#
# Side effects:
#   Prints error messages to stdout if kernel or version is not found
check_for_catalog_entry() 
{
    local catalog=$1; shift
    local language=$1; shift
    local targetname=$1; shift
    if [ ! -z $1 ]; then
        local targetversion=$1; shift
    fi
    
    if [ ! "$(jq -r ".\"$language\".\"$targetname\"" "$catalog")" = "null" ]; then
        if [ ! -z $targetversion ]; then
            # we expect to find version if its provided
            if [ ! "$(jq -r ".\"$language\".\"$targetname\".\"$targetversion\"" $catalog)" = "null" ]; then
                last_check=1
            else
                echo "Found kernel for $targetname"
                echo "Could not find version: $targetversion"
                last_check=0
            fi
        else
            last_check=1
        fi
    else
        # no target found
        echo "Checking for catalog entry failed for: $targetname"
        echo "Checked catalog: $catalog"
        last_check=0
    fi
}

# Retrieve and display all available versions for a specific kernel package.
#
# This function first verifies that the kernel exists in the catalog, then extracts
# and displays all available version numbers for that kernel.
#
# Parameters:
#   $1 - catalog: Path to the JSON catalog file to search
#   $2 - language: Language of the kernel (e.g., "R", "Python")
#   $3 - targetname: Name of the kernel to get versions for
#
# Returns:
#   Exits with status 1 if the kernel is not found in the catalog
#
# Side effects:
#   Prints available versions to stdout, or error message if kernel not found
get_versions_for_package() 
{
    local catalog=$1; shift
    local language=$1; shift
    local targetname=$1; shift
    
    check_for_catalog_entry $catalog $language $targetname
    if [ $last_check = 0 ]; then
        echo "$targetname not present in catalog at $catalog"
        exit 1
    else
        last_check=-1
    fi

    available_versions=$(jq -r ".\"$language\".\"$targetname\"| keys[]" "$catalog")
    echo "Available versions for $targetname:"
    echo $available_versions
}

# Display a list of all available kernels from the central repository catalog.
#
# This function reads the central kernel catalog and displays all available kernels
# in a tabular format showing language, kernel name, and version for each entry.
#
# Parameters:
#   None
#
# Returns:
#   No return value
#
# Side effects:
#   Prints a tab-separated table of available kernels to stdout
function kernels__available() # get a list of available kernels from the central repo
{
    icrn_catalog=${ICRN_KERNEL_CATALOG}
    echo "Available kernels in ICRN catalog ($icrn_catalog):"
    languages=$(jq -r '. | keys[]' $icrn_catalog)
    echo -e "Language\tKernel\tVersion"
    for language in $languages; do
        kernels=$(jq -r ".$language | keys[]" $icrn_catalog)
        for kernel in $kernels; do
            versions=$(jq -r ".$language.$kernel | keys[]" $icrn_catalog)
        for version in $versions; do
                echo -e $language"\t"$kernel"\t"$version
            done
        done
    done
}
# Alias for kernels__available() - display a list of all available kernels.
#
# This is a convenience function that calls kernels__available() with all passed arguments.
#
# Parameters:
#   All arguments are passed through to kernels__available()
#
# Returns:
#   Same as kernels__available()
function kernels__avail() # alias for available
{
    kernels__available "$@"
}

# Display a list of kernels that have been checked out and are ready for use.
#
# This function reads the user's local catalog and displays all kernels that have
# been successfully checked out, showing language, kernel name, and version.
#
# Parameters:
#   None
#
# Returns:
#   No return value
#
# Side effects:
#   Prints a tab-separated table of checked-out kernels to stdout
function kernels__list() # get the list of kernels already checked out and ready for use
{
    user_catalog=${ICRN_USER_CATALOG}
    echo "checked out kernels in in user catalog (${ICRN_USER_CATALOG}):"
    languages=$(jq -r '. | keys[]' $user_catalog)
    echo -e "Language\tKernel\tVersion"
    for language in $languages; do
        kernels=$(jq -r ".$language | keys[]" $user_catalog)
        for kernel in $kernels; do
            versions=$(jq -r ".$language.$kernel | keys[]" $user_catalog)
        for version in $versions; do
                echo -e $language"\t"$kernel"\t"$version
            done
        done
    done
}

# Activate a kernel that has already been checked out for use in Jupyter.
#
# This function activates a previously checked-out kernel, making it available for use
# in Jupyter notebooks. For R kernels, it creates symbolic links and updates .Renviron.
# For Python kernels, it installs the kernel spec using ipykernel.
# The special value "none" can be used to deactivate all kernels for a language.
#
# Parameters:
#   $1 - language: Language of the kernel (e.g., "R", "Python")
#   $2 - targetname: Name of the kernel to activate, or "none" to deactivate all
#   $3 - version: Version number of the kernel (required unless targetname is "none")
#
# Returns:
#   Exits with status 1 if parameters are missing or invalid, or if kernel path not found
#
# Side effects:
#   - For R: Creates symbolic link and updates .Renviron via update_r_libs.sh
#   - For Python: Installs/uninstalls Jupyter kernel specs
#   - Removes existing kernel installations before installing new ones
function kernels__use() # use a kernel which is already checked out
{
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift

    # ensure we get a uc-first label for lang
    language="$(tr '[:lower:]' '[:upper:]' <<< ${language:0:1})${language:1}"

    local target_r_environ_file=${HOME}"/.Renviron"
    # dependent on PATH VAR
    local target_r_libs_script="update_r_libs.sh"

    if [ "$targetname" = "none" ]; then
        echo "Desired kernel: none for $language"
    elif [ -z $targetname ] || [ -z $language ]; then
        echo "usage: icrn_manager kernels use <language> <kernel name> [version number]"
        echo "       or: icrn_manager kernels use <language> none"
        help
        exit 1
    elif [ -z $version ] && [ "$targetname" != "none" ]; then
        echo "usage: icrn_manager kernels use <language> <kernel name> <version number>"
        echo "       or: icrn_manager kernels use <language> none"
        help
        exit 1
    else
        echo "Desired kernel:"
        echo "Language: "$language
        echo "Kernel: "$targetname
        if [ "$targetname" != "none" ]; then
        echo "Version: "$version
        fi
    fi

    icrn_catalog=${ICRN_KERNEL_CATALOG}
    user_catalog=${ICRN_USER_CATALOG}
    # add in checking for various needed entities
    # TODO: convert this to using the kernel-checking methods above
    if [ "$targetname" = "none" ]; then
        case $language in
            "R")
                echo "Removing preconfigured kernels from R..."
                ${target_r_libs_script} ${target_r_environ_file}
                ;;
            "Python")
                echo "Removing preconfigured kernels from Python..."
                
                # Get list of kernels from user catalog
                user_catalog=${ICRN_USER_CATALOG}
                if [ -f "$user_catalog" ]; then
                    # Get all Python kernels from user catalog
                    catalog_kernels=$(jq -r '.Python | to_entries[] | .key + "-" + (.value | to_entries[] | .key)' "$user_catalog" 2>/dev/null || echo "")
                    
                    if [ -n "$catalog_kernels" ]; then
                        echo "Found Python kernels in user catalog: $catalog_kernels"
                        
                        # Get list of installed kernels from jupyter
                        installed_kernels=$(jupyter kernelspec list --json 2>/dev/null | jq -r '.kernelspecs | keys[]' 2>/dev/null || echo "")
                        
                        if [ -n "$installed_kernels" ]; then
                            echo "Found installed kernels."
                            # echo "Found installed kernels: $installed_kernels"
                            
                            # Remove only kernels that are both in catalog and installed
                            for catalog_kernel in $catalog_kernels; do
                                if echo "$installed_kernels" | grep -q "^$catalog_kernel$"; then
                                    echo "Removing kernel: $catalog_kernel"
                                    jupyter kernelspec uninstall -y "$catalog_kernel" 2>/dev/null || echo "Failed to remove kernel: $catalog_kernel"
                                else
                                    echo "Kernel $catalog_kernel not found in jupyter kernelspec list, skipping"
                                fi
                            done
                        else
                            echo "No installed kernels found in jupyter kernelspec list"
                        fi
                    else
                        echo "No Python kernels found in user catalog"
                    fi
                else
                    echo "User catalog not found"
                fi
                
                echo "Python kernel removal complete"
                ;;
            *)
                echo "Unsupported language '$language' for kernel removal"
                echo "Supported languages: R, Python"
                exit 1
                ;;
        esac
    else
        absolute_path=$(jq -r ".\"$language\".\"$targetname\".\"$version\".\"absolute_path\"" $user_catalog)
        overlay_path=$(jq -r ".\"$language\".\"$targetname\".\"$version\".\"overlay_path\"" $user_catalog)
        # absolute path for R is determined by activating the R install and finding the location of its library directory
        # then we create a link to it
        # user_overlay_location="${ICRN_USER_KERNEL_BASE}/${language_lower}/${targetname}-${version}/"
        echo "checking for: "$absolute_path
        
        case $language in
            "R")
                if [ -z "$overlay_path" ] || [ "$overlay_path" = "null" ]; then
                    echo "ERROR: Overlay path missing from user catalog for $language $targetname $version."
                    echo "Run 'icrn_manager kernels get $language $targetname $version' to re-register the overlay."
                    exit 1
                fi
                if [ ! -d "$overlay_path" ]; then
                    echo "ERROR: Overlay path recorded in user catalog does not exist: $overlay_path"
                    echo "Consider cleaning and re-checking out this kernel."
                    exit 1
                fi
                target_kernel_link_path=${ICRN_USER_KERNEL_BASE}/${targetname}
                if [ -e "$target_kernel_link_path" ]; then
                    echo "Found existing link; removing..."
                    echo "$target_kernel_link_path"
                    rm -f "$target_kernel_link_path"
                fi
                if [ -d "$absolute_path" ]; then
                    echo "Found. Linking and Activating..."
                    ln -s $absolute_path $target_kernel_link_path 
                    ${target_r_libs_script} ${target_r_environ_file} $absolute_path $overlay_path
                    echo "Done."
                else
                    echo "Path could not be found. There is a problem with your user catalog."
                    echo "Consider cleaning the entry in your catalog via: ./icrn_manager kernels clean $language $targetname $version"
                    echo "And then checking out the kernel again."
                    exit 1
                fi
                ;;
            "Python")
                if [ -d "$absolute_path" ]; then
                    echo "Found. Activating Python kernel..."
                    
                    # Check if kernel is already installed
                    kernel_name="${targetname}-${version}"
                    display_name="${targetname} ${version}"
                    
                    # Check if kernel already exists
                    if jupyter kernelspec list 2>/dev/null | grep -q "^$kernel_name\$"; then
                        echo "Kernel $kernel_name already exists. Removing..."
                        jupyter kernelspec uninstall -y "$kernel_name" 2>/dev/null || echo "Failed to remove existing kernel"
                    fi
                    
                    # Activate the conda environment and install the kernel
                    echo "Installing Python kernel: $kernel_name"
                    source "$absolute_path/bin/activate"
                    
                    # Install the kernel
                    python -m ipykernel install --user --name "$kernel_name" --display-name="$display_name" 2>/dev/null
                    
                    # Deactivate the environment
                    source "$absolute_path/bin/deactivate"
                    
                    echo "Python kernel installation complete."
                    echo "Kernel '$kernel_name' is now available in Jupyter."
                else
                    echo "Path could not be found. There is a problem with your user catalog."
                    echo "Consider cleaning the entry in your catalog via: ./icrn_manager kernels clean $language $targetname $version"
                    echo "And then checking out the kernel again."
                    exit 1
                fi
                ;;
            *)
                echo "Unsupported language '$language' for kernel activation"
                echo "Supported languages: R, Python"
                exit 1
                ;;
        esac
    fi
}

# Alias for kernels__use() - activate a kernel that has already been checked out.
#
# This is a convenience function that calls kernels__use() with all passed arguments.
#
# Parameters:
#   All arguments are passed through to kernels__use()
#
# Returns:
#   Same as kernels__use()
function kernels__activate() # alias for use
{
    "kernels__use" "$@"
}

# Register the overlay directory path for a kernel in the user's catalog.
#
# This function updates the user catalog with the overlay path for a specific kernel.
# The overlay directory is used for storing user-specific customizations and additional
# packages that should be loaded alongside the kernel.
#
# Parameters:
#   $1 - language: Language of the kernel (e.g., "R", "Python")
#   $2 - targetname: Name of the kernel
#   $3 - version: Version number of the kernel
#
# Returns:
#   0 if overlay path was successfully registered, 1 if overlay directory not found
#
# Side effects:
#   Updates the user catalog JSON file with the overlay_path field
function register_user_overlay_in_user_catalog() # add the overlay location to the users catalog
{
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift

    language_lower=$(echo "$language" | tr '[:upper:]' '[:lower:]')
    user_overlay_location="${ICRN_USER_KERNEL_BASE}/${language_lower}/${targetname}-${version}/"
    echo checking for: $user_overlay_location
    if [ -e $user_overlay_location ]; then
        echo "Found."
        echo "Updating user's catalog with $user_overlay_location"
        user_catalog_tmp=$(mktemp)
        jq -r ".\"$language\".\"$targetname\".\"$version\".\"overlay_path\"=\"$user_overlay_location\"" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"
        # user catalog now contains path to this kernel's main R library.
        echo "Done."
        echo ""
        echo "Be sure to call \"icrn_manager kernels use $language $targetname $version\" to begin using this kernel in R."
        return 0
    else
        echo "ERROR: Could not register the overlay location."
        return 1
    fi
}

# Identify and register the R library location for an R kernel in the user catalog.
#
# This function determines the main library path of an R kernel installation by
# executing Rscript to query the library paths. It then updates the user catalog
# with the absolute path to the R library directory.
#
# Parameters:
#   $1 - target_unpacked: Path to the unpacked R kernel conda environment
#   $2 - language: Language of the kernel (should be "R")
#   $3 - targetname: Name of the kernel
#   $4 - version: Version number of the kernel
#
# Returns:
#   0 if R library path was successfully registered, 1 if conda environment not found
#
# Side effects:
#   - Executes Rscript to determine library paths
#   - Updates the user catalog JSON file with the absolute_path field
function register_r_library_in_user_catalog() # without unpacking, identify R kernel library location
{
    local target_unpacked=$1; shift
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift
    
    # echo checking for: $target_unpacked"/bin/activate"
    # if [ -e $target_unpacked"/bin/activate" ]; then
    echo checking for: $target_unpacked"/conda-meta"
    if [ -d $target_unpacked"/conda-meta" ]; then
        # WARNING: this is weak - relies on preparer and environment ensuring this is top slot
        # --vanilla ensures that we aren't interpreting an existing kernel-fu environment variable
        # "R_HOME=''" ensures we don't get complaints from R that R_HOME is set, but we're calling a Rscript that isn't located there
        # we want to get a very plain readout of where this R install's main kernel is.
        echo "getting R path."
	    target_kernel_path=$(R_LIBS='' R_HOME='' R_LIBS_USER='' R_LIBS_SITE='' $target_unpacked/bin/Rscript --vanilla -e 'cat(.libPaths()[1])')
        echo "determined: $target_kernel_path"
        
        echo "Updating user's catalog with $target_kernel_path"
        user_catalog_tmp=$(mktemp)
        jq -r ".\"$language\".\"$targetname\".\"$version\"={\"absolute_path\":\"$target_kernel_path\"}" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"
        # user catalog now contains path to this kernel's main R library.
        echo "Done."
        echo ""
        echo "Be sure to call \"icrn_manager kernels use $language $targetname $version\" to begin using this kernel in R."
        return 0
    else
        # echo "ERROR: Could not find conda environment activation script at $target_unpacked/bin/activate"
        echo "ERROR: Could not confirm target is a conda environment via existence of $target_unpacked/conda-meta"
        return 1
    fi
}

# Register the Python kernel environment path in the user catalog.
#
# This function updates the user catalog with the absolute path to a Python kernel's
# conda environment. The environment must have a bin/activate script to be recognized
# as a valid conda environment.
#
# Parameters:
#   $1 - target_unpacked: Path to the unpacked Python kernel conda environment
#   $2 - language: Language of the kernel (should be "Python")
#   $3 - targetname: Name of the kernel
#   $4 - version: Version number of the kernel
#
# Returns:
#   0 if Python environment path was successfully registered, 1 if activation script not found
#
# Side effects:
#   Updates the user catalog JSON file with the absolute_path field
function register_python_library_in_user_catalog() # unpack and configure a Python kernel environment
{
    local target_unpacked=$1; shift
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift
    
    echo checking for: $target_unpacked"/bin/activate"
    if [ -e $target_unpacked"/bin/activate" ]; then
        # presence of $target_unpacked"/bin/activate" indicates this is a conda environment as expected        
        echo "Updating user's catalog with $language $targetname and $version"
        user_catalog_tmp=$(mktemp)
        jq -r ".\"$language\".\"$targetname\".\"$version\"={\"absolute_path\":\"$target_unpacked\"}" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"
        
        echo "Done."
        echo ""
        echo "Be sure to call \"icrn_manager kernels use $language $targetname $version\" to begin using this kernel in Python."
        return 0
    else
        echo "ERROR: Could not find conda environment activation script at $target_unpacked/bin/activate"
        return 1
    fi
}

# Alias for kernels__get_in_place() - check out a kernel from the central repository.
#
# This is a convenience function that calls kernels__get_in_place() with all passed arguments.
#
# Parameters:
#   All arguments are passed through to kernels__get_in_place()
#
# Returns:
#   Same as kernels__get_in_place()
function kernels__get() # alias for get in place
{
    "kernels__get_in_place" "$@"
}

# Check out a kernel from the central repository without relocating it.
#
# This function retrieves a kernel from the central repository and registers it in the
# user catalog. The kernel remains in its original location in the central repository.
# For R kernels, it also creates an overlay directory for user-specific packages.
# The function validates input parameters to prevent path traversal and wildcard attacks.
#
# Parameters:
#   $1 - language: Language of the kernel (e.g., "R", "Python")
#   $2 - targetname: Name of the kernel to check out
#   $3 - version: Version number of the kernel
#
# Returns:
#   Exits with status 1 if:
#     - Parameters are missing or invalid
#     - Invalid characters detected in kernel name or version (security check)
#     - Kernel not found in central catalog
#     - Target environment location not found
#     - Security violation detected (path would escape intended directory)
#
# Side effects:
#   - Creates overlay directory for R kernels
#   - Updates user catalog with kernel paths
#   - Validates input to prevent security vulnerabilities
function kernels__get_in_place() # prep for 'use' without relocating kernel
{
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift

    # ensure we get a uc-first label for lang
    language="$(tr '[:lower:]' '[:upper:]' <<< ${language:0:1})${language:1}"

    # Validate input parameters to prevent path traversal and wildcard attacks
    if [[ "$targetname" =~ [\]\/\[\*\?\\] ]] || [[ "$version" =~ [\]\/\[\*\?\\] ]]; then
        echo "Error: Invalid characters in kernel name or version. Cannot contain wildcards (*?[]) or path separators (/)"
        exit 1
    fi
    
    if [ -z $version ] || [ -z $targetname ] || [ -z $language ]; then
        echo "usage: icrn_manager kernels get <language> <kernel name> <version number>"
        help
        exit 1
    else
        echo "Desired kernel:"
        echo "Language: "$language
        echo "Kernel: "$targetname
        echo "Version: "$version
        
    fi
    icrn_catalog=${ICRN_KERNEL_CATALOG}
    user_catalog=${ICRN_USER_CATALOG}
    echo ""
    echo "ICRN Catalog:"
    echo $icrn_catalog
    echo "User Catalog:"
    echo $user_catalog
    echo ""
    
    # get the target file from the ICRN catalog
    # target_file=$(jq -r ".$language.$targetname.\"$version\".\"conda-pack\"" $icrn_catalog)
    target_location=$(jq -r ".$language.$targetname.\"$version\".\"environment_location\"" $icrn_catalog)
    if [ ! "$target_location" = "null" ]; then
                
        # language, targetname, and version specify the path for a conda-activate command
        # language, targetname, and version also specify the info for the overlay directory creation
        # we need to get the R-path needed and register it in the user's config
        # we need to get the users overlay library, and register it in the user's config
    
        if [ -e $target_location ]; then
            # identify overlay library location, make it if it doesn't exist
            # what to do if it DOES exist? - nothing, i think.
            # Create language-specific subdirectory structure
            language_lower=$(echo "$language" | tr '[:upper:]' '[:lower:]')
            user_overlay_location="${ICRN_USER_KERNEL_BASE}/${language_lower}/${targetname}-${version}/"
            
            # Safety check: ensure the path is within the intended directory
            if [[ "$user_overlay_location" != "$ICRN_USER_KERNEL_BASE"* ]]; then
                echo "Error: Security violation - target path would escape intended directory"
                echo "Target: $user_overlay_location"
                echo "Base: $ICRN_USER_KERNEL_BASE"
                exit 1
            fi
            
            if [ ! -d "$user_overlay_location" ]; then
                echo "Making target directory: $user_overlay_location"
                mkdir -p "$user_overlay_location"
            else
                echo "NOTICE: target directory: $user_overlay_location already exists."
            fi
            
            # Use language-specific unpacking function
            case $language in
                "R")
                    echo "registering R library"
                    register_r_library_in_user_catalog "$target_location" "$language" "$targetname" "$version"
                    echo "registering user overlay"
                    if ! register_user_overlay_in_user_catalog "$language" "$targetname" "$version"; then
                        echo "ERROR: Failed to register user overlay for $language $targetname $version"
                        echo "Please ensure ${ICRN_USER_KERNEL_BASE} is writable and retry the checkout."
                        exit 1
                    fi
                    ;;
                "Python")
                    register_python_library_in_user_catalog "$target_location" "$language" "$targetname" "$version"
                    ;;
                *)
                    echo "ERROR: Unsupported language '$language' for kernel unpacking"
                    echo "Supported languages: R, Python"
                    exit 1
                    ;;
            esac
        else
            echo "ERROR: could not find target environment location: $target_location"
            exit 1
        fi
    else
        echo "ERROR: could not find target kernel to get"
        get_versions_for_package "$icrn_catalog" "$language" "$targetname"
        exit 1
    fi
}

# Update a user's copy of a kernel from the central repository.
#
# This function is currently not implemented. It is intended to update an existing
# checked-out kernel to a newer version or refresh it from the central repository.
#
# unclear this will be required under new approach of non-relocation of central kernels
# perhaps re-point to newer version of central kernel, and update R-packages?
# low on to-do list
#
# Parameters:
#   (To be determined when implemented)
#
# Returns:
#   Currently exits with status 1 (not implemented)
#
# Side effects:
#   None (function not yet implemented)
function kernels__update() # update users copy of a kernel from central repo
{
    echo "entered 'update' subcommand"
    echo "method not yet implemented."
    exit 1    
}

# Remove a kernel entry from the user's catalog.
#
# This function removes a kernel entry from the user catalog. If a version is specified,
# only that version is removed. If no version is specified, all versions of the kernel
# are removed. If removing a version leaves no versions for a kernel, the entire
# kernel entry is removed from the catalog.
#
# Parameters:
#   $1 - language: Language of the kernel (e.g., "R", "Python")
#   $2 - targetname: Name of the kernel to remove
#   $3 - version: Optional version number. If omitted, all versions are removed
#
# Returns:
#   Exits with status 1 if:
#     - Required parameters are missing
#     - Kernel not found in user catalog
#     - Specified version not found in user catalog
#
# Side effects:
#   - Updates the user catalog JSON file by removing the specified entry
#   - Removes empty kernel entries if all versions are removed
function kernels__clean() # remove a kernel entry from the users catalog
{
    local language=$1; shift
    local targetname=$1; shift
    local version=$1; shift

    icrn_catalog=${ICRN_KERNEL_CATALOG}
    user_catalog=${ICRN_USER_CATALOG}
    echo ""
    echo "ICRN Catalog:"
    echo $icrn_catalog
    echo "User Catalog:"
    echo $user_catalog
    echo ""


    if [ -z "$version" ] && [ -z "$targetname" ] && [ -z "$language" ]; then
        echo "usage: icrn_manager kernels clean <language> <kernel name> <version number>"
        help
        exit 1
    else
        echo "Desired kernel to scrub from user catalog:"
        echo "Language: "$language
        echo "Kernel: "$targetname
        echo "Version: "$version
        echo ""
    fi
    check_for_catalog_entry "$user_catalog" "$language" "$targetname"
    if [ $last_check = 0 ]; then
        echo "$targetname not present in user catalog at $user_catalog"
        exit 1
    else
        last_check=-1
    fi

    if [ -z "$version" ]; then
        user_catalog_tmp=$(mktemp) && \
        jq -r "del(.\"$language\".\"$targetname\")" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"

    else
        check_for_catalog_entry "$user_catalog" "$language" "$targetname" "$version"
        if [ $last_check = 0 ]; then
            echo "$version for $targetname not present in user catalog at $user_catalog"
            get_versions_for_package $user_catalog $language $targetname
            exit 1
        else
            last_check=-1
        fi
        user_catalog_tmp=$(mktemp) && \
        jq -r "del(.\"$language\".\"$targetname\".\"$version\")" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"
        if [ $(jq -r ".\"$language\".\"$targetname\"" "$user_catalog") = "{}" ]; then
            # if the removal of that version of $targetname results in there being no versions of targetname, remove the entire key.
            user_catalog_tmp=$(mktemp) && \
            jq -r "del(.\"$language\".\"$targetname\")" "$user_catalog" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "$user_catalog"
        fi

    fi
}

# Initialize the ICRN Manager by creating necessary directories and configuration files.
#
# This function sets up the initial environment for ICRN Manager, creating:
# - User base directory (~/.icrn/)
# - Kernel base directory (~/.icrn/icrn_kernels/)
# - Language-specific subdirectories (r/, python/)
# - User catalog JSON file
# - Manager configuration JSON file
#
# It also validates that the central repository and its components exist.
#
# Parameters:
#   $1 - central_repository: Optional path to the central kernel repository.
#        If not provided, uses the default path (/sw/icrn/jupyter/icrn_ncsa_resources/Kernels)
#
# Returns:
#   No return value
#
# Side effects:
#   - Creates directory structure in user's home directory
#   - Creates and populates configuration files
#   - Updates existing configuration if central_repository is provided
#   - Prints warnings if central repository components are not found
function kernels__init() # create base resources
{
    echo "Initializing icrn kernel resources..."
    local central_repository=$1; shift
    overwrite=""
    if [ -z $central_repository ]; then
        central_repository=${central_catalog_default}
    else
	echo "will overwrite location"
	overwrite="yes"
    fi
    echo ""
    echo "central catalog location will be: ${central_repository}"
    echo ""
    
    # Determine which paths will be affected
    ICRN_MANAGER_CONFIG=${ICRN_MANAGER_CONFIG:-${ICRN_USER_BASE}/manager_config.json}
    
    echo "The following paths will be created or modified:"
    echo ""
    
    local paths_to_create=()
    local paths_to_overwrite=()
    
    # Check ICRN_USER_BASE
    if [ ! -e "${ICRN_USER_BASE}/" ]; then
        paths_to_create+=("${ICRN_USER_BASE}/ (directory)")
    fi
    
    # Check ICRN_USER_KERNEL_BASE
    if [ ! -e "${ICRN_USER_KERNEL_BASE}" ]; then
        paths_to_create+=("${ICRN_USER_KERNEL_BASE} (directory)")
    fi
    
    # Check language-specific subdirectories
    if [ ! -e "${ICRN_USER_KERNEL_BASE}/r" ]; then
        paths_to_create+=("${ICRN_USER_KERNEL_BASE}/r (directory)")
    fi
    
    if [ ! -e "${ICRN_USER_KERNEL_BASE}/python" ]; then
        paths_to_create+=("${ICRN_USER_KERNEL_BASE}/python (directory)")
    fi
    
    # Check ICRN_USER_CATALOG
    if [ ! -e "${ICRN_USER_CATALOG}" ]; then
        paths_to_create+=("${ICRN_USER_CATALOG} (file)")
    fi
    
    # Check ICRN_MANAGER_CONFIG
    if [ ! -e "${ICRN_MANAGER_CONFIG}" ]; then
        paths_to_create+=("${ICRN_MANAGER_CONFIG} (file)")
    elif [ -n "$overwrite" ]; then
        paths_to_overwrite+=("${ICRN_MANAGER_CONFIG} (file - will update central catalog path)")
    fi
    
    # Display paths that will be created
    if [ ${#paths_to_create[@]} -gt 0 ]; then
        echo "Paths that will be CREATED:"
        for path in "${paths_to_create[@]}"; do
            echo "  - $path"
        done
        echo ""
    fi
    
    # Display paths that will be overwritten/modified
    if [ ${#paths_to_overwrite[@]} -gt 0 ]; then
        echo "Paths that will be MODIFIED:"
        for path in "${paths_to_overwrite[@]}"; do
            echo "  - $path"
        done
        echo ""
    fi
    
    # If nothing will be created or modified, inform user
    if [ ${#paths_to_create[@]} -eq 0 ] && [ ${#paths_to_overwrite[@]} -eq 0 ]; then
        echo "All required paths already exist. No changes will be made."
        echo ""
        return 0
    fi
    
    # Ask for confirmation
    read -r -p "Do you want to proceed with these changes? [y/N] " response
    if [[ ! "$response" =~ ^([yY][eE][sS]|[yY])$ ]]; then
        echo "Initialization cancelled."
        exit 0
    fi
    echo ""
    
    # check for existence of 
    #~{HOME}/.icrn/
    #~{HOME}/.icrn/icrn_kernels/
    #~{HOME}/.icrn/user_catalog.json
    echo "Checking for user resources, and creating them if they don't exist..."
    if [ ! -e ${ICRN_USER_BASE}/ ]; then
        echo "creating ${ICRN_USER_BASE}/"
        mkdir -p ${ICRN_USER_BASE}
    else
        echo "base icrn directory exists at ${ICRN_USER_BASE}/"
    fi
    if [ ! -e ${ICRN_USER_KERNEL_BASE} ]; then
        echo "creating ${ICRN_USER_KERNEL_BASE}"
        mkdir -p ${ICRN_USER_KERNEL_BASE}
    else
        echo "base icrn kernel exists at ${ICRN_USER_KERNEL_BASE}"
    fi
    
    # Create language-specific subdirectories
    if [ ! -e ${ICRN_USER_KERNEL_BASE}/r ]; then
        echo "creating ${ICRN_USER_KERNEL_BASE}/r"
        mkdir -p ${ICRN_USER_KERNEL_BASE}/r
    else
        echo "R kernel directory exists at ${ICRN_USER_KERNEL_BASE}/r"
    fi
    
    if [ ! -e ${ICRN_USER_KERNEL_BASE}/python ]; then
        echo "creating ${ICRN_USER_KERNEL_BASE}/python"
        mkdir -p ${ICRN_USER_KERNEL_BASE}/python
    else
        echo "Python kernel directory exists at ${ICRN_USER_KERNEL_BASE}/python"
    fi
    if [ ! -e ${ICRN_USER_CATALOG} ]; then
        echo "creating ${ICRN_USER_CATALOG}"
        echo "{}" > ${ICRN_USER_CATALOG}
    else
        echo "base icrn user catalog exists at ${ICRN_USER_CATALOG}"
    fi

    # Manager config is json, holds location of the central repo (for now), and sub-paths
    # user calls ./icrn_manager kernels init <path to central repo>
    # or omits path, and central repo is defaulted to value above
    # regardless, config must be written in the user's ICRN location for future reference
    # user may edit config to repoint to new central repo
    ICRN_MANAGER_CONFIG=${ICRN_MANAGER_CONFIG:-${ICRN_USER_BASE}/manager_config.json}
    if [ ! -e ${ICRN_MANAGER_CONFIG} ]; then
        echo "creating ${ICRN_MANAGER_CONFIG}"
        echo "{
        \"icrn_central_catalog_path\": \"${central_repository}\",
        \"icrn_r_kernels\": \"R\",
        \"icrn_python_kernels\": \"Python\",
	    \"icrn_kernel_catalog\": \"icrn_kernel_catalog.json\"
        }" > $ICRN_MANAGER_CONFIG
        # non-append enables re-pointing of central repo via 'init' later
    else
        echo "Configuration for manager exists at ${ICRN_MANAGER_CONFIG}"
    fi
    echo ""
    if [ -n "$overwrite" ]; then
	echo "Updating location of central catalog to: $central_repository"
        user_catalog_tmp=$(mktemp)
        jq -r ".\"icrn_central_catalog_path\"=\"$central_repository\"" "${ICRN_MANAGER_CONFIG}" > "$user_catalog_tmp" && mv "$user_catalog_tmp" "${ICRN_MANAGER_CONFIG}"
    fi 
    echo ""
    ICRN_KERNEL_REPOSITORY=$(jq -r ".\"icrn_central_catalog_path\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_R_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_r_kernels\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_PYTHON_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_python_kernels\"" "${ICRN_MANAGER_CONFIG}")
    ICRN_KERNEL_CATALOG=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_kernel_catalog\"" "${ICRN_MANAGER_CONFIG}")

    echo "Checking for ICRN resources..."
    if [ ! -e ${ICRN_KERNEL_REPOSITORY} ]; then
        echo "Warning: Cannot find core kernel base directory at: $ICRN_KERNEL_REPOSITORY"
    else
        echo "Found core kernel base directory: $ICRN_KERNEL_REPOSITORY"
    fi
    if [ ! -e ${ICRN_R_KERNELS} ]; then
        echo "Warning: Cannot find core kernel R root at: $ICRN_R_KERNELS" 
    else
        echo "Found core kernel R root: $ICRN_R_KERNELS"
    fi
    if [ ! -e ${ICRN_PYTHON_KERNELS} ]; then
        echo "Warning: Cannot find core kernel Python root at: $ICRN_PYTHON_KERNELS" 
    else
        echo "Found core kernel Python root: $ICRN_PYTHON_KERNELS"
    fi
    if [ ! -e ${ICRN_KERNEL_CATALOG} ]; then
        echo "Warning: Cannot find core kernel catalog at: $ICRN_KERNEL_CATALOG"
    else
        echo "Found core kernel catalog at: $ICRN_KERNEL_CATALOG"
    fi
    echo "Done."
    echo ""
}

# Check if initialization is needed and perform it automatically if required
#
# This function checks if the ICRN Manager has been initialized by verifying
# the existence of the manager configuration file. If not initialized, it
# automatically calls kernels__init with the default central repository path.
#
# Parameters:
#   None
#
# Returns:
#   0 if initialization was performed, 1 if already initialized
#
# Side effects:
#   - Calls kernels__init() if configuration is missing
#   - Creates user directories and configuration files
function check_and_init_if_needed()
{
    if [ ! -e "${ICRN_MANAGER_CONFIG}" ]; then
        echo "ICRN Manager not initialized. Auto-initializing with default settings..."
        echo ""
        kernels__init
        return 0
    fi
    return 1
}

# Main launcher function for kernel management subcommands.
#
# This function routes kernel-related subcommands to their respective handler functions.
# It provides a unified interface for all kernel operations and includes confirmation
# prompts for destructive operations like 'clean'.
#
# Parameters:
#   $1 - cmdname: Subcommand name (e.g., "init", "list", "available", "get", "use", "clean")
#   $@ - Additional arguments passed to the subcommand handler
#
# Returns:
#   Exits with status 1 if:
#     - No subcommand is specified
#     - Invalid subcommand name is provided
#
# Side effects:
#   - Prompts for confirmation before executing 'clean' subcommand
#   - Calls the appropriate subcommand handler function
function kernels() # launcher
{
    local cmdname=$1; shift
    
    # Auto-initialize if needed (skip for 'init' command itself)
    if [ "$cmdname" != "init" ]; then
        check_and_init_if_needed
        # After auto-init, reload config variables since they may have changed
        if [ -e "${ICRN_MANAGER_CONFIG}" ]; then
            ICRN_KERNEL_REPOSITORY=$(jq -r ".\"icrn_central_catalog_path\"" "${ICRN_MANAGER_CONFIG}")
            ICRN_R_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_r_kernels\"" "${ICRN_MANAGER_CONFIG}")
            ICRN_PYTHON_KERNELS=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_python_kernels\"" "${ICRN_MANAGER_CONFIG}")
            ICRN_KERNEL_CATALOG=${ICRN_KERNEL_REPOSITORY}"/"$(jq -r ".\"icrn_kernel_catalog\"" "${ICRN_MANAGER_CONFIG}")
        fi
    fi
    
    if [ -z "$cmdname" ]; then
        echo ""
        echo Error: No subcommand specified.
        echo ""
        help
        exit 1
    elif [ "$cmdname" = "clean" ]; then
        echo "Removing kernel entries for : $@"
        confirm "Are you sure? [Y/n]"
        kernels__clean "$@"
    elif [ ! -z "$(grep 'function kernels__'${cmdname} $0)" ]; then
        "kernels__$cmdname" "$@"
    else
        echo ""
        echo Error: $cmdname is not a valid subfunction name.
        echo ""
        help
        exit 1
    fi

}

# Display usage information and available commands for ICRN Manager.
#
# This function prints a help message showing the correct usage syntax and
# available subcommands for the icrn_manager tool.
#
# Parameters:
#   None
#
# Returns:
#   No return value
#
# Side effects:
#   Prints help text to stdout
function help() # Show a list of functions
{
    # grep "^function" $0
    echo ""
    echo "usage: "
    echo " $0 kernels <subcommand>"
    echo "    init"
    echo "    update"
    echo "    list"
    echo "    available"
    echo "    get <language> <kernel> <version>"
    echo "    use <language> <kernel> <version>"
    echo "    use <language> none"
    echo " "
    echo " "
}

# check for valid function
if declare -f "$1" >/dev/null 2>&1; then
    if [ ! "$2" = "init" ]; then
        environment_error=false
        if [ ! -e "$ICRN_USER_CATALOG" ]; then
            echo "Couldn't locate user catalog at:"
            echo "$ICRN_USER_CATALOG"
            echo "Did you run `icrn_manager kernels init`?"
            environment_error=true
        fi
        if [ ! -e "$ICRN_KERNEL_CATALOG" ]; then
            echo "Couldn't locate ICRN's central catalog at:"
            echo "$ICRN_KERNEL_CATALOG"
            echo "Please contact support."
            environment_error=true
        fi
        if [ ! -e "$ICRN_USER_BASE" ]; then
            echo "Couldn't locate user's ICRN base directory:"
            echo "$ICRN_USER_BASE"
            echo "Did you run `./icrn_manager kernels init`?"
            environment_error=true
        fi
        if [ ! -e "$ICRN_USER_KERNEL_BASE" ]; then
            echo "Couldn't locate user's ICRN Kernel base directory:"
            echo "$ICRN_USER_KERNEL_BASE"
            echo "Did you run `./icrn_manager kernels init`?"
            environment_error=true
        fi
        if [ ! -e "$ICRN_KERNEL_REPOSITORY" ]; then
            echo "Couldn't locate the ICRN kernel repository:"
            echo "$ICRN_KERNEL_REPOSITORY"
            echo "Please contact support."
            environment_error=true
        fi
        if [ "$environment_error" = true ]; then
            echo "Encountered one or more environment variable errors."
            echo "Cannot continue until errors are resolved."
        fi
    fi
    "$@" 
else
  echo "Function $1 not recognized" >&2
  help
  exit 1
fi