@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/_shared/scripts/sync-template-skills.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Sync whitelisted skills from monorepo skills/ into template/skills/.
+ * Preserves template/skills/README.md (template-specific index).
+ */
+
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = resolve(__dirname, '../..');
+const REPO_ROOT = resolve(SKILLS_ROOT, '..');
+const TEMPLATE_ROOT = join(REPO_ROOT, 'template');
+const TEMPLATE_SKILLS = join(TEMPLATE_ROOT, 'skills');
+const README_PATH = join(TEMPLATE_SKILLS, 'README.md');
+
+const WHITELIST = [
+  '_shared',
+  'playable-animate',
+  'playable-art',
+  'playable-debug',
+  'playable-focus',
+  'playable-fx-decompose',
+  'playable-fx-peak',
+  'playable-record',
+  'playable-validate',
+  'playable-verify-ui',
+];
+
+const LEGACY_DIRS = [
+  'playable-animation-polish',
+  'playable-decompose-fx',
+  'playable-debug-playback',
+  'playable-focus-playground',
+  'playable-frame-fx-peak-pipeline',
+  'playable-gpt-art-pipeline',
+  'playable-gpt-fx-frame-animation',
+  'playable-record-playback',
+  'playable-ui-optimization',
+  'playable-ui-regression-checklist',
+  'playable-ui-reference-matching',
+  'playable-frame-text-layout',
+  'playable-single-html-bundle',
+  'playable-performance-interaction',
+  'playable-video-validate-loop',
+];
+
+const EXCLUDE = new Set(['node_modules', '__pycache__', '.DS_Store']);
+
+async function copyDir(src, dest) {
+  await mkdir(dest, { recursive: true });
+  await cp(src, dest, {
+    recursive: true,
+    filter: (name) => !EXCLUDE.has(name.split('/').pop()),
+  });
+}
+
+/**
+ * Keep template/ in a clean, un-bootstrapped state.
+ * ensure-project / create-playable will bootstrap focus-lab and playground
+ * on first use, so we do not ship stale generated files in the template.
+ */
+async function cleanTemplateBootstrapArtifacts() {
+  const playgroundDir = join(TEMPLATE_ROOT, 'playground');
+  const focusLabDir = join(TEMPLATE_ROOT, 'focus-lab');
+
+  for (const file of ['registry.json', 'vfx-catalog.json']) {
+    await rm(join(playgroundDir, file), { force: true });
+  }
+
+  try {
+    const entries = await readdir(focusLabDir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.name === '.gitkeep') continue;
+      await rm(join(focusLabDir, ent.name), { recursive: true, force: true });
+    }
+  } catch {
+    /* focus-lab may not exist */
+  }
+}
+
+async function main() {
+  let readme = '';
+  try {
+    readme = await readFile(README_PATH, 'utf8');
+  } catch {
+    /* ok */
+  }
+
+  for (const name of LEGACY_DIRS) {
+    await rm(join(TEMPLATE_SKILLS, name), { recursive: true, force: true });
+  }
+
+  for (const name of WHITELIST) {
+    const src = join(SKILLS_ROOT, name);
+    const dest = join(TEMPLATE_SKILLS, name);
+    await rm(dest, { recursive: true, force: true });
+    await copyDir(src, dest);
+    console.log(`  + ${name}`);
+  }
+
+  if (readme) await writeFile(README_PATH, readme, 'utf8');
+
+  await cleanTemplateBootstrapArtifacts();
+  console.log('[sync-template-skills] done →', TEMPLATE_SKILLS);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/project-templates/phaser/skills/_shared/scripts/verify-asset-code-sync.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * Asset ↔ code consistency gate (Ring 4).
+ *
+ * Checks:
+ *  1. assets/images/tiles/* filenames match TILE_KEYS (or similar) in game code
+ *  2. load.image / load.atlas paths in game/** resolve on disk
+ *  3. Orphan tiles on disk not referenced in code → fail
+ *  4. Optional assets/asset-manifest.json runtime assets are wired in game code
+ *
+ * Exit 0 = pass, 2 = fail
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  let root = process.cwd();
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--root' || argv[i] === '--project') {
+      root = argv[i + 1] || root;
+      i += 1;
+    } else if (argv[i].startsWith('--root=')) {
+      root = argv[i].slice('--root='.length);
+    }
+  }
+  return { root: path.resolve(root) };
+}
+
+function walkTsFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) walkTsFiles(full, out);
+    else if (/\.(ts|js|tsx|jsx)$/.test(name)) out.push(full);
+  }
+  return out;
+}
+
+function extractTileKeys(content) {
+  const keys = new Set();
+  const arrayMatch = content.match(/TILE_KEYS\s*=\s*\[([\s\S]*?)\]/);
+  if (arrayMatch) {
+    for (const m of arrayMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
+      keys.add(m[1]);
+    }
+  }
+  const constMatch = content.match(/const\s+TILE_KEYS\s*:\s*[^=]*=\s*\[([\s\S]*?)\]/);
+  if (constMatch) {
+    for (const m of constMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
+      keys.add(m[1]);
+    }
+  }
+  return keys;
+}
+
+function extractLoadPaths(content) {
+  const paths = new Set();
+  const re =
+    /this\.load\.(?:image|atlas|spritesheet|audio|bitmapFont)\(\s*['"][^'"]+['"]\s*,\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    paths.add(m[1].replace(/^\//, ''));
+  }
+  return paths;
+}
+
+function normalizeRelPath(rel) {
+  return String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}
+
+function pathWithoutAssets(rel) {
+  return normalizeRelPath(rel).replace(/^assets\//, '');
+}
+
+function assetStem(rel) {
+  return path.basename(normalizeRelPath(rel), path.extname(rel));
+}
+
+function loadPathMatches(loadPath, manifestPath) {
+  const load = normalizeRelPath(loadPath);
+  const manifest = normalizeRelPath(manifestPath);
+  return load === manifest || load === pathWithoutAssets(manifest) || load.endsWith(`/${pathWithoutAssets(manifest)}`);
+}
+
+function sourceReferencesAsset(source, manifestPath) {
+  const rel = normalizeRelPath(manifestPath);
+  const noAssets = pathWithoutAssets(rel);
+  const base = path.basename(rel);
+  const stem = assetStem(rel);
+  return (
+    source.includes(rel) ||
+    source.includes(noAssets) ||
+    source.includes(base) ||
+    (stem.length >= 3 && source.includes(stem))
+  );
+}
+
+function tileKeyMatchesAsset(tileKeys, manifestPath) {
+  const stem = assetStem(manifestPath);
+  const normalized = stem.replace(/^tile_/, '');
+  return [...tileKeys].some(
+    (key) => key === stem || key === normalized || stem.endsWith(`_${key}`) || stem === `tile_${key}`,
+  );
+}
+
+function resolveAssetPath(root, rel) {
+  const candidates = [
+    path.join(root, rel),
+    path.join(root, 'assets', rel.replace(/^assets\//, '')),
+    path.join(root, 'public', rel),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function readAssetManifest(root, failures) {
+  const manifestPath = path.join(root, 'assets/asset-manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (err) {
+    failures.push(`asset-manifest.json invalid JSON: ${err.message}`);
+    return null;
+  }
+
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    failures.push('asset-manifest.json top-level must be an object');
+    return null;
+  }
+  if (!manifest.assets || typeof manifest.assets !== 'object' || Array.isArray(manifest.assets)) {
+    failures.push('asset-manifest.json: assets must be an object keyed by numericId');
+    return null;
+  }
+
+  return manifest;
+}
+
+function validateManifestRuntimeAssets(root, manifest, sourceText, loadPaths, tileKeys, failures) {
+  if (!manifest) return;
+
+  const allowedUsage = new Set(['runtime', 'reference-only']);
+  for (const [id, entry] of Object.entries(manifest.assets || {})) {
+    if (!/^\d+$/.test(String(id))) {
+      failures.push(`asset-manifest.json: asset key "${id}" is not a numericId`);
+    }
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      failures.push(`asset-manifest.json: asset ${id} must be an object`);
+      continue;
+    }
+
+    const rel = normalizeRelPath(entry.path);
+    const usage = entry.usage || 'runtime';
+    if (!allowedUsage.has(usage)) {
+      failures.push(`asset-manifest.json: asset ${id} usage "${usage}" must be runtime or reference-only`);
+    }
+    if (!rel) {
+      failures.push(`asset-manifest.json: asset ${id} missing path`);
+      continue;
+    }
+    if (!resolveAssetPath(root, rel)) {
+      failures.push(`asset-manifest.json: asset ${id} path missing on disk: ${rel}`);
+      continue;
+    }
+
+    const loaded = [...loadPaths].some((loadPath) => loadPathMatches(loadPath, rel));
+    const referenced = sourceReferencesAsset(sourceText, rel);
+    const tileMatched = entry.role === 'tile' && tileKeyMatchesAsset(tileKeys, rel);
+
+    if (usage === 'reference-only') {
+      if (loaded) {
+        failures.push(`Runtime load references reference-only manifest asset ${id}: ${rel}`);
+      }
+      continue;
+    }
+
+    if (!loaded && !referenced && !tileMatched) {
+      failures.push(`Runtime manifest asset ${id} is not referenced by game code: ${rel}`);
+    }
+  }
+}
+
+function listTileFiles(root) {
+  const dir = path.join(root, 'assets/images/tiles');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => /\.(webp|png|jpg)$/i.test(f))
+    .map((f) => path.basename(f, path.extname(f)));
+}
+
+function main() {
+  const { root } = parseArgs(process.argv);
+  const failures = [];
+  const gameDir = path.join(root, 'game');
+
+  const tileKeys = new Set();
+  const loadPaths = new Set();
+  const sourceChunks = [];
+  for (const file of walkTsFiles(gameDir)) {
+    const content = fs.readFileSync(file, 'utf8');
+    sourceChunks.push(content);
+    for (const k of extractTileKeys(content)) tileKeys.add(k);
+    for (const p of extractLoadPaths(content)) loadPaths.add(p);
+  }
+  const sourceText = sourceChunks.join('\n');
+
+  const tileFiles = listTileFiles(root);
+  if (tileKeys.size > 0 && tileFiles.length > 0) {
+    for (const key of tileKeys) {
+      const hasFile = tileFiles.some((f) => f === key || f === `tile_${key}` || f.endsWith(`_${key}`));
+      if (!hasFile) {
+        failures.push(`TILE_KEYS contains "${key}" but no matching file under assets/images/tiles/`);
+      }
+    }
+    for (const file of tileFiles) {
+      const normalized = file.replace(/^tile_/, '');
+      const matched = [...tileKeys].some(
+        (k) => k === file || k === normalized || file.endsWith(`_${k}`) || file === `tile_${k}`,
+      );
+      if (!matched) {
+        failures.push(`Orphan tile asset "${file}" not referenced in TILE_KEYS`);
+      }
+    }
+  }
+
+  for (const rel of loadPaths) {
+    if (!resolveAssetPath(root, rel)) {
+      failures.push(`game load path missing on disk: ${rel}`);
+    }
+  }
+
+  const referencesDir = path.join(root, 'assets/references');
+  if (fs.existsSync(referencesDir)) {
+    for (const rel of loadPaths) {
+      if (rel.includes('assets/references/') || rel.includes('references/')) {
+        failures.push(`Runtime load references reference-only asset: ${rel}`);
+      }
+    }
+  }
+
+  const manifest = readAssetManifest(root, failures);
+  validateManifestRuntimeAssets(root, manifest, sourceText, loadPaths, tileKeys, failures);
+
+  const ok = failures.length === 0;
+  const result = {
+    ok,
+    tileKeyCount: tileKeys.size,
+    tileFileCount: tileFiles.length,
+    loadPathCount: loadPaths.size,
+    manifestAssetCount: manifest ? Object.keys(manifest.assets || {}).length : 0,
+    failures,
+  };
+  console.log(JSON.stringify(result, null, 2));
+  if (ok) {
+    process.stderr.write('OK verify:asset-code-sync\n');
+  }
+  process.exit(ok ? 0 : 2);
+}
+
+main();

package/project-templates/phaser/skills/_shared/scripts/verify-atom-conformance.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Atom-tree → on-disk conformance verifier (growth-rings ring 4 DoD).
+ *
+ * Checks:
+ *  1. docs/atom-tree.json meta.selectedAtoms — each selected atom is materialized (linked skill dir or scaffold-manifest entry)
+ *  2. atom-tree declared atom refs are covered by selected/materialized atoms
+ *  2. docs/layout-spec.md assetMapping paths — each referenced asset file exists on disk
+ *
+ * Usage: node skills/_shared/scripts/verify-atom-conformance.mjs [--project <dir>]
+ * Exit 0 = pass, 2 = fail
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const opts = { project: process.cwd() };
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--project') {
+      opts.project = argv[i + 1] || opts.project;
+      i += 1;
+    }
+  }
+  return opts;
+}
+
+function readJsonSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectTreeAtomRefs(value, refs = new Set()) {
+  if (!value || typeof value !== 'object') return refs;
+  if (Array.isArray(value)) {
+    for (const item of value) collectTreeAtomRefs(item, refs);
+    return refs;
+  }
+  const atom = value.atom;
+  if (typeof atom === 'string') refs.add(atom);
+  else if (atom && typeof atom === 'object') {
+    if (typeof atom.id === 'string') refs.add(atom.id);
+    if (typeof atom.substitute === 'string') refs.add(atom.substitute);
+  }
+  for (const child of Object.values(value)) collectTreeAtomRefs(child, refs);
+  return refs;
+}
+
+function extractAssetPathsFromLayoutSpec(content) {
+  const paths = new Set();
+  // assetMapping table rows: | id | path | ...
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 2) continue;
+    if (/^id$/i.test(parts[0]) || /^---/.test(parts[0])) continue;
+    const candidate = parts[1];
+    if (/^(assets\/|images\/|audio\/)/.test(candidate) || candidate.includes('/')) {
+      if (!candidate.includes('{{')) paths.add(candidate.replace(/^\//, ''));
+    }
+  }
+  // inline paths assets/...
+  for (const m of content.matchAll(/`(assets\/[^`]+)`/g)) {
+    paths.add(m[1]);
+  }
+  return [...paths];
+}
+
+function parseScaffoldManifest(content) {
+  const atoms = new Set();
+  for (const line of content.split('\n')) {
+    const m = line.match(/\|\s*([^\s|]+\.aigameplay[^\s|]*|[^\s|]+\.aiconfig[^\s|]*)\s*\|/i);
+    if (m) atoms.add(m[1].trim());
+  }
+  return atoms;
+}
+
+function main() {
+  const { project } = parseArgs(process.argv);
+  const root = path.resolve(project);
+  const failures = [];
+
+  const atomTreePath = path.join(root, 'docs/atom-tree.json');
+  const atomTree = readJsonSafe(atomTreePath);
+  if (!atomTree) {
+    process.stderr.write('Missing or invalid docs/atom-tree.json\n');
+    process.exit(2);
+  }
+
+  const atoms = Array.isArray(atomTree?.meta?.selectedAtoms) ? atomTree.meta.selectedAtoms : [];
+  if (atoms.length === 0) {
+    failures.push('atom-tree.json: meta.selectedAtoms is empty');
+  }
+
+  const scaffoldPath = path.join(root, 'docs/scaffold-manifest.md');
+  const scaffoldAtoms = fs.existsSync(scaffoldPath)
+    ? parseScaffoldManifest(fs.readFileSync(scaffoldPath, 'utf8'))
+    : new Set();
+
+  for (const atom of atoms) {
+    const skillRef = String(atom).trim();
+    if (!skillRef || skillRef.includes('{{')) continue;
+    const linkedDir = path.join(root, '.claude/skills', skillRef);
+    const hasLinked = fs.existsSync(linkedDir);
+    const hasScaffold = scaffoldAtoms.has(skillRef);
+    const gameGlob = path.join(root, 'game');
+    let referencedInGame = false;
+    if (fs.existsSync(gameGlob)) {
+      // lightweight: skill ref basename appears somewhere under game/
+      const needle = skillRef.split('/').pop() || skillRef;
+      referencedInGame = walkIncludes(gameGlob, needle, 3);
+    }
+    if (!hasLinked && !hasScaffold && !referencedInGame) {
+      failures.push(`atom "${skillRef}" not materialized (no .claude/skills link, scaffold-manifest, or game reference)`);
+    }
+  }
+
+  const declaredRefs = collectTreeAtomRefs({
+    engine: atomTree.engine,
+    remixSpec: atomTree?.meta?.remixSpec,
+    globals: atomTree.globals,
+    scenes: atomTree.scenes,
+    review: atomTree.review,
+  });
+  const selectedSet = new Set(atoms.map((atom) => String(atom).trim()).filter(Boolean));
+  for (const ref of declaredRefs) {
+    if (ref.includes('{{')) continue;
+    if (selectedSet.has(ref)) continue;
+    const linkedDir = path.join(root, '.claude/skills', ref);
+    const hasLinked = fs.existsSync(linkedDir);
+    if (!hasLinked) {
+      failures.push(`atom-tree declared atom "${ref}" is not selected or linked`);
+    }
+  }
+
+  const layoutPath = path.join(root, 'docs/layout-spec.md');
+  if (fs.existsSync(layoutPath)) {
+    const layoutContent = fs.readFileSync(layoutPath, 'utf8');
+    const assetPaths = extractAssetPathsFromLayoutSpec(layoutContent);
+    for (const rel of assetPaths) {
+      const abs = path.join(root, rel.startsWith('assets/') ? rel : `assets/${rel}`);
+      if (!fs.existsSync(abs)) {
+        failures.push(`assetMapping path missing on disk: ${rel}`);
+      }
+    }
+  } else {
+    failures.push('docs/layout-spec.md missing (required for ring 4 atom conformance)');
+  }
+
+  const result = {
+    ok: failures.length === 0,
+    checkedAtoms: atoms.length,
+    declaredAtoms: declaredRefs.size,
+    failures,
+  };
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(result.ok ? 0 : 2);
+}
+
+function walkIncludes(dir, needle, depth) {
+  if (depth <= 0) return false;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (walkIncludes(full, needle, depth - 1)) return true;
+    } else if (entry.isFile() && /\.(ts|js|html|json|md)$/i.test(entry.name)) {
+      const text = fs.readFileSync(full, 'utf8');
+      if (text.includes(needle)) return true;
+    }
+  }
+  return false;
+}
+
+main();