@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/playable-record/scripts/verify-firstwin.mjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+/**
+ * Headless first-level win probe — objective DoD for ring 1 `firstLevelWin`.
+ *
+ * Boots the game, triggers debug auto-play via window.__playable.autoPlay(),
+ * polls getState() until isGameOver && currentPhase === 'ENDCARD', then exits 0.
+ *
+ * Usage:
+ *   node skills/playable-record/scripts/verify-firstwin.mjs --root=. --use-dev --url=http://localhost:3000/
+ *   npm run verify:firstwin
+ *
+ * Exit 0 = first level winnable (ENDCARD reached)
+ * Exit 2 = contract broken or win not reached within timeout
+ * Exit 1 = unexpected error
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { evaluateContract, snapshotContractInPage } from './verify-contract.mjs';
+import { detectDevUrl, startDevServer, startHttpServer, waitForHttp } from './lib/dev-server.mjs';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+const DEFAULT_SCENE = 'MainScene';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const POLL_INTERVAL_MS = 250;
+/** DOM id of the on-screen one-click clear button (see game/contract/publish.ts). */
+const DEBUG_CLEAR_BUTTON_ID = 'playable-debug-clear';
+
+/** Append the `debug=1` flag that gates the on-screen one-click clear button. */
+function withDebugFlag(url) {
+  return url.includes('debug=1') ? url : `${url}${url.includes('?') ? '&' : '?'}debug=1`;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    url: null,
+    useDev: false,
+    port: 8080,
+    scene: DEFAULT_SCENE,
+    timeout: DEFAULT_TIMEOUT_MS,
+    headed: false,
+    json: false,
+  };
+  for (const arg of argv) {
+    if (arg === '--use-dev') opts.useDev = true;
+    else if (arg === '--headed') opts.headed = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg.startsWith('--url=')) opts.url = arg.slice('--url='.length);
+    else if (arg.startsWith('--port=')) opts.port = Number(arg.slice('--port='.length));
+    else if (arg.startsWith('--scene=')) opts.scene = arg.slice('--scene='.length);
+    else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice('--timeout='.length));
+  }
+  return opts;
+}
+
+/**
+ * Open the base url WITHOUT ?debug=1 and confirm the one-click clear button is
+ * absent — proving the button is gated by the debug flag and won't leak into
+ * production or MP4 capture. Returns a (possibly empty) list of problems.
+ */
+async function verifyButtonGating(context, baseUrl) {
+  const page = await context.newPage();
+  try {
+    await page.goto(baseUrl, { waitUntil: 'networkidle', timeout: 60000 });
+    const present = await page
+      .waitForFunction((id) => !!document.getElementById(id), DEBUG_CLEAR_BUTTON_ID, { timeout: 3000 })
+      .then(() => true)
+      .catch(() => false);
+    if (present) {
+      return [
+        `one-click clear button (#${DEBUG_CLEAR_BUTTON_ID}) is visible without ?debug=1 — it must be gated by the debug flag so it stays out of production/capture`,
+      ];
+    }
+    return [];
+  } finally {
+    await page.close().catch(() => {});
+  }
+}
+
+function getPlayableStateInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.getState === 'function') {
+    return window.__playable.getState();
+  }
+  const sm = window.__game?.scene?.getScene(sceneKey)?.sceneManager;
+  if (!sm) return null;
+  return {
+    currentPhase: sm.currentPhase,
+    isGameOver: typeof sm.isGameOver === 'function' ? sm.isGameOver() : false,
+  };
+}
+
+function isFirstWinStateInPage(sceneKey = 'MainScene') {
+  let state = null;
+  if (window.__playable && typeof window.__playable.getState === 'function') {
+    state = window.__playable.getState();
+  } else {
+    const sm = window.__game?.scene?.getScene(sceneKey)?.sceneManager;
+    if (sm) {
+      state = {
+        currentPhase: sm.currentPhase,
+        isGameOver: typeof sm.isGameOver === 'function' ? sm.isGameOver() : false,
+      };
+    }
+  }
+  if (!state) return false;
+  return !!state.isGameOver && state.currentPhase === 'ENDCARD';
+}
+
+async function gameSourceFiles(dir) {
+  const out = [];
+  async function walk(current) {
+    let entries = [];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = `${current}/${entry.name}`;
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (/\.(mjs|cjs|js|jsx|ts|tsx)$/.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(`${dir}/game`);
+  return out;
+}
+
+export function detectAutoPlayCheatsInSource(source) {
+  const problems = [];
+  const autoPlayBody = extractAutoPlayBody(source);
+  if (/\bforceWin\s*\(/.test(autoPlayBody)) {
+    problems.push('autoPlay must not use forceWin() or equivalent direct-win helper');
+  }
+  if (/\bshowWinScreen\s*\(/.test(autoPlayBody)) {
+    problems.push('autoPlay must not call showWinScreen() directly');
+  }
+  if (/currentPhase\s*=\s*['"]ENDCARD['"]/.test(autoPlayBody)) {
+    problems.push('autoPlay must not set currentPhase directly to ENDCARD');
+  }
+  return problems;
+}
+
+function extractAutoPlayBody(source) {
+  const patterns = [
+    /\b(?:async\s+)?(?:function\s+)?autoPlay\s*\([^)]*\)\s*\{/,
+    /\bautoPlay\s*:\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>\s*\{/,
+  ];
+  const match = patterns.map((pattern) => pattern.exec(source)).find(Boolean);
+  if (!match || match.index == null) return '';
+  const open = source.indexOf('{', match.index);
+  if (open < 0) return '';
+  let depth = 0;
+  for (let i = open; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '{') depth += 1;
+    if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return source.slice(open + 1, i);
+    }
+  }
+  return source.slice(open + 1);
+}
+
+export async function detectAutoPlayCheats(projectRoot) {
+  const problems = [];
+  for (const file of await gameSourceFiles(projectRoot)) {
+    const source = await readFile(file, 'utf8');
+    for (const problem of detectAutoPlayCheatsInSource(source)) {
+      problems.push(`${file.replace(`${projectRoot}/`, '')}: ${problem}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * @returns {Promise<{ ok: boolean, problems: string[], url: string, finalState?: object, elapsedMs?: number }>}
+ */
+export async function runFirstWinProbe(opts) {
+  const { chromium } = await import('playwright');
+  const projectRoot = resolve(opts.root);
+  const cheatProblems = await detectAutoPlayCheats(projectRoot);
+  if (cheatProblems.length > 0) {
+    return { ok: false, problems: cheatProblems, url: opts.url || '(not started)' };
+  }
+  let server = null;
+  let browser = null;
+  let url = opts.url;
+
+  if (opts.url && !opts.useDev) {
+    /* external server */
+  } else if (opts.useDev) {
+    server = startDevServer(projectRoot);
+    url = await detectDevUrl(server, opts.url || 'http://127.0.0.1:3000/', 30000);
+  } else {
+    server = startHttpServer(opts.port, projectRoot);
+    url = `http://127.0.0.1:${opts.port}/game/index.html`;
+  }
+
+  const killServer = () => {
+    if (server && !server.killed) server.kill('SIGTERM');
+  };
+
+  try {
+    await waitForHttp(url, 30000);
+    browser = await chromium.launch({ headless: !opts.headed });
+    const context = await browser.newContext({ viewport: { width: 1080, height: 1920 } });
+    const page = await context.newPage();
+    // Open with ?debug=1 so the on-screen one-click clear button is mounted.
+    await page.goto(withDebugFlag(url), { waitUntil: 'networkidle', timeout: 60000 });
+
+    await page
+      .waitForFunction(
+        (key) => {
+          if (window.__playable && typeof window.__playable.autoPlay === 'function') return true;
+          const s = window.__game && window.__game.scene && window.__game.scene.getScene(key);
+          return !!(s && typeof s._onDebugAutoPlay === 'function');
+        },
+        opts.scene,
+        { timeout: 15_000 },
+      )
+      .catch(() => {
+        /* snapshot below reports missing hooks */
+      });
+
+    const snapshot = await page.evaluate(
+      ([key, src]) => {
+        // eslint-disable-next-line no-eval
+        const fn = eval(`(${src})`);
+        return fn(key);
+      },
+      [opts.scene, snapshotContractInPage.toString()],
+    );
+    const contract = evaluateContract(snapshot, opts.scene);
+    if (!contract.ok) {
+      return {
+        ok: false,
+        problems: contract.problems,
+        url,
+      };
+    }
+
+    // Hard requirement (ring 1+): an on-screen one-click clear debug button must be
+    // mounted when the page is opened with ?debug=1.
+    const debugButton = await page
+      .waitForFunction(
+        (id) => {
+          const el = document.getElementById(id);
+          if (!el) return null;
+          const style = window.getComputedStyle(el);
+          const rect = el.getBoundingClientRect();
+          // NOTE: do not use offsetParent — it is null for position:fixed elements
+          // (which the debug button is) in Chromium, so it cannot gauge visibility.
+          const visible =
+            style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            style.opacity !== '0' &&
+            rect.width > 0 &&
+            rect.height > 0;
+          return { present: true, visible };
+        },
+        DEBUG_CLEAR_BUTTON_ID,
+        { timeout: 8000 },
+      )
+      .then((handle) => handle.jsonValue())
+      .catch(() => ({ present: false, visible: false }));
+    if (!debugButton.present || !debugButton.visible) {
+      return {
+        ok: false,
+        problems: [
+          `no visible one-click clear debug button (#${DEBUG_CLEAR_BUTTON_ID}) under ?debug=1 — ring 1+ requires a debug-gated one-click clear; mount it via publishPlayableRuntime()/mountDebugClearButton() in game/contract/publish.ts`,
+        ],
+        url,
+      };
+    }
+
+    const phasePath = [];
+    const pushPhase = (phase) => {
+      if (typeof phase === 'string' && phasePath[phasePath.length - 1] !== phase) {
+        phasePath.push(phase);
+      }
+    };
+    const initialState = await page.evaluate(
+      (src) => {
+        // eslint-disable-next-line no-eval
+        const fn = eval(`(${src})`);
+        return fn();
+      },
+      getPlayableStateInPage.toString(),
+    );
+    pushPhase(initialState?.currentPhase);
+
+    // Trigger the clear by clicking the on-screen debug button — this verifies the
+    // button is actually wired to autoPlay(), not just present in the DOM.
+    const autoStarted = await page.evaluate((id) => {
+      const el = document.getElementById(id);
+      if (!el) return false;
+      el.click();
+      return true;
+    }, DEBUG_CLEAR_BUTTON_ID);
+    if (!autoStarted) {
+      return {
+        ok: false,
+        problems: [`one-click clear button (#${DEBUG_CLEAR_BUTTON_ID}) disappeared before it could be clicked`],
+        url,
+      };
+    }
+
+    const startMs = Date.now();
+    let finalState = null;
+    while (Date.now() - startMs < opts.timeout) {
+      finalState = await page.evaluate(
+        (src) => {
+          // eslint-disable-next-line no-eval
+          const fn = eval(`(${src})`);
+          return { won: fn(), state: window.__playable?.getState?.() ?? null };
+        },
+        isFirstWinStateInPage.toString(),
+      );
+      pushPhase(finalState?.state?.currentPhase);
+      if (finalState?.won) {
+        // Gating check: the debug button must NOT appear without ?debug=1, so it
+        // never leaks into production / MP4 capture.
+        const gatingProblems = await verifyButtonGating(context, url);
+        if (gatingProblems.length > 0) {
+          return { ok: false, problems: gatingProblems, url, finalState: finalState.state };
+        }
+        return {
+          ok: true,
+          problems: [],
+          url,
+          finalState: finalState.state,
+          elapsedMs: Date.now() - startMs,
+          phasePath,
+        };
+      }
+      await page.waitForTimeout(POLL_INTERVAL_MS);
+    }
+
+    finalState = await page.evaluate(() =>
+      window.__playable?.getState?.() ?? null,
+    );
+    return {
+      ok: false,
+      problems: [
+        `first level did not reach ENDCARD within ${opts.timeout}ms (last state: ${JSON.stringify(finalState)})`,
+      ],
+      url,
+      finalState,
+      elapsedMs: Date.now() - startMs,
+      phasePath,
+    };
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    killServer();
+  }
+}
+
+function printHuman(result) {
+  console.log(`[verify:firstwin] ${result.ok ? 'OK' : 'FAIL'} — ${result.url}`);
+  if (result.ok) {
+    console.log(`  ENDCARD reached in ${result.elapsedMs ?? '?'}ms`);
+    if (result.finalState) console.log(`  final state: ${JSON.stringify(result.finalState)}`);
+    if (result.phasePath) console.log(`  phase path: ${result.phasePath.join(' → ')}`);
+  } else {
+    for (const p of result.problems) console.log(`  ✗ ${p}`);
+    if (result.elapsedMs != null) console.log(`  elapsed: ${result.elapsedMs}ms`);
+    if (result.finalState) console.log(`  final state: ${JSON.stringify(result.finalState)}`);
+    if (result.phasePath) console.log(`  phase path: ${result.phasePath.join(' → ')}`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await runFirstWinProbe(opts);
+  await writeValidatorArtifact(opts.root, 'firstwin', result).catch(() => {});
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(`[verify:firstwin] ${err.message}`);
+    process.exit(1);
+  });
+}