@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/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-templates/phaser/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();