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:
- Round Grouping: Matches are grouped by their
bracket_roundnumber. - Match Status: Displays participant IDs, current scores, and whether the match is
Pending,Complete, or aDraw/Error. - 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
.envfile 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
stagecolumn in the database is not set totop_cut. - "BYE" Display: If a match participant is null, the script automatically treats the slot as a "BYE" for bracket progression.