@joystack/cli 0.1.54 → 0.1.56

package/lib/shot/shot.mjs

@@ -0,0 +1,320 @@
+// `joystack shot <script>`: a short Playwright script of the agent's own, run
+// against the running game, with the parts that go wrong when every script
+// does them for itself done once here.
+//
+//   joystack shot .joystack/look.mjs
+//
+// The script exports one function. It is handed a page already open on the
+// game, at a phone's size, under a player name of its own, with the game
+// started; it drives the game to the moment it wants and calls
+// `shot(name)` for each picture:
+//
+//   export default async ({ page, game, shot }) => {
+//     await page.selectOption('#jump', '6');
+//     await game.waitFor((w) => w.query('boss').length > 0);
+//     await shot('boss');
+//   };
+//
+// What the command owns, so a script never does it:
+// - the check before anything starts: the file parses, exports a function, and
+//   neither launches a browser nor opens an address of its own (check.mjs);
+// - the dev stack: the one running for the game (in the maker, the draft's), or
+//   one started for the length of the command;
+// - the moment the page opens: only once the dev server has finished updating
+//   after an edit (ready.mjs), and the run is stopped, saying so, when the game
+//   updates under it;
+// - the browser: one, with the same flags every time, closed afterwards, and
+//   one script at a time on a computer (lock.mjs);
+// - time: every step of the page waits at most a few seconds, the whole script
+//   a minute unless --timeout says otherwise.
+//
+// The script runs in a child process (run.mjs) with the same preloads a
+// browser smoke gets, so it can import the joystack doors and a stuck script
+// is stopped by ending that process.
+
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findProject } from '../project.mjs';
+import { stackOrigin, stateFolderIn } from '../assets-sheet.mjs';
+import { makerDevPort, makerDraft } from '../maker.mjs';
+import { joystackTestPreload, SMOKE_PRELOAD } from '../test-cmd.mjs';
+import { checkScript } from './check.mjs';
+import { devState, untilReady } from './ready.mjs';
+import { takeLock } from './lock.mjs';
+
+export const SHOT_HELP = `joystack shot <script.mjs> [--size phone|tablet|desktop] [--landscape] [--query <k=v&…>] [--timeout <seconds>] [--out <dir>] [--port <n>]
+
+  Runs a short Playwright script against the running game and writes the
+  pictures it takes to .joystack/shots/<name>.png. The script exports one
+  function, handed a page already open on the game:
+
+    export default async ({ page, game, shot, log }) => {
+      await page.keyboard.press('Space');            // real input
+      await game.waitFor((w) => w.query('enemy').length >= 3);
+      await shot('three-enemies');
+    };
+
+  page   the Playwright page, on the game, started and showing what a player
+         sees; never goto or launch a browser of your own
+  game   the world handle openPage gives a smoke (not the page's window.game):
+         me(), mine(), ownIds(), entity(), snapshot(), query(selector: a component
+         name, tag:<name> or def:<name>), get(), set() (a dev room only),
+         send(), driveTo(), waitFor(), pause(), resume(), setTimeScale(),
+         players(). Every read is a promise: await game.query('boss')
+  shot   shot(name) writes the page as it is now; the dev tools are left out.
+         game.pause() first makes it a picture of one instant
+  log    log(...) prints a line
+
+  Wait for the moment, not for a time: game.waitFor or page.waitForSelector
+  wait only until it comes, where page.waitForTimeout is padded for the
+  slowest computer and still misses on it. A debug overlay the game has is
+  turned on as a player would (its key, or --query), then pictured.
+
+  --size     phone (390×844, the default), tablet (820×1180) or desktop
+             (1280×800); phone and tablet at twice the pixels
+  --landscape  the screen turned on its side
+  --query    added to the game's address: --query "level=3"
+  --timeout  seconds the whole script may take (default 60, at most 300);
+             each step on the page, and game.waitFor and driveTo, wait at
+             most 5 s
+  --out      the folder the pictures go to (outside the game's own files,
+             or each picture is an edit the game reloads for)
+  --port     the dev server's port, when this game's is not the one found
+
+  Write the script under .joystack/ (.joystack/look.mjs), which is not part
+  of the game. It is checked before anything starts, and the page opens only
+  once the dev server has finished updating after an edit; the run stops if
+  the game updates while it runs, and fails if the game throws. One page, one
+  player: in a multiplayer game it joins the game's one room, beside anyone
+  playing, so set(), pause() and setTimeScale() change their game too (a
+  time scale is put back to 1 when the script ends). It cannot stage an
+  entity the game does not spawn; that is a smoke's, openPage({ stage }). One
+  script at a time on a computer. Uses the dev stack already running for this
+  game, or starts one for the length of the command. Needs playwright in the
+  game (npm i -D playwright).`;
+
+export const SIZES = {
+  phone: { width: 390, height: 844, scale: 2, touch: true },
+  tablet: { width: 820, height: 1180, scale: 2, touch: true },
+  desktop: { width: 1280, height: 800, scale: 1, touch: false },
+};
+export const TIMEOUT_DEFAULT_S = 60;
+export const TIMEOUT_MOST_S = 300;
+// How long the game has to start once the page is opened, and how often the
+// dev server is asked whether it moved on while the script runs.
+export const START_MOST_MS = 45_000;
+const WATCH_MS = 500;
+
+const VALUED = {
+  '--size': ['size', String],
+  '--query': ['query', (v) => v.replace(/^\?/, '')],
+  '--timeout': ['timeout', Number],
+  '--out': ['out', String],
+  '--port': ['port', Number],
+};
+
+// The arguments after `joystack shot`.
+export function parseShotArgs(rest = []) {
+  const opts = { script: null, size: 'phone', landscape: false, query: '', timeout: TIMEOUT_DEFAULT_S, out: null, port: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--landscape') { opts.landscape = true; continue; }
+    if (a === '--help') continue;
+    if (!a.startsWith('--')) {
+      if (opts.script) throw new Error(`joystack shot runs one script, given two: ${opts.script} and ${a}`);
+      opts.script = a;
+      continue;
+    }
+    if (!VALUED[a]) throw new Error(`joystack shot has no option ${a}.\n\n${SHOT_HELP}`);
+    const v = rest[i + 1];
+    if (v == null || v.startsWith('--')) throw new Error(`${a} needs a value.\n\n${SHOT_HELP}`);
+    const [key, read] = VALUED[a];
+    opts[key] = read(v);
+    i += 1;
+  }
+  if (!opts.script) throw new Error(`joystack shot needs the script to run.\n\n${SHOT_HELP}`);
+  if (!SIZES[opts.size]) throw new Error(`--size is phone, tablet or desktop, not "${opts.size}"`);
+  if (!Number.isFinite(opts.timeout) || opts.timeout <= 0 || opts.timeout > TIMEOUT_MOST_S) throw new Error(`--timeout is a number of seconds above 0 and at most ${TIMEOUT_MOST_S}`);
+  if (opts.port !== null && !(Number.isInteger(opts.port) && opts.port > 0 && opts.port < 65536)) throw new Error('--port needs a port number');
+  return opts;
+}
+
+// The browser context's options for a size.
+export function viewFor(size, landscape) {
+  const s = SIZES[size];
+  const [width, height] = landscape ? [s.height, s.width] : [s.width, s.height];
+  return { viewport: { width, height }, deviceScaleFactor: s.scale, isMobile: s.touch, hasTouch: s.touch };
+}
+
+// The dev stack the script runs against: the one running for the game (in the
+// maker, the draft's, on a port of the maker's choosing), or one started with
+// its room server for the length of the command. In the maker none is
+// started: a second dev server beside the draft's would show nobody anything.
+async function stackFor({ cwd, project, port, startDev, env }) {
+  const at = makerDraft(env);
+  const devPort = port ?? (at ? await makerDevPort(at) : null);
+  try {
+    return await stackOrigin({ cwd, projectDir: project.dir, port: devPort, startDev: at ? null : startDev, mp: true });
+  } catch (err) {
+    if (!at) throw err;
+    throw new Error(`the draft's game is not running yet (the maker is starting it): try again in a moment (${String(err?.message ?? err).split('\n')[0].slice(0, 200)})`);
+  }
+}
+
+// Whether the dev server moved on from the version the script started on.
+export const moved = (now, version) => !!now && (now.state !== 'ready' || (now.pending && now.auto !== false) || (version != null && now.version !== version));
+
+const RUNNER = fileURLToPath(new URL('./run.mjs', import.meta.url));
+// How long the runner has to close its browser after being asked to stop,
+// before it is killed outright.
+const STOP_GRACE_MS = 2000;
+// How long a stop waits for a dev stack still starting, to stop it as well.
+const STACK_WAIT_MS = 10_000;
+
+// Runs the checked script in its own process. Resolves with how it ended:
+// { code } when it exited by itself, { signal } when something else killed it,
+// { moved: true } when the game updated under it, { timedOut: true } when it ran
+// past its limit, { stopped: true } after `stop()`. Returns { done, stop }.
+export function runChild({ projectDir, job, timeoutMs, origin, version, touch = () => {}, env, runner = RUNNER, graceMs = START_MOST_MS + 15_000, watchMs = WATCH_MS }) {
+  const preload = joystackTestPreload(projectDir);
+  const args = ['--import', SMOKE_PRELOAD, ...(preload ? ['--import', preload] : []), runner];
+  const child = spawn(process.execPath, args, { cwd: projectDir, env: { ...env, JOYSTACK_SHOT_JOB: JSON.stringify(job) }, stdio: ['ignore', 'inherit', 'inherit'] });
+  let ended = null;
+  let resolveP;
+  const done = new Promise((r) => { resolveP = r; });
+  let asking = false;
+  const watch = setInterval(async () => {
+    touch();
+    // One question at a time: a busy server answers slower than the ticks.
+    if (asking) return;
+    asking = true;
+    try {
+      if (moved(await devState(origin), version)) end({ moved: true });
+    } finally { asking = false; }
+  }, watchMs);
+  // The runner keeps its own limit on the script; this one is for a runner
+  // stuck past it (a page that stopped answering).
+  const limit = setTimeout(() => end({ timedOut: true }), timeoutMs + graceMs);
+  let kill = null;
+  function end(how) {
+    if (ended) return;
+    ended = how;
+    clearInterval(watch);
+    clearTimeout(limit);
+    if (how.code === undefined && how.signal === undefined) {
+      // Asked first, so Playwright closes its browser; then made to.
+      child.kill('SIGTERM');
+      kill = setTimeout(() => child.kill('SIGKILL'), STOP_GRACE_MS);
+    }
+  }
+  child.on('exit', (code, signal) => {
+    end(signal && code === null ? { signal } : { code: code ?? 0 });
+    clearTimeout(kill);
+    resolveP(ended);
+  });
+  child.on('error', (err) => { end({ code: 1, error: err }); resolveP(ended); });
+  return { done, stop: () => end({ stopped: true }) };
+}
+
+// The error a run's end makes, or null when it succeeded.
+function failureOf(how, { timeout, interrupted }) {
+  if (how.stopped) return Object.assign(new Error(`stopped (${interrupted ?? 'asked'}); the script's browser was closed`), { exitCode: 130 });
+  if (how.moved) return new Error('the game updated while the script ran (a file of the game changed), so its page reloaded: run it again once nothing is being edited');
+  if (how.timedOut) return new Error(`the script did not finish in ${timeout} s and was stopped`);
+  if (how.error) return how.error;
+  if (how.signal) return new Error(`the script's process was killed (${how.signal}), most often for want of memory`);
+  // The runner has said what went wrong in its own words.
+  if (how.code !== 0) return Object.assign(new Error('the script failed'), { reported: true });
+  return null;
+}
+
+// A stack still starting when a stop came, waited for a while so it can be
+// stopped too (in the maker none is ever started), or null.
+async function lateStack(stacking, { interrupted, log }) {
+  if (interrupted) log('  stopping the dev server it was starting…');
+  const late = await Promise.race([stacking.catch(() => null), new Promise((r) => setTimeout(r, STACK_WAIT_MS).unref())]);
+  return late?.started ?? null;
+}
+
+// Run one script. `startDev` starts a dev stack when none is running for the
+// game; `origin` is for a caller that already has one, and `runner` a stand-in
+// for run.mjs (both a test's). Throws with a line fit to print when the run
+// fails; resolves when it succeeded.
+export async function shot({
+  cwd = process.cwd(), script, size = 'phone', landscape = false, query = '', timeout = TIMEOUT_DEFAULT_S, out = null, port = null,
+  startDev, log = console.log, origin, env = process.env, lockDir, runner,
+} = {}) {
+  const file = resolve(cwd, script);
+  // Before anything starts, so a script that cannot work fails in a moment.
+  checkScript(file);
+  const project = findProject(cwd);
+  let started = null;
+  let stacking = null;
+  let stackSettled = false;
+  let release = null;
+  let child = null;
+  let interrupted = null;
+  // Ctrl-C, or a tool's limit on the command: the runner and its browser, the
+  // stack started for the command and the lock go with it. A wait in progress
+  // (the stack starting, an update, the lock) is given up at once. A second
+  // signal, while the first is still being acted on, ends the command there
+  // and then, giving back the lock.
+  let stop;
+  const stopped = new Promise((_, reject) => { stop = reject; });
+  stopped.catch(() => {});
+  const onSignal = (signal) => {
+    if (interrupted) {
+      // Its stop is begun, not waited for: a started stack's processes are
+      // signalled before it returns.
+      Promise.resolve().then(() => started?.stop()).catch(() => {});
+      release?.();
+      process.exit(130);
+    }
+    interrupted = signal;
+    child?.stop();
+    stop(Object.assign(new Error(`stopped (${signal})`), { exitCode: 130 }));
+  };
+  const orStop = (p) => Promise.race([p, stopped]);
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  try {
+    if (!origin) {
+      stacking = stackFor({ cwd, project, port, startDev, env });
+      // Whatever it started is kept the moment it is, a stop or not.
+      stacking.then((r) => { started ??= r?.started ?? null; stackSettled = true; }, () => { stackSettled = true; });
+      ({ origin, started } = await orStop(stacking));
+    }
+    // This game's update is waited out before the lock is taken, so another
+    // game's script never waits on it.
+    await orStop(untilReady(origin, { log }));
+    const taking = takeLock({ dir: lockDir, log });
+    // A lock taken after a stop is given back with the rest.
+    taking.then((r) => { release = r; if (interrupted) r(); }, () => {});
+    release = await orStop(taking);
+    const version = await orStop(untilReady(origin, { log }));
+    const job = {
+      script: file,
+      origin,
+      slug: project.slug,
+      query,
+      view: viewFor(size, landscape),
+      out: out ? resolve(cwd, out) : stateFolderIn(project.dir, 'shots'),
+      projectDir: project.dir,
+      timeoutMs: timeout * 1000,
+      startMs: START_MOST_MS,
+      maker: !!makerDraft(env),
+    };
+    child = runChild({ projectDir: project.dir, job, timeoutMs: job.timeoutMs, origin, version, touch: release.touch, env, runner });
+    const failed = failureOf(await child.done, { timeout, interrupted });
+    if (failed) throw failed;
+  } finally {
+    if (!started && stacking && !stackSettled && !makerDraft(env)) started = await lateStack(stacking, { interrupted, log });
+    // Each step on its own, so one that fails, even at once, still lets the
+    // next run.
+    await Promise.resolve().then(() => started?.stop()).catch(() => {});
+    release?.();
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}

package/lib/start-failed.mjs

@@ -0,0 +1,110 @@
+// POST /__joystack/dev/start-failed  { message, file, line, column, stack }
+//
+// A start that failed in a browser, which the dev tools runtime posts (the
+// injected tag names this route, inject.mjs), written to the dev server's log
+// as one block. `joystack dev` keeps that log in `.joystack/dev/last.log`
+// (dev-log.mjs), where the game's agent reads it: a failure on a phone, or in
+// the maker's Play, is otherwise seen only by the person holding it.
+//
+// The body is written by a page, which may be anyone's on a shared link: it is
+// taken only from a page the dev server served, size-limited, every field cut
+// and cleaned of control characters, and at most PER_MINUTE are written a
+// minute.
+import { relative, sep } from 'node:path';
+import { canonicalDevPath } from './legacy-names.mjs';
+
+export const START_FAILED_PATH = '/__joystack/dev/start-failed';
+const MAX_BYTES = 16 * 1024;
+const PER_MINUTE = 10;
+const STACK_LINES = 30;
+const SHAPE = 'expected { message, file, line, column, stack }';
+
+// Text from a page, for one line of the log: no control characters (an
+// escape sequence would move the terminal, a newline would forge a line of
+// the log), no bidirectional or zero-width marks (a line would read one way
+// in a terminal and another to the agent), cut to `max`.
+function logLine(value, max) {
+  const s = String(value ?? '').replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g, '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+// The block a failed start is written as: what failed, where (the file as it
+// is in the game's folder, or on disk for an engine file), the browser, who
+// sent it, and the stack when there is one, indented under it.
+export function startFailedBlock({ message, file, line, column, stack = [], browser, from }) {
+  const place = file ? `${file}${line ? `:${line}${column ? `:${column}` : ''}` : ''}` : '';
+  const lines = [`✗ The game didn't start in a browser: ${message || 'unknown error'}`];
+  if (place) lines.push(`  at ${place}`);
+  if (browser) lines.push(`  browser: ${browser}`);
+  if (from) lines.push(`  from: ${from}`);
+  for (const l of stack) lines.push(`    ${l}`);
+  return lines.join('\n');
+}
+
+// `log(block)`: where the block goes. `allowed(req)`: whether the request
+// came from a page the dev server served, to the creator. `from(req)`: who
+// sent it, said in the block. `ownHost(host)`: whether a URL's
+// host is the dev server's own. `slug`, `projectDir`, `resolveUrl(urlPath)`:
+// the game served, its folder, and the file a URL serves, to name the file
+// the way the agent finds it.
+export function createStartFailed({ log, allowed, from = () => '', ownHost, slug, projectDir, resolveUrl }) {
+  const times = [];
+
+  // A file the page names, as the agent finds it: a game file by its path in
+  // the game's folder (the server may serve a copy of it), a file of the
+  // server's otherwise by where it is on disk (from the game's folder when
+  // inside it), anything else as it was given.
+  function placeOnDisk(file) {
+    if (!file) return '';
+    let urlPath;
+    try {
+      const url = new URL(file, 'http://x');
+      if (!file.startsWith('/') && !ownHost(url.host)) return file;
+      urlPath = canonicalDevPath(decodeURIComponent(url.pathname));
+    } catch { return file; }
+    const inGame = `/games/${slug}/`;
+    if (urlPath.startsWith(inGame)) return urlPath.slice(inGame.length);
+    const fsPath = resolveUrl(urlPath);
+    if (!fsPath) return urlPath;
+    const rel = projectDir ? relative(projectDir, fsPath) : '';
+    return (rel && !rel.startsWith('..') && !/^[A-Za-z]:/.test(rel) ? rel : fsPath).split(sep).join('/');
+  }
+
+  // Whether another block may be written now.
+  function room() {
+    const now = Date.now();
+    while (times.length && now - times[0] > 60_000) times.shift();
+    if (times.length >= PER_MINUTE) return false;
+    times.push(now);
+    return true;
+  }
+
+  return async function handle(req, res) {
+    const answer = (status, body) => {
+      res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...(body ? {} : { 'Content-Length': 0 }) });
+      res.end(body ? JSON.stringify(body) : undefined);
+    };
+    if (req.method !== 'POST') return answer(405, { error: 'POST only' });
+    if (!allowed(req)) return answer(403, { error: 'only from a page this server served' });
+    let text = '';
+    for await (const c of req) {
+      text += c;
+      if (text.length > MAX_BYTES) return answer(413, { error: 'body too large' });
+    }
+    let body;
+    try { body = JSON.parse(text); } catch { return answer(400, { error: SHAPE }); }
+    if (!body || typeof body !== 'object') return answer(400, { error: SHAPE });
+    if (!room()) return answer(204);
+    const count = (v) => (Number.isInteger(v) && v > 0 && v < 1e7 ? v : 0);
+    log(startFailedBlock({
+      message: logLine(body.message, 500),
+      file: placeOnDisk(logLine(body.file, 500)),
+      line: count(body.line),
+      column: count(body.column),
+      stack: String(body.stack ?? '').split('\n').map((l) => logLine(l, 300)).filter(Boolean).slice(0, STACK_LINES),
+      browser: logLine(req.headers['user-agent'], 200),
+      from: from(req),
+    }));
+    return answer(204);
+  };
+}