strat-gameplay-webapp/backend/terminal_client/update_docs/phase_2.md

● Terminal Client Improvement Plan - Part 2: Robust Argument Parsing

Overview

Replace manual string splitting with shlex for robust argument parsing that handles quoted strings, edge cases, and complex arguments properly.

Files to Create

1. Create backend/terminal_client/arg_parser.py

""" Argument parsing utilities for terminal client commands.

Provides robust parsing for both REPL and CLI commands using shlex to handle quoted strings, spaces, and complex arguments.

Author: Claude Date: 2025-10-27 """ import shlex import logging from typing import Dict, Any, List, Optional, Tuple

logger = logging.getLogger(f'{name}.arg_parser')

class ArgumentParseError(Exception): """Raised when argument parsing fails.""" pass

class CommandArgumentParser: """Parse command-line style arguments for terminal client."""

  @staticmethod
  def parse_args(arg_string: str, schema: Dict[str, Any]) -> Dict[str, Any]:
      """
      Parse argument string according to schema.
      
      Args:
          arg_string: Raw argument string from command
          schema: Dictionary defining expected arguments
              {
                  'league': {'type': str, 'default': 'sba'},
                  'home-team': {'type': int, 'default': 1},
                  'count': {'type': int, 'default': 1, 'positional': True},
                  'verbose': {'type': bool, 'flag': True}
              }
      
      Returns:
          Dictionary of parsed arguments with defaults applied
          
      Raises:
          ArgumentParseError: If parsing fails or validation fails
      """
      try:
          # Use shlex for robust parsing
          tokens = shlex.split(arg_string) if arg_string.strip() else []
      except ValueError as e:
          raise ArgumentParseError(f"Invalid argument syntax: {e}")

      # Initialize result with defaults
      result = {}
      for key, spec in schema.items():
          if 'default' in spec:
              result[key] = spec['default']

      # Track which positional arg we're on
      positional_keys = [k for k, v in schema.items() if v.get('positional', False)]
      positional_index = 0

      i = 0
      while i < len(tokens):
          token = tokens[i]

          # Handle flags (--option or -o)
          if token.startswith('--'):
              option_name = token[2:]

              # Convert hyphen to underscore for Python compatibility
              option_key = option_name.replace('-', '_')

              if option_key not in schema:
                  raise ArgumentParseError(f"Unknown option: {token}")

              spec = schema[option_key]

              # Boolean flags don't need a value
              if spec.get('flag', False):
                  result[option_key] = True
                  i += 1
                  continue

              # Option requires a value
              if i + 1 >= len(tokens):
                  raise ArgumentParseError(f"Option {token} requires a value")

              value_str = tokens[i + 1]

              # Type conversion
              try:
                  if spec['type'] == int:
                      result[option_key] = int(value_str)
                  elif spec['type'] == float:
                      result[option_key] = float(value_str)
                  elif spec['type'] == list:
                      # Parse comma-separated list
                      result[option_key] = [item.strip() for item in value_str.split(',')]
                  elif spec['type'] == 'int_list':
                      # Parse comma-separated integers
                      result[option_key] = [int(item.strip()) for item in value_str.split(',')]
                  else:
                      result[option_key] = value_str
              except ValueError as e:
                  raise ArgumentParseError(
                      f"Invalid value for {token}: expected {spec['type'].__name__}, got '{value_str}'"
                  )

              i += 2

          # Handle positional arguments
          else:
              if positional_index >= len(positional_keys):
                  raise ArgumentParseError(f"Unexpected positional argument: {token}")

              key = positional_keys[positional_index]
              spec = schema[key]

              try:
                  if spec['type'] == int:
                      result[key] = int(token)
                  elif spec['type'] == float:
                      result[key] = float(token)
                  else:
                      result[key] = token
              except ValueError as e:
                  raise ArgumentParseError(
                      f"Invalid value for {key}: expected {spec['type'].__name__}, got '{token}'"
                  )

              positional_index += 1
              i += 1

      return result

  @staticmethod
  def parse_game_id(arg_string: str) -> Optional[str]:
      """
      Parse a game ID from argument string.
      
      Args:
          arg_string: Raw argument string
          
      Returns:
          Game ID string or None
      """
      try:
          tokens = shlex.split(arg_string) if arg_string.strip() else []

          # Look for --game-id option
          for i, token in enumerate(tokens):
              if token == '--game-id' and i + 1 < len(tokens):
                  return tokens[i + 1]

          # If no option, check if there's a positional UUID-like argument
          if tokens and len(tokens[0]) == 36:  # UUID length
              return tokens[0]

          return None

      except ValueError:
          return None

