Release: playback real-stats, BAR launch, deploy config

Author: rlafurud

.github/workflows/ci.yml

@@ -37,8 +37,10 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.11'
-      - run: pip install -r requirements.txt
+      - run: pip install -r requirements-dev.txt
       - name: Compile all modules
         run: python -m compileall -q .
       - name: Import API app
         run: python -c "import app; print('app import OK')"
+      - name: Run unit tests
+        run: python -m pytest -q

.gitignore

@@ -26,3 +26,8 @@ dist/
 
 # backend runtime logs
 backend/log/
+
+# Bundled BAR launcher reference project — NOT part of this repo.
+# Contains a real API key (.env), a venv, game data and demos. The /launch
+# endpoint uses it locally if present and degrades gracefully if absent.
+minigame_generator_v4/

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Text prompt → Beyond All Reason (BAR) minigame config (JSON) generator. A natural-language
+query is matched against a database of existing game scenarios, then a final scenario config is
+synthesized and visualized in the browser. The README is in Korean and is the canonical design doc.
+
+## Commands
+
+Backend (FastAPI, Python 3.11):
+```bash
+cd backend
+pip install -r requirements.txt
+cp .env.example .env            # set OPENAI_API_KEY (BASE_URL optional)
+uvicorn app:app --reload        # http://localhost:8000
+python pipeline.py "<prompt>"   # run the full pipeline from the CLI, no server
+python db_call.py               # smoke-test DB folder/file LLM routing
+```
+
+Frontend (React + Vite, requires Node 20):
+```bash
+cd frontend
+npm install
+npm run dev                     # http://localhost:5173, proxies /api -> :8000
+npm run build                   # production build (this is what CI runs)
+```
+
+There is no test suite. CI (`.github/workflows/ci.yml`, on push/PR to `main`/`dev`) only does
+`npm run build` for the frontend and, for the backend, `python -m compileall` + `import app`
+with a dummy `OPENAI_API_KEY`. **Module import must stay side-effect-free** (no LLM client built
+at import time) or CI breaks — clients are constructed lazily inside functions/constructors.
+
+## Architecture
+
+The core design decision: **do not generate a GDD or new rules from scratch.** Find the most
+similar existing scenario in `backend/db/`, reuse its validated rules, and only synthesize the
+final script. An earlier multi-agent build with an analyst/verify loop was deliberately stripped
+to remove the `game_simulation` (BAR engine) and `psutil` runtime dependencies — do not
+reintroduce them.
+
+### Backend pipeline (`backend/pipeline.py`, `generate()`) — 3 steps
+
+1. **`find_scenario(query)`** — match the prompt to a scenario in `db/scenario/meta.json`.
+   Resilient by design: LLM match (`DBCall`) → keyword overlap fallback (`_keyword_fallback`) →
+   default to the first scenario. Returns `None` only if the scenario DB is unreadable.
+2. **`load_existing_mode(name)`** — build a `gdd` dict from the scenario's `specification` and its
+   referenced rules. Every rule is loaded as `action: existing, validated: True` (never generated).
+   Rule `.lua` files are copied into the per-session `log/<timestamp>/.../rules_temp/`.
+3. **`ScriptDeveloperAgent.run()`** (`script_builder.py`) — a linear LangGraph:
+   `select_map → place_units → generate_rule_config → get_condition → assemble_draft`. Each node
+   is one LLM call (prompts in `developer_prompt.py`); `select_map`/`place_units` loop, issuing
+   `call_db` actions to fetch more context, until the LLM returns `finish`.
+
+`generate()` returns `{scenario, config, raw}` where `config` is the `"normal"` difficulty entry of
+`final_json`. The agent always produces exactly the `["normal"]` difficulty.
+
+### DBCall (`backend/db_call.py`) — two-stage LLM retrieval
+
+`db/meta.json` lists folders (`scenario`, `map`, `unit`, `rule`, `decision`, `verify`, `rubric`);
+each folder's `meta.json` has a `details` map of `{name: {description, file}}`. `DBCall.call(query)`
+asks the LLM to pick a folder, then which files within it — returning file paths relative to `db/`.
+Pass `folder=` to skip folder selection. `call_with_names()` also returns the matched DB key names
+(used by `find_scenario`).
+
+### API (`backend/app.py`)
+
+- `POST /generate {query, seed?}` → pipeline result. `seed` is threaded down to every `ChatOpenAI`
+  for reproducibility.
+- `GET /catalog` → scenarios (from `db/scenario/meta.json`) + maps (from `info/map.json`).
+- `GET /health`. CORS is wide open (`*`).
+- The top-level `try/except` returns `{error, config: None}` rather than raising.
+
+### Frontend (`frontend/src/`)
+
+`App.jsx` loads `/catalog` on mount and calls `/generate` via `api.js`. Components: `PromptInput`
+(prompt + example chips, ⌘/Ctrl+Enter to submit), `ConfigSummary`, `MiniMap` (2D canvas of
+`unit_placement`), `SimPlayback`, `JsonView`. No state library, no router.
+
+## Key conventions
+
+- **LLM model** is hardcoded to `gpt-5.2` in `common.get_client()`. Reads `OPENAI_API_KEY` and
+  optional `BASE_URL` from env. All token usage flows through the shared `TokenTracker` callback.
+- **Coordinate system:** maps are sized in tiles where **1 tile = 512px**. A 16×16 map → 8192×8192
+  pixels. Units are placed in pixel coordinates. Prompts and `MiniMap` both rely on this.
+- **Config shape** (`assemble_draft` output): `{information, end_condition, unit_placement, customize}`.
+  `unit_placement` is keyed by team (`"1"`, `"2"`) → list of `[unit_code, [x, y]]`. `customize` holds
+  rule/gadget config (e.g. `enemy_wave_spawner`).
+- **`backend/db/`** is the source of truth (scenarios, validated rules + their `.lua` codes, maps,
+  units, decisions). **`backend/info/`** holds flat unit/map/gadget summaries fed into prompts
+  (`units_info.json`, `map.json`, etc.) — distinct from `db/`.
+- **Logs:** every pipeline run writes to `backend/log/<timestamp>/` (gitignored). Each agent node
+  dumps its raw result via `common.log_node_result`.
+- **Name matching is fuzzy on purpose:** `pipeline._resolve_db_name` / `_normalize_name` reconcile
+  LLM-returned names against DB keys (case, spaces, parentheses, hyphens). Keep this when LLM output
+  may not match DB keys exactly.
+
+## Git workflow
+
+`main → dev → feature/*`. Branch `feature/*` off `dev`; PR `feature/* → dev`; release via
+`dev → main`. PRs close issues with `Closes #<n>`. Project docs live in the GitHub Wiki (`wiki/`).

