ravensight-playtest 0.1.0

package/src/run/drivers/godot-observation.js

@@ -0,0 +1,138 @@
+// Turns the driver's raw scene tree into the text observation a persona reads.
+//
+// Two jobs beyond formatting. First, keep the outline small: the raw tree of a
+// real game is thousands of nodes, and spec 07 wants the observation under
+// roughly 3k tokens, so a subtree with nothing a player could see or press is
+// dropped. Second, carry the file paths: every scene file and script path in
+// the tree is collected and listed, because a finding that says "the Begin
+// button does nothing" is only actionable if the report can name the scene and
+// script to open.
+import { createHash } from 'node:crypto';
+
+export const MAX_TEXT_CHARS = 12000;
+
+const PRESSABLE = /Button|LineEdit|TextEdit|Slider|CheckBox|CheckButton|OptionButton|ItemList|Tree/;
+
+/**
+ * @param {object} input
+ * @param {object} input.state         result of the driver's get_state
+ * @param {object} [input.gameState]   result of get_game_state
+ * @param {number} input.step
+ * @param {number} input.elapsedMs
+ */
+export function buildObservation({
+  state,
+  gameState = null,
+  step = 0,
+  elapsedMs = 0,
+  maxChars = MAX_TEXT_CHARS,
+  screenshotBase64 = null,
+} = {}) {
+  const collected = { scenes: [], scripts: [] };
+  const tree = state?.tree ?? null;
+  const kept = tree ? prune(tree, collected) : null;
+  const lines = [];
+
+  const scenePath = state?.current_scene_file || '';
+  if (scenePath) lines.push(`scene: ${scenePath}`);
+  if (state?.current_scene) lines.push(`scene node: ${state.current_scene}`);
+  if (collected.scripts.length > 0) lines.push(`scripts: ${collected.scripts.join(', ')}`);
+  if (state?.truncated) lines.push('note: the scene tree was truncated');
+  if (lines.length > 0) lines.push('');
+
+  if (kept) {
+    render(kept, 0, lines);
+  } else {
+    lines.push('(no visible nodes)');
+  }
+
+  const states = gameState?.states ?? {};
+  const stateKeys = Object.keys(states);
+  if (stateKeys.length > 0) {
+    lines.push('', 'game state:');
+    for (const key of stateKeys) {
+      lines.push(`  ${key}: ${JSON.stringify(states[key])}`);
+    }
+  }
+
+  const text = truncate(lines.join('\n'), maxChars);
+  const observation = {
+    step,
+    text,
+    structured: { state, gameState },
+    elapsed_ms: elapsedMs,
+    frame: state?.frame ?? null,
+    scene: scenePath,
+    scenes: collected.scenes,
+    scripts: collected.scripts,
+    hash: createHash('sha1').update(text).digest('hex'),
+  };
+  if (screenshotBase64) observation.screenshot_b64 = screenshotBase64;
+  return observation;
+}
+
+/** True when the outline is too thin to play from, so vision is worth the cost. */
+export function needsVision(observation, { minChars = 200 } = {}) {
+  const body = String(observation?.text ?? '')
+    .split('\n')
+    .filter((line) => !/^(scene|scene node|scripts|note):/.test(line))
+    .join('\n')
+    .trim();
+  return body.length < minChars;
+}
+
+function prune(node, collected) {
+  if (node.scene && !collected.scenes.includes(node.scene)) collected.scenes.push(node.scene);
+  if (node.script && !collected.scripts.includes(node.script)) collected.scripts.push(node.script);
+
+  const children = [];
+  for (const child of node.children ?? []) {
+    const keptChild = prune(child, collected);
+    if (keptChild) children.push(keptChild);
+  }
+  const selfInteresting =
+    Boolean(node.text) ||
+    Boolean(node.script) ||
+    Boolean(node.scene) ||
+    (node.groups ?? []).length > 0 ||
+    PRESSABLE.test(node.type ?? '') ||
+    node.child_count > 0;
+  if (!selfInteresting && children.length === 0) return null;
+  return { ...node, children };
+}
+
+function render(node, depth, lines) {
+  lines.push(`${'  '.repeat(depth)}${describe(node)}`);
+  for (const child of node.children ?? []) render(child, depth + 1, lines);
+}
+
+function describe(node) {
+  const parts = [node.type ?? 'Node', node.name ?? ''];
+  if (node.text) parts.push(JSON.stringify(collapse(node.text)));
+  if (Array.isArray(node.position)) {
+    parts.push(`@(${node.position.map((value) => round(value)).join(',')})`);
+  }
+  const flags = [];
+  if (node.focus) flags.push('focus');
+  if (node.disabled) flags.push('disabled');
+  if (node.visible === false) flags.push('hidden');
+  if ((node.groups ?? []).length > 0) flags.push(`groups=${node.groups.join('|')}`);
+  if (node.child_count > 0) flags.push(`+${node.child_count} more`);
+  if (flags.length > 0) parts.push(`[${flags.join(' ')}]`);
+  if (node.scene) parts.push(`{${node.scene}}`);
+  if (node.script) parts.push(`<${node.script}>`);
+  return parts.filter(Boolean).join(' ');
+}
+
+function collapse(text) {
+  return String(text).replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+
+function round(value) {
+  return typeof value === 'number' ? Math.round(value) : value;
+}
+
+function truncate(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars - 20)}\n... (truncated)`;
+}

package/src/run/drivers/godot-project.js

@@ -0,0 +1,475 @@
+// Everything the Godot driver has to do to a project before Godot starts.
+//
+// The customer's project directory is read only as far as this module is
+// concerned: spec 07 requires it to be byte identical after a run. So the
+// driver copies the project to a temporary directory, injects the addon there,
+// and launches Godot with --path pointing at the copy.
+//
+// The autoload is registered twice in that copy, in override.cfg (the design in
+// spec 07) and in the copy's own project.godot (the fallback spec 07 lists
+// under its open question 1, because override.cfg autoloads are not verified
+// across every project layout). Both name the same script, so registering both
+// is idempotent, and one of them is guaranteed to be the mechanism Godot
+// honors.
+import { execFile } from 'node:child_process';
+import net from 'node:net';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export const ADDON_DIR_NAME = 'ravensight_driver';
+export const AUTOLOAD_NAME = 'RavensightDriver';
+export const AUTOLOAD_VALUE = `*res://addons/${ADDON_DIR_NAME}/driver.gd`;
+export const DEFAULT_EXCLUDES = ['.git', 'node_modules', '.DS_Store'];
+// A runaway copy of a repository with gigabytes of raw assets in it is a worse
+// failure than a clear refusal, so sizing comes first.
+export const DEFAULT_MAX_PROJECT_BYTES = 2 * 1024 * 1024 * 1024;
+
+/** Resolves the addon that ships inside this package. */
+export function packagedAddonDir() {
+  return path.resolve(import.meta.dirname, '../../../addons', ADDON_DIR_NAME);
+}
+
+export async function isGodotProject(projectDir) {
+  try {
+    await fs.access(path.join(projectDir, 'project.godot'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sums the bytes that would be copied, stopping as soon as the cap is passed so
+ * a huge tree is not walked to the end just to be refused.
+ */
+export async function measureProject(dir, { excludes = DEFAULT_EXCLUDES, maxBytes = DEFAULT_MAX_PROJECT_BYTES } = {}) {
+  let total = 0;
+  const stack = [dir];
+  const seen = new Set();
+  const realRoot = await realRootOf(dir);
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (excludes.includes(entry.name)) continue;
+      const full = path.join(current, entry.name);
+      // readdir reports a symlink as neither a file nor a directory, so an
+      // earlier version of this walk skipped symlinked trees entirely: the copy
+      // then dereferenced them and blew straight through the cap. Sizing has to
+      // follow whatever the copy will follow.
+      let stat;
+      if (entry.isSymbolicLink()) {
+        const real = await fs.realpath(full).catch(() => null);
+        // A broken link costs nothing, and a link that points back at something
+        // already counted must not be walked twice or forever.
+        if (!real || seen.has(real)) continue;
+        // Same rule the copy filter applies, so sizing and copying agree about
+        // what they follow. Without it this walk counted the whole project twice.
+        if (resolvesIntoOwnAncestry(real, realRoot)) continue;
+        seen.add(real);
+        stat = await fs.stat(real).catch(() => null);
+        if (!stat) continue;
+        if (stat.isDirectory()) {
+          stack.push(real);
+          continue;
+        }
+      } else if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      } else if (!entry.isFile()) {
+        continue;
+      } else {
+        stat = await fs.stat(full);
+      }
+      total += stat.size;
+      if (total > maxBytes) {
+        throw new Error(
+          `project at ${dir} is larger than ${Math.round(maxBytes / 1e6)} MB, refusing to copy it; pass a smaller --godot-project`,
+        );
+      }
+    }
+  }
+  return total;
+}
+
+/**
+ * True when a symlink target is the project directory itself or one of its
+ * ancestors, which is the shape that makes a dereferencing copy unbounded.
+ *
+ * `selfref -> .` is the whole problem: dereferenced, the copy walks the project
+ * into itself, finds the link again, and repeats until PATH_MAX. `up -> ..` is
+ * the same defect one level out, and would drag the entire tree above the
+ * project into the copy besides. Neither is anything a Godot project needs, so
+ * both are simply dropped.
+ *
+ * Both arguments must already be realpaths. path.resolve() is not enough: on
+ * macOS os.tmpdir() is /var/folders/..., a symlink to /private/var/folders/...,
+ * so a project there compared by resolved-but-not-real paths never matches its
+ * own symlink target and the rule silently does nothing.
+ */
+function resolvesIntoOwnAncestry(realTarget, realRoot) {
+  return realRoot === realTarget || realRoot.startsWith(realTarget + path.sep);
+}
+
+/** The project directory with every symlink in it resolved. */
+async function realRootOf(dir) {
+  return fs.realpath(dir).catch(() => path.resolve(dir));
+}
+
+/**
+ * Replaces a symlink inside the copy with a real file or directory holding the
+ * same content.
+ *
+ * This is the whole reason the copy is safe. `project.godot`, `override.cfg` or
+ * `addons/` can each be a symlink pointing outside the project, and writing to
+ * a symlink writes to its target: the injection would land in the developer's
+ * real files, permanently, and spec 07 requires the project to be byte
+ * identical after a run. Every path this module writes to is materialized first.
+ */
+async function materialize(target) {
+  let info;
+  try {
+    info = await fs.lstat(target);
+  } catch {
+    return;
+  }
+  if (!info.isSymbolicLink()) return;
+  const real = await fs.realpath(target).catch(() => null);
+  // unlink, never rm: it removes the link itself and never touches the target.
+  await fs.unlink(target);
+  if (!real) return;
+  const stat = await fs.stat(real).catch(() => null);
+  if (!stat) return;
+  if (stat.isDirectory()) {
+    await fs.cp(real, target, { recursive: true, dereference: true, force: true });
+  } else {
+    await fs.copyFile(real, target);
+  }
+}
+
+/** Materializes every component of a path inside the copy, outermost first. */
+async function materializePath(root, relativePath) {
+  const parts = relativePath.split('/').filter(Boolean);
+  let current = root;
+  for (const part of parts) {
+    current = path.join(current, part);
+    await materialize(current);
+  }
+}
+
+/**
+ * Copies the project and injects the driver addon.
+ * Returns the copy's path plus the temp root to delete when the run ends.
+ */
+export async function prepareProjectCopy({
+  projectDir,
+  addonDir = packagedAddonDir(),
+  tempRoot,
+  excludes = DEFAULT_EXCLUDES,
+  maxBytes = DEFAULT_MAX_PROJECT_BYTES,
+} = {}) {
+  if (!(await isGodotProject(projectDir))) {
+    throw new Error(`no project.godot in ${projectDir}`);
+  }
+  await measureProject(projectDir, { excludes, maxBytes });
+
+  const root = tempRoot ?? (await fs.mkdtemp(path.join(os.tmpdir(), 'ravensight-playtest-')));
+  const projectCopy = path.join(root, 'project');
+  try {
+    // 0o700: the copy carries whatever the repository carries, including any
+    // local .env files, so no other user on the machine gets to read it.
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    await fs.chmod(root, 0o700);
+
+    // One dereference of any given directory. measureProject counts a symlinked
+    // tree once, so the copy has to copy it once, or the two disagree and the
+    // cap stops meaning anything.
+    const visited = new Set();
+    const realProjectDir = await realRootOf(projectDir);
+    // dereference: a symlink copied as a symlink still points at the developer's
+    // real file, and every write below would go straight through it.
+    await fs.cp(projectDir, projectCopy, {
+      recursive: true,
+      force: true,
+      dereference: true,
+      filter: async (source) => {
+        if (excludes.includes(path.basename(source))) return false;
+        const link = await fs.lstat(source).catch(() => null);
+        if (!link?.isSymbolicLink()) return true;
+        // fs.cp throws ENOENT on a symlink it cannot dereference, and a project
+        // with one broken link in it is not a project that should fail to launch.
+        const real = await fs.realpath(source).catch(() => null);
+        if (!real) return false;
+        if (resolvesIntoOwnAncestry(real, realProjectDir)) return false;
+        if (visited.has(real)) return false;
+        visited.add(real);
+        return true;
+      },
+    });
+
+    // Belt and braces: dereference covers the copy, materialize covers anything
+    // it left behind, so the three paths written below cannot be links.
+    await materializePath(projectCopy, `addons/${ADDON_DIR_NAME}`);
+    await fs.cp(addonDir, path.join(projectCopy, 'addons', ADDON_DIR_NAME), {
+      recursive: true,
+      force: true,
+      dereference: true,
+    });
+    await writeOverrideCfg(projectCopy);
+    await patchProjectGodot(projectCopy);
+    return { tempRoot: root, projectCopy };
+  } catch (error) {
+    // A half written copy is of no use to anyone and the caller has no handle on
+    // it yet, so it does not get to outlive the failure. Only a root this
+    // function created is removed: a tempRoot the caller passed in is theirs.
+    if (!tempRoot) await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function writeOverrideCfg(projectCopy) {
+  await materializePath(projectCopy, 'override.cfg');
+  const overridePath = path.join(projectCopy, 'override.cfg');
+  const existing = await readIfPresent(overridePath);
+  const next = setIniEntry(existing ?? '', 'autoload', AUTOLOAD_NAME, `"${AUTOLOAD_VALUE}"`);
+  await fs.writeFile(overridePath, next, 'utf8');
+  return overridePath;
+}
+
+async function patchProjectGodot(projectCopy) {
+  await materializePath(projectCopy, 'project.godot');
+  const projectPath = path.join(projectCopy, 'project.godot');
+  const existing = await fs.readFile(projectPath, 'utf8');
+  const next = setIniEntry(existing, 'autoload', AUTOLOAD_NAME, `"${AUTOLOAD_VALUE}"`);
+  await fs.writeFile(projectPath, next, 'utf8');
+  return projectPath;
+}
+
+async function readIfPresent(file) {
+  try {
+    return await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sets one key inside one section of a Godot style config file, preserving
+ * every other line, including autoloads the project already registers.
+ */
+export function setIniEntry(text, section, key, value) {
+  const header = `[${section}]`;
+  const lines = text.length > 0 ? text.split('\n') : [];
+  const sectionStart = lines.findIndex((line) => line.trim() === header);
+  const entry = `${key}=${value}`;
+
+  if (sectionStart === -1) {
+    const body = text.replace(/\s*$/, '');
+    const prefix = body.length > 0 ? `${body}\n\n` : '';
+    return `${prefix}${header}\n\n${entry}\n`;
+  }
+
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i += 1) {
+    if (/^\[[^\]]+\]\s*$/.test(lines[i].trim())) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  for (let i = sectionStart + 1; i < sectionEnd; i += 1) {
+    if (keyPattern.test(lines[i])) {
+      lines[i] = entry;
+      return lines.join('\n');
+    }
+  }
+  const insertAt = lastNonEmpty(lines, sectionStart + 1, sectionEnd) + 1;
+  lines.splice(insertAt, 0, entry);
+  return lines.join('\n');
+}
+
+function lastNonEmpty(lines, from, to) {
+  let last = from - 1;
+  for (let i = from; i < to; i += 1) {
+    if (lines[i].trim() !== '') last = i;
+  }
+  return last;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Reads the project's declared engine version, e.g. "4.5" from config/features. */
+export async function readProjectEngineVersion(projectDir) {
+  const text = await readIfPresent(path.join(projectDir, 'project.godot'));
+  if (!text) return null;
+  const match = text.match(/config\/features\s*=\s*PackedStringArray\(([^)]*)\)/);
+  if (!match) return null;
+  for (const raw of match[1].split(',')) {
+    const value = raw.trim().replace(/^"|"$/g, '');
+    if (/^\d+\.\d+$/.test(value)) return value;
+  }
+  return null;
+}
+
+/** Parses "4.5.1.stable.official" into a comparable shape. */
+export function parseGodotVersion(output) {
+  const match = String(output).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) return null;
+  return {
+    version: match[0],
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: match[3] === undefined ? null : Number(match[3]),
+  };
+}
+
+async function defaultProbe(binary) {
+  try {
+    const { stdout, stderr } = await execFileAsync(binary, ['--headless', '--version'], {
+      timeout: 20000,
+    });
+    return parseGodotVersion(`${stdout}\n${stderr}`);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Finds a usable Godot 4.2+ binary the way spec 17 describes: an explicit
+ * path, then $GODOT, then PATH, then the platform's usual install locations.
+ * When the project declares an engine version, a binary with that major.minor
+ * wins over a newer one.
+ *
+ * `RAVENSIGHT_GODOT` is read before the generic `$GODOT` spec 17 names. It is
+ * the variable the README and `check`'s fix hints tell a developer to set, and
+ * a project scoped override should win over a machine wide one: someone whose
+ * `$GODOT` points at the 4.2 build they ship with can point this at the 4.5
+ * they are testing without disturbing it.
+ */
+export async function detectGodotBinary({
+  explicitPath,
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  projectDir,
+  probe = defaultProbe,
+  minMajor = 4,
+  minMinor = 2,
+} = {}) {
+  const wanted = projectDir ? await readProjectEngineVersion(projectDir) : null;
+  const candidates = [];
+  const push = (value) => {
+    if (value && !candidates.includes(value)) candidates.push(value);
+  };
+
+  push(explicitPath);
+  push(env.RAVENSIGHT_GODOT);
+  push(env.GODOT);
+  push(env.GODOT_PATH);
+  for (const name of ['godot', 'godot4']) {
+    for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+      if (dir) push(path.join(dir, platform === 'win32' ? `${name}.exe` : name));
+    }
+  }
+  for (const found of await platformCandidates(platform, env, home)) push(found);
+
+  const usable = [];
+  for (const candidate of candidates) {
+    if (!(await isExecutable(candidate))) continue;
+    const version = await probe(candidate);
+    if (!version) continue;
+    if (version.major < minMajor) continue;
+    if (version.major === minMajor && version.minor < minMinor) continue;
+    usable.push({ path: candidate, ...version });
+    if (explicitPath && candidate === explicitPath) break;
+  }
+  if (usable.length === 0) {
+    const hint = explicitPath
+      ? `--godot-path ${explicitPath} is not a usable Godot ${minMajor}.${minMinor}+ binary`
+      : `no Godot ${minMajor}.${minMinor}+ binary found; install Godot or pass --godot-path`;
+    throw new Error(hint);
+  }
+  if (wanted) {
+    const [major, minor] = wanted.split('.').map(Number);
+    const exact = usable.find((item) => item.major === major && item.minor === minor);
+    if (exact) return { ...exact, projectVersion: wanted, matchesProject: true };
+  }
+  return { ...usable[0], projectVersion: wanted, matchesProject: false };
+}
+
+async function platformCandidates(platform, env, home) {
+  const found = [];
+  if (platform === 'darwin') {
+    for (const dir of ['/Applications', path.join(home, 'Applications')]) {
+      for (const name of await listDir(dir)) {
+        if (/^Godot.*\.app$/.test(name)) {
+          found.push(path.join(dir, name, 'Contents/MacOS/Godot'));
+        }
+      }
+    }
+  } else if (platform === 'win32') {
+    const roots = [env.LOCALAPPDATA, path.join(env.LOCALAPPDATA ?? '', 'Programs'), env.PROGRAMFILES].filter(Boolean);
+    for (const root of roots) {
+      for (const name of await listDir(root)) {
+        if (/^Godot/i.test(name)) {
+          if (name.toLowerCase().endsWith('.exe')) found.push(path.join(root, name));
+          for (const inner of await listDir(path.join(root, name))) {
+            if (/^Godot.*\.exe$/i.test(inner)) found.push(path.join(root, name, inner));
+          }
+        }
+      }
+    }
+  } else {
+    for (const dir of [path.join(home, '.local/bin'), '/usr/local/bin', '/usr/bin', '/opt/godot']) {
+      for (const name of await listDir(dir)) {
+        if (/^godot(4|-4.*)?$/.test(name)) found.push(path.join(dir, name));
+      }
+    }
+  }
+  return found;
+}
+
+async function listDir(dir) {
+  if (!dir) return [];
+  try {
+    return await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+}
+
+async function isExecutable(file) {
+  try {
+    const stat = await fs.stat(file);
+    if (!stat.isFile()) return false;
+    await fs.access(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Finds a loopback port the driver can bind, starting from the spec default. */
+export async function findFreePort(start = 47800, tries = 64) {
+  for (let offset = 0; offset < tries; offset += 1) {
+    const port = start + offset;
+    if (await canBind(port)) return port;
+  }
+  throw new Error(`no free loopback port in ${start}..${start + tries - 1}`);
+}
+
+function canBind(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => resolve(true));
+    });
+  });
+}