@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/skills/_shared/scripts/verify-env.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * Environment pre-flight — checks the toolchain a playable project needs before
+ * the skills pipeline can run, so missing dependencies fail loudly instead of
+ * silently:
+ *   - node    >= 20  (required; engines.node)
+ *   - python3        (required; verify:ui + asset scripts — same bin as package.json)
+ *   - pillow, pyyaml, jsonschema (required; playable-verify-ui/requirements.txt)
+ *   - playwright chromium (optional; record:mp4 — warn only)
+ *
+ * Exit 0 = all required checks pass, 2 = a required check failed, 1 = error.
+ * With --strict, optional (warn) checks are also treated as failures.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/verify-env.mjs --root=.
+ *   node skills/_shared/scripts/verify-env.mjs --root=. --json
+ *   node skills/_shared/scripts/verify-env.mjs --root=. --strict
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const MIN_NODE_MAJOR = 20;
+
+/** Must match package.json scripts (`python3 skills/...`). */
+export const PYTHON_BIN = 'python3';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg === '--json') opts.json = true;
+    else if (arg === '--strict') opts.strict = true;
+  }
+  return opts;
+}
+
+/** @returns {string | null} Resolved python3 binary when `--version` succeeds. */
+export function resolvePythonBin() {
+  const proc = spawnSync(PYTHON_BIN, ['--version'], { encoding: 'utf8' });
+  if (proc.error || proc.status !== 0) return null;
+  return PYTHON_BIN;
+}
+
+/** @returns {{ name: string, required: boolean, status: 'pass'|'warn'|'fail', message: string }} */
+export function checkNode(currentVersion = process.versions.node) {
+  const major = Number(currentVersion.split('.')[0]);
+  const ok = Number.isFinite(major) && major >= MIN_NODE_MAJOR;
+  return {
+    name: 'node',
+    required: true,
+    status: ok ? 'pass' : 'fail',
+    message: ok
+      ? `node ${currentVersion} (>= ${MIN_NODE_MAJOR})`
+      : `node ${currentVersion} (< ${MIN_NODE_MAJOR} required — see engines.node)`,
+  };
+}
+
+export function checkPython() {
+  const bin = resolvePythonBin();
+  if (!bin) {
+    return {
+      name: 'python3',
+      required: true,
+      status: 'fail',
+      message:
+        'python3 not found — verify:ui and asset pipeline scripts will fail until Python 3 is installed',
+    };
+  }
+  const proc = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+  const ver = (proc.stdout || proc.stderr || '').trim();
+  return { name: 'python3', required: true, status: 'pass', message: `${ver} (${bin})` };
+}
+
+/**
+ * @param {string} checkName
+ * @param {string} importSnippet
+ * @param {string} installHint
+ */
+export function checkPythonModule(checkName, importSnippet, installHint) {
+  const bin = resolvePythonBin();
+  if (!bin) {
+    return {
+      name: checkName,
+      required: true,
+      status: 'fail',
+      message: `${checkName} not checked — python3 not found`,
+    };
+  }
+  const proc = spawnSync(bin, ['-c', importSnippet], { encoding: 'utf8' });
+  if (!proc.error && proc.status === 0) {
+    return {
+      name: checkName,
+      required: true,
+      status: 'pass',
+      message: `${checkName} importable via ${bin}`,
+    };
+  }
+  return {
+    name: checkName,
+    required: true,
+    status: 'fail',
+    message: `${checkName} missing for ${bin} — ${installHint}`,
+  };
+}
+
+export function checkPillow() {
+  return checkPythonModule(
+    'pillow',
+    'from PIL import Image',
+    'pip install Pillow (see skills/playable-verify-ui/requirements.txt)',
+  );
+}
+
+export function checkPyYaml() {
+  return checkPythonModule(
+    'pyyaml',
+    'import yaml',
+    'pip install pyyaml (see skills/playable-verify-ui/requirements.txt)',
+  );
+}
+
+export function checkJsonschema() {
+  return checkPythonModule(
+    'jsonschema',
+    'import jsonschema',
+    'pip install jsonschema (see skills/playable-verify-ui/requirements.txt)',
+  );
+}
+
+/**
+ * OCR toolchain for verify:text-overlap. Optional (warn) because the system
+ * `tesseract` binary is heavy and not needed by other gates — but the
+ * text-overlap gate fails under --strict when it is absent.
+ */
+export function checkOcr() {
+  const bin = resolvePythonBin();
+  if (!bin) {
+    return {
+      name: 'ocr-tesseract',
+      required: false,
+      status: 'warn',
+      message: 'OCR not checked — python3 not found',
+    };
+  }
+  const proc = spawnSync(
+    bin,
+    ['-c', 'import pytesseract; pytesseract.get_tesseract_version()'],
+    { encoding: 'utf8' },
+  );
+  if (!proc.error && proc.status === 0) {
+    return { name: 'ocr-tesseract', required: false, status: 'pass', message: 'pytesseract + tesseract available' };
+  }
+  return {
+    name: 'ocr-tesseract',
+    required: false,
+    status: 'warn',
+    message:
+      'OCR missing — verify:text-overlap is DEGRADED. Install pytesseract (requirements.txt) + the tesseract binary (brew/apt install tesseract)',
+  };
+}
+
+/**
+ * @deprecated Vision evidence uses Pillow only; kept for callers that still probe legacy extras.
+ */
+export function checkVisionExtras() {
+  const bin = resolvePythonBin();
+  if (!bin) {
+    return {
+      name: 'vision-supervision',
+      required: false,
+      status: 'warn',
+      message: 'vision evidence not checked — python3 not found',
+    };
+  }
+  const proc = spawnSync(
+    bin,
+    ['-c', 'import supervision; import cv2'],
+    { encoding: 'utf8' },
+  );
+  if (!proc.error && proc.status === 0) {
+    return {
+      name: 'vision-supervision',
+      required: false,
+      status: 'pass',
+      message: 'supervision + opencv-python-headless available for verify:vision',
+    };
+  }
+  return {
+    name: 'vision-supervision',
+    required: false,
+    status: 'warn',
+    message:
+      'vision evidence DEGRADED — install with `pip install -r skills/playable-verify-ui/requirements-vision.txt`',
+  };
+}
+
+export function checkPlaywrightChromium(projectRoot) {
+  let chromium;
+  try {
+    const require = createRequire(join(resolve(projectRoot), 'package.json'));
+    ({ chromium } = require('playwright'));
+  } catch {
+    return {
+      name: 'playwright-chromium',
+      required: false,
+      status: 'warn',
+      message: 'playwright not installed yet — run `npm install` (record:mp4 needs it)',
+    };
+  }
+  try {
+    const exe = chromium.executablePath();
+    if (exe && existsSync(exe)) {
+      return { name: 'playwright-chromium', required: false, status: 'pass', message: 'Chromium browser available' };
+    }
+  } catch {
+    /* executablePath throws when the browser is not installed */
+  }
+  return {
+    name: 'playwright-chromium',
+    required: false,
+    status: 'warn',
+    message: 'Chromium browser not installed — run `npm run record:mp4:install`',
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ playwright?: boolean }} [opts]
+ * @returns {{ ok: boolean, root: string, checks: Array<{ name: string, required: boolean, status: 'pass'|'warn'|'fail', message: string }> }}
+ *   `ok` is true when no required check failed.
+ */
+export function checkEnv(projectRoot, opts = {}) {
+  const root = resolve(projectRoot);
+  const checks = [
+    checkNode(),
+    checkPython(),
+    checkPillow(),
+    checkPyYaml(),
+    checkJsonschema(),
+    checkOcr(),
+  ];
+  if (opts.playwright !== false) checks.push(checkPlaywrightChromium(root));
+  const ok = !checks.some((c) => c.required && c.status === 'fail');
+  return { ok, root, checks };
+}
+
+function printHuman(result) {
+  console.log(`[verify:env] ${result.ok ? 'OK' : 'BLOCKED'} — ${result.root}`);
+  for (const c of result.checks) {
+    const mark = c.status === 'pass' ? '✓' : c.status === 'warn' ? '!' : '✗';
+    const tag = c.required ? '' : ' (optional)';
+    console.log(`  [${mark}] ${c.name}${tag}: ${c.message}`);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = checkEnv(opts.root);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  const requiredFailed = !result.ok;
+  const warned = result.checks.some((c) => c.status === 'warn');
+  if (requiredFailed) process.exit(2);
+  if (opts.strict && warned) process.exit(2);
+  process.exit(0);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`[verify:env] ${err.message}`);
+    process.exit(1);
+  }
+}

