@joystack/cli 0.1.54 → 0.1.55

package/lib/shot/check.mjs

@@ -0,0 +1,57 @@
+// The check a `joystack shot` script passes before anything starts: no dev
+// server is asked, no browser launched, so a script that cannot work fails in
+// a moment rather than after the game has loaded.
+//
+// It refuses a script that does what the command does for it: launching a
+// browser or a page, opening an address, killing processes. A script that
+// opens its own page leaves the one it was given, the one that waited for the
+// game to finish updating; one that names an
+// address guesses a port the dev server may not be on.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { extname } from 'node:path';
+
+// A script is a short file; a larger one is something else passed by mistake.
+const SIZE_MOST = 200_000;
+
+// What a script must not do, each with what to do instead.
+export const REFUSED = [
+  [/\b(chromium|firefox|webkit)\s*\.\s*launch\w*\s*\(/, 'launches a browser: use the `page` your function is given'],
+  [/\.\s*new(Page|Context)\s*\(/, 'opens a page of its own: use the `page` your function is given'],
+  [/\.\s*goto\s*\(/, "opens an address: the page is already on the game (pass the game's own parameters with --query)"],
+  [/\b(pkill|killall)\b|process\s*\.\s*kill\s*\(/, 'kills processes: the command closes its browser itself'],
+  [/(localhost|127\.0\.0\.1):\d+/, 'names an address and a port: the page is already on the game'],
+];
+
+// Throws with a line fit to print when the script at `file` cannot be run;
+// returns nothing when it can.
+export function checkScript(file, { node = process.execPath } = {}) {
+  let st;
+  try {
+    st = statSync(file);
+  } catch {
+    throw new Error(`no script at ${file}`);
+  }
+  if (!st.isFile()) throw new Error(`${file} is not a file`);
+  // .mjs alone: a .js file is a module or not by the nearest package.json, so
+  // the same file would parse in the game's folder and fail in /tmp.
+  if (extname(file) !== '.mjs') throw new Error(`the script is a JavaScript module ending in .mjs, not ${extname(file) || 'a file with no extension'}`);
+  if (st.size > SIZE_MOST) throw new Error(`the script is ${Math.round(st.size / 1000)} kB; a shot script is a few lines that drive the game`);
+  const text = readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  for (const [pattern, why] of REFUSED) {
+    // A line that is all comment is passed over; a comment at the end of a
+    // line is not stripped, since `//` also opens every address.
+    const at = lines.findIndex((l) => !/^\s*\/\//.test(l) && pattern.test(l));
+    if (at >= 0) throw new Error(`line ${at + 1} ${why}:\n  ${lines[at].trim().slice(0, 160)}`);
+  }
+  if (!/\bexport\s+default\b|\bas\s+default\b|\bexport\s*\{[^}]*\bdefault\b/.test(text)) throw new Error('the script exports no function: write `export default async ({ page, game, shot }) => { … }`');
+  // Parsed as a module, as it will be run, so a syntax error is reported with
+  // its line before the game is opened.
+  const parsed = spawnSync(node, ['--check', file], { encoding: 'utf8', timeout: 10_000 });
+  if (parsed.error?.code === 'ETIMEDOUT') throw new Error('the script could not be checked: node --check took over 10 s (the computer is very busy); run it again');
+  if (parsed.status !== 0) {
+    const said = String(parsed.stderr || parsed.error?.message || 'it does not parse').trim().split('\n').filter((l) => l && !/^\s+at /.test(l) && !/^Node\.js v/.test(l));
+    throw new Error(`the script does not parse:\n  ${said.slice(0, 6).join('\n  ')}`);
+  }
+}

package/lib/shot/lock.mjs

@@ -0,0 +1,109 @@
+// One `joystack shot` script at a time on a computer. A headless browser
+// drawing a 3D game without a GPU takes a whole core, and a maker machine has
+// one, shared by every draft's agent and dev server; two at once make both slow
+// enough to time out. The lock is a folder in the temporary folder, holding the
+// owner's process id, so one left by a process that died is taken over.
+// The folder's name carries the user's id, since the temporary folder can be
+// shared by every user of a computer. Windows has no user id (`userInfo()`
+// gives -1), so there it carries the user's name. JOYSTACK_SHOT_LOCK names another folder
+// (a test's own).
+import { closeSync, constants, lstatSync, mkdirSync, openSync, readSync, rmdirSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+
+const user = userInfo();
+export const LOCK_NAME = `joystack-shot-${user.uid >= 0 ? user.uid : user.username.replace(/[^\w-]/g, '_')}.lock`;
+// A lock not touched for this long is taken over whoever holds it, for the
+// process id a dead holder left that the system has since given to another
+// process. Its holder touches it while the script runs (`touch`); untouched,
+// a run waits out an update for at most READY_MOST_MS (ready.mjs, two
+// minutes) before its runner starts touching it.
+export const LOCK_STALE_MS = 10 * 60_000;
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+// The process id in a lock, or null. Only a plain file is read, and without
+// following a link or waiting on a pipe someone left in its place.
+function holder(dir) {
+  try {
+    const fd = openSync(join(dir, 'pid'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const buf = Buffer.alloc(16);
+      const n = readSync(fd, buf, 0, 16, 0);
+      const pid = Number(buf.toString('utf8', 0, n));
+      return Number.isInteger(pid) && pid > 0 ? pid : null;
+    } finally { closeSync(fd); }
+  } catch {
+    return null;
+  }
+}
+
+// Whether `dir` is a lock this user could have made: a folder of its own, not
+// a link to one. Anything else in its place (another user's link, on a
+// computer whose temporary folder every user shares) is never taken down, only
+// waited for.
+function ours(dir) {
+  try {
+    const st = lstatSync(dir);
+    return st.isDirectory() && !st.isSymbolicLink() && (typeof process.getuid !== 'function' || st.uid === process.getuid());
+  } catch {
+    return false;
+  }
+}
+
+// Whether the lock at `dir` was left by a process that is gone, or was not
+// touched for longer than any attempt takes.
+function stale(dir, now) {
+  if (!ours(dir)) return false;
+  try {
+    if (now - lstatSync(dir).mtimeMs > LOCK_STALE_MS) return true;
+  } catch {
+    return false;
+  }
+  const pid = holder(dir);
+  // No pid yet: made a moment ago, and someone is taking it.
+  return pid !== null && !alive(pid);
+}
+
+// Takes a stale lock down: its pid file, then the folder, which fails if
+// anything else is in it. Never a recursive delete of a folder someone else
+// may have made.
+function takeDown(dir) {
+  if (!ours(dir)) return;
+  try { unlinkSync(join(dir, 'pid')); } catch { /* already gone */ }
+  try { rmdirSync(dir); } catch { /* taken again, or not ours to remove */ }
+}
+
+// Waits for the lock and takes it; resolves with `release`, which gives it
+// back if it is still this process's, and `release.touch()`, which says it is
+// still in use. Says once what it waits for. Rejects after `mostMs`.
+export async function takeLock({ dir = process.env.JOYSTACK_SHOT_LOCK || join(tmpdir(), LOCK_NAME), mostMs = 3 * 60_000, pollMs = 250, log = () => {} } = {}) {
+  const until = Date.now() + mostMs;
+  let said = false;
+  for (;;) {
+    try {
+      mkdirSync(dir, { mode: 0o700 });
+      writeFileSync(join(dir, 'pid'), String(process.pid), { flag: 'wx' });
+      const release = () => { if (holder(dir) === process.pid) takeDown(dir); };
+      release.touch = () => { try { const t = new Date(); utimesSync(dir, t, t); } catch { /* gone */ } };
+      return release;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+    if (stale(dir, Date.now())) {
+      takeDown(dir);
+      try { lstatSync(dir); } catch { continue; }
+      // Still there: not ours to take down. Wait as for any holder.
+    }
+    if (Date.now() >= until) throw new Error('another `joystack shot` script was still running after 3 minutes');
+    if (!said) { log('  waiting for another `joystack shot` script to finish…'); said = true; }
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+}

package/lib/shot/ready.mjs

@@ -0,0 +1,45 @@
+// When the dev server is between updates, so a page loaded now stays loaded.
+//
+// Under `joystack dev` a game page reloads as soon as an update starts (an
+// edit, a restored file) and is answered with the "Updating…" page until the
+// new version is ready (static-server.mjs, reloadClient). A script whose page
+// is caught in that reload loses it, so the page is opened only while the
+// server says `ready` with nothing pending. With auto-reload off, changed
+// files wait for someone to ask for a version, and no page reloads meanwhile,
+// so pending changes then hold nothing up.
+import { loopbackJson } from '../assets-page.mjs';
+import { printable } from '../assets-sheet.mjs';
+
+// How often the state is asked for, and for how long an update is waited
+// out.
+export const READY_POLL_MS = 500;
+export const READY_MOST_MS = 120_000;
+
+// The dev server's state (GET /__joystack/dev): `{ state, pending, error,
+// version }`, or null when the server keeps no versions (started without
+// reloads) or does not answer.
+export function devState(origin, { timeoutMs = 3000 } = {}) {
+  return loopbackJson({ port: Number(new URL(origin).port), path: '/__joystack/dev', timeoutMs });
+}
+
+// Resolves with the version that is ready, or null when the server keeps no
+// versions; rejects with the build's error when the newest one failed, or
+// when no update finishes in `mostMs`. Says once, through `log`, that it waits.
+export async function untilReady(origin, { mostMs = READY_MOST_MS, pollMs = READY_POLL_MS, state = devState, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), log = () => {} } = {}) {
+  const until = Date.now() + mostMs;
+  let said = false;
+  for (;;) {
+    const s = await state(origin);
+    if (!s) return null;
+    // Failed with nothing coming: with auto-reload off, changed files make
+    // no version until someone asks, so a failure stands. The game's error is
+    // its own text, so it is kept to one printable line.
+    if (s.state === 'failed' && !(s.pending && s.auto !== false)) {
+      throw new Error(`the game has an error, so it cannot be opened: ${printable(String(s.error ?? 'the update failed')).slice(0, 500)}`);
+    }
+    if (s.state === 'ready' && !(s.pending && s.auto !== false)) return s.version ?? null;
+    if (Date.now() >= until) throw new Error(`the game was still updating after ${Math.round(mostMs / 1000)} s`);
+    if (!said) { log('  waiting for the game to finish updating…'); said = true; }
+    await sleep(pollMs);
+  }
+}

package/lib/shot/run.mjs

@@ -0,0 +1,217 @@
+// The process a `joystack shot` script runs in (started by shot.mjs, with the
+// preloads a browser smoke gets). It reads its job from JOYSTACK_SHOT_JOB,
+// loads the script, opens the game with the engine's own `openPage`, hands the
+// script the page, the world handle and `shot`, and says in one line what went
+// wrong when something does. It exits 0 when the script finished and the game
+// threw nothing, 1 otherwise.
+import { mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { gpuArgs } from '../smoke-gpu-preload.mjs';
+import { loadPlaywright, printable, safeName, writeReplacing } from '../assets-sheet.mjs';
+import { replyLine } from '../assets-export.mjs';
+import { printableLines } from '../printable.mjs';
+
+// How long one step on the page (a click, a wait for a selector, a
+// `game.waitFor`) may take. A script that waits for something that never comes
+// learns it in seconds.
+export const STEP_MS = 5000;
+// The dev tools' button and panel, which the dev server adds to a game page
+// and no player sees, left out of every picture.
+const NO_DEV_TOOLS = 'joystack-devtools { display: none !important; }';
+const ERROR_MOST = 300;
+// Fixed waits longer than this, added up, earn a line saying what to wait on.
+const SLEPT_SAY_MS = 1000;
+
+const job = JSON.parse(process.env.JOYSTACK_SHOT_JOB || 'null');
+const say = (line) => process.stdout.write(`${line}\n`);
+// Output read through a pipe that closes early (`| head`) is no failure of the
+// script: what is not read is dropped, and the run goes on.
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+// Ends the process once the line is written: stderr to a pipe is written
+// asynchronously on macOS, and an exit straight after the write can drop it.
+const fail = async (message) => {
+  await new Promise((r) => process.stderr.write(`joystack shot: ${printableLines(message)}\n`, r));
+  process.exit(1);
+};
+if (!job) await fail('run.mjs is started by `joystack shot`, not on its own');
+
+const scriptUrl = pathToFileURL(job.script).href;
+const shownPath = (file) => (file.startsWith(`${job.projectDir}${sep}`) ? relative(job.projectDir, file) : file);
+
+// The line of the script an error came from, as `line 12: await page.click(…)`,
+// or '' when the stack does not pass through it.
+function scriptLineOf(err) {
+  const stack = String(err?.stack ?? '');
+  // The script may be named through a link (macOS's /var is /private/var), so
+  // its frames can carry either name.
+  let real = job.script;
+  try { real = realpathSync(job.script); } catch { /* removed since: its own name only */ }
+  const names = new Set([job.script, real].flatMap((p) => [pathToFileURL(p).href, p]));
+  let line = null;
+  for (const name of names) {
+    const m = stack.match(new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:(\\d+)`));
+    if (m) { line = Number(m[1]); break; }
+  }
+  if (!line) return '';
+  let text = '';
+  try { text = readFileSync(job.script, 'utf8').split('\n')[line - 1] ?? ''; } catch { /* removed since */ }
+  return `\n  at line ${line} of the script: ${text.trim().slice(0, 160)}`;
+}
+
+// Playwright's timeouts, and the world handle's `waitFor` and `driveTo`, which
+// give up in the page with a plain error.
+const timedOut = (err) => err?.name === 'TimeoutError' || /\b(waitFor|driveTo)\b[^\n]*(timed out|gave up after)/.test(String(err?.message ?? ''));
+
+// What went wrong, in a line or two: Playwright's first line (its call log is
+// for a person debugging Playwright), what a timeout means here, and where.
+function describe(err) {
+  // An error thrown in the page comes back behind Playwright's own words.
+  const first = String(err?.message ?? err).split('\n')[0].replace(/^page\.evaluate: Error: /, '').slice(0, 400);
+  const waited = timedOut(err) ? `\n  each step waits at most ${STEP_MS / 1000} s: the thing it waited for did not happen (a selector the page has not got, a state the game did not reach)` : '';
+  return `${first}${waited}${scriptLineOf(err)}`;
+}
+
+let mod;
+try {
+  mod = await import(scriptUrl);
+} catch (err) {
+  await fail(`the script did not load: ${describe(err)}`);
+}
+if (typeof mod.default !== 'function') await fail('the script exports no function: write `export default async ({ page, game, shot }) => { … }`');
+
+// The engine's door for a process that drives a browser, reachable through the
+// joystack resolver the preload registers.
+let openPage;
+try {
+  ({ openPage } = await import('joystack/smoke'));
+} catch (err) {
+  await fail(`this game's engine has no openPage to open the game with (${String(err?.message ?? err).split('\n')[0]}): npx joystack update`);
+}
+
+let game = null;
+let code = 0;
+let slept = 0;
+// A room keeps a time scale after the page that set it has gone (only a pause
+// is let go), and in a multiplayer game the room is the one people play in, so
+// the scale it had before the script changed it is put back, on every ending.
+// A page stuck in a loop never answers, so the putting back is given a second.
+let scaledFrom = null;
+const putBackTimeScale = () => (scaledFrom === null ? null : Promise.race([
+  scaledFrom.then((from) => game.setTimeScale(from)).catch(() => {}),
+  new Promise((r) => setTimeout(r, 1000).unref()),
+]));
+
+let browser;
+// Asked to stop (by `joystack shot`, or a Ctrl-C reaching the whole group):
+// the browser is closed and the run ends without a word, since what stopped it
+// says why. Playwright's own handlers are off, as they close the browser and
+// leave the script to fail on the closed page, reporting that instead.
+let stopping = false;
+const onStop = async () => {
+  if (stopping) return;
+  stopping = true;
+  await putBackTimeScale();
+  await browser?.close().catch(() => {});
+  process.exit(130);
+};
+process.on('SIGTERM', onStop);
+process.on('SIGINT', onStop);
+try {
+  const { chromium } = await loadPlaywright(job.projectDir, 'a shot script runs');
+  browser = await chromium.launch({ args: [...gpuArgs(), '--disable-dev-shm-usage'], handleSIGTERM: false, handleSIGINT: false, handleSIGHUP: false });
+} catch (err) {
+  await fail(`no browser to run the script in: ${String(err?.message ?? err).split('\n').slice(0, 2).join(' ').slice(0, 400)}`);
+}
+
+try {
+  const context = await browser.newContext(job.view);
+  const id = Math.random().toString(36).slice(2, 10);
+  const url = `${job.origin}/games/${encodeURIComponent(job.slug)}/index.html${job.query ? `?${job.query}` : ''}`;
+  try {
+    game = await openPage({ browser, context, url, as: `shot-${id}`, room: `shot-${id}`, render: 'full', timeoutMs: job.startMs });
+  } catch (err) {
+    throw Object.assign(new Error(`the game did not start: ${String(err?.message ?? err).split('\n').slice(0, 2).join(' ').slice(0, 600)}`), { plain: true });
+  }
+  const { page } = game;
+  page.setDefaultTimeout(STEP_MS);
+  page.setDefaultNavigationTimeout(STEP_MS * 2);
+  // The handle's own waits default to the time the game had to start; the
+  // script's are steps like any other.
+  const handle = {
+    ...game,
+    waitFor: (predicate, opts = {}) => game.waitFor(predicate, { timeoutMs: STEP_MS, ...opts }),
+    driveTo: (entity, target, opts = {}) => game.driveTo(entity, target, { timeoutMs: STEP_MS, ...opts }),
+    setTimeScale: async (value, opts) => {
+      scaledFrom ??= game.timeScale().catch(() => 1);
+      await scaledFrom;
+      if (stopping) return undefined;
+      return game.setTimeScale(value, opts);
+    },
+  };
+  // Every load after the first is the game reloading under the script.
+  let reloads = 0;
+  page.on('domcontentloaded', () => { reloads += 1; });
+  // Fixed waits, added up: a script that sleeps is padded for the slowest
+  // machine and still misses on it.
+  const sleep = page.waitForTimeout.bind(page);
+  page.waitForTimeout = (ms) => { slept += Number(ms) || 0; return sleep(ms); };
+
+  const written = new Map();
+  let n = 0;
+  const shot = async (name) => {
+    n += 1;
+    const base = safeName(name ?? `shot-${n}`);
+    // Two frames drawn first, so the picture is of a whole frame.
+    await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+    const png = await page.screenshot({ type: 'png', style: NO_DEV_TOOLS, timeout: STEP_MS * 3 });
+    mkdirSync(job.out, { recursive: true });
+    const file = join(job.out, `${base}.png`);
+    writeReplacing(file, png);
+    written.set(file, { name: printable(String(name ?? base)), path: shownPath(file) });
+    say(`  📷 ${shownPath(file)}`);
+    return file;
+  };
+  const log = (...parts) => say(printable(parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(p))).join(' ')));
+
+  let timer;
+  const limit = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error(`the script did not finish in ${job.timeoutMs / 1000} s (--timeout)`), { plain: true })), job.timeoutMs);
+  });
+  try {
+    await Promise.race([mod.default({ page, game: handle, shot, log }), limit]);
+  } catch (err) {
+    if (reloads) throw Object.assign(new Error('the game reloaded while the script ran (a file of the game changed): run it again once nothing is being edited'), { plain: true });
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!written.size) say('  the script took no picture: call shot("name") for each one');
+  if (job.maker && written.size) {
+    say('  To show one in your reply, write its line:');
+    for (const w of written.values()) say(`     ${replyLine(w.name, w.path)}`);
+  }
+} catch (err) {
+  // The page failed because the stop closed it: the stop ends the process.
+  if (stopping) await new Promise(() => {});
+  process.stderr.write(`joystack shot: ${printableLines(err?.plain ? err.message : describe(err))}\n`);
+  code = 1;
+}
+// A script that caught the closed page itself and returned says nothing more
+// either.
+if (stopping) await new Promise(() => {});
+if (slept > SLEPT_SAY_MS) say(`  slept ${(slept / 1000).toFixed(1)} s in fixed waits: game.waitFor((w) => …) or page.waitForSelector(…) waits only until the moment comes`);
+// A game that threw while the script drove it is the finding, whether or not
+// the script finished: a picture of a broken game is no evidence of its look.
+if (game?.errors.length) {
+  process.stderr.write(`joystack shot: the game threw while the script ran: ${printable(game.errors.slice(0, 3).map((e) => String(e).slice(0, ERROR_MOST)).join('; '))}\n`);
+  code = 1;
+}
+await putBackTimeScale();
+await browser.close().catch(() => {});
+// Exits rather than waiting for the event loop to empty, since a script given
+// up on can still hold a timer of its own; both streams are written out first.
+await new Promise((r) => process.stdout.write('', r));
+await new Promise((r) => process.stderr.write('', r));
+process.exit(code);