📝 Add docstrings to general-improvements-and-typo-fixes

README.md

@@ -232,7 +232,7 @@ You can also add extra commands by installing "packages".
 - Cloud Posse also provides a large set of packages for installing common DevOps commands
 and utilities via [cloudposse/packages](https://github.com/cloudposse/packages).
 - Google Cloud provides a set of packages for working with GCP
-- OpenTofu provides a packge for installing it, too.
+- OpenTofu provides a package for installing it, too.
 
 Those package repositories are pre-installed in Geodesic, so
 all you need to do is add the packages you want via

README.yaml

@@ -230,7 +230,7 @@ usage: |-
   - Cloud Posse also provides a large set of packages for installing common DevOps commands
   and utilities via [cloudposse/packages](https://github.com/cloudposse/packages).
   - Google Cloud provides a set of packages for working with GCP
-  - OpenTofu provides a packge for installing it, too.
+  - OpenTofu provides a package for installing it, too.
 
   Those package repositories are pre-installed in Geodesic, so
   all you need to do is add the packages you want via

os/debian/Dockerfile.debian

@@ -283,7 +283,7 @@ RUN if [[ -x /usr/local/bin/aws ]]; then mv /usr/local/bin/aws /usr/local/bin/aw
 # Install AWS CLI 2
 # Get AWS CLI V2 version from https://github.com/aws/aws-cli/blob/v2/CHANGELOG.rst if you want
 # but it is updated several times a week, so we choose to just get the latest.
-# It is available in a Debain package `awscli`, but that can be very out of date.
+# It is available in a Debian package `awscli`, but that can be very out of date.
 # ARG AWS_CLI_VERSION=2.15.48
 RUN AWSTMPDIR=$(mktemp -d -t aws-inst-XXXXXXXXXX) && \
       if [ "$TARGETARCH" = "amd64" ]; then \

rootfs/etc/codefresh/require_vars

@@ -26,7 +26,7 @@ function require_cfvar() {
 	echo "$separator"
 	red Build variable \"$var\" has not been set >&2
 
-	# Look for docmentation of VARNAME on the rest of the args
+	# Look for documentation of VARNAME on the rest of the args
 	# First, look for trailing characters on $1 and collect them
 	local rem1=$(expr match "$1" '[^}]*}}[[:blank:]]*\(.*\)')
 
@@ -50,7 +50,7 @@ function require_cfvar() {
 #    EOF
 # Checks each variable with require_cfvar.
 # Variables must be at the start of the line, one per line, but do not need to be quoted.
-# The final EOF must be at the begining of the line.
+# The final EOF must be at the beginning of the line.
 function require_cfvars() {
 	local var
 	local status=0

rootfs/etc/init.d/atlantis.sh

@@ -2,8 +2,7 @@
 
 # Start the atlantis server
 if [ "${ATLANTIS_ENABLED}" == "true" ]; then
-	which atlantis >/dev/null
-	if [ $? -ne 0 ]; then
+	if ! which atlantis >/dev/null; then
 		echo "Atlantis is not installed"
 		exit 1
 	fi
@@ -42,7 +41,7 @@ if [ "${ATLANTIS_ENABLED}" == "true" ]; then
 	export ATLANTIS_CHAMBER_SERVICE=${ATLANTIS_CHAMBER_SERVICE:-atlantis}
 
 	# Export environment from chamber to shell
-	source <(chamber exec ${ATLANTIS_CHAMBER_SERVICE} -- sh -c "export -p")
+	source <(chamber exec "${ATLANTIS_CHAMBER_SERVICE}" -- sh -c "export -p")
 
 	if [ -n "${ATLANTIS_IAM_ROLE_ARN}" ]; then
 		# Map the Atlantis IAM Role ARN to the env we use everywhere in our root modules
@@ -55,11 +54,11 @@ if [ "${ATLANTIS_ENABLED}" == "true" ]; then
 	export ATLANTIS_HOME=${ATLANTIS_HOME:-/home/atlantis}
 
 	# create atlantis user & group
-	(getent group ${ATLANTIS_GROUP} || addgroup ${ATLANTIS_GROUP}) >/dev/null
-	(getent passwd ${ATLANTIS_USER} || adduser -h ${ATLANTIS_HOME} -S -G ${ATLANTIS_GROUP} ${ATLANTIS_USER}) >/dev/null
+	(getent group "${ATLANTIS_GROUP}" || addgroup "${ATLANTIS_GROUP}") >/dev/null
+	(getent passwd "${ATLANTIS_USER}" || adduser -h "${ATLANTIS_HOME}" -S -G "${ATLANTIS_GROUP}" "${ATLANTIS_USER}") >/dev/null
 
 	# Provision terraform cache directory
-	install --directory ${TF_PLUGIN_CACHE_DIR} --owner ${ATLANTIS_USER} --group ${ATLANTIS_GROUP}
+	install --directory "${TF_PLUGIN_CACHE_DIR}" --owner "${ATLANTIS_USER}" --group "${ATLANTIS_GROUP}"
 
 	# Allow atlantis to use /dev/shm
 	if [ -d /dev/shm ]; then
@@ -69,14 +68,14 @@ if [ "${ATLANTIS_ENABLED}" == "true" ]; then
 
 	# Add SSH key to agent, if one is configured so we can pull from private git repos
 	if [ -n "${ATLANTIS_SSH_PRIVATE_KEY}" ]; then
-		source <(gosu ${ATLANTIS_USER} ssh-agent -s)
-		ssh-add - <<<${ATLANTIS_SSH_PRIVATE_KEY}
+		source <(gosu "${ATLANTIS_USER}" ssh-agent -s)
+		ssh-add - <<<"${ATLANTIS_SSH_PRIVATE_KEY}"
 		# Sanitize environment
 		unset ATLANTIS_SSH_PRIVATE_KEY
 	fi
 
 	if [ -n "${ATLANTIS_ALLOW_PRIVILEGED_PORTS}" ]; then
-		setcap "cap_net_bind_service=+ep" $(which atlantis)
+		setcap "cap_net_bind_service=+ep" "$(which atlantis)"
 	fi
 
 	# Do not export these as Terraform environment variables
@@ -92,18 +91,18 @@ if [ "${ATLANTIS_ENABLED}" == "true" ]; then
 	# https://gist.github.com/Kovrinic/ea5e7123ab5c97d451804ea222ecd78a
 
 	# The URL "git@github.com:" is used by `git` (e.g. `git clone`)
-	gosu ${ATLANTIS_USER} git config --global url."https://github.com/".insteadOf "git@github.com:"
+	gosu "${ATLANTIS_USER}" git config --global url."https://github.com/".insteadOf "git@github.com:"
 	# The URL "ssh://git@github.com/" is used by Terraform (e.g. `terraform init --from-module=...`)
 	# NOTE: we use `--add` to append the second URL to the config file
-	gosu ${ATLANTIS_USER} git config --global url."https://github.com/".insteadOf "ssh://git@github.com/" --add
+	gosu "${ATLANTIS_USER}" git config --global url."https://github.com/".insteadOf "ssh://git@github.com/" --add
 
 	# https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage
 	# see rootfs/usr/local/bin/git-credential-github
-	gosu ${ATLANTIS_USER} git config --global credential.helper 'github'
+	gosu "${ATLANTIS_USER}" git config --global credential.helper 'github'
 
 	# Use a primitive init handler to catch signals and handle them properly
 	# Use gosu to drop privileges
 	# Use env to setup the shell environment for atlantis
 	# Then lastly, start the atlantis server
-	exec dumb-init gosu ${ATLANTIS_USER} env BASH_ENV=/etc/direnv/bash atlantis server
+	exec dumb-init gosu "${ATLANTIS_USER}" env BASH_ENV=/etc/direnv/bash atlantis server
 fi

rootfs/etc/profile.d/_40-preferences.sh

@@ -17,7 +17,7 @@ fi
 #
 # Determine the base directory for all customizations.
 # We do some extra processing because GEODESIC_CONFIG_HOME needs to be set as a path in the Geodesic file system,
-# but the user may have set it as a path on the host computer system. We try to accomodate that by
+# but the user may have set it as a path on the host computer system. We try to accommodate that by
 # searching a few other places for the directory if $GEODESIC_CONFIG_HOME does point to a valid directory
 export GEODESIC_CONFIG_HOME
 _GEODESIC_CONFIG_HOME_DEFAULT="/root/.config/geodesic"

rootfs/etc/profile.d/aws.sh

@@ -4,9 +4,10 @@
 # In this script, we do not care about return values, as problems are detected by the resulting empty value.
 
 export AWS_REGION_ABBREVIATION_TYPE=${AWS_REGION_ABBREVIATION_TYPE:-fixed}
-export AWS_DEFAULT_SHORT_REGION=${AWS_DEFAULT_SHORT_REGION:-$(aws-region --${AWS_REGION_ABBREVIATION_TYPE} ${AWS_DEFAULT_REGION:-us-west-2})}
+export AWS_DEFAULT_SHORT_REGION=${AWS_DEFAULT_SHORT_REGION:-$(aws-region --"${AWS_REGION_ABBREVIATION_TYPE}" "${AWS_DEFAULT_REGION:-us-west-2}")}
 export GEODESIC_AWS_HOME
 
+# _aws_config_home locates or creates the AWS configuration directory, exports GEODESIC_AWS_HOME (and may set AWS_CONFIG_FILE), ensures the directory and config file exist with secure permissions, and returns 1 on failure to create a usable directory.
 function _aws_config_home() {
 	for dir in "${GEODESIC_AWS_HOME}" "${LOCAL_HOME}/.aws" "${HOME}/.aws"; do
 		if [ -d "${dir}" ]; then
@@ -80,7 +81,7 @@ function aws_choose_role() {
 }
 
 # Usage: aws_sdk_assume_role <role> [command...]
-# If no command is given, a subshell is started with the role.
+# aws_sdk_assume_role sets ASSUME_ROLE and AWS_PROFILE to the specified role (or an interactively chosen role if none specified) and either launches a login subshell that preserves shell history or executes a given command with that profile, then restores the previous ASSUME_ROLE.
 function aws_sdk_assume_role() {
 	local role=$1
 	shift
@@ -102,13 +103,18 @@ function aws_sdk_assume_role() {
 		history -c
 		history -r
 	else
-		AWS_PROFILE="$role" $*
+		AWS_PROFILE="$role" "$@"
 	fi
 	ASSUME_ROLE="$assume_role"
 }
 
 # Asks AWS what the currently active identity is and
-# sets environment variables accordingly
+# export_current_aws_role sets ASSUME_ROLE to reflect the currently active AWS identity.
+# It inspects the current STS caller identity and the active profile (AWS_PROFILE or AWS_VAULT),
+# attempts to map the active ARN to a more descriptive profile name by consulting the AWS config
+# and credentials files (handling normal IAM roles and Identity Center/SSO roles), warns and
+# exports a redacted marker when the environment profile disagrees with the active identity,
+# and unsets ASSUME_ROLE and returns when no identity can be determined.
 function export_current_aws_role() {
 	local role_name role_names
 	# Could be a primary or assumed role. If we have assumed a role, cut off the session name.
@@ -154,7 +160,8 @@ function export_current_aws_role() {
 					local sso_role_name=$(echo "$role_part" | cut -d'_' -f2) # This selects the second field delimited by '_'
 
 					# Find all profiles that have matching role names
-					local profile_names=($(crudini --get --format=lines "$config_file" | grep "$sso_role_name" | cut -d' ' -f 3))
+					local profile_names
+					mapfile -t profile_names < <(crudini --get --format=lines "$config_file" | grep "$sso_role_name" | cut -d' ' -f 3)
 					local profile_name
 					for profile_name in "${profile_names[@]}"; do
 						# Skip the generic profiles
@@ -173,7 +180,7 @@ function export_current_aws_role() {
 				# Normal IAM role
 				# Assumed roles in AWS config file use the role ARN, not the assumed role ARN, so adjust accordingly.
 				local role_arn=$(printf "%s" "$current_role" | sed 's/:sts:/:iam:/g' | sed 's,:assumed-role/,:role/,')
-				role_names=($(crudini --get --format=lines "$config_file" | grep "$role_arn" | cut -d' ' -f 3))
+				mapfile -t role_names < <(crudini --get --format=lines "$config_file" | grep "$role_arn" | cut -d' ' -f 3)
 				for rn in "${role_names[@]}"; do
 					if [[ $rn == "default" ]] || [[ $rn =~ -identity$ ]]; then
 						continue
@@ -250,14 +257,16 @@ function export_current_aws_role() {
 
 # Keep track of AWS credentials and updates to AWS role environment variables.
 # When changes are noticed, update prompt with current role.
-unset GEODESIC_AWS_ROLE_CACHE # clear out value inherited from supershell
+unset GEODESIC_AWS_ROLE_CACHE # refresh_current_aws_role_if_needed checks whether the active AWS role context has changed and updates cached state if necessary.
+# 
+# It computes a fingerprint from the exported AWS_PROFILE, the modification time of the shared credentials file, and AWS_ACCESS_KEY_ID; if the fingerprint differs from GEODESIC_AWS_ROLE_CACHE it calls export_current_aws_role and updates GEODESIC_AWS_ROLE_CACHE with the new fingerprint.
 function refresh_current_aws_role_if_needed() {
 	local is_exported="^declare -[^ x]*x[^ x]* "
 	local aws_profile=$(declare -p AWS_PROFILE 2>/dev/null)
 	[[ $aws_profile =~ $is_exported ]] || aws_profile=""
 	local credentials_mtime=$(stat -c "%Y" "${AWS_SHARED_CREDENTIALS_FILE:-${GEODESIC_AWS_HOME}/credentials}" 2>/dev/null)
 	local role_fingerprint="${aws_profile}/${credentials_mtime}/${AWS_ACCESS_KEY_ID}"
-	if [[ $role_fingerprint != $GEODESIC_AWS_ROLE_CACHE ]]; then
+	if [[ $role_fingerprint != "$GEODESIC_AWS_ROLE_CACHE" ]]; then
 		export_current_aws_role
 		export GEODESIC_AWS_ROLE_CACHE="${role_fingerprint}"
 	fi
@@ -267,4 +276,4 @@ function refresh_current_aws_role_if_needed() {
 # so only use refresh_current_aws_role_if_needed if they are disabled or overridden
 if [[ ($AWS_OKTA_ENABLED != "true" && ${AWS_VAULT_ENABLED:-false} != "true") || -n $AWS_PROFILE ]]; then
 	PROMPT_HOOKS+=("refresh_current_aws_role_if_needed")
-fi
+fi

rootfs/etc/profile.d/fzf.sh

@@ -10,7 +10,8 @@ fi
 
 # A lot of terminals (including Apple's) do not support 24-bit color and the mapping from 24-bit to 8-bit is horrible.
 # So most of the color schemes are limited to the 256 ANSI colors that nearly every terminal supports.
-# Color schemes that only render properly with 24_bit color support are suffixed with _24
+# _set_fzf_default_opts builds and exports FZF_DEFAULT_OPTS based on the given color scheme.
+# The first argument selects the color scheme (e.g., solar_24, solarized_dark, solarized_light, mild, dark, light, 16, bw); when omitted or unrecognized, a mild/default palette is used.
 
 function _set_fzf_default_opts() {
 	local gray1="232"
@@ -34,7 +35,7 @@ function _set_fzf_default_opts() {
 	local cyan="37"
 	local green="2"
 	local olive="3"
-	local keep="-1" # Keep the exsiting terminal setting for this field
+	local keep="-1" # Keep the existing terminal setting for this field
 
 	local fzf_default_opts
 	case "$1" in
@@ -75,4 +76,4 @@ _set_fzf_default_opts "$FZF_COLORS"
 # Requires fzf v0.18.0 or later
 if [[ $PROMPT_STYLE == plain && ! $FZF_DEFAULT_OPTS =~ --no-unicode ]]; then
 	FZF_DEFAULT_OPTS="${FZF_DEFAULT_OPTS:+${FZF_DEFAULT_OPTS} }--no-unicode"
-fi
+fi

rootfs/etc/profile.d/prompt.sh

@@ -63,6 +63,11 @@ function reload() {
 # Define our own prompt
 PROMPT_HOOKS+=("geodesic_prompt")
 KUBE_PS1_SYMBOL_ENABLE=${KUBE_PS1_SYMBOL_ENABLE:-false}
+# geodesic_prompt Constructs and installs the interactive shell prompt (PS1) using configured style, role, secrets, Terraform and Kubernetes state, and optional banner.
+# 
+# geodesic_prompt selects glyphs and marks based on PROMPT_STYLE (plain, unicode, fancy, or default), computes a level indicator from SHLVL, and sets status/role indicators based on ASSUME_ROLE.
+# It detects active secret environment variables listed in PROMPT_SECRET_ENVS and appends an indicator if any are set, integrates Terraform prompt lines when GEODESIC_TF_PROMPT_ACTIVE is enabled, and adapts the kube prompt prefix for KUBE_PS1.
+# The final PS1 includes an optional BANNER line (with namespace when configured) followed by the directory/host/role segment and prompt glyphs; when no BANNER is defined, PS1 contains only the Terraform and directory segments.
 function geodesic_prompt() {
 
 	case $PROMPT_STYLE in
@@ -119,7 +124,7 @@ function geodesic_prompt() {
 	case $SHLVL in
 	1) level_prompt='.' ;;
 	2) level_prompt=':' ;;
-	3) level_prompt='⋮' ;; # vertical elipsis \u22ee from Mathematical Symbols
+	3) level_prompt='⋮' ;; # vertical ellipsis \u22ee from Mathematical Symbols
 	*) level_prompt="$SHLVL" ;;
 	esac
 	level_prompt=$(bold "${level_prompt}")
@@ -211,4 +216,4 @@ function geodesic_prompt_style() {
 		unset PROMPT_STYLE
 		;;
 	esac
-}
+}

rootfs/etc/profile.d/Ω_overrides.sh

@@ -3,7 +3,7 @@
 # other files that this function needs to be able to see.
 # This file should be the last file in profile.d to execute.
 # This loads user's overrides, which take actions based on any setup that has already occurred.
-# This must come after all setup has happened so that the final configuration is availble for inspection,
+# This must come after all setup has happened so that the final configuration is available for inspection,
 # and there must not be any configuration after this to ensure that anything set here remains set as the user intended.
 
 ## Load user's custom overrides