Predefined schemas for common commands

NEW_GAME_SCHEMA = { 'league': {'type': str, 'default': 'sba'}, 'home_team': {'type': int, 'default': 1}, 'away_team': {'type': int, 'default': 2} }

DEFENSIVE_SCHEMA = { 'alignment': {'type': str, 'default': 'normal'}, 'infield': {'type': str, 'default': 'normal'}, 'outfield': {'type': str, 'default': 'normal'}, 'hold': {'type': 'int_list', 'default': []} }

OFFENSIVE_SCHEMA = { 'approach': {'type': str, 'default': 'normal'}, 'steal': {'type': 'int_list', 'default': []}, 'hit_run': {'type': bool, 'flag': True, 'default': False}, 'bunt': {'type': bool, 'flag': True, 'default': False} }

QUICK_PLAY_SCHEMA = { 'count': {'type': int, 'default': 1, 'positional': True} }

USE_GAME_SCHEMA = { 'game_id': {'type': str, 'positional': True} }

def parse_new_game_args(arg_string: str) -> Dict[str, Any]: """Parse arguments for new_game command.""" return CommandArgumentParser.parse_args(arg_string, NEW_GAME_SCHEMA)

def parse_defensive_args(arg_string: str) -> Dict[str, Any]: """Parse arguments for defensive command.""" return CommandArgumentParser.parse_args(arg_string, DEFENSIVE_SCHEMA)

def parse_offensive_args(arg_string: str) -> Dict[str, Any]: """Parse arguments for offensive command.""" return CommandArgumentParser.parse_args(arg_string, OFFENSIVE_SCHEMA)

def parse_quick_play_args(arg_string: str) -> Dict[str, Any]: """Parse arguments for quick_play command.""" return CommandArgumentParser.parse_args(arg_string, QUICK_PLAY_SCHEMA)

def parse_use_game_args(arg_string: str) -> Dict[str, Any]: """Parse arguments for use_game command.""" return CommandArgumentParser.parse_args(arg_string, USE_GAME_SCHEMA)

Files to Update

2. Update backend/terminal_client/repl.py

Add import at top

from terminal_client.arg_parser import ( parse_new_game_args, parse_defensive_args, parse_offensive_args, parse_quick_play_args, parse_use_game_args, ArgumentParseError )

Replace do_new_game method:

def do_new_game(self, arg): """ Create a new game with lineups and start it.

  Usage: new_game [--league sba|pd] [--home-team N] [--away-team N]
  
  Examples:
    new_game
    new_game --league pd
    new_game --home-team 5 --away-team 3
  """
  async def _new_game():
      try:
          # Parse arguments with robust parser
          args = parse_new_game_args(arg)

          # Use shared command
          gid, success = await game_commands.create_new_game(
              league=args['league'],
              home_team=args['home_team'],
              away_team=args['away_team'],
              set_current=True
          )

          if success:
              self.current_game_id = gid

      except ArgumentParseError as e:
          display.print_error(f"Invalid arguments: {e}")
      except Exception as e:
          display.print_error(f"Failed to create game: {e}")
          logger.exception("New game error")

  self._run_async(_new_game())

Replace do_defensive method:

def do_defensive(self, arg): """ Submit defensive decision.

  Usage: defensive [--alignment TYPE] [--infield DEPTH] [--outfield DEPTH] [--hold BASES]
  
  Options:
    --alignment    normal, shifted_left, shifted_right, extreme_shift
    --infield      in, normal, back, double_play
    --outfield     in, normal, back
    --hold         Comma-separated bases (e.g., 1,3)
  
  Examples:
    defensive
    defensive --alignment shifted_left
    defensive --infield double_play --hold 1,3
  """
  async def _defensive():
      try:
          gid = self._ensure_game()
          await self._ensure_game_loaded(gid)

          # Parse arguments
          args = parse_defensive_args(arg)

          # Submit decision
          await game_commands.submit_defensive_decision(
              game_id=gid,
              alignment=args['alignment'],
              infield=args['infield'],
              outfield=args['outfield'],
              hold_runners=args['hold']
          )

      except ArgumentParseError as e:
          display.print_error(f"Invalid arguments: {e}")
      except ValueError:
          pass  # Already printed error
      except Exception as e:
          display.print_error(f"Failed: {e}")
          logger.exception("Defensive error")

  self._run_async(_defensive())

