@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/play/server.js

@@ -0,0 +1,274 @@
+import { randomBytes } from 'node:crypto';
+import { appendFile, cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { basename, join, resolve } from 'node:path';
+import { launch, viewportOptions, touchSession } from "../verify/browser.js";
+import { hookMapOf } from "../verify/hooks.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { evalJson, load, openTarget } from "../look/look.js";
+import { closeSession, IDLE_MS, playedSource, roundDir, sessionPath, shotName } from "./session.js";
+import { holdFrameTimes, parseStep, px, roundBudget, STEP_LIMITS, untilText } from "./steps.js";
+import { gesture, press } from "./input.js";
+import { PLAY_CLOCK } from "./clock.js";
+import { PLAY_POINTER } from "./pointer.js";
+import { CHANGED, changeOf, gridNow, smallFrame, stateLine } from "./frames.js";
+import { judgeExpect } from "./condition.js";
+import { counters } from "../journey/script.js";
+import { rendererOf } from "../verify/gpu.js";
+import { servedRoot } from "../commands/verify.js";
+import { startFilm, stopFilm } from "../walk/film.js";
+const cfg = JSON.parse(process.argv[2] ?? '{}');
+const dir = roundDir(cfg.root, cfg.round);
+const phone = cfg.viewport === 'phone';
+const sourceDir = playedSource(cfg.target, cfg.root);
+const before = sourceDir ? (await fingerprint(sourceDir)).fingerprint : undefined;
+const live = /^https?:\/\//.test(cfg.target) ? null : servedRoot(resolve(cfg.target));
+const copy = live && basename(live) === 'dist' ? join(dir, '.build') : null;
+if (copy && live) {
+    await rm(copy, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    await cp(live, copy, { recursive: true });
+}
+const opened = await openTarget(cfg.target, copy);
+if (typeof opened === 'string') {
+    console.error(opened);
+    process.exit(1);
+}
+const playedFingerprint = sourceDir && before === (await fingerprint(sourceDir)).fingerprint ? before : undefined;
+const t = opened;
+const budget = roundBudget(t.manifest, cfg.long_minutes ?? 0);
+const { browser } = await launch(false, true);
+const orientation = cfg.orientation ?? (typeof t.manifest.metadata?.orientation === 'string' ? t.manifest.metadata.orientation : '');
+const page = await (await browser.newContext(viewportOptions(cfg.viewport, orientation))).newPage();
+const errors = [];
+page.on('pageerror', (e) => errors.push(String(e.message ?? e).slice(0, 300)));
+page.on('console', (m) => { if (m.type() === 'error')
+    errors.push(m.text().slice(0, 300)); });
+let lost = '';
+page.on('crash', () => { lost ||= 'the browser tab crashed (renderer)'; });
+page.on('close', () => { lost ||= 'the browser tab closed'; });
+browser.on('disconnected', () => { lost ||= 'the browser went away'; });
+const lostAdvice = () => `${lost} at step ${n}. This stops the round; it is not by itself evidence the game is broken. Close the round (play end) and open a new one to retry the same steps; report it as a defect only if it happens again at the same moment.`;
+await page.addInitScript(PLAY_CLOCK);
+await page.addInitScript(PLAY_POINTER);
+await load(page, t.url, hookMapOf(t.manifest));
+const size = page.viewportSize() ?? { width: 1280, height: 720 };
+const renderer = await rendererOf(page);
+const listed = await evalJson(page, 'capture_view', { view: null, verbs: [], verb_gap_ms: 0, hold_ms: 0, freeze: false });
+const verbs = await page.evaluate('Object.keys(window.__FPX_VERBS__ || {})').catch(() => []);
+let cdp = null;
+let n = 0;
+const state = async () => page.evaluate(`(() => { try { const s = window.__FPX_STATE__ && window.__FPX_STATE__(); const j = JSON.stringify(s); return j && j.length < 4000 ? s : null; } catch (e) { return null; } })()`).catch(() => null);
+const field = async (path) => page.evaluate(`((p) => { try { let v = window.__FPX_STATE__ && window.__FPX_STATE__();
+  for (const k of p.split('.')) { if (v === null || v === undefined) return { v: null }; v = k === 'length' && Array.isArray(v) ? v.length : v[k]; }
+  return { v: v === undefined || (v !== null && typeof v === 'object') ? null : v }; } catch (e) { return { v: null }; } })(${JSON.stringify(path)})`).then((r) => r.v).catch(() => null);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const touch = async () => (cdp ??= await touchSession(page));
+const clock = (op) => page.evaluate(`window.__FPX_PLAY_CLOCK__ && window.__FPX_PLAY_CLOCK__.${op}()`).catch(() => { });
+let heldShots = [];
+let clips = [];
+async function whileHeld(ms, run) {
+    const start = Date.now();
+    const shoot = async () => {
+        for (const k of holdFrameTimes(ms)) {
+            await sleep(Math.max(0, k - (Date.now() - start)));
+            const name = shotName(n).replace(/\.png$/, `-held-${k}.png`);
+            await page.screenshot({ path: join(dir, name), scale: 'css' }).then(() => { heldShots.push(join(dir, name)); }).catch(() => { });
+        }
+    };
+    await Promise.all([run, shoot()]);
+}
+let untilOut = null;
+async function holdUntil(s) {
+    const cond = s.until;
+    const judged = async () => cond.kind === 'state' ? judgeExpect({ ...cond.expect, field: 'v' }, { v: (await field(cond.expect.field)) ?? undefined }).verdict : 'fail';
+    if (cond.kind === 'state' && (await judged()) === 'not_observed') {
+        return `the game's state has no ${cond.expect.field} to compare (or it is not a number): until ${untilText(cond)} could never be judged`;
+    }
+    const box = cond.kind === 'change' && cond.box ? (() => {
+        const [x1, y1, x2, y2] = [px(cond.box[0], size.width), px(cond.box[1], size.height), px(cond.box[2], size.width), px(cond.box[3], size.height)];
+        return { x: Math.min(x1, x2), y: Math.min(y1, y2), width: Math.max(1, Math.abs(x2 - x1)), height: Math.max(1, Math.abs(y2 - y1)) };
+    })() : null;
+    const base = cond.kind === 'change' ? await gridNow(page, box) : null;
+    const release = s.hold ? await press(page, touch, phone, s.hold) : null;
+    const start = Date.now();
+    let met = false;
+    try {
+        while (Date.now() - start < s.maxMs && !lost) {
+            await sleep(cond.kind === 'state' ? 50 : 100);
+            met = cond.kind === 'state' ? (await judged()) === 'pass' : changeOf(base, await gridNow(page, box)) >= CHANGED;
+            if (met)
+                break;
+        }
+    }
+    finally {
+        await release?.().catch(() => { });
+    }
+    untilOut = { met, after_ms: Date.now() - start, waited_for: untilText(cond) };
+    return '';
+}
+async function play(s) {
+    switch (s.kind) {
+        case 'hold_at':
+        case 'hold_key':
+            await whileHeld(s.ms, gesture(page, touch, phone, [s]));
+            return '';
+        case 'tap':
+        case 'drag':
+        case 'press':
+        case 'look':
+            await gesture(page, touch, phone, [s]);
+            return '';
+        case 'until':
+            return holdUntil(s);
+        case 'together': {
+            const held = Math.max(0, ...s.parts.map((p) => (p.kind === 'hold_at' || p.kind === 'hold_key' ? p.ms : 0)));
+            await whileHeld(held, gesture(page, touch, phone, s.parts));
+            return '';
+        }
+        case 'wait':
+            await sleep(s.ms);
+            return '';
+        case 'view': {
+            const v = await evalJson(page, 'capture_view', { view: s.name, verbs: [], verb_gap_ms: 0, hold_ms: 300, freeze: false });
+            return v?.entered ? '' : (v?.error || `could not enter ${s.name}`);
+        }
+        case 'verb': {
+            const r = await page.evaluate(`(async (n) => { const v = window.__FPX_VERBS__ || {}; if (typeof v[n] !== 'function') return 'no verb ' + n;
+        try { await Promise.race([v[n](), new Promise((r) => setTimeout(r, 1500))]); return ''; } catch (e) { return 'threw: ' + (e && e.message || e); } })(${JSON.stringify(s.name)})`);
+            return String(r ?? '');
+        }
+        case 'shot':
+            await page.screenshot({ path: join(dir, shotName(n)), scale: 'css' });
+            return '';
+        case 'clip': {
+            const started = await startFilm(page);
+            if (!started.ok)
+                return `no clip: ${started.error}`;
+            await sleep(s.ms);
+            const film = await stopFilm(page, join(dir, shotName(n).replace(/\.png$/, '-clip.webm')));
+            if (film.file)
+                clips.push(film.file);
+            return film.file ? '' : `no clip: ${film.error}`;
+        }
+    }
+}
+async function lookNow() {
+    const file = join(dir, shotName(n).replace(/\.png$/, '-look.jpg'));
+    const at = await smallFrame(page, file);
+    const s = await state();
+    await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, look: basename(file), at: new Date().toISOString() }) + '\n');
+    return { look: file, state: s && typeof s === 'object' ? stateLine(counters(s)) : 'the game publishes no state', size: `${at.width}x${at.height}` };
+}
+async function act(texts, o = {}) {
+    if (!Array.isArray(texts) || !texts.length)
+        return { error: 'no steps' };
+    if (texts.length > STEP_LIMITS.perAct)
+        return { error: `at most ${STEP_LIMITS.perAct} steps per act` };
+    if (n + texts.length > budget)
+        return { error: `the round's budget is ${budget} steps; ${budget - n} left — write the report` };
+    if (lost)
+        return { error: lostAdvice(), browser_lost: true };
+    const results = [];
+    const shots = [];
+    heldShots = [];
+    clips = [];
+    const before = errors.length;
+    await clock('resume');
+    for (const text of texts) {
+        const step = parseStep(text, phone);
+        n++;
+        untilOut = null;
+        const began = Date.now();
+        const error = typeof step === 'string' ? step : await play(step).catch((e) => String(e?.message ?? e).split('\n')[0]);
+        const ms = Date.now() - began;
+        const until = !error && untilOut ? untilOut : null;
+        results.push({ n, step: text, ok: !error, ...(error ? { error } : {}), ...(until ? { until } : {}) });
+        if (!error && typeof step !== 'string' && step.kind === 'shot') {
+            shots.push(join(dir, shotName(n)));
+            await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, shot: shotName(n) }) + '\n');
+        }
+        await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, step: text, ok: !error, error, ms, ...(until ? { until } : {}), at: new Date().toISOString() }) + '\n');
+        if (error && typeof step === 'string')
+            break;
+        if (lost)
+            break;
+    }
+    if (lost) {
+        await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, browser_lost: lost, at: new Date().toISOString() }) + '\n');
+        return { step: n, results, error: lostAdvice(), browser_lost: true, left: budget - n };
+    }
+    const shot = join(dir, shotName(n));
+    await page.screenshot({ path: shot, scale: 'css' });
+    await clock('pause');
+    const newErrors = errors.slice(before);
+    await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, shot: shotName(n), state: await state(), page_errors: newErrors }) + '\n');
+    if (heldShots.length)
+        await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n, held_shots: heldShots.map((p) => basename(p)) }) + '\n');
+    const looked = o.look ? await lookNow() : null;
+    return { step: n, results, shot, ...(looked ?? {}), ...(shots.length ? { shots } : {}), ...(heldShots.length ? { held_frames: heldShots } : {}), ...(clips.length ? { clips } : {}), page_errors: newErrors.length, first_error: newErrors[0] ?? '', left: budget - n };
+}
+await mkdir(dir, { recursive: true });
+await page.screenshot({ path: join(dir, shotName(0)), scale: 'css' });
+await clock('pause');
+await appendFile(join(dir, 'log.jsonl'), JSON.stringify({ n: 0, shot: shotName(0), state: await state(), page_errors: errors.slice() }) + '\n');
+const token = randomBytes(16).toString('hex');
+let idle;
+async function shutdown(why = 'idle') {
+    clearTimeout(idle);
+    if (!closing)
+        await closeSession(cfg.root, cfg.round, why);
+    await browser.close().catch(() => { });
+    await t.close().catch(() => { });
+    process.exit(0);
+}
+const touchIdle = () => { clearTimeout(idle); idle = setTimeout(() => void shutdown('idle'), IDLE_MS); };
+let busy = Promise.resolve();
+let closing = false;
+const server = createServer((req, res) => {
+    const send = (code, body) => { res.writeHead(code, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); };
+    if (req.method !== 'POST' || req.headers['x-play-token'] !== token)
+        return send(403, { error: 'refused' });
+    let raw = '';
+    req.on('data', (c) => { raw += c; if (raw.length > 64_000)
+        req.destroy(); });
+    req.on('end', () => {
+        touchIdle();
+        busy = busy.then(async () => {
+            try {
+                const body = raw ? JSON.parse(raw) : {};
+                if (closing)
+                    send(410, { error: 'the round is closed' });
+                else if (req.url === '/act')
+                    send(200, await act(body.steps, { look: !!body.look }));
+                else if (req.url === '/look')
+                    send(200, lost ? { error: lostAdvice(), browser_lost: true } : { step: n, ...(await lookNow()), left: budget - n });
+                else if (req.url === '/end') {
+                    closing = true;
+                    await closeSession(cfg.root, cfg.round, 'end');
+                    send(200, { ended: true, steps: n });
+                    setTimeout(() => void shutdown('end'), 50);
+                }
+                else
+                    send(404, { error: 'unknown' });
+            }
+            catch (e) {
+                send(500, { error: String(e?.message ?? e) });
+            }
+        });
+    });
+});
+server.listen(0, '127.0.0.1', async () => {
+    const addr = server.address();
+    const session = {
+        pid: process.pid, port: typeof addr === 'object' && addr ? addr.port : 0, token, round: cfg.round, viewport: cfg.viewport,
+        target: cfg.target, width: size.width, height: size.height, started_at: new Date().toISOString(),
+        fingerprint: playedFingerprint, ...(sourceDir ? { source_dir: sourceDir } : {}),
+        views: (listed?.views ?? []).map((v) => v.name), verbs, budget,
+        ...(cfg.long_minutes ? { long_minutes: cfg.long_minutes } : {}), renderer,
+    };
+    await writeFile(sessionPath(cfg.root, cfg.round), JSON.stringify(session, null, 2) + '\n', { mode: 0o600 });
+    touchIdle();
+});
+for (const sig of ['SIGINT', 'SIGTERM'])
+    process.on(sig, () => { void shutdown('signal'); });

