Overview

Date: 2026-05-11

Time: 15:36

Overview

publish-games.py is a standalone FTL2 automation script that uploads browser game files (.html, .js, .wasm) from a local catbeez-games directory to a remote catbeez-arcade server. It supports dev and prod environments and can publish all games or a specified subset. The script uses uv run inline dependencies — no virtualenv setup required.

Usage Patterns

The script is invoked via uv run with environment variables sourced from .env:

source .env && uv run publish-games.py                       # all games to dev
source .env && uv run publish-games.py --prod                # all games to prod
source .env && uv run publish-games.py asteroids dash        # specific games to dev
source .env && uv run publish-games.py --prod asteroids dash # specific games to prod

Game discovery is automatic — discoverlocalgames() finds all .html files in the source directory and derives game names from their stems.

API and Configuration

• --prod flag: Switches from dev to prod environment. Affects which state file and hostname are used.
• Positional args: Optional game names to publish. If omitted, all discovered games are published.
• Environment config (ENVS dict):
• dev: state file state.json, hostname arcade
• prod: state file state-prod.json, hostname catbeez-prod
• GAMES_SRC: Hardcoded path /Users/ben/git/catbeez-games/games — the local directory containing game assets.
• EXTENSIONS: File types uploaded: html, js, wasm.

Key Behaviors

• State file bootstrapping: The script opens an existing state file to extract host connection info (ansiblehost), then re-registers the host with ansiblebecome=True so it can write to catbeez-owned directories. This means the state file must already exist from a prior provisioning run.
• Idempotent uploads: Uses host.copy() and host.file() modules, which are idempotent — re-running is safe.
• No restart needed: The remote app discovers new games dynamically, so publishing is purely a file upload operation.
• Validation: If a named game's .html file doesn't exist locally, the script exits with an error before connecting to the remote host.
• Sparse uploads: Only uploads files that exist locally — if a game has no .wasm file, it's skipped without error.

Relationships

• FTL2 core: Uses from ftl2 import automation as the async context manager entry point. Calls ftl.add_host(), host.file(), and host.copy() modules.
• State files: Reads state.json or state-prod.json to recover host connection details from a previous provisioning run (likely from a separate deploy script).
• catbeez-games repo: Depends on /Users/ben/git/catbeez-games/games as the local source of game assets.
• catbeez-arcade server: The remote target where files land at /home/catbeez/games/. The server's app picks up new files automatically.
• uv: Uses PEP 723 inline script metadata so uv run handles dependency installation (pulls ftl2 from GitHub).