ravensight-playtest 0.4.0 → 0.5.1

package/src/run/drivers/recording.js

@@ -0,0 +1,148 @@
+// Local recording only. This module never uploads, reads credentials, or captures
+// a display/audio device. Final files use the existing opt-in upload allowlist.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { detectFfmpeg } from '../../detect.js';
+import { MAX_VIDEO_BYTES } from '../../upload/allowlist.js';
+
+const execute = promisify(execFile);
+export const RECORDING_LIMITS = Object.freeze({
+  durationMs: 15 * 60 * 1000,
+  videoBytes: MAX_VIDEO_BYTES,
+  frameBytes: 256 * 1024 * 1024,
+  singleFrameBytes: 4 * 1024 * 1024,
+  width: 1280,
+  height: 720,
+  fps: 10,
+  finalizeMs: 60000,
+});
+
+// Test seams may lower limits, never raise production ceilings.
+export function recordingLimits(overrides = {}) {
+  const out = { ...RECORDING_LIMITS };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!(key in out) || !Number.isSafeInteger(value) || value < 1 || value > out[key]) {
+      throw new Error(`invalid recording limit: ${key}`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function recordingViewport(viewport, limits = RECORDING_LIMITS) {
+  const width = Number(viewport?.width ?? viewport?.w ?? limits.width);
+  const height = Number(viewport?.height ?? viewport?.h ?? limits.height);
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1) {
+    throw new Error('recording viewport must have positive integer dimensions');
+  }
+  const scale = Math.min(1, limits.width / width, limits.height / height);
+  return { width: Math.max(1, Math.floor(width * scale)), height: Math.max(1, Math.floor(height * scale)) };
+}
+
+export async function recordingDirectory(runDir) {
+  await fs.mkdir(runDir, { recursive: true });
+  // Reusing an old playable recording after a failed capture is worse than
+  // reporting no recording. Do not silently replace it either.
+  for (const name of ['session.webm', 'session.mp4', 'recording.json']) {
+    if (await fs.lstat(path.join(runDir, name)).then(() => true, e => { if (e.code === 'ENOENT') return false; throw e; })) {
+      throw new Error(`recording output already exists: ${name}`);
+    }
+  }
+  const directory = await fs.mkdtemp(path.join(runDir, '.recording-'));
+  await fs.chmod(directory, 0o700);
+  return directory;
+}
+
+export function recordingMetadata({ driver, startedAt, endedAt, reason = 'stopped', ...details }) {
+  return {
+    schemaVersion: 1, driver, status: 'failed', audio: false,
+    startedAt: new Date(startedAt).toISOString(), endedAt: new Date(endedAt).toISOString(),
+    durationMs: Math.max(0, endedAt - startedAt), durationSource: 'capture-clock',
+    relativePath: null, mimeType: null, bytes: 0, reason, stopReason: reason, ...details,
+  };
+}
+
+export async function saveRecording(runDir, metadata) {
+  const pending = path.join(runDir, '.recording.json.tmp');
+  await fs.writeFile(pending, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  await fs.rename(pending, path.join(runDir, 'recording.json'));
+  return metadata;
+}
+
+export async function videoInfo(file, { limits = RECORDING_LIMITS } = {}) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.size < 16 || stat.size > limits.videoBytes) throw new Error('invalid_video_size');
+  const handle = await fs.open(file, 'r');
+  const head = Buffer.alloc(16);
+  try { await handle.read(head, 0, head.length, 0); } finally { await handle.close(); }
+  const webm = head.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3]));
+  const mp4 = head.toString('ascii', 4, 8) === 'ftyp';
+  if (!webm && !mp4) throw new Error('invalid_video_container');
+  return { bytes: stat.size, mimeType: webm ? 'video/webm' : 'video/mp4' };
+}
+
+// ffprobe is optional for Playwright, whose successful close finalizes WebM.
+// When installed, verify the actual media timeline and absence of audio. A
+// present tool rejecting the media is a failure, never a fallback success.
+export async function probeVideo(file, { limits = RECORDING_LIMITS, run = execute } = {}) {
+  const info = await videoInfo(file, { limits });
+  const binary = process.env.RAVENSIGHT_FFPROBE || (process.env.RAVENSIGHT_FFMPEG
+    ? path.join(path.dirname(process.env.RAVENSIGHT_FFMPEG), process.platform === 'win32' ? 'ffprobe.exe' : 'ffprobe') : 'ffprobe');
+  let stdout;
+  try {
+    ({ stdout } = await run(binary, ['-v', 'error', '-show_entries', 'stream=codec_type,width,height:format=duration', '-of', 'json', file],
+      { timeout: 10000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true }));
+  } catch (error) {
+    if (error.code === 'ENOENT') return info;
+    throw new Error('invalid_video_media');
+  }
+  try {
+    const media = JSON.parse(stdout);
+    const video = media.streams.filter(stream => stream.codec_type === 'video');
+    const durationMs = Math.round(Number(media.format.duration) * 1000);
+    if (video.length !== 1 || media.streams.some(stream => stream.codec_type === 'audio')
+      || !Number.isSafeInteger(durationMs) || durationMs <= 0 || durationMs > limits.durationMs
+      || video[0].width > limits.width || video[0].height > limits.height) throw new Error();
+    return { ...info, durationMs, durationSource: 'media', width: video[0].width, height: video[0].height };
+  } catch { throw new Error('invalid_video_media'); }
+}
+
+/** Encode only numbered PNGs we wrote, with their actual capture timestamps. */
+export async function encodeFrames({ directory, frames, endedAt, limits = RECORDING_LIMITS, encoder, run = execute, inspect = probeVideo }) {
+  if (!frames.length) throw new Error('no_frames');
+  const detected = encoder ?? await detectFfmpeg();
+  if (!detected.path) throw new Error('encoder_unavailable');
+  const first = frames[0].at;
+  const durationMs = Math.min(limits.durationMs, Math.max(1000 / limits.fps, endedAt - first));
+  const lines = ['ffconcat version 1.0'];
+  for (let i = 0; i < frames.length; i++) {
+    const frame = frames[i];
+    if (!/^\d{6}\.png$/.test(frame.name) || !Number.isFinite(frame.at) || (i && frame.at < frames[i - 1].at)) {
+      throw new Error('invalid_frame_timeline');
+    }
+    const end = Math.min(first + durationMs, frames[i + 1]?.at ?? first + durationMs);
+    lines.push(`file '${frame.name}'`, `duration ${Math.max(0.001, (end - frame.at) / 1000).toFixed(6)}`);
+  }
+  lines.push(`file '${frames.at(-1).name}'`);
+  const list = path.join(directory, 'frames.ffconcat');
+  await fs.writeFile(list, `${lines.join('\n')}\n`, { mode: 0o600, flag: 'wx' });
+  const output = path.join(directory, 'encoded.mp4');
+  try {
+    await run(detected.path, [
+      '-nostdin', '-hide_banner', '-loglevel', 'error', '-n',
+      '-protocol_whitelist', 'file', '-f', 'concat', '-safe', '1', '-i', list,
+      '-an', '-vf', `scale=${limits.width}:${limits.height}:force_original_aspect_ratio=decrease,pad=ceil(iw/2)*2:ceil(ih/2)*2,setsar=1`,
+      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-pix_fmt', 'yuv420p',
+      '-r', '30', '-t', (durationMs / 1000).toFixed(3), '-fs', String(limits.videoBytes - 4096),
+      '-movflags', '+faststart', output,
+    ], { cwd: directory, timeout: limits.finalizeMs, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true });
+    const info = await inspect(output, { limits });
+    return { file: output, durationMs, ...info, truncated: info.durationMs != null && info.durationMs + 150 < durationMs };
+  } catch (error) {
+    await fs.rm(output, { force: true });
+    // Never include process output, a game path, or inherited environment in a report.
+    throw new Error(error.killed ? 'encoding_timeout' : 'encoding_failed');
+  }
+}

