@playcraft/cli 0.1.40-beta → 0.1.42

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

@@ -1,285 +0,0 @@
-#!/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

@@ -1,161 +0,0 @@
-#!/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

@@ -1,176 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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.'