spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/studio/webcheck.py

@@ -0,0 +1,210 @@
+"""Load a web build in headless Chrome via the DevTools protocol: console errors + screenshot.
+
+Standard library only (a minimal WebSocket client), so it runs anywhere Chrome is installed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import shutil
+import socket
+import struct
+import subprocess
+import tempfile
+import time
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CHROME_CANDIDATES = ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser")
+
+
+def find_chrome() -> str | None:
+    env = os.environ.get("CHROME_BIN")
+    if env:
+        return env
+    for c in CHROME_CANDIDATES:
+        if shutil.which(c):
+            return shutil.which(c)
+    return None
+
+
+@dataclass
+class WebCheck:
+    console: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    screenshot: bytes | None = None
+    canvas_size: tuple[int, int] | None = None
+    value: object = None  # result of `expression`, if given
+
+
+class _WebSocket:
+    def __init__(self, url: str):
+        m = re.match(r"ws://([^/:]+):(\d+)(/.*)", url)
+        host, port, path = m.group(1), int(m.group(2)), m.group(3)
+        self.sock = socket.create_connection((host, port), timeout=30)
+        key = base64.b64encode(os.urandom(16)).decode()
+        self.sock.sendall((f"GET {path} HTTP/1.1\r\nHost: {host}:{port}\r\nUpgrade: websocket\r\n"
+                           f"Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n").encode())
+        resp = b""
+        while b"\r\n\r\n" not in resp:
+            resp += self.sock.recv(4096)
+        if b" 101 " not in resp.split(b"\r\n")[0]:
+            raise ConnectionError(f"websocket handshake failed: {resp[:200]!r}")
+        self._buf = resp.split(b"\r\n\r\n", 1)[1]
+
+    def send(self, obj: dict) -> None:
+        data = json.dumps(obj).encode()
+        header = bytearray([0x81])
+        n = len(data)
+        if n < 126:
+            header.append(0x80 | n)
+        elif n < 65536:
+            header.append(0x80 | 126)
+            header += struct.pack(">H", n)
+        else:
+            header.append(0x80 | 127)
+            header += struct.pack(">Q", n)
+        mask = os.urandom(4)
+        header += mask
+        self.sock.sendall(bytes(header) + bytes(b ^ mask[i % 4] for i, b in enumerate(data)))
+
+    def _read(self, n: int) -> bytes:
+        while len(self._buf) < n:
+            chunk = self.sock.recv(65536)
+            if not chunk:
+                raise ConnectionError("websocket closed")
+            self._buf += chunk
+        out, self._buf = self._buf[:n], self._buf[n:]
+        return out
+
+    def recv(self) -> dict:
+        payload = b""
+        while True:
+            b1, b2 = self._read(2)
+            n = b2 & 0x7F
+            if n == 126:
+                n = struct.unpack(">H", self._read(2))[0]
+            elif n == 127:
+                n = struct.unpack(">Q", self._read(8))[0]
+            payload += self._read(n)
+            if b1 & 0x80:
+                break
+        return json.loads(payload)
+
+    def close(self) -> None:
+        self.sock.close()
+
+
+def check(url: str, seconds: float = 12.0, size: tuple[int, int] = (960, 540), keys: list[str] | None = None,
+          expression: str | None = None, clicks: list[tuple[float, float, str]] | None = None) -> WebCheck:
+    """Open `url`, wait `seconds` (optionally pressing `keys` midway), return console output and a PNG."""
+    chrome = find_chrome()
+    if chrome is None:
+        raise RuntimeError("Chrome not found (set CHROME_BIN)")
+    result = WebCheck()
+    with tempfile.TemporaryDirectory() as profile:
+        proc = subprocess.Popen(
+            [chrome, "--headless=new", "--no-sandbox", f"--user-data-dir={profile}", "--remote-debugging-port=0",
+             "--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--autoplay-policy=no-user-gesture-required",
+             f"--window-size={size[0]},{size[1]}", "about:blank"],
+            stderr=subprocess.PIPE, stdout=subprocess.DEVNULL, text=True)
+        try:
+            ws_url = _devtools_url(proc)
+            port = re.match(r"ws://[^:]+:(\d+)", ws_url).group(1)
+            targets = json.loads(urllib.request.urlopen(f"http://127.0.0.1:{port}/json/list", timeout=10).read())
+            page = next(t for t in targets if t.get("type") == "page")
+            ws = _WebSocket(page["webSocketDebuggerUrl"])
+            msg_id = 0
+
+            def call(method: str, **params) -> dict:
+                nonlocal msg_id
+                msg_id += 1
+                ws.send({"id": msg_id, "method": method, "params": params})
+                while True:
+                    m = ws.recv()
+                    _collect(m, result)
+                    if m.get("id") == msg_id:
+                        return m.get("result", {})
+
+            call("Runtime.enable")
+            call("Log.enable")
+            call("Page.enable")
+            call("Page.navigate", url=url)
+            deadline = time.time() + seconds
+            pressed = False
+            ws.sock.settimeout(0.5)
+            while time.time() < deadline:
+                if (keys or clicks) and not pressed and time.time() > deadline - seconds / 2:
+                    ws.sock.settimeout(30)
+                    for k in keys or []:
+                        _key(call, k)
+                    for x, y, button in clicks or []:
+                        for t in ("mousePressed", "mouseReleased"):
+                            call("Input.dispatchMouseEvent", type=t, x=x, y=y, button=button, clickCount=1)
+                    ws.sock.settimeout(0.5)
+                    pressed = True
+                try:
+                    _collect(ws.recv(), result)
+                except (socket.timeout, TimeoutError):
+                    pass
+            ws.sock.settimeout(30)
+            shot = call("Page.captureScreenshot", format="png")
+            result.screenshot = base64.b64decode(shot["data"]) if shot.get("data") else None
+            dims = call("Runtime.evaluate", returnByValue=True, expression=(
+                "(() => { const c = document.querySelector('canvas'); return c ? [c.width, c.height] : null })()"))
+            value = dims.get("result", {}).get("value")
+            result.canvas_size = tuple(value) if value else None
+            if expression:
+                ev = call("Runtime.evaluate", returnByValue=True, expression=expression)
+                result.value = ev.get("result", {}).get("value")
+            ws.close()
+        finally:
+            proc.terminate()
+            try:
+                proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+    return result
+
+
+def _devtools_url(proc: subprocess.Popen) -> str:
+    deadline = time.time() + 20
+    while time.time() < deadline:
+        line = proc.stderr.readline()
+        m = re.search(r"DevTools listening on (ws://\S+)", line)
+        if m:
+            return m.group(1)
+    raise RuntimeError("Chrome did not start its DevTools endpoint")
+
+
+def _key(call, key: str) -> None:
+    code = {"Space": 32, "ArrowRight": 39, "ArrowLeft": 37, "KeyX": 88}.get(key, 0)
+    for t in ("keyDown", "keyUp"):
+        call("Input.dispatchKeyEvent", type=t, code=key, key=" " if key == "Space" else key,
+             windowsVirtualKeyCode=code)
+
+
+def _collect(m: dict, result: WebCheck) -> None:
+    method = m.get("method")
+    if method == "Runtime.consoleAPICalled":
+        p = m["params"]
+        text = " ".join(str(a.get("value", a.get("description", ""))) for a in p.get("args", []))
+        result.console.append(f"{p.get('type')}: {text}")
+        if p.get("type") == "error":
+            result.errors.append(text)
+    elif method == "Runtime.exceptionThrown":
+        d = m["params"]["exceptionDetails"]
+        result.errors.append(d.get("exception", {}).get("description") or d.get("text", "exception"))
+    elif method == "Log.entryAdded":
+        e = m["params"]["entry"]
+        if e.get("level") == "error" and "favicon" not in e.get("url", ""):
+            result.errors.append(f"{e.get('source')}: {e.get('text')}")
+
+
+def save_screenshot(res: WebCheck, path: Path) -> None:
+    if res.screenshot:
+        path.write_bytes(res.screenshot)

spawnpoint/studio_cli.py

@@ -0,0 +1,232 @@
+"""CLI handlers for the studio commands: create, tweak, serve."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+from .project import slugify
+from .studio import dataset as dataset_mod, web
+from .studio.brief import GameBrief
+from .studio.llm import LLMError, OpenAICompatible
+from .studio.orchestrator import LayerReport, StudioError, create as do_create, tweak as do_tweak
+
+LAYER_NAMES = {0: "L0 core loop", 1: "L1 goals & enemies", 2: "L2 feel & polish"}
+
+
+def _say(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def _report_layer(r: LayerReport) -> None:
+    b = r.build
+    status = "ok" if b.ok else "FAILED"
+    secs = b.timings.get("total", 0) + (r.web_seconds or 0)
+    _say(f"  [{LAYER_NAMES[r.layer]}] {status} in {secs:.1f}s"
+         + (f" (build {b.timings.get('total', 0):.1f}s, web {r.web_seconds:.1f}s)" if r.web_seconds else ""))
+    for d in b.diagnostics:
+        if d.severity == "error" or r.layer > 0:
+            _say(f"      {d}")
+
+
+def _brief_summary(brief: GameBrief, notes: list[str]) -> None:
+    b = brief
+    enemies = ", ".join(f"{e.count}x {e.name} ({e.archetype})" for e in b.enemies) or "none"
+    _say(f"  “{b.title}” — {b.genre}, palette {b.palette}, goal {b.goal}, {b.length}, difficulty {b.difficulty}")
+    _say(f"  player: {', '.join(b.player.abilities) or 'no abilities'}; jump {b.player.jump_tiles} tiles; "
+         f"speed {b.player.speed}; feel {b.feel}; juice {b.juice}")
+    _say(f"  enemies: {enemies}; pickups: {b.collectible.count}x {b.collectible.name}; hazards: {', '.join(b.hazards) or 'none'}")
+    for n in notes:
+        _say(f"  note: {n}")
+
+
+def create(args) -> int:
+    if getattr(args, "ai_art", False):
+        import os
+        os.environ["SPAWNPOINT_AI_ART"] = "1"  # read by create(); stored in studio.json for later tweaks
+    llm = OpenAICompatible()
+    brief = GameBrief.model_validate(json.loads(args.brief.read_text())) if args.brief else None
+    server: web.Server | None = None
+    out_holder: dict[str, Path] = {}
+
+    def out_dir_for(b: GameBrief) -> Path:
+        out_holder["out"] = (args.out or Path("out") / slugify(b.title)).resolve()
+        _say(f"Building into {_rel(out_holder['out'])}")
+        return out_holder["out"]
+
+    def on_brief(b: GameBrief, notes: list[str]) -> None:
+        _say("Design:")
+        _brief_summary(b, notes)
+
+    def on_layer(r: LayerReport) -> None:
+        nonlocal server
+        _report_layer(r)
+        if r.build.ok and not args.no_web and not args.no_serve and server is None:
+            server = web.Server(out_holder["out"], args.port).start()
+            _say(f"  ▶ playing at {server.url}  (the page reloads as layers land)")
+            if not args.no_open:
+                webbrowser.open(server.url)
+
+    recorder = _recorder(args)
+    _say(f"Designing with {llm.base_url} ..." if brief is None else "Using the given brief ...")
+    try:
+        result = do_create(args.prompt, out_dir_for, llm, seed=args.seed, creative=args.creative,
+                           brief=brief, web_export=not args.no_web, on_layer=on_layer, on_brief=on_brief,
+                           recorder=recorder, playtest=args.playtest,
+                           on_progress=lambda m: _say(f"  [playtest] {m}"))
+    except (LLMError, StudioError) as e:
+        _say(f"error: {e}")
+        return 2
+    if result.creative is not None:
+        c = result.creative
+        _say(f"Creative pass: {'applied' if c.applied else 'dropped'} after {c.rounds} round(s)"
+             + (f": {json.dumps(c.patch)}" if c.applied else (f" — {c.errors[:2]}" if c.errors else "")))
+    if result.playtest is not None:
+        _print_playtest(result.playtest)
+    _say(f"Done in {result.timings.get('total', 0):.1f}s (design {result.timings.get('design', 0):.1f}s; LLM {result.usage}).")
+    out = out_holder["out"]
+    _say(f"Change it:  spawnpoint tweak {_rel(out)} \"make the jump 20% higher\"")
+    _say(f"Native:     spawnpoint run {_rel(out)}")
+    if not result.ok:
+        return 1
+    if server is not None and not args.no_serve:
+        _say("Serving — press Ctrl+C to stop.")
+        try:
+            while True:
+                time.sleep(3600)
+        except KeyboardInterrupt:
+            server.stop()
+    return 0
+
+
+def tweak(args) -> int:
+    llm = OpenAICompatible()
+    project = args.project.resolve()
+    _say(f"Tweaking {project} ...")
+    try:
+        result = do_tweak(project, args.request, llm, web_export=not args.no_web, on_layer=_report_layer,
+                          recorder=_recorder(args))
+    except (LLMError, StudioError) as e:
+        _say(f"error: {e}")
+        return 2
+    if result.changes:
+        _say("Changes:")
+        for c in result.changes:
+            _say(f"  {c}")
+    else:
+        _say("No changes (the request did not map to anything the brief controls).")
+    for n in result.notes:
+        _say(f"  note: {n}")
+    _say(f"Done in {result.timings.get('total', 0):.1f}s (LLM {result.usage}). "
+         "An open browser tab reloads automatically; otherwise run `spawnpoint serve`.")
+    return 0 if result.ok else 1
+
+
+def _print_playtest(res) -> None:
+    from .playtest import tuner
+
+    def table(rep, label):
+        _say(f"  {label}:")
+        for p in rep.profiles.values():
+            causes = ", ".join(f"{k} {v}" for k, v in list(p.causes.items())[:3]) or "no deaths"
+            _say(f"    {p.profile:<8} won {p.wins}/{p.runs}  deaths {p.deaths:<3} ({causes})  "
+                 f"missed jumps {p.jumps_missed}/{p.jumps_intended}  pickups {p.pickup_rate:.0%}  stuck {p.stuck}")
+
+    table(res.baseline, "before" if res.changes else "results")
+    for r in res.rounds:
+        verdict = "kept" if r.get("accepted") else "reverted"
+        _say(f"  round {r['round']} ({verdict}, score {r.get('score_before')} -> {r.get('score_after')}):")
+        for c in r["changes"]:
+            _say(f"    {c}")
+    if res.changes:
+        table(res.final, "after")
+    for issue in res.final.level_issues:
+        _say(f"  level issue: {issue}")
+    _say(f"  targets (difficulty {res.difficulty}): {tuner.targets(res.difficulty)}")
+    _say(f"  report: {_rel(res.files['md'])}  heatmap: {_rel(res.files['heatmap'])}  ({res.seconds:.1f}s)")
+
+
+def playtest(args) -> int:
+    from . import playtest as pt
+    from .studio.orchestrator import studio_playtest
+
+    project = args.project.resolve()
+    profiles = tuple(p.strip() for p in args.profiles.split(",") if p.strip())
+    progress = lambda m: _say(f"  {m}")
+    _say(f"Playtesting {_rel(project)} ...")
+    if (project / "studio.json").exists() and args.difficulty is None:
+        res = studio_playtest(project, runs=args.runs, tune=args.tune, rounds=args.rounds, on_progress=progress)
+    else:
+        res = pt.playtest(project, runs=args.runs, profiles=profiles, tune=args.tune, rounds=args.rounds,
+                          seed=args.seed, difficulty=args.difficulty or 2, on_progress=progress)
+    if args.json:
+        print(res.files["json"].read_text())
+    else:
+        _print_playtest(res)
+    return 0
+
+
+def studio(args) -> int:
+    from .cockpit.server import Cockpit, CockpitServer
+
+    server = CockpitServer(Cockpit(args.workspace), args.port).start()
+    _say(f"Spawn Point Studio at {server.url} (games in {_rel(args.workspace.resolve())}) — Ctrl+C to stop.")
+    if not args.no_open:
+        webbrowser.open(server.url)
+    try:
+        while True:
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        server.stop()
+    return 0
+
+
+def _recorder(args) -> dataset_mod.Recorder | None:
+    if not (getattr(args, "record", False) or dataset_mod.enabled_by_env()):
+        return None
+    rec = dataset_mod.Recorder()
+    _say(f"Recording LLM calls as training data in {rec.directory} (local only)")
+    return rec
+
+
+def dataset(args) -> int:
+    if args.action == "path":
+        _say(str(dataset_mod.default_dir()))
+        return 0
+    st = dataset_mod.stats()
+    if args.json:
+        print(json.dumps(st, indent=2))
+        return 0
+    _say(f"{st['records']} record(s) in {dataset_mod.default_dir()}")
+    for task, t in st["tasks"].items():
+        _say(f"  {task:<9} {t['count']:>5}  accepted {t['accepted']:>5}  corrected by the pipeline {t['corrected']:>5}")
+    if st["models"]:
+        _say("  models: " + ", ".join(f"{m} ({n})" for m, n in st["models"].items()))
+    return 0
+
+
+def serve(args) -> int:
+    project = args.project.resolve()
+    if not (project / web.WEB_DIR / "index.html").exists():
+        _say(f"error: {project} has no web build (run `spawnpoint create` or `tweak` first)")
+        return 2
+    server = web.Server(project, args.port).start()
+    _say(f"Playing at {server.url} — press Ctrl+C to stop.")
+    if not args.no_open:
+        webbrowser.open(server.url)
+    try:
+        while True:
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        server.stop()
+    return 0
+
+
+def _rel(p: Path) -> str:
+    try:
+        return str(p.relative_to(Path.cwd()))
+    except ValueError:
+        return str(p)