package/project-template-v2/skills/_shared/scripts/verify-placeholders.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Placeholder asset verifier (growth-rings ring 1-3 build DoD).
+ *
+ * Enforces the "placeholder-first" rule: visual entities must be backed by real
+ * placeholder image files on disk, not drawn entirely with code (Phaser Graphics
+ * fillRect / fillStyle). Placeholders are the hook for later visual production —
+ * skipping them means later stages cannot tell what an asset should look like.
+ *
+ * Checks:
+ *  1. Every `this.load.image/atlas/spritesheet/audio/...(key, '<path>')` path
+ *     referenced in game/** resolves to a file on disk (no silent 404s / no
+ *     "declared but never generated" assets).
+ *  2. assets/images/ contains at least one real image file (.webp/.png/.jpg) —
+ *     a project with zero placeholder images is rejected as code-draw-only.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/verify-placeholders.mjs --root=.
+ *   npm run verify:placeholders
+ *
+ * Exit 0 = pass, 2 = fail
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeValidatorArtifact } from './lib/validator-artifacts.mjs';
+
+const LOADER_METHODS = [
+  'image',
+  'atlas',
+  'spritesheet',
+  'audio',
+  'bitmapFont',
+  'aseprite',
+  'svg',
+  'video',
+  'multiatlas',
+  'unityAtlas',
+];
+
+const IMAGE_EXT = /\.(webp|png|jpe?g|gif|svg|avif)$/i;
+const ASSET_EXT = /\.(webp|png|jpe?g|gif|svg|avif|mp3|ogg|wav|m4a|aac|json|xml|fnt|atlas|mp4|webm)$/i;
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd() };
+  for (let i = 2; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith('--root=')) opts.root = token.slice('--root='.length);
+    else if (token.startsWith('--project=')) opts.root = token.slice('--project='.length);
+    else if (token === '--root' || token === '--project') {
+      opts.root = argv[i + 1] || opts.root;
+      i += 1;
+    }
+  }
+  return opts;
+}
+
+function walkFiles(dir, filter, depth = 8, acc = []) {
+  if (depth < 0 || !fs.existsSync(dir)) return acc;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name.startsWith('.') && ent.isDirectory()) continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      if (ent.name === 'node_modules') continue;
+      walkFiles(full, filter, depth - 1, acc);
+    } else if (ent.isFile() && filter(ent.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+/** Extract quoted string-literal asset paths from load.* calls in source code. */
+function extractLoadPaths(source) {
+  const paths = new Set();
+  const methodAlt = LOADER_METHODS.join('|');
+  const callRe = new RegExp(`\\.load\\.(?:${methodAlt})\\s*\\(([^)]*)\\)`, 'g');
+  let m;
+  while ((m = callRe.exec(source)) !== null) {
+    const argBlob = m[1];
+    // capture single- or double-quoted literals only (skip template/var args)
+    for (const lit of argBlob.matchAll(/['"]([^'"]+)['"]/g)) {
+      const raw = lit[1].trim();
+      if (!raw) continue;
+      if (/^(https?:)?\/\//i.test(raw)) continue; // remote URL (flagged elsewhere)
+      if (raw.startsWith('data:')) continue;
+      if (raw.includes('${')) continue;
+      // must look like an asset path: has an asset extension OR sits under a dir
+      if (!ASSET_EXT.test(raw) && !raw.includes('/')) continue;
+      paths.add(raw);
+    }
+  }
+  return [...paths];
+}
+
+/** Resolve a referenced asset path against likely disk roots. */
+function resolveAssetPath(root, rel) {
+  const clean = rel.replace(/^\.?\//, '').split('?')[0].split('#')[0];
+  const candidates = [
+    path.join(root, clean),
+    path.join(root, 'public', clean),
+    path.join(root, 'assets', clean),
+  ];
+  return candidates.some((c) => fs.existsSync(c));
+}
+
+function main() {
+  return mainAsync().catch((err) => {
+    console.error(`[verify:placeholders] ${err.message}`);
+    process.exit(1);
+  });
+}
+
+async function mainAsync() {
+  const { root: rawRoot } = parseArgs(process.argv);
+  const root = path.resolve(rawRoot);
+  const failures = [];
+
+  const gameDir = path.join(root, 'game');
+  const referenced = new Set();
+  if (fs.existsSync(gameDir)) {
+    const sources = walkFiles(gameDir, (name) => /\.(ts|js|mjs|cjs)$/i.test(name));
+    for (const file of sources) {
+      const content = fs.readFileSync(file, 'utf8');
+      for (const p of extractLoadPaths(content)) referenced.add(p);
+    }
+  }
+
+  const missing = [];
+  for (const rel of referenced) {
+    if (!resolveAssetPath(root, rel)) missing.push(rel);
+  }
+  for (const rel of missing) {
+    failures.push(`referenced asset missing on disk: ${rel} (declared in game/ load.* but not generated — run npm run placeholder:gen)`);
+  }
+
+  const imagesDir = path.join(root, 'assets', 'images');
+  const imageFiles = walkFiles(imagesDir, (name) => IMAGE_EXT.test(name));
+  if (imageFiles.length === 0) {
+    failures.push(
+      'no placeholder images found under assets/images/ — Ring 1 onward requires real placeholder art (load playable-placeholder skill → npm run placeholder:gen), not code-drawn shapes (Graphics.fillStyle/fillRect)',
+    );
+  }
+
+  const result = {
+    ok: failures.length === 0,
+    referencedAssetCount: referenced.size,
+    placeholderImageCount: imageFiles.length,
+    missing,
+    failures,
+  };
+  await writeValidatorArtifact(root, 'placeholders', result).catch(() => {});
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (result.ok) {
+    process.stdout.write(
+      `[verify:placeholders] OK — ${imageFiles.length} placeholder image(s), ${referenced.size} referenced asset(s) all present\n`,
+    );
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+main();

package/project-template-v2/skills/playable-autoplay/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: playable-autoplay
+description: >-
+  Methodology for implementing playable autoPlay / firstwin harness. Use when a
+  developer receives firstwin-harness, must make window.__playable.autoPlay()
+  drive real player-equivalent actions to ENDCARD, or must debug an autoplay path
+  without cheating through direct terminal-state writes.
+---
+
+# Playable Autoplay Harness
+
+Use this when the task is to make a runnable playable prove first win through
+`window.__playable.autoPlay()` and `npm run verify:firstwin`.
+
+This skill describes **how to implement the path**. Related validation/debug
+skills:
+
+- `playable-record` — runtime contract, `verify:contract`, `verify:firstwin`, and MP4 (MPEG-4 Part 14, 数字多媒体容器格式) recording.
+- `playable-debug` — debug-gated button / one-click entry troubleshooting.
+- `playable-validate` — full validation loop across contract, firstwin, fusion, recording, and video review.
+
+## Goal
+
+`autoPlay()` is a scriptable player, not a win button. It should observe the
+current game state, choose legal player-equivalent actions, execute them through
+the same input/controller path a human uses, wait for state to settle, and repeat
+until the normal game rules reach `ENDCARD`.
+
+## Implementation Method
+
+### 1. Reconstruct the player path
+
+Read `docs/design.md` and current `game/**`, then write down the real path:
+
+- Initial phase and ready condition.
+- Core action: tap, drag, release, aim, fire, select, swap, match, move, etc.
+- Feedback/state change after each action.
+- Progress metric and normal win condition.
+- What state means the game is settled and the next action is safe.
+
+If this path cannot be stated, stop and report a blocker. Do not invent a new
+win path inside autoplay.
+
+### 2. Expose player-equivalent action adapters
+
+Prefer using existing handlers. If needed, add thin adapters around real input
+logic:
+
+```ts
+tapTarget(targetId);
+beginDrag(pieceId);
+moveDrag(x, y);
+releaseDrag(x, y);
+selectTile(tileId);
+fireAt(targetId);
+```
+
+Adapters may normalize coordinates or IDs, but must call the same rule checks,
+state transitions, collision/match logic, feedback triggers, and progress
+updates used by manual play.
+
+Do not put autoplay-only branches in gameplay rules. If an adapter needs a
+shortcut to pass, the real player path is not implemented enough.
+
+### 3. Build observe-plan-act-wait
+
+Implement `autoPlay()` as a deterministic loop:
+
+```ts
+async function autoPlay() {
+  await waitUntilReady();
+  for (let step = 0; step < MAX_STEPS; step += 1) {
+    const state = getState();
+    if (state.isGameOver && state.currentPhase === 'ENDCARD') return;
+
+    const action = chooseNextLegalAction(state);
+    if (!action) throw new Error('autoPlay: no legal next action');
+
+    await performPlayerEquivalentAction(action);
+    await waitForSettle();
+  }
+  throw new Error('autoPlay: max steps exceeded');
+}
+```
+
+Selection should be deterministic for repeatability: sort candidate targets,
+choose the first legal move, or use a fixed seed. Avoid time-random behavior.
+
+### 4. Publish the harness
+
+Expose the neutral runtime contract:
+
+```ts
+window.__playable = {
+  autoPlay,
+  getState,
+  getCanvas, // optional
+  hideDebugUi, // optional
+};
+```
+
+`getState()` must return at least:
+
+```ts
+{
+  currentPhase: 'HOOK' | 'PLAYING' | 'ENDCARD',
+  isGameOver: boolean,
+}
+```
+
+Add useful non-production debug fields only if they help diagnose progress, such
+as `progress`, `step`, `lastAction`, or `remainingTargets`.
+
+### 5. Wire a debug-gated trigger
+
+The firstwin probe opens the page with `?debug=1` and clicks
+`#playable-debug-clear`. Mount a visible button under `?debug=1`, wire its click
+to `window.__playable.autoPlay()`, and keep it absent without `?debug=1`.
+
+Use `playable-debug` if the button is missing, hidden, incorrectly positioned, or
+not connected to `autoPlay()`.
+
+## Anti-Cheat Rules
+
+`autoPlay()` and its helpers must not:
+
+- Set `currentPhase = 'ENDCARD'` directly.
+- Set `isGameOver = true` directly.
+- Call `forceWin()`, `showWinScreen()`, or equivalent direct-win helpers.
+- Delete all obstacles / targets without using normal rules.
+- Add hidden win conditions only reachable by autoplay.
+- Skip required tutorial, matching, collision, collection, or scoring logic by
+  mutating final state.
+
+It may skip non-gameplay waiting, intro delay, or tutorial text only when the
+underlying playable rules still execute through player-equivalent actions.
+
+## Validation Order
+
+Run fast-to-slow:
+
+```bash
+npm run verify:contract
+npm run verify:firstwin -- --timeout=15000
+npm run verify:firstwin
+npm run verify:fusion
+npm run record:mp4 -- --headed --fps=60
+```
+
+Use `playable-record` for what each verifier proves and artifact paths. Use
+`playable-validate` when the task asks for the complete validation loop or video
+evidence.
+
+## Failure Triage
+
+- `window.__playable.autoPlay()` missing: publish the runtime contract first.
+- Debug button missing under `?debug=1`: use `playable-debug`; mount
+  `#playable-debug-clear`.
+- Button visible without `?debug=1`: gate it; it must not leak into production or
+  recording.
+- Timeout with unchanged state: add state/progress fields to `getState()` and
+  inspect which wait/action is stuck.
+- No legal action: the planner cannot see the same candidates a player can; fix
+  observation or expose a real controller adapter.
+- Firstwin passes but manual play fails: reject the implementation; autoplay is
+  bypassing the real path.
+
+## Handoff Evidence
+
+In handoff, report:
+
+- Player path summarized as action → feedback → progress → win.
+- Which adapter(s) `autoPlay()` uses.
+- `verify:contract` result.
+- `verify:firstwin` result and artifact path.
+- Any remaining blocker that affects manual play or recording.

package/project-template-v2/skills/playable-autoplay/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Playable Autoplay Harness'
+  short_description: 'Implement autoPlay through real player-equivalent actions.'
+  default_prompt: 'Implement or debug a playable autoPlay / firstwin harness without direct-win shortcuts.'