boshu2__agentops/scripts/generate-cli-reference.sh

#!/usr/bin/env bash
set -euo pipefail

# Generate cli/docs/COMMANDS.md from ao --help output.
# Usage:
#   ./scripts/generate-cli-reference.sh           # Generate COMMANDS.md
#   ./scripts/generate-cli-reference.sh --check   # Check if committed version is current

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
CLI_DIR="$REPO_ROOT/cli"
AO_BIN="$CLI_DIR/.tmp/ao-docgen"
OUTPUT="$REPO_ROOT/cli/docs/COMMANDS.md"
CHECK_MODE=false
TMPFILE=""

if [[ "${1:-}" == "--check" ]]; then
  CHECK_MODE=true
fi

if ! command -v go >/dev/null 2>&1; then
  echo "ERROR: go is required to generate CLI docs." >&2
  exit 1
fi

cleanup() {
  [[ -n "$TMPFILE" ]] && rm -f "$TMPFILE"
  rm -f "$AO_BIN"
}
trap cleanup EXIT

build_ao() {
  mkdir -p "$(dirname "$AO_BIN")"
  (
    cd "$CLI_DIR"
    go build -o "$AO_BIN" ./cmd/ao
  )
}

extract_commands() {
  awk '
    /^Usage:/ {after_usage=1; next}
    !after_usage {next}

    /^Flags:/ {exit}
    /^Global Flags:/ {exit}
    /^Additional help topics:/ {exit}
    /^Use "/ {exit}

    /^Available Commands:/ {in_commands=1; next}
    in_commands && /^$/ {in_commands=0; next}
    in_commands && NF > 0 {
      cmd=$1
      if (!seen[cmd]++) print cmd
      next
    }

    /^[[:space:]]{2,}[a-z0-9][a-z0-9-]*([[:space:]]+|$)/ {
      cmd=$1
      if (cmd != "ao" && cmd !~ /^-/ && cmd !~ /:$/ && !seen[cmd]++) print cmd
    }
  '
}

extract_usage() {
  awk '
    /^Usage:/ {
      line=$0
      sub(/^Usage:[[:space:]]*/, "", line)
      if (line != "") print line
      in_usage=1
      next
    }
    in_usage {
      if ($0 ~ /^$/) {
        in_usage=0
        next
      }
      line=$0
      sub(/^[[:space:]]+/, "", line)
      if (line != "") print line
    }
  ' | awk '
    /^ao / {
      all[++all_n]=$0
      if ($0 !~ />/) preferred[++pref_n]=$0
    }
    END {
      if (pref_n > 0) print preferred[pref_n]
      else if (all_n > 0) print all[all_n]
    }
  '
}

extract_flags() {
  sed -n '/^Flags:/,/^$/{ /^Flags:/d; /^$/d; p; }'
}

has_non_help_flags() {
  grep -Ev '^[[:space:]]*-h,[[:space:]]*--help[[:space:]]+help for' | grep -Ev '^[[:space:]]*$'
}

generate() {
  cat <<DOC_HEADER
# ao CLI Reference

> Auto-generated by \`scripts/generate-cli-reference.sh\`.
> Do not edit manually. Re-run the script to update.

DOC_HEADER

  local top_help
  top_help="$("$AO_BIN" --help 2>&1)"

  cat <<'DOC_GLOBAL_FLAGS'
## Global Flags

DOC_GLOBAL_FLAGS

  echo "$top_help" | extract_flags | while IFS= read -r line; do
    echo "    $line"
  done
  echo ""

  local commands
  commands="$(echo "$top_help" | extract_commands | grep -v '^$')"

  cat <<'DOC_COMMANDS'
---

## Commands

DOC_COMMANDS

  for cmd in $commands; do
    local cmd_help
    cmd_help="$("$AO_BIN" "$cmd" --help 2>&1 || true)"

    local description
    description="$(echo "$cmd_help" | head -n1)"

    echo "### \`ao ${cmd}\`"
    echo ""
    echo "$description"
    echo ""

    local usage
    usage="$(echo "$cmd_help" | extract_usage || true)"
    if [[ -n "$usage" ]]; then
      echo '```'
      echo "$usage"
      echo '```'
      echo ""
    fi

    local flags_block
    flags_block="$(echo "$cmd_help" | extract_flags || true)"
    if echo "$flags_block" | has_non_help_flags >/dev/null 2>&1; then
      echo "**Flags:**"
      echo ""
      echo '```'
      echo "$flags_block"
      echo '```'
      echo ""
    fi

    local subcmds
    subcmds="$(echo "$cmd_help" | extract_commands | grep -v '^$' || true)"
    if [[ -n "$subcmds" ]]; then
      echo "**Subcommands:**"
      echo ""
      for sub in $subcmds; do
        local sub_help
        sub_help="$("$AO_BIN" "$cmd" "$sub" --help 2>&1 || true)"

        local sub_desc
        sub_desc="$(echo "$sub_help" | head -n1)"

        echo "#### \`ao ${cmd} ${sub}\`"
        echo ""
        echo "$sub_desc"
        echo ""

        local sub_usage
        sub_usage="$(echo "$sub_help" | extract_usage || true)"
        if [[ -n "$sub_usage" ]]; then
          echo '```'
          echo "$sub_usage"
          echo '```'
          echo ""
        fi

        local sub_flags
        sub_flags="$(echo "$sub_help" | extract_flags || true)"
        if echo "$sub_flags" | has_non_help_flags >/dev/null 2>&1; then
          echo "**Flags:**"
          echo ""
          echo '```'
          echo "$sub_flags"
          echo '```'
          echo ""
        fi

        local subsub_cmds
        subsub_cmds="$(echo "$sub_help" | extract_commands | grep -v '^$' || true)"
        if [[ -n "$subsub_cmds" ]]; then
          for subsub in $subsub_cmds; do
            local subsub_help
            subsub_help="$("$AO_BIN" "$cmd" "$sub" "$subsub" --help 2>&1 || true)"

            local subsub_desc
            subsub_desc="$(echo "$subsub_help" | head -n1)"

            echo "##### \`ao ${cmd} ${sub} ${subsub}\`"
            echo ""
            echo "$subsub_desc"
            echo ""

            local subsub_usage
            subsub_usage="$(echo "$subsub_help" | extract_usage || true)"
            if [[ -n "$subsub_usage" ]]; then
              echo '```'
              echo "$subsub_usage"
              echo '```'
              echo ""
            fi

            local subsub_flags
            subsub_flags="$(echo "$subsub_help" | extract_flags || true)"
            if echo "$subsub_flags" | has_non_help_flags >/dev/null 2>&1; then
              echo "**Flags:**"
              echo ""
              echo '```'
              echo "$subsub_flags"
              echo '```'
              echo ""
            fi
          done
        fi
      done
    fi

    echo "---"
    echo ""
  done
}

build_ao

if $CHECK_MODE; then
  TMPFILE="$(mktemp)"
  generate > "$TMPFILE"
  if diff -q "$OUTPUT" "$TMPFILE" >/dev/null 2>&1; then
    echo "cli/docs/COMMANDS.md is up to date."
    exit 0
  fi

  echo "cli/docs/COMMANDS.md is out of date. Run: ./scripts/generate-cli-reference.sh" >&2
  diff -u "$OUTPUT" "$TMPFILE" || true
  exit 1
fi

mkdir -p "$(dirname "$OUTPUT")"
generate > "$OUTPUT"
echo "Generated $OUTPUT"