@playcraft/cli 0.1.49-beta → 0.1.51

package/project-template-v2/skills/playable-record/scripts/verify-firstwin.mjs

@@ -1,398 +0,0 @@
-#!/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);
-  });
-}