Overview

Date: 2026-05-11

Time: 15:36

Overview

This is an FTL2 AI-loop rule that ensures the catbeez-arcade Python wheel and associated game files (HTML, JS, WASM) are uploaded and installed in a Python 3.13 uv-managed virtualenv on the arcade host. It follows the observe/condition/action pattern used by FTL2's reconciliation loop.

Usage Patterns

This rule is not called directly — it's picked up by the FTL2 AI reconciliation loop. The loop evaluates observe to gather state, runs condition() to decide if action is needed, then calls action() if the condition is true.

The rule targets a single host "arcade" and uses three module types via ftl["arcade"]:

await ftl["arcade"].shell(cmd="...")    # Run shell commands
await ftl["arcade"].copy(src=..., dest=..., owner=..., group=...)  # Upload files
await ftl["arcade"].file(path=..., state="directory", owner=..., group=...)  # Ensure directory exists

API and Configuration

• Host: arcade — must be defined in FTL2 inventory
• Observe block: Uses the shell module to check if catbeez-arcade is pip-installed and if .wasm game files exist under ~/games/
• Local paths assumed:
• dist/catbeez_arcade-0.1.0-py3-none-any.whl — the wheel to upload (relative to the rule's working directory)
• ~/git/catbeez-games/games/ — local directory containing game files (HTML, JS, WASM)
• Remote paths:
• ~/.venv/ — Python 3.13 uv venv
• /home/admin/ — wheel upload destination
• /home/admin/games/ — game file destination
• File ownership: All remote files owned by admin:admin

Key Behaviors

• Condition triggers when either: (1) catbeez-arcade is not found in pip output, or (2) the observe command returns a non-zero exit code (game files missing).
• Action is not idempotent in the strict sense — it re-creates the venv and re-uploads all files every time condition is true. The venv creation (uv venv) overwrites any existing venv.
• Uses Python's glob and os inside the action to dynamically discover local game files rather than hardcoding filenames.
• Hardcoded wheel version (0.1.0) — updating the wheel requires editing this rule.
• Sequential file uploads — game files are uploaded one at a time in a loop, not in parallel.

Relationships

• FTL2 modules used: shell, copy, file — standard FTL2 automation modules
• Depends on uv being pre-installed on the arcade host for venv and pip management
• Source material: Game files come from ~/git/catbeez-games/games/, the wheel from dist/
• Part of the catbeez-arcade deployment — likely paired with other rules for systemd service setup, Caddy/nginx config, etc.
• Pattern: Typical of rules found in ftl2-deployments — single-host observe/condition/action with file upload and shell provisioning