ravensight-playtest 0.1.0

package/src/run/drivers/godot.js

@@ -0,0 +1,587 @@
+// The godot_driver Driver implementation (spec 07, spec 03's Driver interface).
+//
+// ./driver.js is the interface: the five methods (launch, observe, act,
+// screenshot, stop), the optional consoleErrors() and chapter(title), the
+// Observation and Action typedefs, and the two places the drivers are allowed
+// to differ. This class implements all of it, and `assertDriver` checks it at
+// load time. Read that file for the contract; there is deliberately no second
+// copy of it here, because two copies drift.
+//
+// Both of the differences ./driver.js names fall on this driver's side: a
+// string `click` target is a scene tree node path, not an accessibility ref,
+// and `stop()` answers `videoPath: null` with a `frames/` sequence beside it,
+// because stitching is ffmpeg's job and ffmpeg stays optional.
+//
+// What happens at launch, in order:
+//   1. find the developer's own Godot binary (spec 17 detection order),
+//   2. copy the project to a temp dir and inject the driver addon there, so
+//      the real project directory is never written to,
+//   3. spawn Godot with --ravensight-driver plus a per run loopback token, and
+//      with RAVENSIGHT_PLAYTEST_TOKEN / _RUN_ID / _JOB_ID / _PERSONA set so the
+//      game's own Ravensight SDK tags every event it tracks as synthetic,
+//   4. dial 127.0.0.1, say hello{token}, and poll ping until the game answers.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { buildObservation, needsVision } from './godot-observation.js';
+import {
+  detectGodotBinary,
+  findFreePort,
+  packagedAddonDir,
+  prepareProjectCopy,
+} from './godot-project.js';
+import { DriverRpcError, GodotRpcClient } from './godot-rpc.js';
+
+export const DRIVER_NAME = 'godot_driver';
+export const BOOT_TIMEOUT_MS = 60000;
+export const BOOT_POLL_MS = 250;
+const FRAMES_PER_SECOND = 60;
+
+/**
+ * The only environment variables forwarded to Godot.
+ *
+ * Godot needs a real environment to start, but it is also running the
+ * customer's game code, and that code has no business seeing the developer's
+ * ANTHROPIC_API_KEY, RAVENSIGHT_TOKEN, cloud credentials or CI secrets. So the
+ * environment is built from this list rather than inherited wholesale. Names are
+ * matched case insensitively, because Windows environment blocks are.
+ */
+export const ENV_ALLOWLIST = [
+  'PATH',
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'SHELL',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'TERM',
+  'TZ',
+  // X11 and Wayland, so a Linux run can find a real or a virtual display. The
+  // last two are what makes the Xvfb path work: a software GL stack usually
+  // lives somewhere LD_LIBRARY_PATH points, and LIBGL_ALWAYS_SOFTWARE is how a
+  // headless CI box is told to use it rather than hunting for a GPU.
+  'DISPLAY',
+  'WAYLAND_DISPLAY',
+  'LD_LIBRARY_PATH',
+  'LIBGL_ALWAYS_SOFTWARE',
+  'XAUTHORITY',
+  'XDG_RUNTIME_DIR',
+  'XDG_DATA_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_SESSION_TYPE',
+  'DBUS_SESSION_BUS_ADDRESS',
+  // Windows.
+  'SystemRoot',
+  'SystemDrive',
+  'windir',
+  'ComSpec',
+  'PATHEXT',
+  'NUMBER_OF_PROCESSORS',
+  'PROCESSOR_ARCHITECTURE',
+  'OS',
+  'USERPROFILE',
+  'USERNAME',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'PROGRAMFILES',
+  'PROGRAMFILES(X86)',
+  'PROGRAMDATA',
+  'HOMEDRIVE',
+  'HOMEPATH',
+];
+const ERROR_LINE = /^(?:USER )?(?:SCRIPT )?ERROR:|^SCRIPT ERROR/;
+const SOURCE_LINE = /^\s+at:\s*(.+)$/;
+
+export class GodotDriver {
+  constructor({
+    projectDir,
+    runDir,
+    godotPath,
+    addonDir = packagedAddonDir(),
+    headless = false,
+    viewport = { w: 1280, h: 720 },
+    playtest = {},
+    driverToken,
+    port,
+    bootTimeoutMs = BOOT_TIMEOUT_MS,
+    callTimeoutMs = 15000,
+    exitTimeoutMs = 5000,
+    treeDepth = 6,
+    settleFrames = 2,
+    keepTemp = false,
+    env = process.env,
+    extraEnv = {},
+    spawnFn = spawn,
+    detect = detectGodotBinary,
+    prepare = prepareProjectCopy,
+    choosePort = findFreePort,
+    now = () => Date.now(),
+  } = {}) {
+    this.name = DRIVER_NAME;
+    this.projectDir = projectDir;
+    this.runDir = runDir;
+    this.godotPath = godotPath;
+    this.addonDir = addonDir;
+    this.headless = headless;
+    this.viewport = viewport;
+    this.playtest = playtest;
+    this.driverToken = driverToken ?? randomBytes(24).toString('hex');
+    this.port = port;
+    this.bootTimeoutMs = bootTimeoutMs;
+    this.callTimeoutMs = callTimeoutMs;
+    this.exitTimeoutMs = exitTimeoutMs;
+    this.treeDepth = treeDepth;
+    this.settleFrames = settleFrames;
+    this.keepTemp = keepTemp;
+    this.env = env;
+    this.extraEnv = extraEnv;
+    this._spawn = spawnFn;
+    this._detect = detect;
+    this._prepare = prepare;
+    this._choosePort = choosePort;
+    this._now = now;
+
+    this.rpc = null;
+    this.child = null;
+    this.godot = null;
+    this.projectCopy = null;
+    this.tempRoot = null;
+    this.logPath = null;
+    this.ping = null;
+    this.exitCode = null;
+    this.exitSignal = null;
+    this.chapters = [];
+
+    this._startedAt = null;
+    this._step = 0;
+    this._shotIndex = 0;
+    this._frameIndex = 0;
+    this._lastHash = null;
+    this._logTail = [];
+    this._logPending = '';
+    this._consoleQueue = [];
+    this._videoTimer = null;
+    this._framesDir = null;
+    this._stopped = false;
+  }
+
+  /** True once the game process exited on its own, which is a finding, not a driver failure. */
+  get crashed() {
+    return !this._stopped && this.exitCode !== null && this.exitCode !== 0;
+  }
+
+  async launch({ recordVideo = false, viewport } = {}) {
+    if (viewport) this.viewport = viewport;
+    if (!this.projectDir) throw new Error('godot driver needs a projectDir');
+    this.godot = this.godotPath
+      ? await this._detect({ explicitPath: this.godotPath, env: this.env, projectDir: this.projectDir })
+      : await this._detect({ env: this.env, projectDir: this.projectDir });
+
+    const prepared = await this._prepare({
+      projectDir: this.projectDir,
+      addonDir: this.addonDir,
+    });
+    this.tempRoot = prepared.tempRoot;
+    this.projectCopy = prepared.projectCopy;
+    try {
+      this.port = this.port ?? (await this._choosePort());
+
+      if (this.runDir) await fs.mkdir(this.runDir, { recursive: true });
+      this.logPath = this.runDir ? path.join(this.runDir, 'godot.log') : null;
+
+      const args = ['--path', this.projectCopy];
+      if (this.headless) args.push('--headless');
+      else args.push('--resolution', `${this.viewport.w}x${this.viewport.h}`);
+      args.push('--', '--ravensight-driver', `--ravensight-driver-port=${this.port}`);
+
+      this.child = this._spawn(this.godot.path, args, {
+        cwd: this.projectCopy,
+        env: this.launchEnv(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      this._attachChild();
+
+      this.rpc = new GodotRpcClient({ port: this.port, timeoutMs: this.callTimeoutMs });
+      await this._connectWithinBootTimeout();
+      await this.rpc.call('hello', { token: this.driverToken });
+      this.ping = await this.rpc.call('ping');
+      this.headless = Boolean(this.ping.headless);
+      this._startedAt = this._now();
+      if (this.headless) {
+        this._consoleQueue.push({
+          kind: 'driver',
+          text:
+            'headless Godot has no viewport and does not route synthesized mouse or GUI input: '
+            + 'screenshots are unavailable and clicking a Control will not press it. '
+            + 'Run windowed for anything with a user interface.',
+        });
+      }
+
+      if (recordVideo) await this._startFrameCapture();
+      return {};
+    } catch (error) {
+      // Everything past this point has already spawned a game and copied a
+      // project, and neither tidies itself up. Without this, a project whose
+      // driver never answers leaves a stray Godot process and a temp copy behind
+      // on every attempt, and the runner retries.
+      await this.stop({ removeTemp: !this.keepTemp }).catch(() => {});
+      throw error;
+    }
+  }
+
+  /**
+   * The environment Godot is launched with. RAVENSIGHT_DRIVER* activate and
+   * authenticate the driver; the RAVENSIGHT_PLAYTEST_* set is read by the
+   * customer's own Ravensight.gd in _ready(), which is what makes every event
+   * the game tracks during this run carry synthetic / persona / pt_run tags.
+   */
+  launchEnv() {
+    const { token, runId, jobId, persona } = this.playtest ?? {};
+    const allowed = new Set(ENV_ALLOWLIST.map((name) => name.toLowerCase()));
+    const out = {};
+    for (const [key, value] of Object.entries(this.env ?? {})) {
+      if (allowed.has(key.toLowerCase())) out[key] = value;
+    }
+    Object.assign(out, this.extraEnv ?? {});
+    Object.assign(out, {
+      RAVENSIGHT_DRIVER: '1',
+      RAVENSIGHT_DRIVER_PORT: String(this.port),
+      RAVENSIGHT_DRIVER_TOKEN: this.driverToken,
+    });
+    if (token) out.RAVENSIGHT_PLAYTEST_TOKEN = token;
+    if (runId) out.RAVENSIGHT_PLAYTEST_RUN_ID = runId;
+    if (jobId) out.RAVENSIGHT_PLAYTEST_JOB_ID = jobId;
+    if (persona) out.RAVENSIGHT_PLAYTEST_PERSONA = persona;
+    return out;
+  }
+
+  async _connectWithinBootTimeout() {
+    const attempts = Math.max(1, Math.ceil(this.bootTimeoutMs / BOOT_POLL_MS));
+    try {
+      await this.rpc.connect({ attempts, delayMs: BOOT_POLL_MS });
+    } catch (error) {
+      const tail = this._logTail.slice(-15).join('\n');
+      const exited = this.exitCode === null ? '' : ` Godot exited with code ${this.exitCode}.`;
+      throw new Error(
+        `${error.message}.${exited}${tail ? `\nLast Godot output:\n${tail}` : ''}`,
+      );
+    }
+  }
+
+  _attachChild() {
+    const log = this.logPath ? createWriteStream(this.logPath, { flags: 'a' }) : null;
+    for (const stream of [this.child.stdout, this.child.stderr]) {
+      if (!stream) continue;
+      stream.on('data', (chunk) => {
+        if (log) log.write(chunk);
+        this._ingestLog(chunk.toString('utf8'));
+      });
+    }
+    this.child.on('exit', (code, signal) => {
+      this.exitCode = code;
+      this.exitSignal = signal;
+      if (log) log.end();
+    });
+    this.child.on('error', (error) => {
+      this._consoleQueue.push({ kind: 'driver', text: `failed to launch Godot: ${error.message}` });
+    });
+  }
+
+  /**
+   * Godot's own errors only reach us as stdout text: the engine's Logger hook
+   * is not available on every 4.x version the CLI supports, so spec 07's
+   * fallback (parse stdout) is the path taken here. An "at:" continuation line
+   * becomes the source of the error above it.
+   */
+  _ingestLog(text) {
+    this._logPending += text;
+    const lines = this._logPending.split('\n');
+    this._logPending = lines.pop() ?? '';
+    for (const line of lines) {
+      this._logTail.push(line);
+      if (this._logTail.length > 200) this._logTail.shift();
+      const source = line.match(SOURCE_LINE);
+      if (source && this._consoleQueue.length > 0) {
+        const last = this._consoleQueue[this._consoleQueue.length - 1];
+        if (!last.source) last.source = source[1].trim();
+        continue;
+      }
+      if (ERROR_LINE.test(line.trim())) {
+        this._consoleQueue.push({ kind: 'error', text: line.trim() });
+      }
+    }
+  }
+
+  async observe({ vision } = {}) {
+    this._step += 1;
+    const snapshot = await this._snapshot();
+    const { state } = snapshot;
+    let gameState = null;
+    try {
+      gameState = await this.rpc.call('get_game_state');
+    } catch (error) {
+      // A broken _ravensight_state() hook in the customer's game is a finding
+      // about their game, not a reason to end the run.
+      if (error instanceof DriverRpcError) {
+        this._consoleQueue.push({ kind: 'error', text: `get_game_state: ${error.rpcMessage}`, source: error.data?.path });
+      } else {
+        throw error;
+      }
+    }
+    let observation = buildObservation({
+      state,
+      gameState,
+      step: this._step,
+      elapsedMs: this._startedAt === null ? 0 : this._now() - this._startedAt,
+    });
+    const wantVision = vision ?? needsVision(observation);
+    if (wantVision && !this.headless) {
+      const shot = await this._rawScreenshot();
+      if (shot) {
+        observation = { ...observation, screenshot_b64: shot.data };
+      }
+    }
+    // changed detection compares outline hashes only, never this observation's
+    // own hash: the observation text also carries the game state section, so
+    // comparing the two kinds of hash reported "changed" on every single act.
+    this._lastHash = snapshot.hash;
+    return observation;
+  }
+
+  async act(action) {
+    if (!action || typeof action.kind !== 'string') {
+      return { ok: false, error: 'action needs a kind', changed: false };
+    }
+    try {
+      await this._perform(action);
+    } catch (error) {
+      if (error instanceof DriverRpcError) {
+        return { ok: false, error: error.rpcMessage, code: error.code, data: error.data, changed: false };
+      }
+      throw error;
+    }
+    if (action.kind === 'quit') return { ok: true, changed: false };
+    // Input reaches the game a frame after it is parsed, and a handler that
+    // changes a label runs a frame after that, so a snapshot taken the instant
+    // an action returns reports the screen as it was one action ago. Settling
+    // first is what makes "changed" mean what the persona loop thinks it means.
+    if (this.settleFrames > 0) {
+      await this.rpc.call('wait_frames', { n: this.settleFrames }).catch(() => {});
+    }
+    const { hash } = await this._snapshot();
+    const changed = this._lastHash !== null && hash !== this._lastHash;
+    this._lastHash = hash;
+    return { ok: true, changed };
+  }
+
+  async _perform(action) {
+    switch (action.kind) {
+      case 'key':
+        await this.rpc.call('key', { keycode: action.key, pressed: true });
+        await this.rpc.call('wait_frames', { n: 1 });
+        await this.rpc.call('key', { keycode: action.key, pressed: false });
+        return;
+      case 'type':
+        for (const char of String(action.text ?? '')) {
+          await this.rpc.call('key', { keycode: char, pressed: true, unicode: char.codePointAt(0) });
+          await this.rpc.call('key', { keycode: char, pressed: false, unicode: char.codePointAt(0) });
+        }
+        if (action.submit) {
+          await this.rpc.call('key', { keycode: 'Enter', pressed: true });
+          await this.rpc.call('key', { keycode: 'Enter', pressed: false });
+        }
+        await this.rpc.call('wait_frames', { n: 2 });
+        return;
+      case 'click': {
+        const target = action.target;
+        if (typeof target === 'string') {
+          await this.rpc.call('click', { node_path: target, button: action.button, double: action.double });
+        } else {
+          await this.rpc.call('click', {
+            x: target?.x ?? 0,
+            y: target?.y ?? 0,
+            button: action.button,
+            double: action.double,
+          });
+        }
+        await this.rpc.call('wait_frames', { n: 2 });
+        return;
+      }
+      case 'press_action':
+        await this.rpc.call(
+          'press_action',
+          { action: action.action, duration_ms: action.duration_ms ?? 50 },
+          { timeoutMs: this.callTimeoutMs + (action.duration_ms ?? 50) },
+        );
+        return;
+      case 'wait': {
+        const frames = Math.max(1, Math.round(((action.ms ?? 0) / 1000) * FRAMES_PER_SECOND));
+        await this.rpc.call('wait_frames', { n: frames }, { timeoutMs: this.callTimeoutMs + (action.ms ?? 0) });
+        return;
+      }
+      case 'set_time_scale':
+        await this.rpc.call('set_time_scale', { scale: action.scale ?? 1 });
+        return;
+      case 'quit':
+        this._stopped = true;
+        await this.rpc.call('quit', { code: 0 }).catch(() => {});
+        return;
+      default:
+        throw new Error(`godot driver cannot perform action kind "${action.kind}"`);
+    }
+  }
+
+  /**
+   * One get_state, plus the hash of the outline it produces.
+   *
+   * Never cached. An earlier version reused the snapshot act() had just taken,
+   * to save a round trip, and that handed the persona a screen one action out of
+   * date: the point of observe() is what is on screen now.
+   */
+  async _snapshot() {
+    const state = await this.rpc.call('get_state', { max_depth: this.treeDepth, visible_only: true });
+    const outline = buildObservation({ state, step: this._step });
+    return { state, hash: outline.hash };
+  }
+
+  async _rawScreenshot() {
+    if (this.headless) return null;
+    try {
+      return await this.rpc.call('screenshot', { max_width: this.viewport.w });
+    } catch (error) {
+      if (error instanceof DriverRpcError) {
+        this._consoleQueue.push({ kind: 'driver', text: `screenshot: ${error.rpcMessage}` });
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Writes screenshots/NN-slug.png inside the run dir, the layout the report
+   * writer links to. Headless runs have no viewport to capture, so the call
+   * reports that rather than failing the step.
+   */
+  async screenshot(name) {
+    if (this.headless) return { path: null, skipped: 'headless' };
+    const shot = await this._rawScreenshot();
+    if (!shot) return { path: null, skipped: 'unavailable' };
+    this._shotIndex += 1;
+    const dir = path.join(this.runDir ?? '.', 'screenshots');
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${String(this._shotIndex).padStart(2, '0')}-${slug(name)}.png`);
+    await fs.writeFile(file, Buffer.from(shot.data, 'base64'));
+    return { path: file, width: shot.width, height: shot.height };
+  }
+
+  /** Console errors since the previous call, from Godot stdout and driver events. */
+  async consoleErrors() {
+    const fromEvents = (this.rpc?.drainEvents() ?? [])
+      .filter((event) => event.type === 'error')
+      .map((event) => ({ kind: 'error', text: event.message, source: event.source, frame: event.frame }));
+    const out = [...this._consoleQueue, ...fromEvents];
+    this._consoleQueue = [];
+    return out;
+  }
+
+  async chapter(title) {
+    this.chapters.push({ title, at: this._startedAt === null ? 0 : this._now() - this._startedAt });
+  }
+
+  /**
+   * Video on a local Godot run is a sequence of stills, not a container: the
+   * frames land in the run dir and whoever wants a webm stitches them with
+   * ffmpeg, which stays optional for the CLI.
+   */
+  async _startFrameCapture({ fps = 4 } = {}) {
+    if (this.headless || !this.runDir) return;
+    this._framesDir = path.join(this.runDir, 'frames');
+    await fs.mkdir(this._framesDir, { recursive: true });
+    this._videoTimer = setInterval(() => {
+      void this._captureFrame();
+    }, Math.round(1000 / fps));
+    if (typeof this._videoTimer.unref === 'function') this._videoTimer.unref();
+  }
+
+  async _captureFrame() {
+    if (this._capturing || this._stopped) return;
+    this._capturing = true;
+    try {
+      const shot = await this._rawScreenshot();
+      if (!shot) return;
+      this._frameIndex += 1;
+      const file = path.join(this._framesDir, `${String(this._frameIndex).padStart(6, '0')}.png`);
+      await fs.writeFile(file, Buffer.from(shot.data, 'base64'));
+    } catch {
+      // A dropped frame is never worth interrupting a run for.
+    } finally {
+      this._capturing = false;
+    }
+  }
+
+  async stop({ removeTemp = !this.keepTemp } = {}) {
+    this._stopped = true;
+    if (this._videoTimer) {
+      clearInterval(this._videoTimer);
+      this._videoTimer = null;
+    }
+    if (this.rpc && !this.rpc.closed) {
+      await this.rpc.call('quit', { code: 0 }, { timeoutMs: 2000 }).catch(() => {});
+    }
+    await this._waitForExit(this.exitTimeoutMs);
+    this.rpc?.close();
+    if (removeTemp && this.tempRoot) {
+      await fs.rm(this.tempRoot, { recursive: true, force: true }).catch(() => {});
+      this.tempRoot = null;
+      this.projectCopy = null;
+    }
+    return {
+      videoPath: null,
+      framesDir: this._framesDir,
+      frameCount: this._frameIndex,
+      chapters: this.chapters,
+      logPath: this.logPath,
+      exitCode: this.exitCode,
+    };
+  }
+
+  async _waitForExit(timeoutMs) {
+    if (!this.child || this.exitCode !== null) return;
+    const exited = await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(false), timeoutMs);
+      if (typeof timer.unref === 'function') timer.unref();
+      this.child.once('exit', () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+    });
+    if (exited) return;
+    try {
+      this.child.kill('SIGKILL');
+    } catch {
+      // Already gone.
+    }
+  }
+}
+
+export function createGodotDriver(options) {
+  return new GodotDriver(options);
+}
+
+function slug(name) {
+  return (
+    String(name ?? 'shot')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 40) || 'shot'
+  );
+}

package/src/run/drivers/index.js

@@ -0,0 +1,52 @@
+import { assertDriver, DriverError } from './driver.js';
+import { createWebDriver } from './web.js';
+
+/**
+ * The driver registry. `playwright_web` is here; `godot_driver` lives in
+ * ./godot.js and is imported lazily so this package still loads on a
+ * machine with no Godot and no addon, and `cli_stdio` is not in v1.
+ *
+ * The names are the server's `PlaytestRun.driver` enum and the report
+ * schema's `driver` enum, not ours to invent.
+ */
+
+export const DRIVERS = Object.freeze(['playwright_web', 'godot_driver', 'cli_stdio']);
+
+/**
+ * @param {string} name
+ * @param {Object} [options]
+ * @param {(specifier: string) => Promise<any>} [options.importer] test seam
+ * @returns {Promise<Object>} a driver satisfying ./driver.js
+ */
+export async function createDriver(name, options = {}) {
+  const load = options.importer || (specifier => import(specifier));
+  switch (name) {
+    case 'playwright_web':
+      return assertDriver(createWebDriver(options), name);
+    case 'godot_driver': {
+      let module;
+      try {
+        module = await load('./godot.js');
+      } catch (error) {
+        throw new DriverError(
+          'The godot_driver is not available in this build of ravensight-playtest. Use --driver playwright_web against a web export, or upgrade the CLI.',
+          { fatal: true }
+        );
+      }
+      const factory = module.createGodotDriver || module.default;
+      if (typeof factory !== 'function') {
+        throw new DriverError('drivers/godot.js does not export createGodotDriver', { fatal: true });
+      }
+      return assertDriver(await factory(options), name);
+    }
+    case 'cli_stdio':
+      throw new DriverError(
+        'The cli_stdio driver is not in this release. In v1 a text build is played through its web front end with --driver playwright_web.',
+        { fatal: true }
+      );
+    default:
+      throw new DriverError(`unknown driver "${name}"; one of: ${DRIVERS.join(', ')}`, { fatal: true });
+  }
+}
+
+export default createDriver;