#!/bin/bash # generate-cli-docs.sh — Generate CLI reference docs from the live bd command tree. set -euo pipefail export LC_ALL=C SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" CHECK_MODE=0 if [ "${1:-}" = "--check" ]; then CHECK_MODE=1 shift fi BD_ARG="${1:-}" TMP_BUILD_DIR="" TMP_OUTPUT_DIR="" cleanup() { if [ -n "$TMP_BUILD_DIR" ]; then rm -rf "$TMP_BUILD_DIR" fi if [ -n "$TMP_OUTPUT_DIR" ]; then rm -rf "$TMP_OUTPUT_DIR" fi } trap cleanup EXIT if [ -n "$BD_ARG" ]; then BD="$BD_ARG" elif [ -x "$PROJECT_ROOT/bd" ]; then BD="$PROJECT_ROOT/bd" else TMP_BUILD_DIR="$(mktemp -d)" BD="$TMP_BUILD_DIR/bd" echo "Building temporary bd for docs generation..." (cd "$PROJECT_ROOT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD" ./cmd/bd/) fi if [ ! -x "$BD" ]; then echo "Error: bd binary not found or not executable: $BD" >&2 echo "Usage: $0 [--check] [path-to-bd]" >&2 exit 1 fi command_doc_id() { printf '%s' "$1" \ | tr '[:upper:] ' '[:lower:]-' \ | sed -E 's/[^a-z0-9-]+/-/g; s/-+/-/g; s/^-//; s/-$//' } trim_trailing_blank_lines() { perl -0pi -e 's/\n+\z/\n/' "$1" } generate_index() { local out_dir="$1" local commands_file="$2" local version_label="$3" local count count="$(wc -l < "$commands_file" | tr -d ' ')" cat > "$out_dir/index.md" << EOF --- id: index title: CLI Reference sidebar_position: 0 --- # CLI Reference Reference for bd ${version_label}. Generated from \`bd help --list\` and \`bd help --doc \`. This reference covers all ${count} live top-level \`bd\` commands. Regenerate it with: \`\`\`bash ./scripts/generate-cli-docs.sh \`\`\` ## Commands EOF while IFS= read -r cmd; do cmd="${cmd%$'\r'}" local doc_id doc_id="$(command_doc_id "$cmd")" printf -- "- [\`bd %s\`](./%s.md)\n" "$cmd" "$doc_id" >> "$out_dir/index.md" done < "$commands_file" } generate_cli_dir() { local out_dir="$1" local commands_file="$2" local version_label="$3" mkdir -p "$out_dir" rm -f "$out_dir"/*.md generate_index "$out_dir" "$commands_file" "$version_label" while IFS= read -r cmd; do cmd="${cmd%$'\r'}" local doc_id doc_id="$(command_doc_id "$cmd")" "$BD" help --doc "$cmd" < /dev/null > "$out_dir/$doc_id.md" trim_trailing_blank_lines "$out_dir/$doc_id.md" done < "$commands_file" } generate_all() { local root="$1" local commands_file="$root/.cli-commands.txt" mkdir -p "$root/docs" "$BD" help --list > "$commands_file" "$BD" help --all > "$root/docs/CLI_REFERENCE.md" trim_trailing_blank_lines "$root/docs/CLI_REFERENCE.md" generate_cli_dir "$root/website/docs/cli-reference" "$commands_file" "Latest" # Versioned snapshots: parse the semver tag from the directory name # (e.g. "version-1.0.0" -> "v1.0.0") so a release bump alone produces # zero diff on the dev tree. local versioned_parent="$PROJECT_ROOT/website/versioned_docs" if [ -d "$versioned_parent" ]; then local versioned_dir for versioned_dir in "$versioned_parent"/version-*; do [ -d "$versioned_dir" ] || continue local dir_name dir_name="$(basename "$versioned_dir")" local version_tag="v${dir_name#version-}" generate_cli_dir \ "$root/website/versioned_docs/$dir_name/cli-reference" \ "$commands_file" \ "$version_tag" done fi rm -f "$commands_file" } if [ "$CHECK_MODE" -eq 1 ]; then TMP_OUTPUT_DIR="$(mktemp -d)" mkdir -p "$TMP_OUTPUT_DIR/website" cp -Rf "$PROJECT_ROOT/website/docs" "$TMP_OUTPUT_DIR/website/docs" if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then cp -Rf "$PROJECT_ROOT/website/versioned_docs" "$TMP_OUTPUT_DIR/website/versioned_docs" fi if [ -f "$PROJECT_ROOT/website/versions.json" ]; then cp -f "$PROJECT_ROOT/website/versions.json" "$TMP_OUTPUT_DIR/website/versions.json" fi generate_all "$TMP_OUTPUT_DIR" if ! diff -qr \ "$PROJECT_ROOT/docs/CLI_REFERENCE.md" \ "$TMP_OUTPUT_DIR/docs/CLI_REFERENCE.md" >/dev/null; then echo "FAIL: docs/CLI_REFERENCE.md is out of sync with live CLI help." echo "Run: ./scripts/generate-cli-docs.sh ${BD_ARG:-}" diff -u "$PROJECT_ROOT/docs/CLI_REFERENCE.md" "$TMP_OUTPUT_DIR/docs/CLI_REFERENCE.md" | sed -n '1,120p' || true exit 1 fi check_dirs=("website/docs/cli-reference") if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then for vdir in "$PROJECT_ROOT/website/versioned_docs"/version-*; do [ -d "$vdir" ] || continue check_dirs+=("website/versioned_docs/$(basename "$vdir")/cli-reference") done fi for rel in "${check_dirs[@]}"; do if [ -d "$PROJECT_ROOT/$rel" ]; then if ! diff -qr "$PROJECT_ROOT/$rel" "$TMP_OUTPUT_DIR/$rel" >/dev/null; then echo "FAIL: $rel is out of sync with live CLI help." echo "Run: ./scripts/generate-cli-docs.sh ${BD_ARG:-}" diff -ur "$PROJECT_ROOT/$rel" "$TMP_OUTPUT_DIR/$rel" | sed -n '1,160p' || true exit 1 fi fi done "$PROJECT_ROOT/scripts/generate-llms-full.sh" --check --source-root "$TMP_OUTPUT_DIR" echo "PASS: generated CLI docs are fresh" else generate_all "$PROJECT_ROOT" echo "Generated CLI docs from: $($BD version 2>/dev/null | head -1 || echo "$BD")" echo "Updated docs/CLI_REFERENCE.md and website CLI reference pages" fi