package/src/run/drivers/stdio.js

@@ -18,7 +18,7 @@ export async function readBridgeConfig(file) {
 }
 
 export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000 } = {}) {
-  let child, buffer = '', nextId = 0, runDirectory, step = 0, shots = 0, lastHash;
+  let child, childState, buffer = '', nextId = 0, runDirectory, step = 0, shots = 0, lastHash;
   const pending = new Map();
   const fail = message => {
     for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new DriverError(message, { fatal: true })); }
@@ -52,6 +52,9 @@ export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000
       const config = await readBridgeConfig(target);
       runDirectory = runDir;
       child = spawnImpl(config.command, config.args || [], { cwd: config.cwd || path.dirname(path.resolve(target)), shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+      const state = { process: child, closed: false, stopping: null };
+      state.close = new Promise(resolve => child.once('close', () => { state.closed = true; resolve(); }));
+      childState = state;
       child.stdout.setEncoding('utf8');
       child.stdout.on('data', chunk => {
         buffer += chunk;
@@ -92,20 +95,33 @@ export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000
     async screenshot(reason) {
       const image = await request('screenshot');
       if (typeof image?.pngBase64 !== 'string' || !image.pngBase64.startsWith('iVBORw0KGgo')) throw new DriverError('This bridge did not return a PNG screenshot.');
-      const relativePath = path.join('screenshots', screenshotName(++shots, reason));
+      const relativePath = path.posix.join('screenshots', screenshotName(++shots, reason));
       const file = path.join(runDirectory, relativePath);
       await fs.writeFile(file, Buffer.from(image.pngBase64, 'base64'));
       return { path: file, relativePath };
     },
     async consoleErrors() { return []; },
     async stop() {
-      if (child && child.exitCode === null && !child.killed) {
-        child.kill('SIGTERM');
-        const process = child;
-        const timer = setTimeout(() => { if (process.exitCode === null) process.kill('SIGKILL'); }, 1000);
-        timer.unref();
-      }
       fail('Game bridge stopped.');
+      const state = childState;
+      if (state && !state.stopping) {
+        state.stopping = (async () => {
+          if (state.closed) return;
+          const process = state.process;
+          let deadline;
+          const force = setTimeout(() => { if (!state.closed) process.kill('SIGKILL'); }, 1000);
+          try {
+            const timedOut = new Promise((resolve, reject) => {
+              deadline = setTimeout(() => reject(new DriverError('Game bridge did not close after stopping.', { fatal: true })), 5000);
+            });
+            if (process.exitCode === null && process.signalCode === null && !process.killed) process.kill('SIGTERM');
+            // Windows can retain the bridge's cwd until its pipes close, even
+            // after exit. Concurrent/repeated stops share the same close wait.
+            await Promise.race([state.close, timedOut]);
+          } finally { clearTimeout(force); clearTimeout(deadline); }
+        })();
+      }
+      if (state) await state.stopping;
       return { videoPath: null };
     }
   };

package/src/run/drivers/web.js

@@ -1,4 +1,5 @@
-import { mkdir, rename, stat, readdir } from 'node:fs/promises';
+import { mkdir, rename, stat, readdir, rm, chmod } from 'node:fs/promises';
+import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, probeVideo } from './recording.js';
 import path from 'node:path';
 import {
   DriverError,
@@ -1121,7 +1122,7 @@ export const CHECK_PLAYTEST_IDENTITY = Object.freeze({ token: 'check', runId: nu
  *   the one the platform implies
  * @returns {Object} a driver
  */
-export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null } = {}) {
+export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null, recording = {}, now = () => Date.now(), inspectVideo = probeVideo } = {}) {
   const editModifier = modifier === 'Meta' || modifier === 'Control' ? modifier : platformModifier(platform);
   let browser = null;
   let context = null;
@@ -1129,6 +1130,16 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
   let target = null;
   let runDirectory = null;
   let videoRequested = false;
+  const limits = recordingLimits(recording);
+  let captureDirectory = null;
+  let captureStartedAt = null;
+  let stopPromise = null;
+  let captureTimer = null;
+  let captureDeadline = null;
+  let runSignal = null;
+  let onAbort = null;
+  let inspecting = false;
+  let terminalReason = null;
   let step = 0;
   let shots = 0;
   let lastHash = null;
@@ -1344,6 +1355,77 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     return observationHash(after);
   }
 
+  function stop({ reason = 'stopped' } = {}) {
+    if (stopPromise) return stopPromise;
+    terminalReason ??= reason;
+    stopPromise = Promise.resolve().then(finalize);
+    return stopPromise;
+  }
+
+  async function finalize() {
+    clearInterval(captureTimer);
+    clearTimeout(captureDeadline);
+    runSignal?.removeEventListener('abort', onAbort);
+    const endedAt = now();
+    let videoPath = null;
+    let promotedPath = null;
+    let finalized = true;
+    // Only the explicitly selected page's handle may become session.webm.
+    const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
+    try { if (context) await withTimeout(context.close(), 15000); } catch { finalized = false; }
+    let metadata = null;
+    if (videoRequested && captureStartedAt != null) {
+      metadata = recordingMetadata({ driver: 'playwright_web', startedAt: captureStartedAt, endedAt,
+        reason: terminalReason, timeOrigin: 'page-creation-request' });
+      if (video) {
+        try {
+          let source;
+          if (typeof video.saveAs === 'function') {
+            source = path.join(captureDirectory, 'selected-final.webm');
+            await withTimeout(video.saveAs(source), 15000);
+          } else source = await withTimeout(video.path(), 15000);
+          // No arbitrary run-directory scan or old-file fallback on a crash.
+          if (path.dirname(path.resolve(source)) !== path.resolve(captureDirectory)) throw new Error('foreign_video_path');
+          const info = await inspectVideo(source, { limits });
+          if (info.mimeType !== 'video/webm') throw new Error('invalid_video_container');
+          const destination = path.join(runDirectory, 'session.webm');
+          await rename(source, destination);
+          promotedPath = destination;
+          await chmod(destination, 0o600);
+          videoPath = destination;
+          metadata = { ...metadata, ...info, relativePath: 'session.webm',
+            status: finalized && ['stopped', 'completed'].includes(terminalReason) ? 'complete' : 'partial' };
+        } catch (error) {
+          if (promotedPath) await rm(promotedPath, { force: true });
+          videoPath = null;
+          metadata.reason = 'video_finalization_failed';
+          metadata.failure = ['invalid_video_size', 'invalid_video_container', 'invalid_video_media', 'foreign_video_path'].includes(error.message) ? error.message : 'recorder_unavailable';
+        }
+      } else metadata.reason = 'video_unavailable';
+    }
+    try { if (browser) await withTimeout(browser.close(), 15000); } catch { /* already closed or unavailable */ }
+    if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true });
+    if (metadata) await saveRecording(runDirectory, metadata);
+    page = null;
+    context = null;
+    browser = null;
+    return { videoPath, ...(metadata ? { recording: metadata } : {}) };
+  }
+
+  async function inspectCapture() {
+    if (inspecting || stopPromise || !captureDirectory) return;
+    inspecting = true;
+    try {
+      let bytes = 0;
+      for (const name of await readdir(captureDirectory)) {
+        bytes += (await stat(path.join(captureDirectory, name))).size;
+      }
+      // Leave room for WebM's final index; oversize output is never published.
+      if (bytes >= Math.max(1, limits.videoBytes - 8 * 1024 * 1024)) await stop({ reason: 'size_limit' });
+    } catch { await stop({ reason: 'capture_failed' }); }
+    finally { inspecting = false; }
+  }
+
   return {
     name: 'playwright_web',
     supportsRefs: true,
@@ -1357,20 +1439,26 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
      * @param {boolean} [opts.recordVideo]
      * @param {{width: number, height: number}} [opts.viewport]
      */
-    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT }) {
+    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT, signal }) {
       if (!url) throw new DriverError('playwright_web needs a target URL', { fatal: true });
+      if (signal?.aborted) throw new DriverError('run canceled before browser launch');
       target = url;
       viewportSize = viewport || DEFAULT_VIEWPORT;
       runDirectory = runDir;
       videoRequested = Boolean(recordVideo);
+      if (videoRequested) {
+        viewport = recordingViewport(viewport, limits);
+        viewportSize = viewport;
+        captureDirectory = await recordingDirectory(runDir);
+      }
 
+      try {
       const playwright = await loadPlaywright(importer);
       await mkdir(runDir, { recursive: true });
-
-      browser = await playwright.chromium.launch({ headless });
+      browser = await playwright.chromium.launch({ headless, ...(videoRequested ? { args: ['--mute-audio'] } : {}) });
       context = await browser.newContext({
         viewport,
-        ...(videoRequested ? { recordVideo: { dir: runDir, size: viewport } } : {})
+        ...(videoRequested ? { recordVideo: { dir: captureDirectory, size: viewport }, permissions: [] } : {})
       });
       // The playtest identity goes in as an init script, not as
       // `extraHTTPHeaders`: a context header rides on every request the page
@@ -1387,7 +1475,34 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       // One token per document: set again by every new document, kept by
       // pushState and hash route changes, which do not run init scripts.
       if (typeof context.addInitScript === 'function') await context.addInitScript(markDocument);
+      if (videoRequested && typeof context.route === 'function') {
+        const origin = new URL(url).origin;
+        await context.route('**/*', route => {
+          const request = route.request();
+          if (request.isNavigationRequest() && !request.frame().parentFrame() && new URL(request.url()).origin !== origin) {
+            return route.abort('blockedbyclient');
+          }
+          return route.continue();
+        });
+      }
+      captureStartedAt = videoRequested ? now() : null;
       page = await context.newPage();
+      if (videoRequested) {
+        // Context video may briefly allocate a popup file; close it immediately
+        // and discard all non-selected files during finalization.
+        page.on('popup', popup => { void popup.close().catch(() => {}); });
+        page.on('crash', () => { void stop({ reason: 'game_crashed' }).catch(() => {}); });
+        page.on('close', () => { if (!stopPromise) void stop({ reason: 'page_closed' }).catch(() => {}); });
+        captureTimer = setInterval(() => { void inspectCapture(); }, 250);
+        captureTimer.unref?.();
+        captureDeadline = setTimeout(() => { void stop({ reason: 'duration_limit' }).catch(() => {}); }, limits.durationMs);
+        captureDeadline.unref?.();
+      }
+      runSignal = signal;
+      onAbort = () => { void stop({ reason: 'canceled' }).catch(() => {}); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) { await stop({ reason: 'canceled' }); throw new DriverError('run canceled during browser launch'); }
+
       page.on('console', message => {
         if (message.type() !== 'error') return;
         let location = null;
@@ -1426,6 +1541,11 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       if (response && response.status() >= 400) {
         throw new DriverError(`${url} answered ${response.status()}`, { fatal: true });
       }
+      } catch (error) {
+        await stop({ reason: 'launch_failed' }).catch(() => {});
+        if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true }).catch(() => {});
+        throw error;
+      }
     },
 
     /** @returns {Promise<import('./driver.js').Observation>} */
