Management Scripts (CLI)

Overview

The BBX platform includes a set of root-level JavaScript utilities designed for terminal-based management, debugging, and auditing. These scripts allow administrators to bypass the web interface for quick data verification and bracket analysis.

Bracket Result Viewer

The view_bracket_results.js script is a CLI utility used to fetch and display the status of the "Top Cut" (single elimination) stage of a tournament. It provides a visual representation of rounds in the terminal and identifies the current champion based on completed match data.

Usage

To run the script, execute the following command from the project root:

node view_bracket_results.js

Configuration

The script relies on environment variables defined in your .env file to target a specific tournament.

| Variable | Description | | :--- | :--- | | TEST_TOURNAMENT_ID | The UUID of the tournament you wish to audit. | | SUPABASE_URL | Your project's Supabase endpoint. | | SUPABASE_ANON_KEY | Your project's public API key. |

Output Format

The script parses the tournament bracket and outputs:

1. Round Grouping: Matches are grouped by their bracket_round number.
2. Match Status: Displays participant IDs, current scores, and whether the match is Pending, Complete, or a Draw/Error.
3. Automatic Winner Identification: Identifies the winner of the final match (Match 1 of the highest round) and prints the 🏆 CHAMPION 🏆.

Example Output:

fetching Top Cut results for tournament: [UUID]

=== Round 1 ===
Match 1: player_a vs player_b -> Winner: player_a (5-2)
Match 2: player_c vs BYE -> Winner: player_c (0-0)

🏆 CHAMPION: player_a 🏆

LLM Integration Service

The lib/openrouter.js module serves as the interface for AI-enhanced tournament features (such as automated match commentary or rules analysis). This is used internally by server-side actions but can be utilized in custom management scripts.

Configuration

Ensure your .env includes the OPENAI_API_KEY. While the library uses the OpenAI SDK, it is pre-configured to point to the OpenRouter base URL for access to a wider variety of models.

import { openrouter } from "./lib/openrouter.js";

// Example: Using the integration in a custom script
const completion = await openrouter.chat.completions.create({
    model: "openai/gpt-4-turbo",
    messages: [{ role: "user", content: "Summarize tournament results..." }],
});

Troubleshooting Utilities

These scripts are primarily for data integrity checks. If the Web UI displays a "Pending" status for a round that should be finished, use the view_bracket_results.js script to verify if a winner_id is missing in the database for any specific match_number.

Common CLI Error Codes

• "Missing TEST_TOURNAMENT_ID": The .env file is missing or the variable name is misspelled.
• "No Top Cut matches found": The tournament exists but has not yet advanced to the Top Cut stage, or the stage column in the database is not set to top_cut.
• "BYE" Display: If a match participant is null, the script automatically treats the slot as a "BYE" for bracket progression.