Replace do_offensive method:

def do_offensive(self, arg): """ Submit offensive decision.

  Usage: offensive [--approach TYPE] [--steal BASES] [--hit-run] [--bunt]
  
  Options:
    --approach     normal, contact, power, patient
    --steal        Comma-separated bases (e.g., 2,3)
    --hit-run      Enable hit-and-run (flag)
    --bunt         Attempt bunt (flag)
  
  Examples:
    offensive
    offensive --approach power
    offensive --steal 2 --hit-run
  """
  async def _offensive():
      try:
          gid = self._ensure_game()
          await self._ensure_game_loaded(gid)

          # Parse arguments
          args = parse_offensive_args(arg)

          # Submit decision
          await game_commands.submit_offensive_decision(
              game_id=gid,
              approach=args['approach'],
              steal_attempts=args['steal'],
              hit_and_run=args['hit_run'],
              bunt_attempt=args['bunt']
          )

      except ArgumentParseError as e:
          display.print_error(f"Invalid arguments: {e}")
      except ValueError:
          pass
      except Exception as e:
          display.print_error(f"Failed: {e}")
          logger.exception("Offensive error")

  self._run_async(_offensive())

Replace do_quick_play method:

def do_quick_play(self, arg): """ Auto-play multiple plays with default decisions.

  Usage: quick_play [COUNT]
  
  Examples:
    quick_play        # Play 1 play
    quick_play 10     # Play 10 plays
    quick_play 27     # Play ~3 innings
  """
  async def _quick_play():
      try:
          gid = self._ensure_game()
          await self._ensure_game_loaded(gid)

          # Parse arguments
          args = parse_quick_play_args(arg)

          # Execute quick play
          plays_completed = await game_commands.quick_play_rounds(
              game_id=gid,
              count=args['count']
          )

          display.print_success(f"Completed {plays_completed} plays")

      except ArgumentParseError as e:
          display.print_error(f"Invalid arguments: {e}")
      except ValueError:
          pass
      except Exception as e:
          display.print_error(f"Failed: {e}")
          logger.exception("Quick play error")

  self._run_async(_quick_play())

Replace do_use_game method:

def do_use_game(self, arg): """ Switch to a different game.

  Usage: use_game <game_id>
  
  Example:
    use_game a1b2c3d4-e5f6-7890-abcd-ef1234567890
  """
  try:
      # Parse arguments
      args = parse_use_game_args(arg)

      gid = UUID(args['game_id'])
      self.current_game_id = gid
      Config.set_current_game(gid)
      display.print_success(f"Switched to game: {gid}")

  except ArgumentParseError as e:
      display.print_error(f"Invalid arguments: {e}")
  except ValueError:
      display.print_error(f"Invalid UUID: {arg}")

Testing Plan

3. Create backend/tests/unit/terminal_client/test_arg_parser.py

""" Unit tests for argument parser. """ import pytest

from terminal_client.arg_parser import ( CommandArgumentParser, ArgumentParseError, parse_new_game_args, parse_defensive_args, parse_offensive_args )

