.shellrc

#!/usr/bin/env zsh

# vim:filetype=zsh syntax=zsh tabstop=2 shiftwidth=2 softtabstop=2 expandtab autoindent fileencoding=utf-8

################################################################################
# This file is sourced by all shells. It is used to define the bare minimum shell
# functions and env vars that are needed during bootstrap of a vanilla OS to
# bootstrap installation of all other config files.
# Functions that are only needed in interactive sessions and depend on DOTFILES_DIR
# or other post-clone env vars should live in .aliases instead.
#
# file location: ${HOME}/.shellrc
# load order: .zshenv [.shellrc], .zshrc [.shellrc, .aliases [.shellrc]], .zlogin
################################################################################

# Guard against re-sourcing -- all call sites can unconditionally 'source ~/.shellrc'
# without needing their own check. This return is a no-op cost (single builtin).
# ZSH_VERSION guard ensures the zsh-only '(( $+functions[...] ))' syntax is never
# evaluated by non-zsh runtimes (e.g. direnv's sandbox).
[[ -n "${ZSH_VERSION-}" ]] && (($+functions[is_shellrc_sourced])) && return

# Dummy function to check if shellrc is sourced (mirrors is_aliases_sourced in .aliases)
# Defined immediately after the guard so that any subsequent 'source ~/.shellrc' in zsh
# returns before re-executing env vars, exports, and function definitions below.
is_shellrc_sourced() {
  return 0
}

# execute 'DEBUG=true zsh' to debug the load order of the custom zsh configuration files
[[ -n "${DEBUG:-}" ]] && echo "loading ${0}"

# BASH_VERSION is set by bash but unset in zsh. Any third-party script sourced
# from here (e.g. antidote.zsh) that checks $BASH_VERSION bare will crash under
# set -u with "parameter not set". Pre-set to empty once here so all downstream
# sources are safe without needing per-callsite workarounds.
BASH_VERSION="${BASH_VERSION:-}"

export ZDOTDIR="${ZDOTDIR:-"${HOME}"}"
export XDG_BIN_HOME="${XDG_BIN_HOME:-"${HOME}/.local/bin"}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-"${HOME}/.cache"}"
export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-"${HOME}/.config"}"
export XDG_DATA_HOME="${XDG_DATA_HOME:-"${HOME}/.local/share"}"
export XDG_STATE_HOME="${XDG_STATE_HOME:-"${HOME}/.local/state"}"

# zsh/datetime provides $EPOCHSECONDS and strftime -- used by current_timestamp,
# current_date, current_timestamp_for_filename, format_duration, step_start/end,
# and print_script_start/duration defined later in this file.
# Loaded here (once) so all downstream callers don't need their own zmodload.
# zmodload is idempotent: re-loading an already-loaded module is a no-op.
# Guard with ZSH_VERSION: direnv evaluates .shellrc in bash, which has no zmodload.
[[ -n "${ZSH_VERSION-}" ]] && zmodload zsh/datetime

# Note: Change these as per your settings. Removing or commenting out a variable
# will leave it unset in all shells started after the next login, which will cause
# any alias, script, or operation that depends on it to be silently skipped.

# ------------ Customizable env vars (MUST BE CHANGED to your values) ------------
# The github username where the setup scripts are downloaded from
export GH_USERNAME='vraravam'

# Keybase username (comment out if you don't use Keybase)
export KEYBASE_USERNAME='avijayr'
# --------------------------------------------------------------------------------

# ---------- Env vars for basic/common setup (can be optionally changed) ---------
# This repo is cloned into this location
export DOTFILES_DIR="${XDG_CONFIG_HOME}/dotfiles"

# Branch name of the dotfiles repo that's to be used for testing PR changes before merging
export DOTFILES_BRANCH='master'

# All development codebases are cloned into a subfolder of this folder
export PROJECTS_BASE_DIR="${HOME}/dev"

# Executable scripts that are not shared as part of this public repo are present here
export PERSONAL_BIN_DIR="${HOME}/personal/dev/bin"

# Many configuration files (eg `.envrc`, `.tool-versions`), that might contain sensitive info and so cannot be committed into those repos are stored here and symlinked to their target destination
export PERSONAL_CONFIGS_DIR="${HOME}/personal/dev/configs"

# All browser profiles are captured in this folder (might contain sensitive info like browsing history and so is considered private)
# Use ${USER} (zsh/PAM builtin) instead of $(whoami) to avoid forking a subprocess on every shell start.
export PERSONAL_PROFILES_DIR="${HOME}/personal/${USER}/browser-profiles"

# Keybase home repo name (comment out if you don't use Keybase)
export KEYBASE_HOME_REPO_NAME='home'

# Keybase profiles repo name (comment out if you don't use Keybase)
export KEYBASE_PROFILES_REPO_NAME='profiles'

# SSH folder
export SSH_CONFIGS_DIR="${HOME}/.ssh"
# --------------------------------------------------------------------------------

# ------------- Env vars for upstream setup (SHOULD NOT be changed) --------------
# Github username for setting upstream remote
export UPSTREAM_GH_USERNAME='vraravam' # Note: DO NOT CHANGE THIS
# --------------------------------------------------------------------------------

export LANG='en_US.UTF-8'
# Setting LC_ALL overrides all other LC_* variables.
# LANG is kept as a fallback.
export LC_ALL='en_US.UTF-8'
export LESSCHARSET='utf-8'

# MACHTYPE is not used here: on a vanilla macOS (Apple Silicon) it incorrectly
# reports 'x86_64' instead of 'arm64' -- a confirmed zsh/macOS bug discussed in
# Apple support forums. uname -m is the only reliable source on all machines.
# The outer ${ARCH:-...} honours any value already exported by a parent process.
export ARCH="${ARCH:-"$(uname -m)"}"
export ARCHFLAGS="-arch ${ARCH}"

# Moving homebrew env vars here itself so that the initial homebrew installation
# on a vanilla OS can be done/applied into memory immediately
case "${ARCH}" in
  *arm*)
    export HOMEBREW_PREFIX='/opt/homebrew'
    ;;
  *)
    export HOMEBREW_PREFIX='/usr/local'
    ;;
esac
export HOMEBREW_NO_ANALYTICS=1
export HOMEBREW_CLEANUP_MAX_AGE_DAYS=3
export HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS=3
export HOMEBREW_BAT=1
export HOMEBREW_VERBOSE_USING_DOTS=1
export HOMEBREW_BUNDLE_FILE="${HOME}/Brewfile"
export HOMEBREW_BUNDLE_FILE_GLOBAL="${HOME}/Brewfile"
export HOMEBREW_NO_ENV_HINTS=1
# Note: If the number and size of downloads is large - allow up to 1hr for any single curl transfer.
export HOMEBREW_CURL_EXTRA_CURL_ARGS='--connect-timeout 300 --max-time 3600'
# TODO: Uncomment once this feature has stabilized
# export HOMEBREW_VERIFY_ATTESTATIONS=1

# Antidote plugin manager home -- set explicitly so it is available before antidote.zsh
# is sourced (e.g. in .zlogin). Mirrors antidote's own platform defaults (see get_dir()
# in antidote.zsh): ~/Library/Caches/antidote on macOS, $XDG_CACHE_HOME/antidote on Linux.
# Note: is_macos is not yet defined here; use $OSTYPE directly.
case "${OSTYPE}" in
  *darwin*)
    export ANTIDOTE_HOME="${HOME}/Library/Caches/antidote"
    ;;
  *)
    export ANTIDOTE_HOME="${XDG_CACHE_HOME}/antidote"
    ;;