@@ -1586,7 +1706,9 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     async screenshot(name) {
       const current = requirePage();
       shots += 1;
-      const relativePath = path.join('screenshots', screenshotName(shots, name));
+      // Forward slashes on every platform: this is the evidence ref the server
+      // matches against upload paths.
+      const relativePath = path.posix.join('screenshots', screenshotName(shots, name));
       const absolute = path.join(runDirectory, relativePath);
       await mkdir(path.dirname(absolute), { recursive: true });
       await current.screenshot({ path: absolute, type: 'png', timeout: ACTION_TIMEOUT_MS });
@@ -1598,33 +1720,8 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       return attachNetworkFailures(consoleBuffer.splice(0, consoleBuffer.length), networkFailures);
     },
 
-    /** @returns {Promise<{videoPath: string|null}>} */
-    async stop() {
-      let videoPath = null;
-      const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
-      try {
-        if (context) await context.close();
-      } catch {
-        // A context that is already gone is not an error worth failing the
-        // run over; the report is already written by the time we get here.
-      }
-      if (video) {
-        try {
-          videoPath = await renameVideo(await video.path(), runDirectory);
-        } catch {
-          videoPath = await findVideo(runDirectory);
-        }
-      }
-      try {
-        if (browser) await browser.close();
-      } catch {
-        // Same: a closed browser is the desired end state either way.
-      }
-      page = null;
-      context = null;
-      browser = null;
-      return { videoPath };
-    }
+    /** Idempotent: cancellation, crashes and finally share one finalization. */
+    stop
   };
 }
 
