help

#!/usr/bin/env bash
#
# List all scripts with their description and usage.
# With an argument, show detailed help for a specific script.
# Prerequisites: Bash, Git, Docker. Optional: ShellCheck (for linting).
#
# Usage: ./help
#        ./help install
#        ./help ./install
#
set -euo pipefail # exit on error, undefined vars, or pipe failures
. "$(dirname "$0")"/lib/debug_info # print debug info and check prerequisites

# If an argument is provided, show detailed help for that script
if [ $# -gt 0 ]; then
  script="${1#./}" # strip leading "./" if present (e.g. "./install" -> "install")

  # Check that the script exists and is a bash script
  if [ ! -f "$script" ]; then
    echo "Error: script '$script' not found" >&2 # >&2 prints to stderr
    exit 1
  fi

  # Verify it's a bash script (first line must be a bash shebang)
  # head -n 1: read only the first line; grep -q: check for bash shebang
  if ! head -n 1 "$script" | grep -q '^#!/usr/bin/env bash$'; then
    echo "Error: '$script' is not a bash script" >&2 # >&2 prints to stderr
    exit 1
  fi

  # Print the full comment header block from the script
  printf "./%s\n\n" "$script"
  while IFS= read -r line; do
    # Skip shebang (e.g. #!/usr/bin/env bash)
    [[ "$line" == "#!"* ]] && continue
    # Stop at the first non-comment line (end of header)
    [[ "$line" != "#"* ]] && break

    text="${line#\#}"   # strip leading '#'
    text="${text# }"    # strip one leading space (preserves further indentation)

    # Print the comment line (empty lines become blank lines for readability)
    printf "  %s\n" "$text"
  done < "$script" # read from the script file

  exit 0
fi

# Find all user-facing scripts (files in root with bash shebang), sorted alphabetically.
# Excludes lib/ files (internal helpers, not intended to be run directly).
scripts=() # array of script names
for f in *; do
  [ -f "$f" ] || continue # skip non-files (directories, globs that didn't match)
  # head -n 1: read only the first line; grep -q: check for bash shebang
  head -n 1 "$f" | grep -q '^#!/usr/bin/env bash$' && scripts+=("$f")
done

# Loop through all scripts in alphabetical order
for script in "${scripts[@]}"; do
  description="" # will hold the first line of the script's comment header
  usage=""       # will hold the Usage: line if present

  # Read the script file line by line to extract the comment header
  while IFS= read -r line; do
    # Skip shebang (e.g. #!/usr/bin/env bash)
    [[ "$line" == "#!"* ]] && continue
    # Stop at the first non-comment line (end of header)
    [[ "$line" != "#"* ]] && break

    text="${line#\#}"   # strip leading '#'
    text="${text# }"    # strip leading space

    # Skip empty comment lines
    if [ -z "$text" ]; then
      continue
    fi

    # Extract usage line or first description line
    if [[ "$text" == Usage:* ]]; then
      usage="${text#Usage: }" # strip "Usage: " prefix
    elif [ -z "$description" ]; then
      description="$text" # first non-empty comment is the description
    fi
  done < "$script" # read from the script file

  # Print the script name, description, and usage (if any)
  printf "./%s\n" "$script"
  printf "  %s\n" "$description"
  if [ -n "$usage" ]; then
    printf "  Usage: %s\n" "$usage"
  fi
  printf "\n"
done