beb939b32a
Test Fixes (609/609 passing): - Fixed DiceSystem API to accept team_id/player_id parameters for audit trails - Fixed dice roll history timing issue in test - Fixed terminal client mock to match resolve_play signature (X-Check params) - Fixed result chart test mocks with missing pitching fields - Fixed flaky test by using groundball_a (exists in both batting/pitching) Documentation Updates: - Added Testing Policy section to backend/CLAUDE.md - Added Testing Policy section to tests/CLAUDE.md - Documented 100% unit test requirement before commits - Added git hook setup instructions Git Hook System: - Created .git-hooks/pre-commit script (enforces 100% test pass) - Created .git-hooks/install-hooks.sh (easy installation) - Created .git-hooks/README.md (hook documentation) - Hook automatically runs all unit tests before each commit - Blocks commits if any test fails All 609 unit tests now passing (100%) Integration tests have known asyncpg connection issues (documented) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
577 lines
19 KiB
Python
577 lines
19 KiB
Python
"""
|
|
Help text and documentation for terminal client commands.
|
|
|
|
Provides detailed, formatted help text for all REPL commands
|
|
with usage examples and option descriptions.
|
|
|
|
Author: Claude
|
|
Date: 2025-10-27
|
|
"""
|
|
from typing import Dict
|
|
from rich.console import Console
|
|
from rich.table import Table
|
|
from rich.panel import Panel
|
|
from rich.markdown import Markdown
|
|
from rich import box
|
|
|
|
console = Console()
|
|
|
|
|
|
class HelpFormatter:
|
|
"""Format and display help text for commands."""
|
|
|
|
@staticmethod
|
|
def show_command_help(command_name: str, help_data: Dict) -> None:
|
|
"""
|
|
Display detailed help for a specific command.
|
|
|
|
Args:
|
|
command_name: Name of the command
|
|
help_data: Dictionary with help information
|
|
{
|
|
'summary': 'Brief description',
|
|
'usage': 'command [OPTIONS]',
|
|
'options': [
|
|
{'name': '--option', 'type': 'TYPE', 'desc': 'Description'}
|
|
],
|
|
'examples': ['example 1', 'example 2']
|
|
}
|
|
"""
|
|
# Build help text
|
|
help_text = []
|
|
|
|
# Summary
|
|
help_text.append(f"**{command_name}** - {help_data.get('summary', 'No description')}")
|
|
help_text.append("")
|
|
|
|
# Usage
|
|
if 'usage' in help_data:
|
|
help_text.append("**USAGE:**")
|
|
help_text.append(f" {help_data['usage']}")
|
|
help_text.append("")
|
|
|
|
# Display in panel
|
|
if help_text:
|
|
md = Markdown("\n".join(help_text[:3])) # Just summary and usage
|
|
panel = Panel(
|
|
md,
|
|
title=f"[bold cyan]Help: {command_name}[/bold cyan]",
|
|
border_style="cyan",
|
|
box=box.ROUNDED
|
|
)
|
|
console.print(panel)
|
|
console.print()
|
|
|
|
# Options
|
|
if 'options' in help_data and help_data['options']:
|
|
console.print("[bold cyan]OPTIONS:[/bold cyan]")
|
|
|
|
# Create options table
|
|
table = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
|
|
table.add_column("Option", style="cyan", no_wrap=True)
|
|
table.add_column("Type", style="yellow")
|
|
table.add_column("Description", style="white")
|
|
|
|
for opt in help_data['options']:
|
|
table.add_row(
|
|
opt['name'],
|
|
opt.get('type', ''),
|
|
opt.get('desc', '')
|
|
)
|
|
|
|
console.print(table)
|
|
console.print()
|
|
|
|
# Examples
|
|
if 'examples' in help_data and help_data['examples']:
|
|
console.print("[bold cyan]EXAMPLES:[/bold cyan]")
|
|
for example in help_data['examples']:
|
|
console.print(f" {example}")
|
|
console.print()
|
|
|
|
# Notes
|
|
if 'notes' in help_data:
|
|
console.print(f"[dim]{help_data['notes']}[/dim]")
|
|
console.print()
|
|
|
|
@staticmethod
|
|
def show_command_list() -> None:
|
|
"""Display list of all available commands."""
|
|
console.print("\n[bold cyan]Available Commands:[/bold cyan]\n")
|
|
|
|
# Game Management
|
|
console.print("[bold yellow]Game Management:[/bold yellow]")
|
|
console.print(" new_game Create a new game with test lineups and start it")
|
|
console.print(" list_games List all games in state manager")
|
|
console.print(" use_game Switch to a different game")
|
|
console.print(" status Display current game state")
|
|
console.print(" box_score Display box score")
|
|
console.print()
|
|
|
|
# Gameplay
|
|
console.print("[bold yellow]Gameplay:[/bold yellow]")
|
|
console.print(" defensive Submit defensive decision")
|
|
console.print(" offensive Submit offensive decision")
|
|
console.print(" resolve Resolve the current play")
|
|
console.print(" resolve_with Resolve with a specific outcome (testing)")
|
|
console.print(" quick_play Auto-play multiple plays")
|
|
console.print()
|
|
|
|
# Testing
|
|
console.print("[bold yellow]Testing & Development:[/bold yellow]")
|
|
console.print(" list_outcomes Show all available PlayOutcome values")
|
|
console.print(" test_location Test hit location distribution")
|
|
console.print(" rollback Roll back the last N plays")
|
|
console.print()
|
|
|
|
# X-Check Testing (Dice Systems)
|
|
console.print("[bold yellow]X-Check Testing:[/bold yellow]")
|
|
console.print(" roll_jump Roll jump dice for stolen base testing")
|
|
console.print(" test_jump Test jump roll distribution")
|
|
console.print(" roll_fielding Roll fielding check dice")
|
|
console.print(" test_fielding Test fielding roll distribution")
|
|
console.print()
|
|
|
|
# Interrupt Plays
|
|
console.print("[bold yellow]Interrupt Plays:[/bold yellow]")
|
|
console.print(" force_wild_pitch Force a wild pitch interrupt play")
|
|
console.print(" force_passed_ball Force a passed ball interrupt play")
|
|
console.print()
|
|
|
|
# Utilities
|
|
console.print("[bold yellow]Utilities:[/bold yellow]")
|
|
console.print(" config Show configuration")
|
|
console.print(" clear Clear the screen")
|
|
console.print(" help Show help for commands")
|
|
console.print(" quit/exit Exit the REPL")
|
|
console.print()
|
|
|
|
console.print("[dim]Type 'help <command>' for detailed information.[/dim]")
|
|
console.print("[dim]Use TAB for auto-completion of commands and options.[/dim]\n")
|
|
|
|
|
|
# Detailed help data for each command
|
|
HELP_DATA = {
|
|
'new_game': {
|
|
'summary': 'Create a new game with test lineups and start it immediately',
|
|
'usage': 'new_game [--league LEAGUE] [--home-team ID] [--away-team ID]',
|
|
'options': [
|
|
{
|
|
'name': '--league',
|
|
'type': 'sba|pd',
|
|
'desc': 'League type (default: sba)'
|
|
},
|
|
{
|
|
'name': '--home-team',
|
|
'type': 'INT',
|
|
'desc': 'Home team ID (default: 1)'
|
|
},
|
|
{
|
|
'name': '--away-team',
|
|
'type': 'INT',
|
|
'desc': 'Away team ID (default: 2)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'new_game',
|
|
'new_game --league pd',
|
|
'new_game --league sba --home-team 5 --away-team 3'
|
|
]
|
|
},
|
|
|
|
'defensive': {
|
|
'summary': 'Submit defensive decision for the current play',
|
|
'usage': 'defensive [--alignment TYPE] [--infield DEPTH] [--outfield DEPTH] [--hold BASES]',
|
|
'options': [
|
|
{
|
|
'name': '--alignment',
|
|
'type': 'STRING',
|
|
'desc': 'Defensive alignment: normal, shifted_left, shifted_right, extreme_shift (default: normal)'
|
|
},
|
|
{
|
|
'name': '--infield',
|
|
'type': 'STRING',
|
|
'desc': 'Infield depth: in, normal, back, double_play (default: normal)'
|
|
},
|
|
{
|
|
'name': '--outfield',
|
|
'type': 'STRING',
|
|
'desc': 'Outfield depth: in, normal, back (default: normal)'
|
|
},
|
|
{
|
|
'name': '--hold',
|
|
'type': 'LIST',
|
|
'desc': 'Comma-separated bases to hold runners: 1,2,3 (default: none)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'defensive',
|
|
'defensive --alignment shifted_left',
|
|
'defensive --infield double_play --hold 1,3',
|
|
'defensive --alignment extreme_shift --infield back --outfield back'
|
|
]
|
|
},
|
|
|
|
'offensive': {
|
|
'summary': 'Submit offensive decision for the current play',
|
|
'usage': 'offensive [--approach TYPE] [--steal BASES] [--hit-run] [--bunt]',
|
|
'options': [
|
|
{
|
|
'name': '--approach',
|
|
'type': 'STRING',
|
|
'desc': 'Batting approach: normal, contact, power, patient (default: normal)'
|
|
},
|
|
{
|
|
'name': '--steal',
|
|
'type': 'LIST',
|
|
'desc': 'Comma-separated bases to steal: 2,3 (default: none)'
|
|
},
|
|
{
|
|
'name': '--hit-run',
|
|
'type': 'FLAG',
|
|
'desc': 'Execute hit-and-run play (default: false)'
|
|
},
|
|
{
|
|
'name': '--bunt',
|
|
'type': 'FLAG',
|
|
'desc': 'Attempt bunt (default: false)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'offensive',
|
|
'offensive --approach power',
|
|
'offensive --steal 2',
|
|
'offensive --steal 2,3 --hit-run',
|
|
'offensive --approach contact --bunt'
|
|
]
|
|
},
|
|
|
|
'resolve': {
|
|
'summary': 'Resolve the current play using submitted decisions',
|
|
'usage': 'resolve',
|
|
'options': [],
|
|
'examples': [
|
|
'resolve'
|
|
],
|
|
'notes': 'Both defensive and offensive decisions must be submitted before resolving.'
|
|
},
|
|
|
|
'list_outcomes': {
|
|
'summary': 'Display all available PlayOutcome values for manual outcome testing',
|
|
'usage': 'list_outcomes',
|
|
'options': [],
|
|
'examples': [
|
|
'list_outcomes'
|
|
],
|
|
'notes': 'Shows a categorized table of all play outcomes. Use these values with resolve_with command.'
|
|
},
|
|
|
|
'resolve_with': {
|
|
'summary': 'Resolve current play with a specific outcome (bypassing dice rolls)',
|
|
'usage': 'resolve_with <OUTCOME>\n resolve_with x-check <POSITION> [<RESULT>[+<ERROR>]]',
|
|
'options': [
|
|
{
|
|
'name': 'OUTCOME',
|
|
'type': 'STRING',
|
|
'desc': 'PlayOutcome enum value. Use list_outcomes to see all available values.'
|
|
},
|
|
{
|
|
'name': 'POSITION',
|
|
'type': 'P|C|1B|2B|3B|SS|LF|CF|RF',
|
|
'desc': 'For x-check: defensive position to test (required)'
|
|
},
|
|
{
|
|
'name': 'RESULT',
|
|
'type': 'G1|G2|G3|F1|F2|F3|SI1|SI2|DO2|DO3|TR3|FO|PO',
|
|
'desc': 'For x-check: force specific converted result (optional)'
|
|
},
|
|
{
|
|
'name': 'ERROR',
|
|
'type': 'NO|E1|E2|E3|RP',
|
|
'desc': 'For x-check: force specific error result (optional, default: NO)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'resolve_with single_1',
|
|
'resolve_with homerun',
|
|
'resolve_with groundball_a',
|
|
'resolve_with double_uncapped',
|
|
'resolve_with strikeout',
|
|
'resolve_with x-check SS # Random X-Check to shortstop',
|
|
'resolve_with x-check LF DO2 # Force double to LF, no error',
|
|
'resolve_with x-check 2B G2+E1 # Force groundout to 2B with E1',
|
|
'resolve_with x-check SS SI2+E2 # Force single to SS with E2',
|
|
'resolve_with x-check LF FO+RP # Force flyout to LF with rare play'
|
|
],
|
|
'notes': 'Experimental feature for testing specific scenarios without random dice rolls. X-Check mode uses full defense tables and error charts with actual player ratings. When RESULT+ERROR are specified, table lookups are bypassed for precise testing of specific outcomes.'
|
|
},
|
|
|
|
'quick_play': {
|
|
'summary': 'Auto-play multiple plays with default decisions',
|
|
'usage': 'quick_play [COUNT]',
|
|
'options': [
|
|
{
|
|
'name': 'COUNT',
|
|
'type': 'INT',
|
|
'desc': 'Number of plays to execute (default: 1). Positional argument.'
|
|
}
|
|
],
|
|
'examples': [
|
|
'quick_play',
|
|
'quick_play 10',
|
|
'quick_play 27 # Play roughly 3 innings',
|
|
'quick_play 100 # Play full game quickly'
|
|
]
|
|
},
|
|
|
|
'status': {
|
|
'summary': 'Display current game state',
|
|
'usage': 'status',
|
|
'options': [],
|
|
'examples': [
|
|
'status'
|
|
]
|
|
},
|
|
|
|
'box_score': {
|
|
'summary': 'Display box score for the current game',
|
|
'usage': 'box_score',
|
|
'options': [],
|
|
'examples': [
|
|
'box_score'
|
|
]
|
|
},
|
|
|
|
'list_games': {
|
|
'summary': 'List all games currently loaded in state manager',
|
|
'usage': 'list_games',
|
|
'options': [],
|
|
'examples': [
|
|
'list_games'
|
|
]
|
|
},
|
|
|
|
'use_game': {
|
|
'summary': 'Switch to a different game',
|
|
'usage': 'use_game <GAME_ID>',
|
|
'options': [
|
|
{
|
|
'name': 'GAME_ID',
|
|
'type': 'UUID',
|
|
'desc': 'UUID of the game to switch to. Positional argument.'
|
|
}
|
|
],
|
|
'examples': [
|
|
'use_game a1b2c3d4-e5f6-7890-abcd-ef1234567890',
|
|
'use_game <TAB> # Use tab completion to see available games'
|
|
]
|
|
},
|
|
|
|
'config': {
|
|
'summary': 'Show terminal client configuration',
|
|
'usage': 'config',
|
|
'options': [],
|
|
'examples': [
|
|
'config'
|
|
]
|
|
},
|
|
|
|
'clear': {
|
|
'summary': 'Clear the screen',
|
|
'usage': 'clear',
|
|
'options': [],
|
|
'examples': [
|
|
'clear'
|
|
]
|
|
},
|
|
|
|
# X-Check Testing Commands
|
|
'roll_jump': {
|
|
'summary': 'Roll jump dice for stolen base testing',
|
|
'usage': 'roll_jump [LEAGUE]',
|
|
'options': [
|
|
{
|
|
'name': 'LEAGUE',
|
|
'type': 'sba|pd',
|
|
'desc': 'League type (default: sba)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'roll_jump # Roll for SBA league',
|
|
'roll_jump pd # Roll for PD league'
|
|
],
|
|
'notes': 'Components: 1d20 check (1=pickoff, 2=balk, 3+=normal), 2d6 jump total'
|
|
},
|
|
|
|
'test_jump': {
|
|
'summary': 'Test jump roll distribution statistics',
|
|
'usage': 'test_jump [COUNT] [LEAGUE]',
|
|
'options': [
|
|
{
|
|
'name': 'COUNT',
|
|
'type': 'integer',
|
|
'desc': 'Number of rolls to test (default: 10)'
|
|
},
|
|
{
|
|
'name': 'LEAGUE',
|
|
'type': 'sba|pd',
|
|
'desc': 'League type (default: sba)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'test_jump # 10 rolls for SBA',
|
|
'test_jump 100 # 100 rolls for SBA',
|
|
'test_jump 50 pd # 50 rolls for PD'
|
|
],
|
|
'notes': 'Shows pickoff/balk/normal frequency and 2d6 distribution'
|
|
},
|
|
|
|
'roll_fielding': {
|
|
'summary': 'Roll fielding check dice for X-Check defensive plays',
|
|
'usage': 'roll_fielding <POSITION> [LEAGUE]',
|
|
'options': [
|
|
{
|
|
'name': 'POSITION',
|
|
'type': 'P|C|1B|2B|3B|SS|LF|CF|RF',
|
|
'desc': 'Fielding position (required)'
|
|
},
|
|
{
|
|
'name': 'LEAGUE',
|
|
'type': 'sba|pd',
|
|
'desc': 'League type (default: sba)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'roll_fielding SS # Roll for shortstop (SBA)',
|
|
'roll_fielding P pd # Roll for pitcher (PD)',
|
|
'roll_fielding CF # Roll for center field'
|
|
],
|
|
'notes': 'Components: 1d20 range, 3d6 error total, d100/special rare play check'
|
|
},
|
|
|
|
'test_fielding': {
|
|
'summary': 'Test fielding roll distribution for a position',
|
|
'usage': 'test_fielding <POSITION> [COUNT] [LEAGUE]',
|
|
'options': [
|
|
{
|
|
'name': 'POSITION',
|
|
'type': 'P|C|1B|2B|3B|SS|LF|CF|RF',
|
|
'desc': 'Fielding position (required)'
|
|
},
|
|
{
|
|
'name': 'COUNT',
|
|
'type': 'integer',
|
|
'desc': 'Number of rolls (default: 10)'
|
|
},
|
|
{
|
|
'name': 'LEAGUE',
|
|
'type': 'sba|pd',
|
|
'desc': 'League type (default: sba)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'test_fielding SS # 10 rolls for shortstop',
|
|
'test_fielding 2B 100 # 100 rolls for second base',
|
|
'test_fielding CF 50 pd # 50 rolls for center field (PD)'
|
|
],
|
|
'notes': 'Shows rare play frequency, average range/error, and distribution stats'
|
|
},
|
|
|
|
'test_location': {
|
|
'summary': 'Test hit location distribution for an outcome',
|
|
'usage': 'test_location <OUTCOME> [HANDEDNESS] [COUNT]',
|
|
'options': [
|
|
{
|
|
'name': 'OUTCOME',
|
|
'type': 'PlayOutcome',
|
|
'desc': 'PlayOutcome enum value (e.g., groundball_c)'
|
|
},
|
|
{
|
|
'name': 'HANDEDNESS',
|
|
'type': 'L|R',
|
|
'desc': 'Batter handedness (default: R)'
|
|
},
|
|
{
|
|
'name': 'COUNT',
|
|
'type': 'integer',
|
|
'desc': 'Number of samples (default: 100)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'test_location groundball_c',
|
|
'test_location groundball_c L',
|
|
'test_location flyout_b R 200'
|
|
],
|
|
'notes': 'Shows distribution of hit locations based on pull rates'
|
|
},
|
|
|
|
'rollback': {
|
|
'summary': 'Roll back the last N plays',
|
|
'usage': 'rollback <NUM_PLAYS>',
|
|
'options': [
|
|
{
|
|
'name': 'NUM_PLAYS',
|
|
'type': 'integer',
|
|
'desc': 'Number of plays to roll back (must be > 0)'
|
|
}
|
|
],
|
|
'examples': [
|
|
'rollback 1 # Undo the last play',
|
|
'rollback 3 # Undo the last 3 plays',
|
|
'rollback 5 # Undo the last 5 plays'
|
|
],
|
|
'notes': 'Deletes plays from database and reconstructs state by replaying'
|
|
},
|
|
|
|
'force_wild_pitch': {
|
|
'summary': 'Force a wild pitch interrupt play',
|
|
'usage': 'force_wild_pitch',
|
|
'options': [],
|
|
'examples': [
|
|
'force_wild_pitch # Runner on 2nd advances to 3rd'
|
|
],
|
|
'notes': 'Advances all runners one base. This is an interrupt play (pa=0)'
|
|
},
|
|
|
|
'force_passed_ball': {
|
|
'summary': 'Force a passed ball interrupt play',
|
|
'usage': 'force_passed_ball',
|
|
'options': [],
|
|
'examples': [
|
|
'force_passed_ball # Runner on 1st advances to 2nd'
|
|
],
|
|
'notes': 'Advances all runners one base. This is an interrupt play (pa=0)'
|
|
}
|
|
}
|
|
|
|
|
|
def get_help_text(command: str) -> Dict:
|
|
"""
|
|
Get help data for a command.
|
|
|
|
Args:
|
|
command: Command name
|
|
|
|
Returns:
|
|
Help data dictionary or empty dict if not found
|
|
"""
|
|
return HELP_DATA.get(command, {})
|
|
|
|
|
|
def show_help(command: str = None) -> None:
|
|
"""
|
|
Show help for a command or list all commands.
|
|
|
|
Args:
|
|
command: Command name or None for command list
|
|
"""
|
|
if command:
|
|
help_data = get_help_text(command)
|
|
if help_data:
|
|
HelpFormatter.show_command_help(command, help_data)
|
|
else:
|
|
console.print(f"[yellow]No help available for '{command}'[/yellow]")
|
|
console.print("[dim]Type 'help' to see all available commands.[/dim]")
|
|
else:
|
|
HelpFormatter.show_command_list()
|