esac
export ANTIDOTE_ZSH="${HOMEBREW_PREFIX}/opt/antidote/share/antidote/antidote.zsh"
export ANTIDOTE_PLUGIN_ZSH="${ZDOTDIR}/.zsh_plugins.zsh"
export ANTIDOTE_PLUGIN_TXT="${ZDOTDIR}/.zsh_plugins.txt"

# --------------------------------------------------------------------------
# GROUP 1: Bootstrap Utilities
# Available immediately after .shellrc is sourced on a vanilla OS.
# Used by fresh-install-of-osx.sh during first-time installation before the
# dotfiles repo is cloned and before .aliases is loaded.
# --------------------------------------------------------------------------

# --------------------------------------------------------------------------
# 1a. Shell state & basic predicates
# --------------------------------------------------------------------------

# Returns true if $1 is empty or unset.
is_zero_string() {
  [[ -z "${1}" ]]
}

# Returns true if $1 is non-empty.
is_non_zero_string() {
  [[ -n "${1}" ]]
}

# Returns true if the array named $1 has no elements.
is_empty_array() {
  ((${#${(P)1}[@]} == 0))
}

# Returns true if the array named $1 has at least one element.
is_non_empty_array() {
  ((${#${(P)1}[@]} > 0))
}

# Returns true if stdin is a TTY, or if FORCE_COLOR is set (used to enable color
# output in non-TTY subshells such as direnv or CI pipelines).
is_running_in_tty() {
  [[ -t 0 ]] || is_non_zero_string "${FORCE_COLOR:-}"
}

# Joins array elements into a bulleted list string, each on a new line with a 2-space
# indent and '- ' prefix: e.g. "  - item1\n  - item2".
# Usage: join_array <array_name>
# Example: join_array my_arr
#
# NOTE: The delimiter is hardcoded as a literal in the (pj:...:) flag because zsh does
# not expand variables inside parameter expansion flags -- e.g. (pj:${delimiter}:) treats
# ${delimiter} as a literal string rather than expanding it.
join_array() {
  local -a arr=("${(@P)${1:?join_array: array name required}}")
  is_empty_array arr && return
  echo $'\n  - '"${(pj:\n  - :)arr}"
}

# Returns true if the current shell is zsh.
# ${ZSH_VERSION-} uses the '-' operator: if ZSH_VERSION is unset, substitute
# empty string; if set (even to empty), use its value. Combined with -n, this
# is true only when ZSH_VERSION is set AND non-empty -- which is always the case
# when running inside zsh, since zsh unconditionally sets it to a version string.
is_zsh() {
  [[ -n "${ZSH_VERSION-}" ]]
}

# Replaces the value of HOME with '~' to shorten displayed paths.
# Pure-zsh parameter expansion -- no subprocess fork.
#
# Color functions apply tilde substitution automatically via _colorize, so any
# path passed through a color function is display-ready without an explicit call
# here. Call this explicitly only for:
#   - Bare echo/printf call sites that display paths WITHOUT a color wrapper.
#   - Plain-text segments in section headers (not passed through a color function).
#
# NOTE: when searching for all substitution sites, also grep for '_colorize' --
# it centralises the inline expansion ${2//${HOME}/~} (see comment there for why
# it is inlined rather than calling this function).
replace_home_with_tilde() {
  echo "${1//${HOME}/~}"
}

# Remove trailing slash if present. Pure parameter expansion -- no subprocess.
strip_trailing_slash() {
  echo "${1%\/}"
}

# Returns the portion of $1 before the first occurrence of $2 (default: space).
# Usage: extract_first_word <string> [delimiter]
extract_first_word() {
  local input="${1}"
  local delimiter="${2:- }"
  local first_part="${input%%${delimiter}*}"
  echo "${first_part}"
}

# --------------------------------------------------------------------------
# 1b. Terminal colors
# --------------------------------------------------------------------------

# Do not use colors if there's no terminal
if ! is_running_in_tty; then
  NC=''
  BLACK=''
  DARK_GRAY=''
  RED=''
  LIGHT_RED=''
  GREEN=''
  LIGHT_GREEN=''
  ORANGE=''
  YELLOW=''
  BLUE=''
  LIGHT_BLUE=''
  PURPLE=''
  LIGHT_PURPLE=''
  CYAN=''
  LIGHT_CYAN=''
  LIGHT_GRAY=''
  WHITE=''
else
  # Variables are assigned as $'\e[...' literals -- avoids $(colorize ...) subshell
  # forks on every shell start.
  NC=$'\e[0m'         # No Color
  BLACK=$'\e[0;30m'
  DARK_GRAY=$'\e[1;30m'
  RED=$'\e[0;31m'
  LIGHT_RED=$'\e[1;31m'
  GREEN=$'\e[0;32m'
  LIGHT_GREEN=$'\e[1;32m'
  ORANGE=$'\e[0;33m'
  YELLOW=$'\e[1;33m'
  BLUE=$'\e[0;34m'
  LIGHT_BLUE=$'\e[1;34m'
  PURPLE=$'\e[0;35m'
  LIGHT_PURPLE=$'\e[1;35m'
  CYAN=$'\e[0;36m'
  LIGHT_CYAN=$'\e[1;36m'
  LIGHT_GRAY=$'\e[0;37m'
  WHITE=$'\e[1;37m'
fi

# Single implementation point for all color functions -- mirrors the private
# colorize() method in string.rb. Applies tilde substitution AND wraps in ANSI
# codes; public color functions below are one-line delegators.
# $1 = ANSI color variable (e.g. ${YELLOW}), $2 = string to colorize.
# Usage: _colorize <color_var> <string>
#
# Why inline ${2//${HOME}/~} rather than calling replace_home_with_tilde "${2}":
# replace_home_with_tilde prints via 'echo', so capturing it requires a $()
# subshell fork on every call. The inline expansion is a no-fork zsh built-in.
_colorize() { printf "${1}${2//${HOME}/~}${NC}"; }

# Color functions -- ordered by ANSI SGR code (matches variable declarations above).
black()        { _colorize "${BLACK}"        "${1}"; }
dark_gray()    { _colorize "${DARK_GRAY}"    "${1}"; }
red()          { _colorize "${RED}"          "${1}"; }
light_red()    { _colorize "${LIGHT_RED}"    "${1}"; }
green()        { _colorize "${GREEN}"        "${1}"; }
light_green()  { _colorize "${LIGHT_GREEN}"  "${1}"; }
orange()       { _colorize "${ORANGE}"       "${1}"; }
yellow()       { _colorize "${YELLOW}"       "${1}"; }
blue()         { _colorize "${BLUE}"         "${1}"; }
light_blue()   { _colorize "${LIGHT_BLUE}"   "${1}"; }
purple()       { _colorize "${PURPLE}"       "${1}"; }
light_purple() { _colorize "${LIGHT_PURPLE}" "${1}"; }
cyan()         { _colorize "${CYAN}"         "${1}"; }
light_cyan()   { _colorize "${LIGHT_CYAN}"   "${1}"; }
light_gray()   { _colorize "${LIGHT_GRAY}"   "${1}"; }
white()        { _colorize "${WHITE}"        "${1}"; }

# Logging functions are pure formatters: prefix + message. They do NOT apply
# tilde substitution. Any path in the message must be passed through a color
# function (yellow/cyan/etc.) which applies substitution automatically, or
# through replace_home_with_tilde for uncolored plain-text path segments.
# Usage: success|info|warn|debug <message>

# Send a macOS notification center alert. Safe to call even if osascript is absent.
# Strips ANSI escape codes from the message before passing to osascript -- osascript
# has no terminal and would display raw escape sequences as literal characters.
# Named with leading underscore to avoid collision with any system or plugin command
# named 'notify' (e.g. mise's command_not_found_handler) which would return 127
# and trigger the ERR trap in cron scripts.
# Usage: _dotfiles_notify <message> [title]
_dotfiles_notify() {
  local _msg="${1}"
  local _title="${2:-Dotfiles}"
  # Use is_executable rather than command_exists -- osascript is a fixed macOS
  # system binary at a known path, and is_executable checks the file directly
  # ([[ -x ]]) rather than searching functions/aliases/builtins/PATH.
  if is_executable '/usr/bin/osascript'; then
    # Strip ANSI escape sequences inline using zsh parameter expansion -- no subshell fork.
    # (S) = shortest match; ## = one-or-more (requires extendedglob); replaces all occurrences globally.
    # Pattern: ESC + '[' + zero-or-more digits/semicolons + final letter (e.g. \e[0;31m).
    # local_options scopes extendedglob to this function only -- avoids affecting callers.
    # A sed subshell was avoided here because the ERR trap (set in cron scripts) is inherited
    # into $(...) subshells, and shell functions are not available inside them.
    setopt local_options extendedglob
    local _esc=$'\e'
    _msg="${(S)_msg//${_esc}\[[0-9;]##[a-zA-Z]/}"
    osascript -e "display notification \"${_msg}\" with title \"${_title}\"" 2>/dev/null || true
  fi
}

success() {
  # Suppressed when running inside a direnv subshell. DIRENV_IN_ENVRC=1 is set by
  # direnv during .envrc evaluation and survives strict_env (unlike DIRENV_DIR).
  # Cron, CI, and interactive shells are unaffected.
  # Use error for messages that must always be visible regardless of context.
  # if/else avoids a bare '|| echo' where is_non_zero_string returning 1 could
  # trigger an ERR trap in callers running under set -e.
  if ! is_non_zero_string "${DIRENV_IN_ENVRC:-}"; then
    echo "✅ $(green '**SUCCESS**') ${1}"
  fi
}

info() {
  # Suppressed when running inside a direnv subshell. DIRENV_IN_ENVRC=1 is set by
  # direnv during .envrc evaluation and survives strict_env (unlike DIRENV_DIR).
  # Cron, CI, and interactive shells are unaffected.
  # Use error for messages that must always be visible regardless of context.
  # if/else avoids a bare '|| echo' where is_non_zero_string returning 1 could
  # trigger an ERR trap in callers running under set -e.
  if ! is_non_zero_string "${DIRENV_IN_ENVRC:-}"; then
    echo "ℹ️ $(cyan '**INFO**') ${1}"
  fi
}

warn() {
  # Suppressed when running inside a direnv subshell. DIRENV_IN_ENVRC=1 is set by
  # direnv during .envrc evaluation and survives strict_env (unlike DIRENV_DIR).
  # Use error for messages that must always be visible regardless of context.
  # if/else avoids a bare '|| echo' where is_non_zero_string returning 1 could
  # trigger an ERR trap in callers running under set -e.
  if ! is_non_zero_string "${DIRENV_IN_ENVRC:-}"; then
    echo "⚠️ $(light_red '**WARN**') ${1}"
  fi
}

user_action() {
  # Prints a message prompting the user to perform a manual step (e.g. restart
  # an app, run a command, open a URL). Distinct from warn (which signals an
  # unexpected problem) and info (which is purely informational). Suppressed
  # in direnv subshells -- direnv runs headlessly and cannot act on prompts.
  # if/else avoids a bare '|| echo' where is_non_zero_string returning 1 could
  # trigger an ERR trap in callers running under set -e.
  if ! is_non_zero_string "${DIRENV_IN_ENVRC:-}"; then
    echo "➡️ $(yellow '**ACTION**') ${1}"
  fi
}

debug() {
  # Suppressed when running inside a direnv subshell. DIRENV_IN_ENVRC=1 is set by
  # direnv during .envrc evaluation and survives strict_env (unlike DIRENV_DIR).
  # Cron, CI, and interactive shells are unaffected.
  # Use error for messages that must always be visible regardless of context.
  # if/else avoids a bare '|| echo' where is_non_zero_string returning 1 could
  # trigger an ERR trap in callers running under set -e.
  if ! is_non_zero_string "${DIRENV_IN_ENVRC:-}"; then
    echo "⚙️ $(light_purple '**DEBUG**') ${1}"
  fi
}

error() {
  # Inline substitution rather than a color function: the message body is output
  # as plain text (no color wrapper) and also passed to _dotfiles_notify, which receives
  # a raw string -- ANSI codes would appear as literal escape characters there.
  local _msg="${1//${HOME}/~}"
  echo "❌ $(red '**ERROR**') ${_msg} 🤓"
  _dotfiles_notify "${_msg} 🤓" "❌ Error" || true
  return 1
}

# Prints <char> repeated <length> times to stdout. Used by section header
# helpers to generate padding lines. Defaults to '-' for the char and a
# quarter of the terminal width for the length.
# Usage: print_chars_for_length [char] [length]
print_chars_for_length() {
  local char="${1:--}"  # default to using '-'
  # ${COLUMNS} is a zsh special variable updated on SIGWINCH -- no tput fork needed.
  # Fallback to 80 when COLUMNS is 0 (e.g. cron -- no terminal attached).
  local final_length=${2:=$((${COLUMNS:-80} / 4))}
  printf "${char}%.0s" {1..${final_length}}
}

# Internal helper shared by section_header and section_header2.
# Usage: _section_header_impl <header> <char> <glyph> <color_fn> <indent>
_section_header_impl() {
  # Inline substitution rather than a color function: the header is output as
  # plain text between the two colored padding segments -- it has no color wrapper,
  # so color functions cannot apply tilde sub on its behalf.
  local header="${1//${HOME}/~}"
  local char="${2}"
  local glyph="${3}"
  local color_fn="${4}"
  local indent="${5:-}"
  local indent_len=${#indent}
  # ${COLUMNS} is a zsh special variable -- no tput subprocess fork needed.
  # Fallback to 80 when COLUMNS is 0 (e.g. cron -- no terminal attached).
  local viewport_length=${COLUMNS:-80}
  local header_length=${#header}
  local final_length=$(((viewport_length - header_length - indent_len) / 2 - 10))

  # Pre-compute the padding string once to avoid calling print_chars_for_length
  # twice via $(...) -- each $(...) call forks a subshell.
  local padding
  printf -v padding "${char}%.0s" {1..${final_length}}
  echo "${indent}$(${color_fn} "${padding}") ${glyph} ${header} $(${color_fn} "${padding}")"
}

section_header() {
  _section_header_impl "${1}" '=' '⏳' 'light_blue'
}

# Sub-level section header: used for steps nested inside a top-level section_header.
# Uses '-' padding, a '🔷' glyph, cyan colour, and 2-space indent to visually subordinate it.
section_header2() {
  _section_header_impl "${1}" '-' '🔷' 'cyan' '  '
}

# Formats a duration given in seconds into a human-readable string "HH:MM:SS".
# Writes the result directly into the caller-supplied variable name (no subshell).
# Usage: format_duration <seconds> <varname>
# Example: format_duration 3725 my_var  →  my_var="01h:02m:05s"
format_duration() {
  local _fd_seconds="${1}" _fd_varname="${2}"
  printf -v "${_fd_varname}" '%02dh:%02dm:%02ds' \
    $((_fd_seconds / 3600)) \
    $(((_fd_seconds % 3600) / 60)) \
    $((_fd_seconds % 60))
}

# Writes the current datetime as "YYYY-MM-DD HH:MM:SS" into the caller-supplied variable.
# Usage: current_timestamp <varname>
current_timestamp() {
  strftime -s "${1}" '%Y-%m-%d %H:%M:%S' "${EPOCHSECONDS}"
}

# Writes the current date as "YYYY-MM-DD" into the caller-supplied variable.
# Suitable for lexicographic date comparisons.
# Usage: current_date <varname>
current_date() {
  strftime -s "${1}" '%Y-%m-%d' "${EPOCHSECONDS}"
}

# Writes the current datetime as "YYYY-MM-DD-HH-MM" into the caller-supplied variable.
# Suitable for use in filenames and hostnames (no colons or spaces).
# Usage: current_timestamp_for_filename <varname>
current_timestamp_for_filename() {
  strftime -s "${1}" '%Y-%m-%d-%H-%M' "${EPOCHSECONDS}"
}

# Prints a timestamped "Script started at" banner. Call at the top of main() and
# capture $EPOCHSECONDS before calling to pass to print_script_summary later.
# Only prints when this is the outermost script -- nested subprocess scripts
# stay silent so the outer script's banner is unambiguous in cron output.
print_script_start() {
  # is_outermost_script || return 0: safe under set -e -- both branches resolve
  # to exit 0 (|| only fires when is_outermost_script returns 1, and return 0
  # exits with 0). Avoids the && pattern where the false branch returns 1.
  is_outermost_script || return 0
  local start_time_human
  current_timestamp start_time_human
  echo "$(cyan "${_SCRIPT_NAME:-}") $(purple '==>') $(yellow 'Script started at:') $(light_blue "${start_time_human}")"
}

# Prints a "Script finished at / Total duration" banner.
# Usage: print_script_duration <start_epoch_seconds>
# If start_epoch_seconds is empty or omitted, returns silently -- safe to call
# unconditionally when the start time may not have been captured.
# Only prints when this is the outermost script -- see print_script_start.
print_script_duration() {
  is_outermost_script || return 0
  local start_time_seconds="${1:-}"
  if is_zero_string "${start_time_seconds}"; then return 0; fi
  local end_time_human
  current_timestamp end_time_human
  local end_time_seconds="${EPOCHSECONDS}"
  local duration=$((end_time_seconds - start_time_seconds))

  local duration_human
  format_duration "${duration}" duration_human

  echo "$(cyan "${_SCRIPT_NAME:-}") $(purple '==>') $(yellow 'Script finished at:') $(light_blue "${end_time_human}") ($(yellow 'Total duration:') $(light_blue "${duration_human}") $(yellow 'seconds'))."
}

# --------------------------------------------------------------------------
# 1c. Global state variables
#
# Variables that form the shared-state backbone of .shellrc and the scripts
# that source it. Documented here in one place to make the relationships
# between them clear.
#
# CONVENTION -- three tiers, same _ prefix for tiers 2 and 3:
#
#   _DOTFILES_* ALL_CAPS  (exported env var)
#     Internal infrastructure. Inherited by subprocesses via export.
#     Examples: _DOTFILES_SCRIPT_DEPTH, _DOTFILES_CRON_BACKUP_FILE.
#
#   _lowercase  typeset -a at file scope  (non-exported global)
#     Process-wide arrays declared once in this file. Shared by all
#     functions in the same process without exporting.
#     Examples: _script_start_times, _step_start_times.
#
#   _lowercase  local -a / local in main()  (dynamically-scoped local)
#     Declared in each script's main(). Zsh's dynamic scoping makes them
#     readable by callees without being passed as arguments.
#     Examples: _step_warnings, _step_errors, _current_section.
#
# The declaration context (typeset -a at file scope vs. local inside main())
# and surrounding comments distinguish tiers 2 and 3 -- no additional naming
# difference is needed.
#
# --- Collection-pattern locals (tier 3) ---
#
#   _step_warnings          (local -a in each script's main())
#     Array of non-critical recoverable issue strings. Populated by
#     _record_warning(). Read and printed by print_script_summary().
#
#   _step_errors            (local -a in each script's main())
#     Array of significant non-fatal failure strings. Populated by
#     _record_error(). Read and printed by print_script_summary().
#
#   _current_section        (local in each script's main())
#     String tracking which named section/step is currently executing.
#     Set directly (no 'local') inside helpers like _perform_update so
#     the assignment writes into main()'s local via dynamic scoping.
#     Included in every _record_warning/_record_error message as context.
#
# --- Depth counter (tier 1) ---
#
#   _DOTFILES_SCRIPT_DEPTH  (exported env var)
#     Integer counter incremented by each main() that uses the collection
#     pattern. Inherited by subprocess scripts via export. Since subprocess
#     env changes do not propagate back to the parent, the parent's depth
#     is unaffected by any inner script's execution.
#     print_script_summary() uses this to suppress output when depth > 1,
#     ensuring only the outermost script's summary is printed.
#
# --- Step-timing globals (tier 2) ---
#
#   _script_start_times     (typeset -a, non-exported global)
#     Stack of epoch-second timestamps for script-level start times.
#     Used by step_end() to compute total-elapsed. Must be populated by
#     scripts that use step_start/step_end (fresh-install, software-updates-
#     cron). Scripts that only call print_script_summary() without
#     step_start/step_end do not need it.
#
#   _step_start_times       (typeset -a, non-exported global)
#     Stack of epoch-second timestamps for individual step start times.
#     Pushed by step_start(), popped by step_end(). Supports nested steps.
#
# --- Cron infrastructure (tier 1) ---
#
#   _DOTFILES_CRON_BACKUP_FILE  (exported env var)
#     Path to the temporary crontab backup file. Written by suspend_cron()
#     and fresh-install-of-osx.sh before cron is removed. Read by
#     resume_cron() and EXIT/ERR traps to restore the crontab on exit or
#     failure.
# --------------------------------------------------------------------------

# Dynamically-scoped locals (_step_warnings, _step_errors, _current_section) are declared
# with 'local' inside each script's main() -- no top-level initialisation needed here.

# Non-exported globals: step-timing stacks used by step_start/step_end.
# Two consumers, two mechanisms -- intentionally separate:
#
#   print_script_summary [start_time]
#     Takes its start time as an optional argument (a local variable captured
#     at the top of main()). When non-empty, calls print_script_duration
#     internally. This keeps it self-contained and usable by scripts that
#     never call step_start/step_end (e.g. run-all.rb,
#     cleanup-browser-profiles.rb) -- those scripts do NOT push to
#     _script_start_times and have no need to.
#
#   step_end
#     Needs a "total elapsed since script start" value independently of
#     whatever argument was passed to print_script_summary.  It reads
#     _script_start_times[-1] for this.  Scripts that call step_start/step_end
#     (fresh-install-of-osx.sh, software-updates-cron.sh) MUST push their
#     start epoch onto _script_start_times so step_end's total-elapsed column
#     is correct.
#
# Consequence: if step_start/step_end are ever added to a script that
# only calls print_script_summary (run-all.rb, cleanup-browser-profiles.rb),
# that script must also push its start epoch onto _script_start_times,
# otherwise step_end will fall back to the current time and report 0s elapsed.
typeset -a _script_start_times=()
typeset -a _step_start_times=()

# Exported infrastructure: well-known path for suspend_cron/resume_cron.
# Exported so subshells and ERR/EXIT trap handlers share the same path even
# when they run before .aliases is sourced.
export _DOTFILES_CRON_BACKUP_FILE="${TMPDIR:-/tmp}/crontab_backup"

# --------------------------------------------------------------------------
# 1d. Step timing helpers
# Used by fresh-install-of-osx.sh and software-updates-cron.sh for per-step
# progress reporting. See print_script_start/duration (section 1b) for
# overall script timing, which is independent of this stack-based mechanism.
# --------------------------------------------------------------------------

# Initialise the script-level clock.  Pushes if the stack is empty so the same
# process can define a later epoch without clobbering the original.  Safe to
# call multiple times.
step_timing_init() {
  if is_empty_array _script_start_times; then
    _script_start_times+=("${EPOCHSECONDS}")
  fi
}

# Record the start of a step.  Should be called just before section_header.
step_start() {
  step_timing_init
  _step_start_times+=("${EPOCHSECONDS}")
}

# Print how long the most recent step took, plus total elapsed since init.
step_end() {
  local now delta_step delta_total
  now="${EPOCHSECONDS}"

  # Pop the most recent step start time from the stack.
  # If the step stack is empty (e.g. step_end called without a matching
  # step_start after an error), fall back to the current epoch's start time
  # from the script timings stack so the duration stays meaningful.
  local step_start_time
  if is_empty_array _step_start_times; then
    if is_non_empty_array _script_start_times; then
      step_start_time="${_script_start_times[-1]}"
      warn "step_end called without matching step_start; using current epoch start time as fallback"
    else
      step_start_time="${now}"
      warn "step_end called without any timing stack initialised; using current time as fallback"
    fi
  else
    step_start_time="${_step_start_times[-1]}"
    _step_start_times=("${(@)_step_start_times[1,-2]}")
  fi

  delta_step=$((now - step_start_time))
  local step_human
  format_duration "${delta_step}" step_human

  # Use the most recently pushed script-start epoch for total elapsed.
  local script_start_time
  if is_non_empty_array _script_start_times; then
    script_start_time="${_script_start_times[-1]}"
  else
    script_start_time="${now}"
    warn "step_end: _script_start_times is empty; total elapsed will be 0"
  fi
  delta_total=$((now - script_start_time))
  local total_human
  format_duration "${delta_total}" total_human

  echo "$(purple '    ⏱') $(yellow 'step:') $(light_blue "${step_human}") $(yellow '| elapsed:') $(light_blue "${total_human}")"
}

# Append a non-critical issue to _step_warnings (declared local in the calling script's main).
# Also emits an inline warn so the issue is visible in the log at the point it occurs.
# Relies on zsh dynamic scoping: the caller's main() must declare:
#   local _current_section='(init)'
#   local -a _step_warnings=()
# Each entry is prefixed with [_SCRIPT_NAME][_current_section] for traceability in nested calls.
_record_warning() {
  local msg="${1:-unknown warning}"
  _step_warnings+=("[${_SCRIPT_NAME:-unknown}][${_current_section:-unknown}] ${msg}")
  warn "${msg}"
}

# Append a significant non-fatal failure to _step_errors (declared local in the calling script's main).
# Also emits an inline warn so the failure is visible in the log at the point it occurs.
# Relies on zsh dynamic scoping: the caller's main() must declare:
#   local _current_section='(init)'
#   local -a _step_errors=()
# Each entry is prefixed with [_SCRIPT_NAME][_current_section] for traceability in nested calls.
_record_error() {
  local msg="${1:-unknown error}"
  _step_errors+=("[${_SCRIPT_NAME:-unknown}][${_current_section:-unknown}] ${msg}")
  warn "${msg}"
}

# Print a grouped summary of all warnings and errors collected via _record_warning/_record_error.
# Reads _step_warnings and _step_errors from the caller's scope via zsh dynamic scoping.
# Must be called after shellrc is sourced (uses section_header and warn).
#
# Usage: print_script_summary [start_epoch_seconds [message]]
#
# Accepts an optional start time (epoch seconds from $EPOCHSECONDS, captured
# before print_script_start). When provided, calls print_script_duration
# internally -- no separate call needed. Omit when no start time is available
# (e.g. early-exit paths before the start epoch was captured).
# Accepts an optional info message as $2. When provided, it is printed via
# info before the warnings/errors list -- use this instead of a bare info/success
# call immediately before print_script_summary. Guarded with ${2:-} so omitting
# it is safe under set -u.
# Only prints when this is the outermost script in a nested call chain.
# _SCRIPT_NAME is read directly via zsh dynamic scoping -- no argument needed.
print_script_summary() {
  # is_outermost_script || return 0: safe under set -e -- see print_script_start.
  is_outermost_script || return 0
  local _pss_start_time="${1:-}"
  local _pss_msg="${2:-}"
  local _pss_title="${_SCRIPT_NAME:-}"

  local viewport_length=${COLUMNS:-80}
  local final_length=$(((viewport_length) * 3 / 4))
  echo $(dark_gray "$(print_chars_for_length '*' ${final_length})")

  if is_non_zero_string "${_pss_msg}"; then info "${_pss_msg}"; fi
  if (($+_step_warnings)) && is_non_empty_array _step_warnings; then
    _section_header_impl "$(cyan "${_pss_title}") $(yellow "${#_step_warnings[@]} warning(s)")" '-' '⏳' 'orange'
    local _psw
    for _psw in "${_step_warnings[@]}"; do
      warn "  ${_psw}"
    done
  fi
  if (($+_step_errors)) && is_non_empty_array _step_errors; then
    _section_header_impl "$(cyan "${_pss_title}") $(red "${#_step_errors[@]} error(s) -- manual attention needed")" '-' '⏳' 'light_red'
    local _pse
    for _pse in "${_step_errors[@]}"; do
      warn "  ${_pse}"
    done
  fi
  # Send exactly one notification when there are issues to report, gated solely
  # on whether errors/warnings were collected -- independent of the title source.
  # Success notifications are intentionally omitted -- the user can see success in
  # the terminal. Notifications are reserved for failures that warrant attention,
  # especially in headless/cron contexts. Scripts with custom success notifications
  # (e.g. fresh-install, software-updates-cron) handle them outside this function.
  local -a _pss_parts=()
  if (($+_step_errors))   && is_non_empty_array _step_errors; then   _pss_parts+=("${#_step_errors[@]} error(s)"); fi
  if (($+_step_warnings)) && is_non_empty_array _step_warnings; then _pss_parts+=("${#_step_warnings[@]} warning(s)"); fi
  if is_non_empty_array _pss_parts; then
    _dotfiles_notify "${_pss_title}: completed with ${(j: and :)_pss_parts}." "⚠️ ${_pss_title}" || true
  fi
  if is_non_zero_string "${_pss_start_time}"; then print_script_duration "${_pss_start_time}"; fi
}

# --------------------------------------------------------------------------
# 1e. Filesystem & OS predicates
# --------------------------------------------------------------------------

# Returns true if the current machine is ARM (Apple Silicon or other arm64 CPU).
is_arm() {
  # == glob is faster than =~ (no regex engine); valid in both bash [[ ]] and zsh.
  [[ "${ARCH}" == *arm* ]]
}

# Returns true if $1 is a non-empty path pointing to an executable file or command.
is_executable() {
  is_non_zero_string "${1}" && [[ -x "${1}" ]]
}

# Returns true if $1 is a non-empty path that is a symbolic link.
is_symbolic_link() {
  is_non_zero_string "${1}" && [[ -L "${1}" ]]
}

# Returns true if $1 is a non-empty path pointing to a regular file.
is_file() {
  is_non_zero_string "${1}" && [[ -f "${1}" ]]
}

# Returns true if target file ($1) is missing or older than source file ($2).
# Uses the shell's built-in -nt (newer-than) test which compares modification times.
# Common pattern: if is_file_older_than "$cache" "$source"; then regenerate_cache; fi
#
# Arguments:
#   $1 - target file path (typically a cache file)
#   $2 - source file path (typically a binary or config file)
#
# Returns:
#   0 (true) if target is missing or source is newer (regeneration needed)
#   1 (false) if target exists and is newer than or same age as source (cache valid)
#
# Examples:
#   if is_file_older_than "$cache" "$binary"; then "$binary" --generate-cache; fi
#   if is_file_older_than "${git_version_cache}" "${git_bin}"; then cache_git_version; fi
is_file_older_than() {
  [[ ! -f "${1}" || "${2}" -nt "${1}" ]]
}

# Returns true if $1 is a non-empty path pointing to a directory.
is_directory() {
  is_non_zero_string "${1}" && [[ -d "${1}" ]]
}

# Returns true if $1 is a regular file with non-zero size.
is_non_empty_file() {
  is_file "${1}" && [[ -s "${1}" ]]
}

is_directory_empty() {
  # $(ls -A) kept intentionally -- the pure-zsh glob alternative (*(ND[1])) cannot
  # be used here because .shellrc is sourced by direnv in bash, and bash has no
  # zsh glob qualifiers.  A ZSH_VERSION branch was considered but rejected: the
  # function is only called a handful of times (e.g. set_ssh_folder_permissions),
  # never on the startup hot path, so the ls fork cost is negligible.
  is_directory "${1}" && [[ -z "$(ls -A "${1}")" ]]
}

# Creates $1 (and any intermediate directories) if it does not already exist.
# Warns and skips silently if $1 is empty or unset.
# Guards with is_directory to avoid forking mkdir when the directory already
# exists -- the common case on every shell startup (e.g. XDG_CACHE_HOME).
ensure_dir_exists() {
  if is_non_zero_string "${1}"; then
    is_directory "${1}" || mkdir -pv "${1}"
  else
    warn "Skipping creation of the directory since '$(purple "${1}")' is not defined"
  fi
}

# Ruby load path for shared utilities -- add both dotfiles and personal bin to RUBYLIB
# so Ruby scripts can use 'require' instead of 'require_relative' for shared utilities.
# Only add directories that exist.
# Guarded by is_zsh: the array join syntax '${(j.:.)array}' is zsh-only and when direnv
# sources this file in bash, this block must be skipped.
if is_zsh; then
  RUBYLIB_PATHS=()
  is_directory "${DOTFILES_DIR}/scripts/utilities" && RUBYLIB_PATHS+=("${DOTFILES_DIR}/scripts/utilities")
  is_directory "${PERSONAL_BIN_DIR}" && RUBYLIB_PATHS+=("${PERSONAL_BIN_DIR}")
  if is_non_empty_array RUBYLIB_PATHS; then
    export RUBYLIB="${(j.:.)RUBYLIB_PATHS}${RUBYLIB:+:${RUBYLIB}}"
  fi
  unset RUBYLIB_PATHS
fi

# Returns true if $1 is a non-empty path whose direct child .git directory exists.
# Checks the repo root explicitly -- does not work from nested sub-directories by design.
is_git_repo() {
  is_non_zero_string "${1}" && is_directory "${1}/.git"
  # git -C "${1}" rev-parse --is-inside-work-tree &>/dev/null  # alternative that works from any nested sub-directory
}

# Returns the git config value for <key> in [folder] (defaults to $PWD).
# Returns an empty string silently if the key is not set -- callers decide whether that is an error.
# Usage: get_git_config_value <key> [folder]
get_git_config_value() {
  local key="${1}" folder="${2:-${PWD}}"
  git -C "${folder}" config --get "${key}" 2>/dev/null || true
}

# Sources $1 if it is a non-empty path pointing to a regular file; warns otherwise.
load_file_if_exists() {
  is_file "${1}" && source "${1}" || warn "Couldn't load file: '$(cyan "${1}")'"
}

# delete_directory_if_exists() {
#   is_directory "${1}" && echo "$(red 'Deleting') '$(green "${1}")'" && sudo rm -rf "${1}"
# }

# Returns true if $1 names a known command, function, alias, or shell builtin.
command_exists() {
  (($+commands[${1}] || $+functions[${1}] || $+aliases[${1}] || $+builtins[${1}]))
}

# Returns true if the current OS is macOS.
is_macos() {
  # == glob is faster than =~ (no regex engine); valid in both bash [[ ]] and zsh.
  [[ "${OSTYPE}" == *darwin* ]]
}

# Returns true if the current OS is Linux.
is_linux() {
  # == glob is faster than =~ (no regex engine); valid in both bash [[ ]] and zsh.
  [[ "${OSTYPE}" == *Linux* ]]
}

# Returns true if FIRST_INSTALL is set to a non-empty value.
# ${FIRST_INSTALL:-} uses the ':-' operator: if FIRST_INSTALL is unset OR empty,
# substitute empty string; if set and non-empty, use its value. Combined with -n,
# this is true only when FIRST_INSTALL holds a real value -- treating unset and
# set-but-empty identically. This is intentional: only a deliberate non-empty
# assignment (e.g. FIRST_INSTALL=true) should activate vanilla-OS behaviour.
# Note: two occurrences in fresh-install-of-osx.sh use the raw form because
# they run before _download_and_source_shellrc has sourced .shellrc.
is_first_install() {
  [[ -n "${FIRST_INSTALL:-}" ]]
}

# Returns true if the current OS is Windows (MSYS/MinGW environment).
is_windows() {
  # == glob is faster than =~ (no regex engine); consistent with is_macos/is_linux.
  [[ "${OSTYPE}" == *MINGW* ]]
}

# Returns true if this is the outermost script in a nested call chain.
# _DOTFILES_SCRIPT_DEPTH is exported and incremented by each main() that uses
# the deferred-collection pattern. Subprocesses inherit the counter but their
# increments do not propagate back to the parent. Defaults to 0 when unset so
# standalone scripts (which never set the counter) are treated as outermost --
# consistent with the ':-0' used in the increment expression in each main().
is_outermost_script() {
  [[ ${_DOTFILES_SCRIPT_DEPTH:-0} -le 1 ]]
}

# Decrements _DOTFILES_SCRIPT_DEPTH, guarding against underflow. Called from
# EXIT traps in every script that increments the counter. Mirrors
# Logging.decrement_script_depth in logging.rb.
_decrement_script_depth() {
  if [[ ${_DOTFILES_SCRIPT_DEPTH:-0} -gt 0 ]]; then
    export _DOTFILES_SCRIPT_DEPTH=$((_DOTFILES_SCRIPT_DEPTH - 1))
  fi
}

# Returns true if sudo credentials are currently cached (i.e. sudo can run
# without prompting for a password). Use this to guard any function that calls
# sudo and may be invoked from cron or other non-interactive contexts where a
# prompt would hang indefinitely.
has_sudo_credentials() {
  sudo -n true 2>/dev/null
}

# --------------------------------------------------------------------------
# 1f. PATH & environment variable manipulation
# --------------------------------------------------------------------------

# Append helpers: each adds $1 to the named variable only if $1 is an
# existing directory. No-op if the directory does not exist. Safe to call
# multiple times -- the underlying path arrays deduplicate in zsh.
append_to_path_if_dir_exists() {
  is_directory "${1}" && path+="${1}"
}

append_to_fpath_if_dir_exists() {
  is_directory "${1}" && fpath+="${1}"
}

# --------------------------------------------------------------------------
# 1g. Bootstrap operations
# Called by fresh-install-of-osx.sh and post-brew-install.sh.
# set_ssh_folder_permissions is also called from ~/.envrc directly.
# --------------------------------------------------------------------------

# Asks for the administrator password upfront and keeps it alive until the calling script
# finishes. Uses a background loop that refreshes sudo every 60 seconds.
# Safe to call multiple times -- skips silently if the background loop is already running.
keep_sudo_alive() {
  # Avoid duplicate background loops (e.g. when child scripts also call this)
  if is_non_zero_string "${KEEP_SUDO_ALIVE_PID:-}" && kill -0 "${KEEP_SUDO_ALIVE_PID}" 2>/dev/null; then
    return
  fi
  step_start
  section_header2 "$(yellow 'Keeping sudo alive till this script has finished')"
  sudo -v
  while true; do has_sudo_credentials; sleep 60; kill -0 "$$" || exit; done 2>/dev/null &
  export KEEP_SUDO_ALIVE_PID=$!
  step_end
}

# Migrates a git repo from the legacy loose/packed-refs format to reftable.
# Requires git 2.45+; silently skips on older git (e.g. the system git on a
# vanilla macOS, which does not support 'git refs migrate'). After migration
# it removes stale loose-ref files that 'git refs migrate' may leave behind in
# .git/refs/heads/, .git/refs/tags/, and .git/refs/remotes/ -- those stale
# files confuse some git operations even though the canonical refs now live in
# the reftable directory.
# Usage: migrate_git_repo_to_reftable [repo-dir]
#   repo-dir defaults to $PWD when omitted -- use this to migrate the repo in
#   the current directory without having to specify the path explicitly.
migrate_git_repo_to_reftable() {
  local repo_dir="${1:-${PWD}}"
  if ! is_git_repo "${repo_dir}"; then return 0; fi

  # git rev-parse --show-ref-format was added in git 2.45; fall back to 'files'
  # on older git so the guard below correctly detects a non-reftable repo.
  local ref_format
  ref_format="$(git -C "${repo_dir}" rev-parse --show-ref-format 2>/dev/null || echo 'files')"
  if [[ "${ref_format}" == 'reftable' ]]; then return 0; fi

  # 'git refs migrate' requires git 2.45+. On older git (vanilla macOS system
  # git) this returns non-zero; skip silently -- fresh-install calls this again
  # after Homebrew's modern git is on PATH.
  if ! git -C "${repo_dir}" refs migrate --ref-format=reftable 2>/dev/null; then
    debug "git refs migrate unavailable (requires git 2.45+) -- skipping reftable migration for '$(yellow "${repo_dir}")'"
    return 0
  fi

  # 'git refs migrate' writes all refs to the reftable directory and should
  # clear loose refs, but may leave behind empty files in the legacy
  # .git/refs/{heads,tags,remotes}/ trees. Remove them so they cannot shadow
  # the canonical reftable entries.
  # Named helper instead of anonymous '()': bash can parse 'name() {}' at file
  # load time; '()' is a parse-time error in bash even inside 'if is_zsh'.
  # setopt is a runtime-only issue in bash and this function is never called
  # from bash, so no is_zsh guard is needed.
  _remove_loose_reftable_refs() {
    setopt localoptions NULL_GLOB
    rm -f "${repo_dir}/.git/refs/heads/"* "${repo_dir}/.git/refs/tags/"* "${repo_dir}/.git/refs/remotes/"*
  }
  _remove_loose_reftable_refs
  # Named functions defined inside another function persist in the global table
  # after the outer function returns -- unfunction immediately after use to avoid
  # polluting the global namespace in non-subshell call sites (e.g. direct
  # interactive calls, clone_repo_into from fresh-install-of-osx.sh).
  unfunction _remove_loose_reftable_refs

  success "Migrated '$(cyan "${repo_dir}")' refs to reftable format"
}

# Clones a git repo into a temp folder, moves the .git dir into the real target
# location, and does an initial checkout there. Works around git's refusal to
# clone into a non-empty directory (e.g. HOME). If the target is already a git
# repo, runs fetch-unshallow instead. Always updates submodules afterwards.
# Usage: clone_repo_into <repo-url> <target-folder> [branch]
clone_repo_into() {
  local start_time=${EPOCHSECONDS}  # $EPOCHSECONDS from zsh/datetime -- no $(date +%s) fork
  local target_folder="${2}"
  ensure_dir_exists "${target_folder}"
  if ! is_git_repo "${target_folder}"; then
    # Since git does not allow cloning into a non-empty folder (like the home folder), clone into a temp folder, then copy the .git folder into the real target location, and do a checkout
    local tmp_folder
    tmp_folder="$(mktemp -d)"
    # Note: Do not use --depth while cloning since that messes up when using upstream to rebase from
    GIT_SSH_COMMAND="ssh -o ConnectTimeout=20" git -C "${tmp_folder}" clone -q -c init.defaultRefFormat=reftable "${1}" .
    if [[ $? -ne 0 ]]; then
      warn "Failed to clone '$(cyan "${1}")' into '$(cyan "${target_folder}")'"
      return 1
    fi

    mv "${tmp_folder}/.git" "${target_folder}"
    rm -rf "${tmp_folder}"
    git -C "${target_folder}" restore .

    # Correct HEAD file after reftable clone-via-mv (.git/HEAD retains a '.invalid' placeholder since
    # the move bypasses git's normal post-clone finalisation; shell prompts read .git/HEAD directly)
    local real_ref
    real_ref="$(git -C "${target_folder}" symbolic-ref HEAD 2>/dev/null)"
    is_non_zero_string "${real_ref}" && echo "ref: ${real_ref}" >"${target_folder}/.git/HEAD"

    # Migrate to reftable if the clone used the legacy files format. On a vanilla
    # macOS the system git (< 2.45) ignores -c init.defaultRefFormat=reftable and
    # 'git refs migrate' is unavailable, so this is a no-op until Homebrew's git
    # is on PATH. fresh-install-of-osx.sh calls this again post-Homebrew for repos
    # that were cloned with system git.
    migrate_git_repo_to_reftable "${target_folder}"

    success "Successfully cloned '$(cyan "${1}")' into '$(cyan "${target_folder}")'"

    local target_branch="${3:-}"
    if is_non_zero_string "${target_branch}"; then
      git -C "${target_folder}" switch "${target_branch}"
      local checked_out_branch
      checked_out_branch="$(git -C "${target_folder}" branch --show-current)"
      [[ "${checked_out_branch}" != "${target_branch}" ]] && error "'${target_branch}' is not equal to the branch that was checked out: '${checked_out_branch}'; something is wrong. Please correct before retrying!"
    fi
  else
    # is_git_repo = (is_non_zero_string && is_directory .git) -- logical complement of the if above,
    # so this else is exhaustive and the condition check is redundant.
    debug "Fetching '$(yellow "${target_folder}")' since it's already a git repo"
    git -C "${target_folder}" fetch-unshallow
    success "Successfully fetched '$(cyan "${1}")' into '$(cyan "${target_folder}")'"
    # Only warn if FETCH_HEAD has commits not yet in HEAD -- fetch-unshallow always
    # runs but may bring in nothing new (repo already up to date).
    local incoming_count
    incoming_count="$(git -C "${target_folder}" rev-list HEAD..FETCH_HEAD --count 2>/dev/null || echo 0)"
    if [[ "${incoming_count}" -gt 0 ]]; then
      warn 'Remember to merge the incoming changes into the working tree!'
    fi
  fi

  # Always update submodules after clone or pull -- new commits may introduce submodule changes.
  GIT_SSH_COMMAND="ssh -o ConnectTimeout=20 -o ServerAliveInterval=10 -o ServerAliveCountMax=3" git -C "${target_folder}" submodule update --init --recursive --remote --rebase --force
  local end_time=${EPOCHSECONDS}  # no $(date +%s) fork
  local duration=$((end_time - start_time))
  debug "Process took ${duration} seconds"
}

# Sets secure permissions on SSH_CONFIGS_DIR (700 on the directory, 600 on all
# files) and adds any bare identity files (id_*) to the ssh-agent keychain.
# Kept in .shellrc for two independent reasons:
#   1. Bootstrap: called in fresh-install-of-osx.sh before install-dotfiles.rb
#      creates the ~/.aliases symlink (vanilla OS pre-symlink window).
#   2. Bash-compat: called from .envrc files (evaluated by direnv in a bash
#      subshell); .aliases contains zsh-only syntax and cannot be sourced in bash.
set_ssh_folder_permissions() {
  info "$(yellow 'Setting ssh config file permissions')"
  ensure_dir_exists "${SSH_CONFIGS_DIR}"
  # Set directory permissions first
  if ! chmod 700 "${SSH_CONFIGS_DIR}"; then
    warn "Failed to set permissions on '$(cyan "${SSH_CONFIGS_DIR}")'"
    return
  fi

  if ! is_directory_empty "${SSH_CONFIGS_DIR}"; then
    find "${SSH_CONFIGS_DIR}" -type f -exec chmod 600 {} \; && success "Ensured correct permissions for '$(cyan "${SSH_CONFIGS_DIR}")' and files within it." || warn "Failed to set file permissions in '$(cyan "${SSH_CONFIGS_DIR}")'"

    find "${SSH_CONFIGS_DIR}" -maxdepth 1 -name "id_*" ! -name '*.*' -type f -exec ssh-add -q "{}" \; && success "Added ssh identity files from '$(cyan "${SSH_CONFIGS_DIR}")'." || warn "Failed to add ssh identity files from '$(cyan "${SSH_CONFIGS_DIR}")'"
  else
    warn "'$(cyan "${SSH_CONFIGS_DIR}")' exists but is empty. No file permissions to set."
  fi
}

# Runs "$@" and evals its stdout into the current shell environment.
# Silently skips if the command fails or produces no output (stderr suppressed).
# Usage: eval_shellenv <command> [args...]  e.g. eval_shellenv brew shellenv
eval_shellenv() {
  local output
  if output="$("$@" 2>/dev/null)"; then
    eval "${output}"
  fi
}

# --------------------------------------------------------------------------
# 1h. Cron management - bootstrap layer
#
# Contains the primitives needed to safely suspend and resume cron around any
# script that may run before (or during) a fresh install, including before the
# dotfiles repo has been cloned.  These functions only depend on utilities
# already defined in this file (is_file, is_non_empty_file, ensure_dir_exists,
# debug/info/success/warn/error) so they are guaranteed to be available the
# moment .shellrc is sourced on any machine.
#
# The higher-level cron helpers (_create_crontab, recron) live in .aliases
# because they reference DOTFILES_DIR, HOMEBREW_PREFIX, and other variables
# that are only meaningful after the dotfiles repo has been cloned and the full
# shell environment has been set up.  See the matching section in .aliases for
# those functions and a fuller explanation of the split.
# --------------------------------------------------------------------------
# Helper functions for delegating to Ruby utilities
# --------------------------------------------------------------------------

# Internal helper: calls a Ruby Cron module method with positional arguments.
# Eliminates duplication of $LOAD_PATH setup across cron wrapper functions.
# Usage: _call_ruby_cron <method_name> [args...]
# Example: _call_ruby_cron create_crontab "/path/to/file"
#          _call_ruby_cron recron
_call_ruby_cron() {
  local method="${1:-}"
  if is_zero_string "${method}"; then
    error '_call_ruby_cron: method name required'
    return 1
  fi
  shift

  local args_str=""
  if [[ $# -gt 0 ]]; then
    # Build comma-separated list of single-quoted Ruby string literals.
    local -a args_parts=()
    for arg in "$@"; do
      args_parts+=("'${arg}'")
    done
    # Join with ', '
    local IFS=', '
    args_str="${args_parts[*]}"
  fi

  ruby -e "\$LOAD_PATH.unshift('${DOTFILES_DIR}/scripts/utilities'); require 'cron'; Cron.${method}(${args_str})"
}

# Loads a cron file into the system crontab. Shared by suspend_cron/resume_cron
# (bootstrap layer, here) and recron (.aliases layer) so neither duplicates logic.
# Thin wrapper that delegates to Ruby Cron.restore_cron.
# Usage: restore_cron <cron-file-path>
restore_cron() {
  _call_ruby_cron restore_cron "$@"
}

# Thin wrapper that delegates to Ruby Cron.suspend_cron.
# Backs up the current crontab to _DOTFILES_CRON_BACKUP_FILE and removes all cron jobs.
suspend_cron() {
  _call_ruby_cron suspend_cron
}

# Thin wrapper that delegates to Ruby Cron.resume_cron.
# Restores crontab from _DOTFILES_CRON_BACKUP_FILE and cleans up the backup file.
resume_cron() {
  _call_ruby_cron resume_cron
}

# --------------------------------------------------------------------------
# 1i. Config reloading (used post-bootstrap to apply changes)
# --------------------------------------------------------------------------

# Reloads zsh configuration files in order (.zshenv → .zshrc → .zlogin).
# WARNING: sourcing these files from a context that is itself sourced by them
# can cause infinite loops. Use only for manual post-change reloads or targeted
# bootstrap scenarios (e.g. fresh-install applying new config mid-run).
load_zsh_configs() {
  # _SCRIPT_NAME is set as a script-scoped global in each script; unset in
  # interactive shells. The fallback makes the caller visible in both contexts.
  debug "load_zsh_configs called from '$(yellow "${_SCRIPT_NAME:-<interactive>}")'"
  local file
  local file_list=('.zshenv' '.zshrc' '.zlogin')
  for file in "${file_list[@]}"; do
    # ${ZDOTDIR} is safe to use here: this function is defined inside .shellrc,
    # so .shellrc must have already run -- and .shellrc initialises ZDOTDIR at
    # line 38 (export ZDOTDIR="${ZDOTDIR:-"${HOME}"}") before this function is
    # ever defined. ZDOTDIR is therefore always set correctly, even in cron or
    # fresh-install subshell contexts where .zshenv has not been sourced.
    debug "load_zsh_configs: loading '$(cyan "${ZDOTDIR}/${file}")'"
    load_file_if_exists "${ZDOTDIR}/${file}"
  done
}

# Prints a standardized usage message and exits.
# Used by scripts in $DOTFILES_DIR/scripts/ that may be invoked during fresh-install
# before install-dotfiles.rb has run (e.g. add-upstream-git-config.rb).
# Usage: print_usage <script-name> <option-descriptions...>
#
# Example:
#   print_usage "${0:t}" \
#     "-a <app-name>  --> (mandatory) The application name" \
#     "-v             --> (optional) Verbose output"
print_usage() {
  local script_name="${1}"
  shift
  echo "$(red 'Usage'): $(cyan "${script_name}") $(yellow "${1:+"[options]"}")"
  while [[ $# -gt 0 ]]; do
    echo "  ${1}"
    shift
  done
  exit 1
}