@playcraft/cli 0.0.44 → 0.0.47

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Knife 12B — Developer build verification pipeline.
+ * Reads active slice evidenceTier, runs tier commands, writes validate/build.json.
+ *
+ * Usage: node skills/playable-record/scripts/verify-build.mjs --root=. [--skip-vlm]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getActiveSlice, readState } from '../../_shared/scripts/state-store.mjs';
+import { writeBuildArtifact } from './lib/build-artifact.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const EVIDENCE_TIERS = new Set(['probe', 'autoplay', 'video-vlm']);
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), skipVlm: false, json: false };
+  for (const arg of argv) {
+    if (arg === '--skip-vlm' || arg === '--skip-vlm=true') opts.skipVlm = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) {
+      opts.root = arg.slice('--root='.length);
+      opts.root = path.isAbsolute(opts.root) ? opts.root : path.resolve(process.cwd(), opts.root);
+    }
+  }
+  if (process.env.PLAYCRAFT_SKIP_VLM === '1') opts.skipVlm = true;
+  return opts;
+}
+
+function readIteration(root) {
+  try {
+    const md = fs.readFileSync(path.join(root, 'docs/project-state.md'), 'utf8');
+    const m = md.match(/^iteration:\s*(\d+)/m);
+    if (m) return Number(m[1]);
+  } catch {
+    /* fall through */
+  }
+  const state = readState(root);
+  const h = state.handoff?.iteration;
+  return Number(h) || 1;
+}
+
+function runNpm(root, script, extraArgs = [], timeoutMs = 180_000) {
+  const result = spawnSync('npm', ['run', script, '--', ...extraArgs], {
+    cwd: root,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    command: `npm run ${script}${extraArgs.length ? ` -- ${extraArgs.join(' ')}` : ''}`,
+  };
+}
+
+function recordAutoplayMp4(root, ring) {
+  return runNpm(
+    root,
+    'record:mp4',
+    [`--out=validate/ring${ring}`, '--name=autoplay', '--use-dev'],
+    360_000,
+  );
+}
+
+/**
+ * @param {{ root: string, skipVlm?: boolean }} opts
+ */
+export function runVerifyBuild(opts) {
+  const root = path.resolve(opts.root);
+  const slice = getActiveSlice(readState(root));
+  const problems = [];
+  const commands = [];
+  const artifactRefs = [];
+
+  if (!slice) {
+    const artifact = writeBuildArtifact(root, {
+      ok: false,
+      sliceId: 'none',
+      evidenceTier: 'probe',
+      iteration: readIteration(root),
+      commands: [],
+      artifactRefs: [],
+      problems: ['no active slice — seed sliceState before npm run build'],
+    });
+    return { ok: false, artifact, exitCode: 2 };
+  }
+
+  const tier = EVIDENCE_TIERS.has(String(slice.evidenceTier))
+    ? String(slice.evidenceTier)
+    : 'probe';
+  const iteration = readIteration(root);
+  let ok = true;
+
+  if (tier === 'probe') {
+    const r = runNpm(root, 'verify:slice', ['--use-dev']);
+    commands.push(r.command);
+    if (!r.ok) {
+      ok = false;
+      problems.push(r.stderr.slice(-400) || r.stdout.slice(-400) || 'verify:slice failed');
+    } else {
+      artifactRefs.push(`validate/slice/${slice.sliceId}.json`);
+    }
+  } else if (tier === 'autoplay') {
+    for (const script of ['verify:contract', 'verify:lifecycle']) {
+      const r = runNpm(root, script, ['--use-dev']);
+      commands.push(r.command);
+      if (!r.ok) {
+        ok = false;
+        problems.push(`${script} failed: ${(r.stderr || r.stdout).slice(-300)}`);
+      }
+    }
+    artifactRefs.push(`validate/ring${iteration}/contract.json`, `validate/ring${iteration}/lifecycle.json`);
+  } else if (tier === 'video-vlm') {
+    if (opts.skipVlm) {
+      const rAutoplay = runNpm(root, 'verify:contract', ['--use-dev']);
+      commands.push(rAutoplay.command);
+      if (!rAutoplay.ok) {
+        ok = false;
+        problems.push('PLAYCRAFT_SKIP_VLM: contract check failed (VLM skipped for CI)');
+      }
+      problems.push('PLAYCRAFT_SKIP_VLM=1 — video-vlm tier degraded to contract-only (live e2e must run full VLM)');
+    } else {
+      const mp4Path = path.join(root, `validate/ring${iteration}/autoplay.mp4`);
+      if (!fs.existsSync(mp4Path)) {
+        const rec = recordAutoplayMp4(root, iteration);
+        commands.push(rec.command);
+        if (!rec.ok) {
+          ok = false;
+          problems.push(`record:mp4 failed: ${(rec.stderr || rec.stdout).slice(-300)}`);
+        }
+      }
+      if (ok || fs.existsSync(mp4Path)) {
+        artifactRefs.push(`validate/ring${iteration}/autoplay.mp4`);
+        const vlmArgs = [`--ring=${iteration}`];
+        if (slice.sliceId) vlmArgs.push(`--slice-id=${slice.sliceId}`);
+        const vlm = runNpm(root, 'verify:vlm-video', vlmArgs, 360_000);
+        commands.push(vlm.command);
+        if (!vlm.ok) {
+          ok = false;
+          problems.push(`verify:vlm-video failed: ${(vlm.stderr || vlm.stdout).slice(-300)}`);
+        } else {
+          artifactRefs.push(`validate/ring${iteration}/vlm-video.json`);
+        }
+      }
+    }
+  }
+
+  const artifact = writeBuildArtifact(root, {
+    ok,
+    sliceId: slice.sliceId,
+    evidenceTier: tier,
+    iteration,
+    commands,
+    artifactRefs,
+    problems,
+  });
+
+  return { ok, artifact, exitCode: ok ? 0 : 2 };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = runVerifyBuild(opts);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result.artifact, null, 2)}\n`);
+  } else {
+    console.log(
+      `[verify:build] ok=${result.ok} slice=${result.artifact.sliceId} tier=${result.artifact.evidenceTier}`,
+    );
+    if (!result.ok && result.artifact.problems?.length) {
+      for (const p of result.artifact.problems) console.error(`  • ${p}`);
+    }
+  }
+  process.exit(result.exitCode);
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) main();

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

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * Live runtime-contract probe — the dynamic half of the Playable ⇄ Harness
+ * contract check (the static half is verify_runtime_contract.js).
+ *
+ * It boots the game in a headless browser and asserts, within a few seconds,
+ * that the recorder's entry points are actually wired at runtime:
+ *   - window.__playable is published as the neutral harness entry point
+ *   - window.__game may exist as a legacy engine handle, but must not shadow
+ *     Phaser.Game.start()
+ *   - MainScene.sceneManager.currentPhase is a string, or __playable.getState()
+ *     returns a string currentPhase
+ *   - MainScene._onDebugAutoPlay() or __playable.autoPlay() is a function
+ *
+ * This turns "record:mp4 silently times out after 30s" into a clear failure in
+ * seconds. The validation rule lives in `evaluateContract` so it can be unit
+ * tested and reused by record-playable.mjs without a second browser launch.
+ *
+ * Exit 0 = contract satisfied, 2 = contract broken, 1 = unexpected error.
+ *
+ * Usage:
+ *   node skills/playable-record/scripts/verify-contract.mjs --root=. --use-dev --url=http://localhost:3000/
+ *   node skills/playable-record/scripts/verify-contract.mjs --root=.            # standalone http-server
+ *   node skills/playable-record/scripts/verify-contract.mjs --url=http://localhost:3000/ --json
+ */
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectDevUrl, startDevServer, startHttpServer, waitForHttp } from './lib/dev-server.mjs';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+const DEFAULT_SCENE = 'MainScene';
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    url: null,
+    useDev: false,
+    port: 8080,
+    scene: DEFAULT_SCENE,
+    timeout: 8000,
+    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;
+}
+
+/**
+ * Validate a runtime snapshot of the contract surface. Pure — no browser — so it
+ * is unit-tested directly and shared with record-playable.mjs.
+ *
+ * @param {object|null|undefined} snapshot
+ * @param {string} [sceneKey]
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function evaluateContract(snapshot, sceneKey = DEFAULT_SCENE) {
+  const problems = [];
+  const warnings = [];
+  if (!snapshot || (!snapshot.hasPlayable && !snapshot.hasGame)) {
+    problems.push('window.__playable is not defined — publishPlayableRuntime() was never called');
+    return { ok: false, problems, warnings };
+  }
+  if (snapshot.gameStartShadowed) {
+    problems.push('window.__game.start shadows Phaser.Game.start — put harness start/autoPlay on window.__playable instead');
+  }
+  if (snapshot.hasPlayable) {
+    if (snapshot.playableAutoPlayType !== 'function') {
+      problems.push('window.__playable.autoPlay() must be a function');
+    }
+    if (snapshot.playableGetStateType !== 'function') {
+      problems.push('window.__playable.getState() must be a function');
+    }
+    if (snapshot.playableCurrentPhaseType !== 'string') {
+      problems.push('window.__playable.getState().currentPhase must be a PlayablePhase string');
+    } else if (snapshot.playableCurrentPhase !== 'HOOK') {
+      problems.push('window.__playable.getState().currentPhase must start at HOOK');
+    }
+    if (snapshot.playableIsGameOverType !== 'boolean') {
+      problems.push('window.__playable.getState().isGameOver must be a boolean');
+    }
+  } else {
+    warnings.push(
+      'Legacy scene contract in use — migrate to window.__playable via publishPlayableRuntime() (deprecation target: 2026-Q3)',
+    );
+    if (!snapshot.hasScene) {
+      problems.push(`scene "${sceneKey}" not found on window.__game`);
+      return { ok: false, problems, warnings };
+    }
+    if (!snapshot.hasSceneManager) {
+      problems.push('scene.sceneManager is missing');
+    } else {
+      if (snapshot.currentPhaseType !== 'string') {
+        problems.push('sceneManager.currentPhase must be a PlayablePhase string');
+      }
+      if (snapshot.isGameOverType !== 'function') {
+        problems.push('sceneManager.isGameOver() must be a function');
+      }
+    }
+    if (snapshot.onDebugAutoPlayType !== 'function') {
+      problems.push('scene._onDebugAutoPlay() must be a function');
+    }
+  }
+  return { ok: problems.length === 0, problems, warnings };
+}
+
+/** The function evaluated inside the page to snapshot the contract surface. */
+/* c8 ignore start — runs in the browser, not under node coverage */
+export function snapshotContractInPage(sceneKey) {
+  const playable = window.__playable;
+  const game = window.__game;
+  const gameStartShadowed = !!(
+    game &&
+    Object.prototype.hasOwnProperty.call(game, 'start') &&
+    Object.getPrototypeOf(game) &&
+    typeof Object.getPrototypeOf(game).start === 'function'
+  );
+  let playableState = null;
+  try {
+    playableState = playable && typeof playable.getState === 'function' ? playable.getState() : null;
+  } catch {
+    playableState = null;
+  }
+  if (playable) {
+    return {
+      hasPlayable: true,
+      hasGame: !!game,
+      gameStartShadowed,
+      playableAutoPlayType: typeof playable.autoPlay,
+      playableGetStateType: typeof playable.getState,
+      playableCurrentPhase: playableState ? playableState.currentPhase : undefined,
+      playableCurrentPhaseType: playableState ? typeof playableState.currentPhase : 'undefined',
+      playableIsGameOverType: playableState ? typeof playableState.isGameOver : 'undefined',
+    };
+  }
+  if (!game) return { hasPlayable: false, hasGame: false };
+  const scene = game.scene && game.scene.getScene ? game.scene.getScene(sceneKey) : null;
+  if (!scene) return { hasPlayable: false, hasGame: true, hasScene: false, gameStartShadowed };
+  const sm = scene.sceneManager;
+  return {
+    hasPlayable: false,
+    hasGame: true,
+    hasScene: true,
+    gameStartShadowed,
+    hasSceneManager: sm != null,
+    currentPhase: sm ? sm.currentPhase : undefined,
+    currentPhaseType: sm ? typeof sm.currentPhase : 'undefined',
+    isGameOverType: sm ? typeof sm.isGameOver : 'undefined',
+    onDebugAutoPlayType: typeof scene._onDebugAutoPlay,
+  };
+}
+/* c8 ignore stop */
+
+/**
+ * Boot the game and probe the runtime contract.
+ * @returns {Promise<{ ok: boolean, problems: string[], snapshot: object, url: string }>}
+ */
+export async function runContractProbe(opts) {
+  const { chromium } = await import('playwright');
+  const projectRoot = resolve(opts.root);
+  let server = null;
+  let browser = null;
+  let url = opts.url;
+  let external = false;
+
+  if (opts.url && !opts.useDev) {
+    external = true;
+  } 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();
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+
+    // Give the game a few seconds to boot and bind the contract, but fail fast.
+    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 && s.sceneManager && typeof s._onDebugAutoPlay === 'function');
+        },
+        opts.scene,
+        { timeout: opts.timeout },
+      )
+      .catch(() => {
+        /* tolerate — the snapshot below reports exactly what is missing */
+      });
+
+    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 result = evaluateContract(snapshot, opts.scene);
+    return { ...result, snapshot, url, external };
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    killServer();
+  }
+}
+
+function printHuman(result) {
+  console.log(`[verify:contract] ${result.ok ? 'OK' : 'BROKEN'} — ${result.url}`);
+  if (result.ok) {
+    const phase = result.snapshot?.currentPhase ?? result.snapshot?.playableCurrentPhase ?? '?';
+    console.log(`  contract satisfied (phase=${phase})`);
+    for (const w of result.warnings ?? []) console.log(`  ⚠ ${w}`);
+  } else {
+    for (const p of result.problems) console.log(`  ✗ ${p}`);
+    for (const w of result.warnings ?? []) console.log(`  ⚠ ${w}`);
+    console.log('  See game/runtime-contract.ts — record:mp4 / one-click clear depend on these hooks.');
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await runContractProbe(opts);
+  await writeValidatorArtifact(opts.root, 'contract', 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:contract] ${err.message}`);
+    process.exit(1);
+  });
+}