feat: add cli support linux proton issue #128 (draft)

.gitignore

@@ -255,6 +255,7 @@ __marimo__/
 
 # Lua Language Server
 .luarc.json
+.lua-lsp/
 
 # Compiled Lua sources
 luac.out

CLAUDE.md

@@ -73,7 +73,7 @@ Controls the game lifecycle and provides the CLI.
 - **CLI** (`cli.py`): Entry point (`balatrobot`). Handles arguments like `--fast`, `--debug`, `--headless`.
 - **Manager** (`manager.py`): `BalatroInstance` context manager. Starts the game process, handles logging, and waits for the API to be healthy.
 - **Config** (`config.py`): Configuration management using `dataclasses` and environment variables.
-- **Platform Abstraction** (`platforms/`): Cross-platform game launcher system with platform-specific implementations for macOS, Windows, and native Love2D.
+- **Platform Abstraction** (`platforms/`): Cross-platform game launcher system with platform-specific implementations for macOS, Windows, Linux (Steam/Proton), and native Love2D.
 
 ### 2. Lua Layer (`src/lua/`)
 

docs/cli.md

@@ -223,6 +223,47 @@ uvx balatrobot serve --fast
 uvx balatrobot serve --love-path "/path/to/love" --lovely-path "/path/to/liblovely.dylib"
 ```
 
+### Linux (Steam/Proton) Platform (Experimental)
+
+This platform is in development, and you may encounter bugs. If you do intend to run BalatroBot on Steam Deck/Proton, please report any issues you encounter.
+
+The `linux` platform launches Balatro via Steam's Proton compatibility layer. The CLI auto-detects Steam, Proton, and Balatro paths across all Steam library folders.
+
+**Auto-Detected Paths:**
+
+- `BALATROBOT_LOVE_PATH`: `~/.local/share/Steam/steamapps/common/Balatro/Balatro.exe`
+- `BALATROBOT_LOVELY_PATH`: `~/.local/share/Steam/steamapps/common/Balatro/version.dll`
+
+**Auto-Detected Environment:**
+
+The launcher automatically configures the following when not already set:
+
+- `DISPLAY`: Detected from X11 sockets in `/tmp/.X11-unix/` (e.g. `:0`)
+- `XAUTHORITY`: Detected from `XDG_RUNTIME_DIR/xauth_*` or `~/.Xauthority`
+- `WINEDLLOVERRIDES=version=n,b`: Forces Wine to load the native `version.dll` (Lovely injector) instead of Wine's built-in implementation. This is the equivalent of setting the Steam launch option `WINEDLLOVERRIDES="version=n,b" %command%`.
+
+**Requirements:**
+
+- Balatro installed via Steam
+- [Proton](https://github.com/ValveSoftware/Proton) installed via Steam (Settings > Compatibility)
+- [Lovely Injector](https://github.com/ethangreen-dev/lovely-injector) `version.dll` placed in the Balatro game directory
+- Balatro must have been run at least once through Steam to create the Wine prefix
+- Mods directory: `~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods`
+
+**Launch:**
+
+```bash
+# Auto-detects paths, display, and Wine configuration
+uvx balatrobot serve --fast
+
+# Or specify custom paths
+uvx balatrobot serve --love-path "/path/to/Balatro.exe" --lovely-path "/path/to/version.dll"
+```
+
+!!! note "Steam Deck"
+
+    This platform works on Steam Deck, including when connected via SSH where `DISPLAY` and `XAUTHORITY` are not set. The launcher auto-detects the gamescope X server and Xauthority file. Since the read-only OS does not include `make`, use `./scripts/dev.sh` as a drop-in replacement for development tasks (see [Contributing](contributing.md#steam-deck--environments-without-make)).
+
 ### Native Platform (Linux Only)
 
 The `native` platform runs Balatro from source code using the LÖVE framework installed via package manager. This requires specific directory structure:

docs/contributing.md

@@ -4,7 +4,7 @@ Guide for contributing to BalatroBot development.
 
 !!! warning "Help Needed: Linux (Proton) Support"
 
-    We currently lack CLI support for **Linux (Proton)**. Contributions to implement this platform are highly welcome!
+    CLI support for **Linux (Proton)** is in development. Contributions to implement this platform are highly welcome!
 
     Please refer to the existing implementations for guidance:
 
@@ -53,6 +53,10 @@ export BALATROBOT_AUDIO=0
 
 **Setup:** Install [direnv](https://direnv.net/), then create `.envrc` in the project root with the above configuration, updating paths for your system.
 
+### External Development Tools
+
+`uv sync --group dev --group test` installs Python dependencies only. Non-Python tools such as `stylua` and `lua-language-server` are not managed by `uv` and must be installed separately if you want Lua formatting and Lua type checking.
+
 ### Lua LSP Configuration
 
 The `.luarc.json` file should be placed at the root of the balatrobot repository. It configures the Lua Language Server for IDE support (autocomplete, diagnostics, type checking).
@@ -65,6 +69,27 @@ The `.luarc.json` file should be placed at the root of the balatrobot repository
     - Love2D library: `path/to/love2d/library` (clone locally: [LuaCATS/love2d](https://github.com/LuaCATS/love2d))
     - LuaSocket library: `path/to/luasocket/library` (clone locally: [LuaCATS/luasocket](https://github.com/LuaCATS/luasocket))
 
+**Quick setup:** Clone the LuaCATS libraries into a `.lua-lsp/` directory (already gitignored):
+
+```bash
+mkdir -p .lua-lsp
+git clone --depth 1 https://github.com/LuaCATS/love2d.git .lua-lsp/love2d
+git clone --depth 1 https://github.com/LuaCATS/luasocket.git .lua-lsp/luasocket
+```
+
+Then update the `workspace.library` paths in `.luarc.json` — the Steamodded `lsp_def` path varies by platform:
+
+| Platform             | Steamodded `lsp_def` path                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| macOS                | `~/Library/Application Support/Balatro/Mods/smods/lsp_def`                                                                 |
+| Windows              | `%AppData%/Balatro/Mods/smods/lsp_def`                                                                                     |
+| Linux (Steam/Proton) | `~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/smods/lsp_def` |
+| Linux (Native)       | `~/.config/love/Mods/smods/lsp_def`                                                                                        |
+
+!!! note "Steamodded version suffix"
+
+    Your `smods` directory may include a version suffix (e.g. `smods-1.0.0-beta-1503a`). Use the actual directory name on your system.
+
 **Example `.luarc.json`:**
 
 ```json
