#!/usr/bin/env bash
# br-help - BlackRoad OS unified help system
# Lists all available commands with descriptions parsed from script headers
set -o pipefail

PINK='\033[38;5;205m'
AMBER='\033[38;5;214m'
BLUE='\033[38;5;69m'
VIOLET='\033[38;5;135m'
GREEN='\033[38;5;82m'
RESET='\033[0m'

BIN_DIR="$HOME/bin"

# Extract description from script header
get_desc() {
  local file="$1"
  [[ -f "$file" ]] || return
  # Skip shebang, separators (===), copyright, blank # lines; take first real comment
  head -15 "$file" 2>/dev/null | \
    grep '^#' | \
    grep -v '^#!' | \
    grep -v '^# *=\{3,\}' | \
    grep -v -i 'copyright\|proprietary\|confidential\|license\|unauthorized\|intellectual\|ai-assisted\|NOT licensed\|All Rights' | \
    grep -v '^# *$' | \
    head -1 | sed 's/^# *//' | cut -c1-60
}

show_category() {
  local label="$1"; shift
  local color="$1"; shift
  local commands=("$@")
  printf "\n%b  %s%b\n" "$color" "$label" "$RESET"
  for cmd in "${commands[@]}"; do
    local path="$BIN_DIR/$cmd"
    if [[ -x "$path" ]] || [[ -f "$path" ]]; then
      local desc
      desc=$(get_desc "$path")
      printf "    %b%-22s%b %s\n" "$GREEN" "$cmd" "$RESET" "${desc:-—}"
    fi
  done
}

printf '%b╔══════════════════════════════════════════════════╗%b\n' "$PINK" "$RESET"
printf '%b║          BlackRoad OS Command Reference          ║%b\n' "$PINK" "$RESET"
printf '%b╚══════════════════════════════════════════════════╝%b\n' "$PINK" "$RESET"

show_category "CORE" "$PINK" \
  blackroad brctl bros road roadid fleet mesh blackroad-shell

show_category "AI HUB" "$VIOLET" \
  br-ai br-infer br-fleet-ai br-models ai blackroad-ai ask br-code-assistant

show_category "AGENTS & ORCHESTRATION" "$VIOLET" \
  blackroad-agent blackroad-agents agent-collab agent-swarm agent-worker \
  claude-agent roundtable rt-ask rt-context

show_category "LLM PROVIDERS" "$GREEN" \
  llama ollama-os gemini-cli gemmy grok-cli

show_category "FLEET AI (ask-*)" "$AMBER" \
  ask-node ask-alice ask-cecilia ask-octavia ask-lucidia ask-aria

show_category "STATUS & MONITORING" "$BLUE" \
  br-status br-stats br-dashboard br-stats-enhanced

show_category "DEPLOYMENT & INFRA" "$AMBER" \
  br-deploy br-pack br-hw br-sync br-run bb-deploy

show_category "DEVELOPMENT" "$GREEN" \
  br-search br-index brc brx br-generate

show_category "NETWORK & SECURITY" "$BLUE" \
  br-security br-send cf-dns blackroad-mesh blackroad-gateway

show_category "MEDIA & BRAND" "$VIOLET" \
  br-video br-video-create br-art br-gui br-palette br-shape

# Count available commands
total=$(find "$BIN_DIR" -maxdepth 1 -type f -perm +111 2>/dev/null | wc -l | tr -d ' ')
printf "\n%b  %s commands in ~/bin/%b\n" "$PINK" "$total" "$RESET"
printf "  Run any command with --help for details\n\n"