Lua API rewrite

[S1M0N38]

This pull request introduces significant updates to the repository, including new development workflows, code quality improvements, and the removal of outdated Lua files. The most impactful changes involve adding conventional commit guidelines, enhancing testing workflows, integrating new formatting tools, and simplifying the Lua mod implementation by removing unused files.

Development Workflow Enhancements:

• .claude/commands/commit.md: Added detailed instructions for generating conventional commit messages, including commit types, scopes, and a step-by-step workflow.
• .claude/commands/test.md: Added instructions for running tests based on the testing guidelines in CLAUDE.md.

Code Quality Improvements:

• .claude/settings.json: Introduced post-tool-use hooks for formatting Lua and Python files using StyLua and Ruff.
• .editorconfig: Added configuration for consistent code formatting across Lua and Python files, including indentation, line endings, and charset settings.
• .github/workflows/code_quality.yml: Added a StyLua job to check Lua file formatting in the CI pipeline.

Lua Mod Simplification:

• balatrobot.lua: Simplified the mod initialization by removing unused middleware and bot-related files, focusing solely on the Lua API.
• Removed outdated Lua files (src/lua/bot.lua, src/lua/hook.lua, src/lua/list.lua) that were no longer relevant to the current implementation. [1] [2] [3]

Developer Tools Integration:

• .vscode/extensions.json: Recommended extensions for Python, Lua, and code quality tools like Ruff and StyLua.
• .vscode/settings.json: Configured VSCode settings for Python testing using pytest.

Documentation Updates:

• CLAUDE.md: Added comprehensive documentation on development commands, testing workflows, architecture overview, and coding standards for Python and Lua.

---

The new Lua API expose a limited set of function compare to the original API. However each API function is now well tested (The full gameplay test will be added in future release).

Functions:

• get_game_state - Gets the current game state
• go_to_menu - Navigates to the main menu
• start_run - Starts a new game run with specified parameters (deck, stake, seed, challenge)
• skip_or_select_blind - Skips or selects the current blind
• play_hand_or_discard - Plays selected cards or discards them
• cash_out - Cashes out from the current round to enter the shop
• shop - Selects an action for shop (currently supports "next_round")

[Copilot]

Pull Request Overview

This pull request introduces a comprehensive rewrite of the Lua API implementation with significantly improved testing infrastructure and code quality standards. The most impactful change is the complete replacement of the complex middleware and hook system with a simplified, direct UDP-based API that provides better reliability and maintainability.

Key changes include:

• Complete rewrite of the Lua API architecture removing middleware/hook dependencies
• Addition of comprehensive test suites covering all API functions and connection handling
• Implementation of development workflow improvements including conventional commits, code formatting, and CI enhancements

Reviewed Changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_connection.py	New comprehensive UDP connection and protocol handling tests
tests/test_api_functions.py	New test suite covering all API functions with game state validation
tests/conftest.py	New shared test configuration and helper functions
src/lua/utils.lua	Rewritten utility functions focusing on game state extraction
src/lua/types.lua	New type definitions for improved code documentation
src/lua/api.lua	Complete rewrite of API with direct UDP communication
balatrobot.lua	Simplified mod initialization removing outdated dependencies

[Copilot]

Function is missing a docstring explaining its parameters and purpose. Should document what constitutes a valid error response format.

Suggested change

	"""Helper function to assert error response format and content."""
	"""
	Helper function to assert the format and content of an error response.
	Args:
	response (dict): The response dictionary to validate. Must contain at least
	the keys "error" and "state".
	expected_error_text (str): The expected error message text to check within
	the "error" field of the response.
	expected_context_keys (list, optional): A list of keys expected to be present
	in the "context" field of the response, if the "context" field exists.
	Raises:
	AssertionError: If the response does not match the expected format or content.
	"""

[Copilot]

The debug integration appears to be optional but there's no comment explaining when/why this dependency might not be available or what debugplus-api provides.

Suggested change

	-- Load debug
	-- Load debug
	-- Attempt to load the optional debugplus-api module. This module provides additional debugging utilities,
	-- such as the ability to register custom debug commands and log structured data. It is not required for
	-- the core functionality of the program and is primarily intended for development and debugging purposes.
	-- If the module is unavailable or incompatible, the program will continue to function without it.

[Copilot]

Magic number 3 for EVENT_QUEUE_THRESHOLD lacks explanation. Should document why this specific value is used for determining when game state transitions are complete.

Suggested change

	local SOCKET_TIMEOUT = 0
	local SOCKET_TIMEOUT = 0
	-- The threshold for determining when game state transitions are complete.
	-- This value represents the minimum number of events required in the queue
	-- to trigger a state transition. The value of 3 was chosen based on empirical
	-- testing and ensures smooth gameplay without unnecessary delays.

[Copilot]

The conversion from 0-based to 1-based indexing is performed in-place, modifying the original args.cards array. This could cause confusion if the args are reused elsewhere. Consider creating a new array for the converted indices.