@@ -132,7 +157,7 @@ ln -s "$(pwd)" ~/.config/love/Mods/balatrobot/
 New-Item -ItemType SymbolicLink -Path "$env:APPDATA\Balatro\Mods\balatrobot" -Target (Get-Location)
 ```
 
-### 3. Install Dependencies
+### 3. Install Dependencies (Windows/Mac/Linux Native only, see [Steam Deck / Environments Without Make](#steam-deck--environments-without-make))
 
 ```bash
 make install
@@ -142,7 +167,7 @@ make install
 
 Activate the virtual environment to use the `balatrobot` command:
 
-**macOS/Linux:**
+**macOS/Linux (Native or Proton):**
 
 ```bash
 source .venv/bin/activate
@@ -174,6 +199,7 @@ Tests use Python + pytest to communicate with the Lua API. You don't need to hav
 
 ```bash
 # Run all tests (runs CLI and Lua suites separately)
+# If on Proton/Steam Deck use: uv run ./scripts/dev.sh test
 make test
 
 # Run Lua tests (parallel execution recommended)
@@ -216,6 +242,25 @@ make all       # Run quality checks + tests
 
     The `make fixtures` command is only required if you need to explicitly generate fixtures. When running tests, missing fixtures are automatically generated if required.
 
+### Steam Deck / Environments Without Make
+
+On platforms where `make` is not available (e.g. Steam Deck's read-only OS), use `scripts/dev.sh` as a drop-in replacement:
+
+```bash
+./scripts/dev.sh help      # Show all available commands
+./scripts/dev.sh install   # Install all dependencies
+./scripts/dev.sh lint      # Run ruff linter
+./scripts/dev.sh format    # Format code
+./scripts/dev.sh typecheck # Run type checkers
+./scripts/dev.sh quality   # Run all quality checks
+./scripts/dev.sh test      # Run all tests
+./scripts/dev.sh fixtures  # Generate test fixtures
+./scripts/dev.sh stop      # Kill all BalatroBot and Balatro processes
+./scripts/dev.sh all       # Run quality checks + tests
+```
+
+The script mirrors all Makefile targets and can be used anywhere `make <target>` is referenced in these docs.
+
 ## Code Structure
 
 ```

docs/example-bot.md

@@ -85,10 +85,10 @@ if __name__ == "__main__":
     uvx balatrobot serve
     ```
 
-2. In another terminal, run the bot:
+2. In another terminal, run the bot from the repo root:
 
     ```bash
-    uv run bot.py
+    uv run examples/bot.py
     ```
 
 The bot will automatically start a new game and play until it wins or loses.

docs/installation.md

@@ -38,7 +38,7 @@ Mods/
 | Linux (Steam/Proton) | `~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/` |
 | Linux (Native)       | `~/.config/love/Mods/balatrobot/`                                                                             |
 
-> Steam/Proton launcher not supported yet. Track progress in [#128](https://github.com/coder/balatrobot/issues/128)
+> Linux (Steam/Proton) is an experimental platform via the `linux` platform. See the [CLI Reference](cli.md#linux-steamproton-platform) for details.
 
 ### 3. Launch Balatro
 

examples/bot.py

@@ -0,0 +1,74 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "requests",
+# ]
+# ///
+
+import requests
+
+# BalatroBot API endpoint
+URL = "http://127.0.0.1:12346"
+
+
+def rpc(method: str, params: dict = {}) -> dict:
+    """Send a JSON-RPC 2.0 request to the BalatroBot API."""
+    response = requests.post(
+        URL,
+        json={
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+            "id": 1,
+        },
+    )
+    data = response.json()
+    # Raise if error, otherwise return result (contains game state)
+    if "error" in data:
+        raise Exception(data["error"]["message"])
+    return data["result"]
+
+
+def play_game():
+    """Play a complete game of Balatro."""
+    # Return to menu and start a new game
+    rpc("menu")
+    state = rpc("start", {"deck": "RED", "stake": "WHITE"})
+    print(f"Started game with seed: {state['seed']}")
+
+    # Main game loop
+    while state["state"] != "GAME_OVER":
+        match state["state"]:
+            case "BLIND_SELECT":
+                # Always select the current blind
+                state = rpc("select")
+
+            case "SELECTING_HAND":
+                # Play the first 5 cards (simple strategy)
+                num_cards = min(5, len(state["hand"]["cards"]))
+                cards = list(range(num_cards))
+                state = rpc("play", {"cards": cards})
+
+            case "ROUND_EVAL":
+                # Collect rewards and go to shop
+                state = rpc("cash_out")
+
+            case "SHOP":
+                # Skip the shop and proceed to next round
+                state = rpc("next_round")
+
+            case _:
+                # Handle any transitional states
+                state = rpc("gamestate")
+
+    # Game ended
+    if state["won"]:
+        print(f"Victory! Final ante: {state['ante_num']}")
+    else:
+        print(f"Game over at ante {state['ante_num']}, round {state['round_num']}")
+
+    return state["won"]
+
+
+if __name__ == "__main__":
+    play_game()

scripts/dev.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# dev.sh — Make-compatible dev task runner for environments without make (e.g. Steam Deck).
+# Usage: ./scripts/dev.sh <target>
+# Mirrors the targets in the project Makefile.
+
+set -euo pipefail
+
+YELLOW='\033[33m'
+GREEN='\033[32m'
+BLUE='\033[34m'
+RED='\033[31m'
+RESET='\033[0m'
+
+MAX_XDIST="${MAX_XDIST:-6}"
+CLI_XDIST_WORKERS="${CLI_XDIST_WORKERS:-2}"
+XDIST_WORKERS=$(python -c "import multiprocessing as mp; print(min(mp.cpu_count(), $MAX_XDIST))")
+LUA_XDIST_WORKERS="${LUA_XDIST_WORKERS:-2}"
+
+print_msg() { printf "%b\n" "$1"; }
+
+cmd_help() {
+    print_msg "${BLUE}BalatroBot Development Tasks${RESET}"
+    print_msg ""
+    print_msg "${YELLOW}Available targets:${RESET}"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "help"      "Show this help message"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "install"   "Install balatrobot and all dependencies (including dev)"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "lint"      "Run ruff linter (check only)"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "format"    "Run formatters (ruff, mdformat, stylua)"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "typecheck" "Run type checkers (Python and Lua)"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "quality"   "Run all code quality checks"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "fixtures"  "Generate fixtures"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "stop"      "Stop BalatroBot and Balatro processes"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "test"      "Run all tests"
+    printf "  ${GREEN}%-18s${RESET} %s\n" "all"       "Run all code quality checks and tests"
+}
+
+cmd_install() {
+    print_msg "${YELLOW}Installing all dependencies...${RESET}"
+    uv sync --group dev --group test
+}
+
+cmd_lint() {
+    print_msg "${YELLOW}Running ruff linter...${RESET}"
+    ruff check --fix --select I .
+    ruff check --fix .
+}
+
+cmd_format() {
+    print_msg "${YELLOW}Running ruff formatter...${RESET}"
+    ruff check --select I --fix .
+    ruff format .
+    print_msg "${YELLOW}Running mdformat formatter...${RESET}"
+    mdformat ./docs README.md CLAUDE.md .claude/skills/balatrobot/SKILL.md
+    if command -v stylua >/dev/null 2>&1; then
+        print_msg "${YELLOW}Running stylua formatter...${RESET}"
+        stylua src/lua
+    else
+        print_msg "${BLUE}Skipping stylua formatter (stylua not found)${RESET}"
+    fi
+}
+
+cmd_typecheck() {
+    print_msg "${YELLOW}Running Python type checker...${RESET}"
+    ty check
+    if command -v lua-language-server >/dev/null 2>&1 && [ -f .luarc.json ]; then
+        print_msg "${YELLOW}Running Lua type checker...${RESET}"
+        lua-language-server --check balatrobot.lua src/lua \
+            --configpath="$(pwd)/.luarc.json" 2>/dev/null
+    else
+        print_msg "${BLUE}Skipping Lua type checker (lua-language-server not found or .luarc.json missing)${RESET}"
+    fi
+}
+
+cmd_quality() {
+    cmd_lint
+    cmd_typecheck
+    cmd_format
+    print_msg "${GREEN}All checks completed${RESET}"
+}
+
+cmd_fixtures() {
+    print_msg "${YELLOW}Generating all fixtures...${RESET}"
+    if ! python tests/fixtures/generate.py; then
+        print_msg "${RED}Fixture generation failed. Make sure BalatroBot is already running and reachable, then try again.${RESET}"
+        return 1
+    fi
+}
+
+cmd_stop() {
+    local stopped=0
+
+    if pkill -f "balatrobot serve" >/dev/null 2>&1; then
+        print_msg "${YELLOW}Stopped BalatroBot serve process(es).${RESET}"
+        stopped=1
+    fi
+
+    if pkill -f "Balatro.exe" >/dev/null 2>&1; then
+        print_msg "${YELLOW}Stopped Balatro game process(es).${RESET}"
+        stopped=1
+    fi
+
+    if [ "$stopped" -eq 0 ]; then
+        print_msg "${BLUE}No BalatroBot or Balatro processes found.${RESET}"
+    fi
+}
+
+cmd_test() {
+    print_msg "${YELLOW}Running tests/cli with ${CLI_XDIST_WORKERS} workers...${RESET}"
+    pytest -n "${CLI_XDIST_WORKERS}" tests/cli
+    print_msg "${YELLOW}Running tests/lua with ${LUA_XDIST_WORKERS} workers...${RESET}"
+    pytest -n "${LUA_XDIST_WORKERS}" tests/lua
+}
+
+cmd_all() {
+    cmd_lint
+    cmd_format
+    cmd_typecheck
+    cmd_test
+    print_msg "${GREEN}All checks and tests completed${RESET}"
+}
+
+target="${1:-help}"
+case "$target" in
+    help|install|lint|format|typecheck|quality|fixtures|stop|test|all)
+        "cmd_${target}"
+        ;;
+    *)
+        print_msg "${RED}Unknown target: ${target}${RESET}"
+        cmd_help
+        exit 1
+        ;;
+esac