class TestCommandArgumentParser: """Tests for CommandArgumentParser."""

  def test_parse_simple_string_arg(self):
      """Test parsing simple string argument."""
      schema = {'name': {'type': str, 'default': 'default'}}
      result = CommandArgumentParser.parse_args('--name test', schema)
      assert result['name'] == 'test'

  def test_parse_integer_arg(self):
      """Test parsing integer argument."""
      schema = {'count': {'type': int, 'default': 1}}
      result = CommandArgumentParser.parse_args('--count 42', schema)
      assert result['count'] == 42

  def test_parse_flag_arg(self):
      """Test parsing boolean flag."""
      schema = {
          'verbose': {'type': bool, 'flag': True, 'default': False}
      }
      result = CommandArgumentParser.parse_args('--verbose', schema)
      assert result['verbose'] is True

  def test_parse_int_list(self):
      """Test parsing comma-separated integer list."""
      schema = {'bases': {'type': 'int_list', 'default': []}}
      result = CommandArgumentParser.parse_args('--bases 1,2,3', schema)
      assert result['bases'] == [1, 2, 3]

  def test_parse_quoted_string(self):
      """Test parsing quoted string with spaces."""
      schema = {'message': {'type': str, 'default': ''}}
      result = CommandArgumentParser.parse_args('--message "hello world"', schema)
      assert result['message'] == 'hello world'

  def test_parse_positional_arg(self):
      """Test parsing positional argument."""
      schema = {
          'count': {'type': int, 'positional': True, 'default': 1}
      }
      result = CommandArgumentParser.parse_args('10', schema)
      assert result['count'] == 10

  def test_parse_mixed_args(self):
      """Test parsing mix of options and positional."""
      schema = {
          'count': {'type': int, 'positional': True, 'default': 1},
          'league': {'type': str, 'default': 'sba'}
      }
      result = CommandArgumentParser.parse_args('5 --league pd', schema)
      assert result['count'] == 5
      assert result['league'] == 'pd'

  def test_parse_unknown_option_raises(self):
      """Test that unknown option raises error."""
      schema = {'name': {'type': str, 'default': 'default'}}
      with pytest.raises(ArgumentParseError, match="Unknown option"):
          CommandArgumentParser.parse_args('--invalid test', schema)

  def test_parse_missing_value_raises(self):
      """Test that missing value for option raises error."""
      schema = {'name': {'type': str, 'default': 'default'}}
      with pytest.raises(ArgumentParseError, match="requires a value"):
          CommandArgumentParser.parse_args('--name', schema)

  def test_parse_invalid_type_raises(self):
      """Test that invalid type conversion raises error."""
      schema = {'count': {'type': int, 'default': 1}}
      with pytest.raises(ArgumentParseError, match="expected int"):
          CommandArgumentParser.parse_args('--count abc', schema)

  def test_parse_empty_string(self):
      """Test parsing empty string returns defaults."""
      schema = {
          'name': {'type': str, 'default': 'default'},
          'count': {'type': int, 'default': 1}
      }
      result = CommandArgumentParser.parse_args('', schema)
      assert result['name'] == 'default'
      assert result['count'] == 1

  def test_parse_hyphen_to_underscore(self):
      """Test that hyphens in options convert to underscores."""
      schema = {'home_team': {'type': int, 'default': 1}}
      result = CommandArgumentParser.parse_args('--home-team 5', schema)
      assert result['home_team'] == 5

class TestPrebuiltParsers: """Tests for pre-built parser functions."""

  def test_parse_new_game_args_defaults(self):
      """Test new_game parser with defaults."""
      result = parse_new_game_args('')
      assert result['league'] == 'sba'
      assert result['home_team'] == 1
      assert result['away_team'] == 2

  def test_parse_new_game_args_custom(self):
      """Test new_game parser with custom values."""
      result = parse_new_game_args('--league pd --home-team 5 --away-team 3')
      assert result['league'] == 'pd'
      assert result['home_team'] == 5
      assert result['away_team'] == 3

  def test_parse_defensive_args_defaults(self):
      """Test defensive parser with defaults."""
      result = parse_defensive_args('')
      assert result['alignment'] == 'normal'
      assert result['infield'] == 'normal'
      assert result['outfield'] == 'normal'
      assert result['hold'] == []

  def test_parse_defensive_args_with_hold(self):
      """Test defensive parser with hold runners."""
      result = parse_defensive_args('--alignment shifted_left --hold 1,3')
      assert result['alignment'] == 'shifted_left'
      assert result['hold'] == [1, 3]

  def test_parse_offensive_args_flags(self):
      """Test offensive parser with flags."""
      result = parse_offensive_args('--approach power --hit-run --bunt')
      assert result['approach'] == 'power'
      assert result['hit_run'] is True
      assert result['bunt'] is True

  def test_parse_offensive_args_steal(self):
      """Test offensive parser with steal attempts."""
      result = parse_offensive_args('--steal 2,3')
      assert result['steal'] == [2, 3]

Benefits of Improved Parsing

1. Handles quoted strings: --message "double steal attempt" works correctly
2. Better error messages: Clear feedback on what went wrong
3. Type validation: Automatic conversion with helpful errors
4. Consistent behavior: Same parsing logic for REPL and CLI
5. Extensible: Easy to add new argument types
6. Edge case handling: Properly handles empty strings, trailing spaces, etc.

Example Usage

Before (manual parsing, breaks on spaces):

⚾ > defensive --hold 1,3 # Works ⚾ > defensive --alignment shifted left # Breaks! (sees 'shifted' and 'left' separately)

After (shlex parsing, handles correctly):

⚾ > defensive --hold 1,3 # Still works ⚾ > defensive --alignment "shifted left" # Now works with quotes! ⚾ > quick_play 10 # Positional arg works ⚾ > offensive --hit-run --bunt # Multiple flags work