DEPLOY.md

@@ -0,0 +1,37 @@
+# 배포 가이드 (무료: Vercel + Render)
+
+프론트엔드(정적 SPA)는 Vercel에, 백엔드(FastAPI)는 Render에 올리는 무료 구성입니다.
+
+> ⚠️ **"BAR에서 실행"(`/launch`)은 배포본에서 동작하지 않습니다.** 그 기능은 백엔드가 도는
+> 머신의 데스크톱에서 `spring.exe`를 띄우는 것이라, 화면도 BAR도 없는 클라우드 서버에선
+> 불가능합니다. 배포본에서는 자동으로 "launcher not found"로 안전하게 실패하고, 브라우저
+> 근사 플레이백(SimPlayback)은 정상 동작합니다.
+>
+> ⚠️ **호스팅은 무료지만 LLM 호출은 본인 OpenAI 키로 과금됩니다.** (토큰만큼)
+
+## 1. 백엔드 — Render (무료 Web Service)
+
+1. Render Dashboard → **New → Blueprint** → 이 저장소 선택 → 루트의 [`render.yaml`](render.yaml) 감지.
+2. 환경변수 `OPENAI_API_KEY` 를 Render 대시보드에서 입력 (절대 커밋 금지).
+3. 배포 후 URL 확인 (예: `https://rtsgame-backend.onrender.com`).
+
+- 무료 티어는 15분 무활동 시 **슬립** → 첫 요청에 1분+ 콜드스타트. 발표 직전 `/health` 한 번
+  호출해 깨워두거나 외부 cron으로 5~10분마다 ping.
+- LLM 응답이 수십 초~2분 걸리므로 **서버리스(Vercel/Netlify Functions)에는 백엔드를 두면 안 됩니다**
+  (짧은 타임아웃에 끊김). Render 같은 상시 컨테이너여야 합니다.
+
+## 2. 프론트엔드 — Vercel (무료)
+
+1. Vercel → **New Project** → 이 저장소 선택.
+2. **Root Directory = `frontend`** 로 지정 ([`frontend/vercel.json`](frontend/vercel.json)이 빌드/SPA 라우팅 처리).
+3. 환경변수 **`VITE_API_BASE`** = 위 Render 백엔드 URL (예: `https://rtsgame-backend.onrender.com`).
+4. 배포.
+
+`VITE_API_BASE`가 없으면(로컬 dev) 자동으로 Vite 프록시(`/api` → `localhost:8000`)를 씁니다.
+프로덕션에서만 이 변수로 실제 백엔드를 가리킵니다. — [frontend/src/api.js](frontend/src/api.js)
+
+## 3. 확인
+
+- 백엔드: `https://<render-url>/health` → `{"status":"ok"}`
+- 프론트: Vercel URL 접속 → 프롬프트 생성 → 결과/플레이백 표시.
+  (첫 생성은 Render 콜드스타트로 느릴 수 있음.)

