balatrobot 0.7.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

balatrobot/__init__.py

@@ -1,21 +1,7 @@
-"""BalatroBot - Python client for the BalatroBot game API."""
+"""BalatroBot - API for developing Balatro bots."""
 
-from .client import BalatroClient
-from .enums import Actions, Decks, Stakes, State
-from .exceptions import BalatroError
-from .models import G
+from balatrobot.config import Config
+from balatrobot.manager import BalatroInstance
 
-__version__ = "0.7.3"
-__all__ = [
-    # Main client
-    "BalatroClient",
-    # Enums
-    "Actions",
-    "Decks",
-    "Stakes",
-    "State",
-    # Exception
-    "BalatroError",
-    # Models
-    "G",
-]
+__version__ = "1.0.0"
+__all__ = ["BalatroInstance", "Config", "__version__"]

balatrobot/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m balatrobot."""
+
+from balatrobot.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

balatrobot/cli.py

@@ -0,0 +1,56 @@
+"""CLI entry point for BalatroBot launcher."""
+
+import argparse
+import asyncio
+
+from balatrobot.config import Config
+from balatrobot.manager import BalatroInstance
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser for balatrobot CLI."""
+    # fmt: off
+    parser = argparse.ArgumentParser(prog="balatrobot", description="Start Balatro with BalatroBot mod loaded")
+
+    # No defaults - env vars and dataclass defaults handle it
+    parser.add_argument("--host", help="Server hostname (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, help="Server port (default: 12346)")
+    parser.add_argument("--logs-path", help="Directory for log files (default: logs)")
+
+    # Boolean flags - store_const so None means "not provided" -> check env var
+    parser.add_argument("--fast", action="store_const", const=True, help="Enable fast mode (10x speed)")
+    parser.add_argument("--headless", action="store_const", const=True, help="Enable headless mode")
+    parser.add_argument("--render-on-api", action="store_const", const=True, help="Render only on API calls")
+    parser.add_argument("--audio", action="store_const", const=True, help="Enable audio")
+    parser.add_argument("--debug", action="store_const", const=True, help="Enable debug mode")
+    parser.add_argument("--no-shaders", action="store_const", const=True, help="Disable shaders")
+
+    # Path args
+    parser.add_argument("--balatro-path", help="Path to Balatro executable")
+    parser.add_argument("--lovely-path", help="Path to lovely library")
+    parser.add_argument("--love-path", help="Path to LOVE executable")
+    parser.add_argument("--platform", choices=["darwin", "linux", "windows", "native"])
+    # fmt: on
+
+    return parser
+
+
+async def async_main(argv: list[str] | None = None) -> int:
+    """Async main entry point."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+    config = Config.from_args(args)
+
+    async with BalatroInstance(config) as instance:
+        print(f"Balatro running on port {instance.port}. Press Ctrl+C to stop.")
+        while True:
+            await asyncio.sleep(5)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for balatrobot CLI."""
+    try:
+        asyncio.run(async_main(argv))
+        return 0
+    except KeyboardInterrupt:
+        return 0

balatrobot/config.py

@@ -0,0 +1,101 @@
+"""Configuration dataclass for BalatroBot launcher."""
+
+import os
+from dataclasses import dataclass
+from typing import Any, Self
+
+# Mapping: config field -> env var
+ENV_MAP: dict[str, str] = {
+    "host": "BALATROBOT_HOST",
+    "port": "BALATROBOT_PORT",
+    "fast": "BALATROBOT_FAST",
+    "headless": "BALATROBOT_HEADLESS",
+    "render_on_api": "BALATROBOT_RENDER_ON_API",
+    "audio": "BALATROBOT_AUDIO",
+    "debug": "BALATROBOT_DEBUG",
+    "no_shaders": "BALATROBOT_NO_SHADERS",
+    "balatro_path": "BALATROBOT_BALATRO_PATH",
+    "lovely_path": "BALATROBOT_LOVELY_PATH",
+    "love_path": "BALATROBOT_LOVE_PATH",
+    "platform": "BALATROBOT_PLATFORM",
+    "logs_path": "BALATROBOT_LOGS_PATH",
+}
+
+BOOL_FIELDS = frozenset(
+    {"fast", "headless", "render_on_api", "audio", "debug", "no_shaders"}
+)
+INT_FIELDS = frozenset({"port"})
+
+
+def _parse_env_value(field: str, value: str) -> str | int | bool:
+    """Convert env var string to proper type. Raises ValueError on invalid int."""
+    if field in BOOL_FIELDS:
+        return value in ("1", "true")
+    if field in INT_FIELDS:
+        return int(value)  # Raises ValueError if invalid
+    return value
+
+
+@dataclass
+class Config:
+    """Configuration for BalatroBot launcher."""
+
+    # HTTP
+    host: str = "127.0.0.1"
+    port: int = 12346
+
+    # Balatro
+    fast: bool = False
+    headless: bool = False
+    render_on_api: bool = False
+    audio: bool = False
+    debug: bool = False
+    no_shaders: bool = False
+
+    # Launcher
+    balatro_path: str | None = None
+    lovely_path: str | None = None
+    love_path: str | None = None
+
+    # Instance
+    platform: str | None = None
+    logs_path: str = "logs"
+
+    @classmethod
+    def from_args(cls, args) -> Self:
+        """Create Config from CLI args with env var fallback."""
+        kwargs: dict[str, Any] = {}
+
+        for field, env_var in ENV_MAP.items():
+            cli_val = getattr(args, field, None)
+            if cli_val is not None:
+                kwargs[field] = cli_val
+            elif (env_val := os.environ.get(env_var)) is not None:
+                kwargs[field] = _parse_env_value(field, env_val)
+
+        return cls(**kwargs)
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """Create Config from environment variables only."""
+        kwargs: dict[str, Any] = {}
+
+        for field, env_var in ENV_MAP.items():
+            if (env_val := os.environ.get(env_var)) is not None:
+                kwargs[field] = _parse_env_value(field, env_val)
+
+        return cls(**kwargs)
+
+    def to_env(self) -> dict[str, str]:
+        """Convert config to environment variables dict."""
+        env: dict[str, str] = {}
+        for field, env_var in ENV_MAP.items():
+            value = getattr(self, field)
+            if value is None:
+                continue
+            if field in BOOL_FIELDS:
+                if value:
+                    env[env_var] = "1"
+            else:
+                env[env_var] = str(value)
+        return env

balatrobot/manager.py

@@ -0,0 +1,129 @@
+"""Context manager for a Balatro instance."""
+
+import asyncio
+import subprocess
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+
+from balatrobot.config import Config
+from balatrobot.platforms import get_launcher
+
+HEALTH_TIMEOUT = 30.0
+
+
+class BalatroInstance:
+    """Context manager for a single Balatro instance."""
+
+    def __init__(self, config: Config | None = None, **overrides) -> None:
+        """Initialize a Balatro instance.
+
+        Args:
+            config: Base configuration. If None, uses Config from environment.
+            **overrides: Override specific config fields (e.g., port=12347).
+        """
+        base = config or Config.from_env()
+        self._config = replace(base, **overrides) if overrides else base
+        self._process: subprocess.Popen | None = None
+        self._log_path: Path | None = None
+
+    @property
+    def port(self) -> int:
+        """Get the port this instance is running on."""
+        return self._config.port
+
+    @property
+    def process(self) -> subprocess.Popen:
+        """Get the subprocess. Raises if not started."""
+        if self._process is None:
+            raise RuntimeError("Instance not started")
+        return self._process
+
+    @property
+    def log_path(self) -> Path | None:
+        """Get the log file path, if available."""
+        return self._log_path
+
+    async def _wait_for_health(self, timeout: float = HEALTH_TIMEOUT) -> None:
+        """Wait for health endpoint to respond."""
+        url = f"http://{self._config.host}:{self._config.port}"
+        payload = {"jsonrpc": "2.0", "method": "health", "params": {}, "id": 1}
+        start = asyncio.get_event_loop().time()
+
+        while asyncio.get_event_loop().time() - start < timeout:
+            try:
+                async with httpx.AsyncClient(timeout=2.0) as client:
+                    response = await client.post(url, json=payload)
+                    data = response.json()
+                    if "result" in data and data["result"].get("status") == "ok":
+                        return
+            except (httpx.ConnectError, httpx.TimeoutException):
+                pass
+            await asyncio.sleep(0.5)
+
+        raise RuntimeError(
+            f"Health check failed after {timeout}s on "
+            f"{self._config.host}:{self._config.port}"
+        )
+
+    async def start(self) -> None:
+        """Start the Balatro instance and wait for health."""
+        if self._process is not None:
+            raise RuntimeError("Instance already started")
+
+        # Create session directory
+        timestamp = datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+        session_dir = Path(self._config.logs_path) / timestamp
+        session_dir.mkdir(parents=True, exist_ok=True)
+        self._log_path = session_dir / f"{self._config.port}.log"
+
+        # Get launcher and start process
+        launcher = get_launcher(self._config.platform)
+        print(f"Starting Balatro on port {self._config.port}...")
+
+        self._process = await launcher.start(self._config, session_dir)
+
+        # Wait for health
+        print(f"Waiting for health check on {self._config.host}:{self._config.port}...")
+        try:
+            await self._wait_for_health()
+        except RuntimeError as e:
+            await self.stop()
+            raise RuntimeError(f"{e}. Check log file: {self._log_path}") from e
+
+        print(f"Balatro started (PID: {self._process.pid})")
+
+    async def stop(self) -> None:
+        """Stop the Balatro instance."""
+        if self._process is None:
+            return
+
+        process = self._process
+        self._process = None
+
+        print(f"Stopping instance on port {self._config.port}...")
+
+        # Try graceful termination first
+        process.terminate()
+
+        loop = asyncio.get_running_loop()
+        try:
+            await asyncio.wait_for(
+                loop.run_in_executor(None, process.wait),
+                timeout=5,
+            )
+        except asyncio.TimeoutError:
+            print(f"Force killing instance on port {self._config.port}...")
+            process.kill()
+            await loop.run_in_executor(None, process.wait)
+
+    async def __aenter__(self) -> "BalatroInstance":
+        """Start instance on context entry."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        """Stop instance on context exit."""
+        await self.stop()

balatrobot/platforms/__init__.py

@@ -0,0 +1,51 @@
+"""Platform detection and launcher dispatch."""
+
+import platform as platform_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from balatrobot.platforms.base import BaseLauncher
+
+VALID_PLATFORMS = frozenset({"darwin", "linux", "windows", "native"})
+
+
+def get_launcher(platform: str | None = None) -> "BaseLauncher":
+    """Get launcher for the specified or detected platform.
+
+    Args:
+        platform: Optional platform to use instead of auto-detection.
+            Valid values: "darwin", "linux", "windows", "native"
+
+    Returns:
+        Launcher instance for the platform
+
+    Raises:
+        RuntimeError: If platform is not supported
+        ValueError: If platform is invalid
+    """
+    # Use override if provided, otherwise auto-detect
+    if platform:
+        if platform not in VALID_PLATFORMS:
+            raise ValueError(
+                f"Invalid platform '{platform}'. "
+                f"Must be one of: {', '.join(sorted(VALID_PLATFORMS))}"
+            )
+        system = platform
+    else:
+        system = platform_module.system().lower()
+
+    match system:
+        case "darwin":
+            from balatrobot.platforms.macos import MacOSLauncher
+
+            return MacOSLauncher()
+        case "linux":
+            raise NotImplementedError("Linux launcher not yet implemented")
+        case "windows":
+            raise NotImplementedError("Windows launcher not yet implemented")
+        case "native":
+            from balatrobot.platforms.native import NativeLauncher
+
+            return NativeLauncher()
+        case _:
+            raise RuntimeError(f"Unsupported platform: {system}")

balatrobot/platforms/base.py

@@ -0,0 +1,69 @@
+"""Base launcher class for all platforms."""
+
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from balatrobot.config import Config
+
+
+class BaseLauncher(ABC):
+    """Abstract base class for platform-specific launchers."""
+
+    @abstractmethod
+    def validate_paths(self, config: Config) -> None:
+        """Validate paths exist, apply platform defaults if None.
+
+        Mutates config in-place with platform-specific defaults.
+
+        Raises:
+            RuntimeError: If required paths are missing or invalid.
+        """
+        ...
+
+    @abstractmethod
+    def build_env(self, config: Config) -> dict[str, str]:
+        """Build environment dict for subprocess.
+
+        Returns:
+            Environment dict including os.environ and platform-specific vars.
+        """
+        ...
+
+    @abstractmethod
+    def build_cmd(self, config: Config) -> list[str]:
+        """Build command list for subprocess.
+
+        Returns:
+            Command list suitable for subprocess.Popen.
+        """
+        ...
+
+    async def start(self, config: Config, session_dir: Path) -> subprocess.Popen:
+        """Start Balatro with the given configuration.
+
+        Args:
+            config: Launcher configuration (mutated with defaults).
+            session_dir: Directory for log files.
+
+        Returns:
+            The subprocess.Popen object.
+
+        Raises:
+            RuntimeError: If startup fails.
+        """
+        self.validate_paths(config)
+        env = self.build_env(config)
+        cmd = self.build_cmd(config)
+
+        log_path = session_dir / f"{config.port}.log"
+
+        with open(log_path, "w") as log:
+            process = subprocess.Popen(
+                cmd,
+                env=env,
+                stdout=log,
+                stderr=subprocess.STDOUT,
+            )
+
+        return process

balatrobot/platforms/macos.py

@@ -0,0 +1,47 @@
+"""macOS platform launcher."""
+
+import os
+from pathlib import Path
+
+from balatrobot.config import Config
+from balatrobot.platforms.base import BaseLauncher
+
+
+class MacOSLauncher(BaseLauncher):
+    """macOS-specific Balatro launcher."""
+
+    def validate_paths(self, config: Config) -> None:
+        """Validate paths, apply macOS defaults if None."""
+        if config.love_path is None:
+            config.love_path = str(
+                Path.home()
+                / "Library/Application Support/Steam/steamapps/common/Balatro"
+                / "Balatro.app/Contents/MacOS/love"
+            )
+        if config.lovely_path is None:
+            config.lovely_path = str(
+                Path.home()
+                / "Library/Application Support/Steam/steamapps/common/Balatro"
+                / "liblovely.dylib"
+            )
+
+        love = Path(config.love_path)
+        lovely = Path(config.lovely_path)
+
+        if not love.exists():
+            raise RuntimeError(f"LOVE executable not found: {love}")
+        if not lovely.exists():
+            raise RuntimeError(f"liblovely.dylib not found: {lovely}")
+
+    def build_env(self, config: Config) -> dict[str, str]:
+        """Build environment with DYLD_INSERT_LIBRARIES."""
+        assert config.lovely_path is not None
+        env = os.environ.copy()
+        env["DYLD_INSERT_LIBRARIES"] = config.lovely_path
+        env.update(config.to_env())
+        return env
+
+    def build_cmd(self, config: Config) -> list[str]:
+        """Build macOS launch command."""
+        assert config.love_path is not None
+        return [config.love_path]

balatrobot/platforms/native.py

@@ -0,0 +1,111 @@
+"""Native LOVE launcher for Linux environments."""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+from balatrobot.config import Config
+from balatrobot.platforms.base import BaseLauncher
+
+
+def _detect_love_path() -> Path | None:
+    """Detect LOVE executable in PATH."""
+    found = shutil.which("love")
+    return Path(found) if found else None
+
+
+def _detect_lovely_path() -> Path | None:
+    """Detect liblovely.so in standard locations."""
+    candidates = [
+        Path("/usr/local/lib/liblovely.so"),
+        Path.home() / ".local/lib/liblovely.so",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+class NativeLauncher(BaseLauncher):
+    """Native LOVE launcher using LD_PRELOAD injection (Linux only).
+
+    This launcher is designed for:
+    - Docker containers with LOVE installed
+    - Linux development environments with native LOVE
+
+    Requirements:
+    - Linux operating system
+    - `love` executable in PATH or specified via --love-path
+    - liblovely.so specified via --lovely-path
+    - Game directory specified via --balatro-path
+    """
+
+    def validate_paths(self, config: Config) -> None:
+        """Validate and auto-detect paths for native Linux launcher."""
+        if platform.system().lower() != "linux":
+            raise RuntimeError("Native launcher is only supported on Linux")
+
+        errors: list[str] = []
+
+        # balatro_path (required, no auto-detect)
+        if config.balatro_path is None:
+            errors.append(
+                "Game directory is required.\n"
+                "  Set via: --balatro-path or BALATROBOT_BALATRO_PATH"
+            )
+        else:
+            balatro = Path(config.balatro_path)
+            if not balatro.is_dir():
+                errors.append(f"Game directory not found: {balatro}")
+
+        # lovely_path (required, auto-detect)
+        if config.lovely_path is None:
+            detected = _detect_lovely_path()
+            if detected:
+                config.lovely_path = str(detected)
+            else:
+                errors.append(
+                    "Lovely library is required.\n"
+                    "  Set via: --lovely-path or BALATROBOT_LOVELY_PATH\n"
+                    "  Expected: /usr/local/lib/liblovely.so"
+                )
+        if config.lovely_path:
+            lovely = Path(config.lovely_path)
+            if not lovely.is_file():
+                errors.append(f"Lovely library not found: {lovely}")
+            elif lovely.suffix != ".so":
+                errors.append(f"Lovely library has wrong extension: {lovely}")
+
+        # love_path (required, auto-detect via PATH)
+        if config.love_path is None:
+            detected = _detect_love_path()
+            if detected:
+                config.love_path = str(detected)
+            else:
+                errors.append(
+                    "LOVE executable is required.\n"
+                    "  Set via: --love-path or BALATROBOT_LOVE_PATH\n"
+                    "  Or install love and ensure it's in PATH"
+                )
+        if config.love_path:
+            love = Path(config.love_path)
+            if not love.is_file():
+                errors.append(f"LOVE executable not found: {love}")
+
+        if errors:
+            raise RuntimeError("Path validation failed:\n\n" + "\n\n".join(errors))
+
+    def build_env(self, config: Config) -> dict[str, str]:
+        """Build environment with LD_PRELOAD."""
+        assert config.lovely_path is not None
+        env = os.environ.copy()
+        env["LD_PRELOAD"] = config.lovely_path
+        env.update(config.to_env())
+        return env
+
+    def build_cmd(self, config: Config) -> list[str]:
+        """Build native LOVE launch command."""
+        assert config.love_path is not None
+        assert config.balatro_path is not None
+        return [config.love_path, config.balatro_path]