@pageai/ralph-loop 1.0.0

package/scripts/lib/spinner.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Spinner module for ralph.sh
+# Animated spinner display with step tracking
+# Dependencies: constants.sh, timing.sh, terminal.sh
+
+# Spinner characters
+SPINNER='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
+SPINNER_PID=""
+CURRENT_STEP="Thinking"
+
+# Spinner function - runs in background, reads step from STEP_FILE
+# Usage: start_spinner; do_work; stop_spinner
+start_spinner() {
+  echo "Thinking" > "$STEP_FILE"
+  echo "" > "$PREVIEW_LINE_FILE"
+
+  (
+    # Spinner chars as array for proper unicode handling
+    local -a SPIN_CHARS=(⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
+    local i=0
+    local spin_len=${#SPIN_CHARS[@]}
+    local term_width=$(tput cols 2>/dev/null || echo 80)
+    local preview_max=$((term_width - 6))  # Leave room for "    > "
+    while true; do
+      local step=$(cat "$STEP_FILE" 2>/dev/null || echo "Thinking")
+      local preview=$(cat "$PREVIEW_LINE_FILE" 2>/dev/null || echo "")
+      local char="${SPIN_CHARS[$i]}"
+      # Truncate preview if needed
+      if [ ${#preview} -gt $preview_max ]; then
+        preview="${preview:0:$((preview_max - 3))}..."
+      fi
+      # Line 1: spinner + step, Line 2: dimmed preview
+      printf "\r\033[K  ${C}%s${R} %s" "$char" "$step"
+      if [ -n "$preview" ]; then
+        printf "\n\033[K    ${D}▸ %s${R}\033[A" "$preview"
+      fi
+      i=$(( (i + 1) % spin_len ))
+      sleep 0.1
+    done
+  ) &
+  SPINNER_PID=$!
+}
+
+# Stop the spinner
+stop_spinner() {
+  if [ -n "$SPINNER_PID" ] && kill -0 "$SPINNER_PID" 2>/dev/null; then
+    kill "$SPINNER_PID" 2>/dev/null
+    wait "$SPINNER_PID" 2>/dev/null || true
+    # Clear both lines (spinner and preview)
+    printf "\r\033[K\n\033[K\033[A\r"
+  fi
+  SPINNER_PID=""
+}
+
+# Update spinner step based on output line and record step timing
+update_spinner_step() {
+  local line="$1"
+  local detected=$(detect_step "$line")
+  if [ -n "$detected" ]; then
+    echo "$detected" > "$STEP_FILE"
+
+    # Clean step name (remove trailing spaces) for timing tracking
+    local clean_step=$(echo "$detected" | sed 's/ *$//')
+
+    # Record timing if step changed
+    if [ "$clean_step" != "$CURRENT_STEP_NAME" ]; then
+      record_step_time "$clean_step"
+    fi
+  fi
+}
+
+# Update the preview line shown under the spinner
+update_preview_line() {
+  local line="$1"
+  # Skip empty lines or lines that are just whitespace
+  [ -z "$line" ] && return
+  [[ "$line" =~ ^[[:space:]]*$ ]] && return
+  # Sanitize: replace newlines/tabs with spaces, collapse multiple spaces
+  # This prevents multi-line content from breaking cursor positioning
+  line=$(echo "$line" | tr '\n\t\r' ' ' | sed 's/  */ /g; s/^ *//; s/ *$//')
+  # Skip if sanitization resulted in empty string
+  [ -z "$line" ] && return
+  # Write to preview file (spinner reads this)
+  echo "$line" > "$PREVIEW_LINE_FILE"
+}

package/scripts/lib/terminal.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Terminal module for ralph.sh
+# ANSI support detection and terminal width utilities
+# Dependencies: constants.sh
+
+# Check if terminal supports ANSI escape sequences
+check_ansi_support() {
+  # Check if $TERM is set and not dumb
+  if [ -z "$TERM" ] || [ "$TERM" = "dumb" ]; then
+    ANSI_SUPPORTED=false
+    return
+  fi
+  # Check for known terminal types that don't support ANSI
+  case "$TERM" in
+    dumb|unknown|network)
+      ANSI_SUPPORTED=false
+      return
+      ;;
+  esac
+  # Check if stdout is a terminal
+  if [ ! -t 1 ]; then
+    ANSI_SUPPORTED=false
+    return
+  fi
+  ANSI_SUPPORTED=true
+}
+
+# Get terminal width (default to 80 if unavailable)
+get_terminal_width() {
+  if command -v tput &> /dev/null; then
+    local width=$(tput cols 2>/dev/null)
+    if [ -n "$width" ] && [ "$width" -gt 0 ]; then
+      echo "$width"
+      return
+    fi
+  fi
+  # Fallback to stty
+  if command -v stty &> /dev/null; then
+    local width=$(stty size 2>/dev/null | cut -d' ' -f2)
+    if [ -n "$width" ] && [ "$width" -gt 0 ]; then
+      echo "$width"
+      return
+    fi
+  fi
+  echo "80"
+}
+
+# Truncate line to fit terminal width
+truncate_line() {
+  local line="$1"
+  local max_width="$2"
+  if [ ${#line} -gt $max_width ]; then
+    echo "${line:0:$((max_width - 3))}..."
+  else
+    echo "$line"
+  fi
+}

package/scripts/lib/timing.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+# Timing module for ralph.sh
+# Step timing tracking and duration formatting
+# Dependencies: constants.sh
+#
+# Steps: Thinking, Reading code, Implementing, Writing tests, Testing, Linting,
+#        Typechecking, Committing
+
+# Step timing tracking (using indexed arrays for bash 3.x compatibility)
+STEP_NAMES=("Thinking" "Reading code" "Implementing" "Writing tests" "Testing" "Linting" "Typechecking" "Committing")
+ITERATION_STEP_VALUES=(0 0 0 0 0 0 0 0)   # Step times for current iteration
+SESSION_STEP_VALUES=(0 0 0 0 0 0 0 0)     # Accumulated step times across all iterations
+CURRENT_STEP_NAME=""              # Name of current step being timed
+CURRENT_STEP_START=0              # Timestamp when current step started
+
+# Get step emoji by name (bash 3.x compatible)
+get_step_emoji() {
+  case "$1" in
+    "Thinking") echo "🤔" ;;
+    "Reading code") echo "📖" ;;
+    "Implementing") echo "⚡" ;;
+    "Writing tests") echo "✍️" ;;
+    "Testing") echo "🧪" ;;
+    "Linting") echo "🧹" ;;
+    "Typechecking") echo "📝" ;;
+    "Committing") echo "📦" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Get step index by name (-1 if not found)
+get_step_index() {
+  local name="$1"
+  for i in "${!STEP_NAMES[@]}"; do
+    if [ "${STEP_NAMES[$i]}" = "$name" ]; then
+      echo "$i"
+      return
+    fi
+  done
+  echo "-1"
+}
+
+# Format duration in seconds to MM:SS or HH:MM:SS
+format_duration() {
+  local seconds=$1
+  local hours=$((seconds / 3600))
+  local mins=$(((seconds % 3600) / 60))
+  local secs=$((seconds % 60))
+
+  if [ $hours -gt 0 ]; then
+    printf "%02d:%02d:%02d" $hours $mins $secs
+  else
+    printf "%02d:%02d" $mins $secs
+  fi
+}
+
+# Format delta with color coding (stock market style)
+# Returns: colored string with +/- prefix, or empty if first iteration
+format_delta() {
+  local current=$1
+  local previous=$2
+
+  # Skip if first iteration (no previous time)
+  if [ "$previous" -eq 0 ]; then
+    echo ""
+    return
+  fi
+
+  local delta=$((current - previous))
+
+  if [ $delta -lt 0 ]; then
+    # Faster (green with - prefix)
+    local abs_delta=$((-delta))
+    printf "${GR}-%ds${R}" $abs_delta
+  elif [ $delta -gt 0 ]; then
+    # Slower (red with + prefix)
+    printf "${RD}+%ds${R}" $delta
+  else
+    # Same time
+    printf "~"
+  fi
+}
+
+# Record time spent in current step when transitioning to a new step
+# Usage: record_step_time "new_step_name"
+# Pass empty string to finalize the last step without starting a new one
+record_step_time() {
+  local new_step="$1"
+
+  # If we have a current step, record its elapsed time
+  if [ -n "$CURRENT_STEP_NAME" ] && [ "$CURRENT_STEP_START" -gt 0 ]; then
+    local now=$(date +%s)
+    local elapsed=$((now - CURRENT_STEP_START))
+
+    # Only record if there's actual time (more than 0 seconds)
+    if [ "$elapsed" -gt 0 ]; then
+      local idx=$(get_step_index "$CURRENT_STEP_NAME")
+      if [ "$idx" -ge 0 ]; then
+        # Add to iteration step times
+        local current_time=${ITERATION_STEP_VALUES[$idx]}
+        ITERATION_STEP_VALUES[$idx]=$((current_time + elapsed))
+
+        # Add to session step times
+        local session_time=${SESSION_STEP_VALUES[$idx]}
+        SESSION_STEP_VALUES[$idx]=$((session_time + elapsed))
+      fi
+    fi
+  fi
+
+  # Start timing the new step (if provided)
+  if [ -n "$new_step" ]; then
+    CURRENT_STEP_NAME="$new_step"
+    CURRENT_STEP_START=$(date +%s)
+  else
+    # No new step - clear tracking
+    CURRENT_STEP_NAME=""
+    CURRENT_STEP_START=0
+  fi
+}
+
+# Format step duration for display
+# Usage: format_step_duration 45  # -> "45s"
+# Usage: format_step_duration 125 # -> "02:05"
+format_step_duration() {
+  local seconds=$1
+  if [ "$seconds" -lt 60 ]; then
+    echo "${seconds}s"
+  else
+    local mins=$((seconds / 60))
+    local secs=$((seconds % 60))
+    printf "%02d:%02d" $mins $secs
+  fi
+}
+
+# Format step times as inline display string
+# Usage: format_step_times "ITERATION" or "SESSION"
+# Returns: "│ 🧪 Testing: 45s │ 🧹 Linting: 12s" (sorted by duration descending)
+format_step_times() {
+  local mode="$1"
+  local output=""
+  local sorted_steps=()
+
+  # Build array of "duration:step_name" for sorting
+  for i in "${!STEP_NAMES[@]}"; do
+    local step="${STEP_NAMES[$i]}"
+    local time
+    if [ "$mode" = "SESSION" ]; then
+      time=${SESSION_STEP_VALUES[$i]}
+    else
+      time=${ITERATION_STEP_VALUES[$i]}
+    fi
+    if [ "$time" -gt 0 ]; then
+      sorted_steps+=("$time:$step")
+    fi
+  done
+
+  # Sort by duration descending (reverse numeric sort on first field)
+  if [ ${#sorted_steps[@]} -gt 0 ]; then
+    IFS=$'\n' sorted_steps=($(sort -t: -k1 -rn <<<"${sorted_steps[*]}"))
+    unset IFS
+  fi
+
+  # Build output string
+  for item in "${sorted_steps[@]}"; do
+    local time="${item%%:*}"
+    local step="${item#*:}"
+    local emoji=$(get_step_emoji "$step")
+    local formatted=$(format_step_duration $time)
+
+    if [ -n "$output" ]; then
+      output="$output ${C}│${R} "
+    fi
+    output="$output$emoji $step: ${Y}$formatted${R}"
+  done
+
+  echo "$output"
+}
+
+# Initialize iteration step times at start of new iteration
+# Usage: init_iteration_step_times
+init_iteration_step_times() {
+  # Clear iteration step times (reset all to 0)
+  ITERATION_STEP_VALUES=(0 0 0 0 0 0 0 0)
+
+  # Start timing with "Thinking" as default initial step
+  CURRENT_STEP_NAME="Thinking"
+  CURRENT_STEP_START=$(date +%s)
+}
+
+# Display session step totals at end of run
+# Usage: display_session_step_totals
+display_session_step_totals() {
+  local step_output=$(format_step_times "SESSION")
+
+  if [ -n "$step_output" ]; then
+    echo -e "  📊 Session totals: $step_output"
+  fi
+}
+
+# Detect current step from output line
+# Returns: step name based on output patterns
+detect_step() {
+  local line="$1"
+
+  # Check patterns in order of specificity
+  if echo "$line" | grep -qiE "(git commit|committing)"; then
+    echo "Committing       "
+  elif echo "$line" | grep -qiE "(npm test|jest|vitest|testing|test.*pass|test.*fail)"; then
+    echo "Testing          "
+  elif echo "$line" | grep -qiE "(eslint|lint|prettier|formatting)"; then
+    echo "Linting          "
+  elif echo "$line" | grep -qiE "(npm run typecheck|tsc|typescript|typecheck)"; then
+    echo "Typechecking     "
+  elif echo "$line" | grep -qiE "(\.test\.|\.spec\.|test file|writing test)"; then
+    echo "Writing tests    "
+  elif echo "$line" | grep -qiE "(write|edit|creating|updating|modifying).*\.(ts|js|sh|json|md)"; then
+    echo "Implementing     "
+  elif echo "$line" | grep -qiE "(read|glob|grep|searching|finding|looking)"; then
+    echo "Reading code     "
+  else
+    echo ""
+  fi
+}