backend/app.py

@@ -8,8 +8,21 @@
 """
 
 import json
+import os
+import sys
+import subprocess
 from pathlib import Path
 
+# Windows consoles default to cp949 in a Korean locale; the pipeline's progress
+# logs contain emoji (🔎, ⚠️, …). Without this, the first such print() raises
+# UnicodeEncodeError and bubbles up as a /generate failure. Force UTF-8 so logs
+# never crash a request.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
@@ -19,6 +32,15 @@
 CURRENT_DIR = Path(__file__).resolve().parent
 DB_DIR = CURRENT_DIR / "db"
 INFO_DIR = CURRENT_DIR / "info"
+RULE_CODES_DIR = DB_DIR / "rule" / "codes"
+
+# The full BAR launcher lives in the bundled v4 project. Its game_simulator
+# converts a config (same JSON shape this backend emits) into a Spring start
+# script and launches spring.exe. It reads its own .env (SPRING_DATADIR,
+# BAR_ENGINE_PATH, GAME_VERSION) via load_dotenv inside main.py.
+V4_DIR = CURRENT_DIR.parent / "minigame_generator_v4"
+SIM_DIR = V4_DIR / "game_simulator"
+SIM_MAIN = SIM_DIR / "main.py"
 
 app = FastAPI(title="RTSGame Minigame Generator", version="0.1.0")
 
@@ -79,6 +101,77 @@ def generate(req: GenerateRequest):
         return {"error": str(e), "config": None}
 
 
+class LaunchRequest(BaseModel):
+    config: dict
+    # "gadget" = run the scenario's own gadgets only (no movement/vlm AI);
+    # "movement"/"vlm" enable the v4 experiment gadgets.
+    mode: str = "gadget"
+
+
+def _resolve_gadgets(config: dict) -> list:
+    """Each customize key corresponds to a rule gadget whose Lua lives at
+    db/rule/codes/<key>.lua. The launcher copies these into the engine and
+    enables them; the per-key config is delivered via the scenariooptions blob.
+    Missing files are skipped (the scenario still launches without them)."""
+    gadgets = []
+    for key in (config.get("customize") or {}):
+        lua = RULE_CODES_DIR / f"{key}.lua"
+        if lua.exists():
+            gadgets.append(str(lua))
+    return gadgets
+
+
+@app.post("/launch")
+def launch(req: LaunchRequest):
+    """Launch the generated config in the actual BAR client via the bundled
+    v4 game_simulator. Fire-and-forget: spring.exe opens its own window and the
+    request returns as soon as the process is spawned."""
+    if not SIM_MAIN.exists():
+        return {"launched": False, "error": f"BAR launcher not found at {SIM_MAIN}"}
+
+    config = req.config or {}
+    if not config.get("information", {}).get("map_name"):
+        return {"launched": False, "error": "config has no information.map_name"}
+
+    # Prefer the v4 venv interpreter — it has the deps (PIL/numpy/dotenv) that
+    # game_simulator/utils import; fall back to whatever `python` is on PATH.
+    venv_py = V4_DIR / ".venv" / "Scripts" / "python.exe"
+    python_exe = str(venv_py) if venv_py.exists() else "python"
+
+    gen_dir = SIM_DIR / "_generated"
+    gen_dir.mkdir(exist_ok=True)
+    cfg_path = gen_dir / "launch_config.json"
+    with open(cfg_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+
+    gadgets = _resolve_gadgets(config)
+
+    cmd = [python_exe, str(SIM_MAIN), "--config", str(cfg_path), "--mode", req.mode]
+    if gadgets:
+        cmd += ["--gadgets"] + gadgets
+
+    log_dir = CURRENT_DIR / "log"
+    log_dir.mkdir(exist_ok=True)
+    try:
+        log_fh = open(log_dir / "launch.log", "a", encoding="utf-8")
+        # New process group so the game survives a uvicorn reload/restart.
+        creationflags = subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
+        subprocess.Popen(
+            cmd, cwd=str(SIM_DIR),
+            stdout=log_fh, stderr=subprocess.STDOUT,
+            creationflags=creationflags,
+        )
+    except Exception as e:
+        return {"launched": False, "error": str(e)}
+
+    return {
+        "launched": True,
+        "mode": req.mode,
+        "map": config["information"]["map_name"],
+        "gadgets": [Path(g).stem for g in gadgets],
+    }
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run("app:app", host="0.0.0.0", port=8000, reload=True)

backend/requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8

backend/tests/conftest.py

@@ -0,0 +1,6 @@
+import os
+import sys
+
+# Make backend modules (app, pipeline, ...) importable regardless of the cwd
+# pytest is launched from.
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

backend/tests/test_app.py

@@ -0,0 +1,33 @@
+"""Unit tests for the pure helpers in app.py (no subprocess / engine launch)."""
+from pathlib import Path
+
+import app
+
+
+def test_resolve_gadgets_maps_customize_keys_to_existing_lua():
+    # 'prioritize_target' ships as db/rule/codes/prioritize_target.lua;
+    # the bogus key must be silently skipped, not raise.
+    cfg = {"customize": {"prioritize_target": {}, "nonexistent_gadget": {}}}
+    names = [Path(g).name for g in app._resolve_gadgets(cfg)]
+    assert "prioritize_target.lua" in names
+    assert all("nonexistent_gadget" not in n for n in names)
+
+
+def test_resolve_gadgets_handles_empty_or_missing_customize():
+    assert app._resolve_gadgets({}) == []
+    assert app._resolve_gadgets({"customize": {}}) == []
+    assert app._resolve_gadgets({"customize": None}) == []
+
+
+def test_resolve_gadgets_returns_absolute_existing_paths():
+    for path in app._resolve_gadgets({"customize": {"prioritize_target": {}}}):
+        assert Path(path).is_file()
+
+
+def test_launch_request_defaults_to_gadget_mode():
+    req = app.LaunchRequest(config={"information": {"map_name": "BarR 1.1"}})
+    assert req.mode == "gadget"
+
+
+def test_load_json_returns_default_on_missing_file(tmp_path):
+    assert app._load_json(tmp_path / "missing.json", {"fallback": True}) == {"fallback": True}

backend/tests/test_pipeline.py

@@ -0,0 +1,42 @@
+"""Unit tests for the pure (no LLM, no engine) helpers in pipeline.py.
+
+These guard the resilient scenario-matching fallback chain
+(LLM match -> keyword overlap -> default) that runs when the DB/LLM layer
+returns nothing useful.
+"""
+import pipeline
+
+
+def test_normalize_name_strips_parens_and_collapses_separators():
+    assert pipeline._normalize_name("Multi-Front Defense") == "multi_front_defense"
+    assert pipeline._normalize_name("Siege Planning (v2)") == "siege_planning"
+    assert pipeline._normalize_name("time__phased  production") == "time_phased_production"
+
+
+def test_resolve_db_name_exact_match_wins():
+    candidates = ["Multi-Front Defense", "Siege Planning"]
+    assert pipeline._resolve_db_name("Multi-Front Defense", candidates) == "Multi-Front Defense"
+
+
+def test_resolve_db_name_fuzzy_match_on_casing_and_separators():
+    candidates = ["Multi-Front Defense", "Siege Planning"]
+    # LLM may return a differently-cased / spaced variant of the DB key.
+    assert pipeline._resolve_db_name("multi front defense", candidates) == "Multi-Front Defense"
+
+
+def test_resolve_db_name_unknown_returns_input_unchanged():
+    candidates = ["Multi-Front Defense"]
+    assert pipeline._resolve_db_name("Totally Unknown Mode", candidates) == "Totally Unknown Mode"
+
+
+def test_keyword_fallback_picks_highest_overlap():
+    details = {
+        "Multi-Front Defense": {"description": "defend multiple fronts against waves"},
+        "Siege Planning": {"description": "plan a siege on a fixed base"},
+    }
+    assert pipeline._keyword_fallback("defend against waves", details) == "Multi-Front Defense"
+
+
+def test_keyword_fallback_no_overlap_returns_none():
+    details = {"Siege Planning": {"description": "plan a siege"}}
+    assert pipeline._keyword_fallback("xyzzy qwerty", details) is None

frontend/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env.local for local overrides, or set in the Vercel project settings.
+# Leave UNSET in local dev so calls go through the Vite proxy (/api).
+# In production, point this at the deployed backend origin:
+VITE_API_BASE=https://rtsgame-backend.onrender.com