package/dist/play/session.js

@@ -0,0 +1,231 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, openSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const PLAY_DIR = join('.funtools', 'play');
+export const DEFAULT_ROUNDS = 3;
+export const IDLE_MS = 15 * 60_000;
+export const sessionPath = (root, round) => join(roundDir(root, round), 'session.json');
+export const closedPath = (root, round) => join(roundDir(root, round), 'closed.json');
+export async function closeSession(root, round, why) {
+    const from = sessionPath(root, round);
+    if (!existsSync(from))
+        return;
+    try {
+        const s = JSON.parse(readFileSync(from, 'utf8'));
+        await writeFile(closedPath(root, round), JSON.stringify({ ...s, closed: why, closed_at: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch { }
+    await rm(from, { force: true });
+}
+export function playRoot(cwd) {
+    for (let d = resolve(cwd);; d = dirname(d)) {
+        try {
+            if (statSync(join(d, PLAY_DIR)).isDirectory())
+                return d;
+        }
+        catch { }
+        if (existsSync(join(d, 'funpixel.json')) || dirname(d) === d)
+            break;
+    }
+    return resolve(cwd);
+}
+export function playedSource(target, root) {
+    if (!/^https?:\/\//.test(target))
+        return target;
+    const local = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(target);
+    return local && existsSync(join(root, 'funpixel.json')) ? root : null;
+}
+export const roundDir = (root, n) => join(root, PLAY_DIR, `round-${n}`);
+export const shotName = (n) => `${String(n).padStart(3, '0')}.png`;
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+};
+export function roundsAll(root) {
+    const dir = join(root, PLAY_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((d) => { const m = /^round-(\d+)$/.exec(d); return m ? [Number(m[1])] : []; }).sort((a, b) => a - b);
+}
+export async function claimRound(root) {
+    await mkdir(join(root, PLAY_DIR), { recursive: true });
+    for (let n = (roundsAll(root).at(-1) ?? 0) + 1;; n++) {
+        try {
+            await mkdir(roundDir(root, n));
+            return n;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+    }
+}
+export function roundsFiled(root) {
+    const dir = join(root, PLAY_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((d) => {
+        const m = /^round-(\d+)$/.exec(d);
+        return m && existsSync(join(dir, d, 'report.json')) ? [Number(m[1])] : [];
+    }).sort((a, b) => a - b);
+}
+export async function openSession(root, round) {
+    const path = sessionPath(root, round);
+    if (!existsSync(path))
+        return null;
+    try {
+        const s = JSON.parse(readFileSync(path, 'utf8'));
+        if (alive(s.pid))
+            return s;
+        await closeSession(root, round, 'gone');
+        return null;
+    }
+    catch { }
+    await rm(path, { force: true });
+    return null;
+}
+export async function openSessions(root) {
+    const out = [];
+    for (const n of roundsAll(root)) {
+        const s = await openSession(root, n);
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+export function closedUnfiled(root, round) {
+    if (existsSync(join(roundDir(root, round), 'report.json')))
+        return null;
+    try {
+        return JSON.parse(readFileSync(closedPath(root, round), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function ancestors(max = 8) {
+    const out = [];
+    let pid = process.ppid;
+    for (let i = 0; i < max && pid > 1; i++) {
+        let line = '';
+        try {
+            line = execFileSync('ps', ['-o', 'ppid=', '-o', 'args=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        }
+        catch {
+            break;
+        }
+        const m = /^(\d+)\s+([\s\S]*)$/.exec(line);
+        if (!m)
+            break;
+        out.push({ pid, args: m[2] });
+        pid = Number(m[1]);
+    }
+    return out;
+}
+const INTERPRETERS = /^(?:sh|bash|zsh|dash|ksh|fish|node|nodejs|deno|bun|tsx|ts-node|python\d*(?:\.\d+)?|ruby|perl)$/;
+export function scriptOf(args) {
+    const t = args.trim().split(/\s+/);
+    if (!INTERPRETERS.test(basename(t[0] ?? '')))
+        return null;
+    for (const w of t.slice(1)) {
+        if (/^-(?:c|e|-eval|p|-print|m)$/.test(w))
+            return null;
+        if (!w.startsWith('-'))
+            return w;
+    }
+    return null;
+}
+export function helperOutsideRound(procs, root, round, cwd = process.cwd()) {
+    const mine = resolve(roundDir(root, round)) + sep;
+    const shared = [resolve(root), tmpdir(), '/tmp', '/private/tmp', '/var/folders', '/private/var/folders'].map((d) => resolve(d) + sep);
+    for (const p of procs) {
+        const s = scriptOf(p.args);
+        if (!s)
+            continue;
+        for (const f of isAbsolute(s) ? [s] : [resolve(cwd, s), resolve(root, s)]) {
+            let file = f;
+            try {
+                if (!statSync(f).isFile())
+                    continue;
+                file = realpathSync(f);
+            }
+            catch {
+                continue;
+            }
+            if (/[\\/]node_modules[\\/]/.test(file))
+                continue;
+            const real = (d) => { try {
+                return realpathSync(d.slice(0, -1)) + sep;
+            }
+            catch {
+                return d;
+            } };
+            if (file.startsWith(real(mine)) || f.startsWith(mine))
+                break;
+            if (shared.some((d) => file.startsWith(real(d)) || f.startsWith(d)))
+                return file;
+        }
+    }
+    return null;
+}
+export async function pickSession(root, round) {
+    if (round !== undefined) {
+        const s = await openSession(root, round);
+        return s ? { session: s } : { error: `round ${round} is not open in ${root}`, hint: existsSync(roundDir(root, round)) ? 'it was closed; open a new one: funtools play [dir]' : 'funtools play status lists the rounds here' };
+    }
+    const open = await openSessions(root);
+    if (open.length === 1)
+        return { session: open[0] };
+    if (!open.length)
+        return { error: `no play round is open in ${root}`, hint: 'open one in the game folder: funtools play [dir], or name it: --dir <game folder>' };
+    return {
+        error: `${open.length} rounds are open in ${root} (${open.map((s) => `round ${s.round} ${s.viewport}`).join(', ')})`,
+        hint: `name yours: --round ${open.map((s) => s.round).join(' or --round ')} (the number play printed when it opened your round)`,
+    };
+}
+export async function call(s, path, body = {}) {
+    const r = await fetch(`http://127.0.0.1:${s.port}${path}`, {
+        method: 'POST', headers: { 'content-type': 'application/json', 'x-play-token': s.token }, body: JSON.stringify(body),
+        signal: AbortSignal.timeout(5 * 60_000),
+    });
+    const j = await r.json().catch(() => ({ error: `HTTP ${r.status}` }));
+    if (!r.ok)
+        throw new Error(j.error ?? `HTTP ${r.status}`);
+    return j;
+}
+export async function startServer(cfg, timeoutMs = 90_000) {
+    await mkdir(roundDir(cfg.root, cfg.round), { recursive: true });
+    const logPath = join(roundDir(cfg.root, cfg.round), 'server.log');
+    const out = openSync(logPath, 'w');
+    const here = fileURLToPath(import.meta.url);
+    const script = join(here, '..', `server${extname(here)}`);
+    const child = spawn(process.execPath, [script, JSON.stringify(cfg)], { detached: true, stdio: ['ignore', out, out] });
+    child.unref();
+    const done = { exited: false };
+    child.on('exit', () => { done.exited = true; });
+    const until = Date.now() + timeoutMs;
+    while (Date.now() < until) {
+        await new Promise((r) => setTimeout(r, 200));
+        const s = await openSession(cfg.root, cfg.round);
+        if (s)
+            return s;
+        if (done.exited)
+            break;
+    }
+    if (!done.exited) {
+        try {
+            process.kill(child.pid);
+        }
+        catch { }
+    }
+    const log = existsSync(logPath) ? readFileSync(logPath, 'utf8').trim().split('\n').slice(-3).join(' ') : '';
+    throw new Error(`the play session did not start${log ? `: ${log}` : ''}`);
+}