@@ -1694,37 +1791,4 @@ export function attachNetworkFailures(entries, failures) {
   });
 }
 
-/**
- * Playwright names its recording with a random id. The upload allowlist and
- * the server's 90 day lifecycle rule are written against `session.webm`, so
- * the file is renamed rather than uploaded under whatever name it got.
- *
- * @param {string} source
- * @param {string} runDir
- * @returns {Promise<string>}
- */
-async function renameVideo(source, runDir) {
-  const target = path.join(runDir, 'session.webm');
-  if (!source || path.resolve(source) === path.resolve(target)) return target;
-  await rename(source, target);
-  return target;
-}
-
-/**
- * @param {string} runDir
- * @returns {Promise<string|null>}
- */
-async function findVideo(runDir) {
-  try {
-    const entries = await readdir(runDir);
-    const webm = entries.find(entry => entry.endsWith('.webm'));
-    if (!webm) return null;
-    const source = path.join(runDir, webm);
-    await stat(source);
-    return await renameVideo(source, runDir);
-  } catch {
-    return null;
-  }
-}
-
 export default createWebDriver;

package/src/run/drivers/webdriver.js

@@ -61,7 +61,7 @@ export function createWebDriverAdapter({name='desktop_driver',fetch:fetchImpl=gl
    }catch(error){return {ok:false,changed:false,error:error instanceof DriverError?error.message:'Device input failed.'};}
    finally {if(session)await request('DELETE',route('/actions')).catch(()=>{});}
   },
-  async screenshot(reason){const relativePath=path.join('screenshots',screenshotName(++shots,reason));const file=path.join(runDirectory,relativePath);await fs.writeFile(file,Buffer.from(await frame(),'base64'));return {path:file,relativePath,reason};},
+  async screenshot(reason){const relativePath=path.posix.join('screenshots',screenshotName(++shots,reason));const file=path.join(runDirectory,relativePath);await fs.writeFile(file,Buffer.from(await frame(),'base64'));return {path:file,relativePath,reason};},
   async consoleErrors(){return [];},
   async stop(){if(session){const current=route('');session=null;await request('DELETE',current);}return {videoPath:null};}
  };return driver;