@playcraft/cli 0.0.43 → 0.0.46

package/project-template/skills/_shared/scripts/harness-smoke.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * Harness self-test — the playable harness's own regression check.
+ *
+ * Confirms the deterministic, offline guarantees a project must always hold so
+ * the recording/debug feedback loop stays trustworthy:
+ *   1. runtime contract — game/ still exposes the recorder/debug hooks (static)
+ *   2. game-config     — the single-source config loads and looks sane
+ *   3. (--full) verify:ui — the full static suite passes (needs python3)
+ *   4. (--live) verify:contract — boots the game and probes the contract at
+ *               runtime (needs a server + Playwright Chromium)
+ *
+ * Exit 0 = healthy, 2 = harness broken, 1 = unexpected error.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/harness-smoke.mjs --root=.
+ *   node skills/_shared/scripts/harness-smoke.mjs --root=. --full
+ *   node skills/_shared/scripts/harness-smoke.mjs --root=. --live
+ *   node skills/_shared/scripts/harness-smoke.mjs --root=. --json
+ */
+
+import { access, readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = resolve(__dirname, '../..');
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), full: false, live: false, json: 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 === '--full') opts.full = true;
+    else if (arg === '--live') opts.live = true;
+    else if (arg === '--json') opts.json = true;
+  }
+  return opts;
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Resolve a verify-ui lib, preferring the project's own copy, then the template's. */
+function resolveLib(projectRoot, relFromScripts) {
+  const candidates = [
+    join(projectRoot, 'skills/playable-verify-ui/scripts', relFromScripts),
+    join(SKILLS_ROOT, 'playable-verify-ui/scripts', relFromScripts),
+  ];
+  for (const c of candidates) {
+    try {
+      require.resolve(c);
+      return c;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+async function checkRuntimeContract(projectRoot) {
+  const libPath = resolveLib(projectRoot, 'lib/runtime_contract.js');
+  if (!libPath) {
+    return { name: 'runtime-contract', status: 'skip', message: 'scanner not found' };
+  }
+  const { scanRuntimeContract } = require(libPath);
+  const res = scanRuntimeContract(projectRoot);
+  return res.ok
+    ? {
+        name: 'runtime-contract',
+        status: 'pass',
+        message: `contract satisfied (${res.filesScanned} game file(s))`,
+      }
+    : {
+        name: 'runtime-contract',
+        status: 'fail',
+        message: `${res.missing.length} symbol(s) missing`,
+        details: res.missing,
+      };
+}
+
+async function checkGameConfig(projectRoot) {
+  const tsPath = join(projectRoot, 'game/config/game-config.ts');
+  const jsPath = join(projectRoot, 'game/config/game-config.js');
+  const configPath = (await exists(tsPath))
+    ? tsPath
+    : (await exists(jsPath))
+      ? jsPath
+      : null;
+  if (!configPath) {
+    return { name: 'game-config', status: 'fail', message: 'no game/config/game-config.{ts,js}' };
+  }
+  const libPath = resolveLib(projectRoot, 'lib/config_expr.js');
+  if (!libPath) {
+    return { name: 'game-config', status: 'skip', message: 'loader not found' };
+  }
+  try {
+    const { loadGameConfig } = require(libPath);
+    const cfg = loadGameConfig(configPath);
+    const problems = [];
+    for (const key of ['DESIGN_WIDTH', 'DESIGN_HEIGHT']) {
+      if (typeof cfg[key] !== 'number' || cfg[key] <= 0) {
+        problems.push(`${key} must be a positive number`);
+      }
+    }
+    if (problems.length) {
+      return { name: 'game-config', status: 'fail', message: problems.join('; ') };
+    }
+    return {
+      name: 'game-config',
+      status: 'pass',
+      message: `loaded ${cfg.DESIGN_WIDTH}x${cfg.DESIGN_HEIGHT} from single source`,
+    };
+  } catch (err) {
+    return { name: 'game-config', status: 'fail', message: err.message };
+  }
+}
+
+function checkVerifyUiFull(projectRoot) {
+  const runner = join(projectRoot, 'skills/playable-verify-ui/scripts/run_all.py');
+  const proc = spawnSync('python3', [runner], { cwd: projectRoot, encoding: 'utf8' });
+  if (proc.error) {
+    return { name: 'verify:ui', status: 'skip', message: `python3 unavailable: ${proc.error.message}` };
+  }
+  return proc.status === 0
+    ? { name: 'verify:ui', status: 'pass', message: 'full static suite passed' }
+    : {
+        name: 'verify:ui',
+        status: 'fail',
+        message: 'static suite reported failures',
+        details: (proc.stdout || proc.stderr || '').trim().split('\n').slice(-6),
+      };
+}
+
+/** Resolve verify-contract.mjs, preferring the project's own copy. */
+function resolveContractProbe(projectRoot) {
+  const candidates = [
+    join(projectRoot, 'skills/playable-record/scripts/verify-contract.mjs'),
+    join(SKILLS_ROOT, 'playable-record/scripts/verify-contract.mjs'),
+  ];
+  for (const c of candidates) {
+    try {
+      require.resolve(c);
+      return c;
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+async function checkContractLive(projectRoot) {
+  const probePath = resolveContractProbe(projectRoot);
+  if (!probePath) {
+    return { name: 'verify:contract', status: 'skip', message: 'live probe not found' };
+  }
+  const isVite =
+    (await exists(join(projectRoot, 'vite.config.ts'))) ||
+    (await exists(join(projectRoot, 'vite.config.js')));
+  try {
+    const { runContractProbe } = await import(pathToFileURL(probePath).href);
+    const res = await runContractProbe({
+      root: projectRoot,
+      url: isVite ? 'http://localhost:3000/' : null,
+      useDev: isVite,
+      port: 8080,
+      scene: 'MainScene',
+      timeout: 8000,
+      headed: false,
+    });
+    return res.ok
+      ? { name: 'verify:contract', status: 'pass', message: `runtime contract satisfied (phase=${res.snapshot?.currentPhase ?? '?'})` }
+      : { name: 'verify:contract', status: 'fail', message: 'runtime contract broken', details: res.problems };
+  } catch (err) {
+    return { name: 'verify:contract', status: 'skip', message: `live probe unavailable: ${err.message}` };
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ full?: boolean, live?: boolean }} [opts]
+ */
+export async function runSmoke(projectRoot, opts = {}) {
+  const root = resolve(projectRoot);
+  const checks = [];
+
+  if (!(await exists(join(root, 'game')))) {
+    return {
+      ok: false,
+      root,
+      checks: [{ name: 'project', status: 'fail', message: 'no game/ directory — not a playable project root' }],
+    };
+  }
+
+  const pendingMarker = join(root, 'game', '.playcraft-scaffold-pending');
+  if (await exists(pendingMarker)) {
+    return {
+      ok: true,
+      root,
+      checks: [
+        {
+          name: 'engine-scaffold',
+          status: 'skip',
+          message: 'pending — run playcraft remix init-template --from-atom-tree before harness checks',
+        },
+      ],
+    };
+  }
+
+  checks.push(await checkRuntimeContract(root));
+  checks.push(await checkGameConfig(root));
+  if (opts.full) checks.push(checkVerifyUiFull(root));
+  if (opts.live) checks.push(await checkContractLive(root));
+
+  const ok = !checks.some((c) => c.status === 'fail');
+  return { ok, root, checks };
+}
+
+function printHuman(result) {
+  console.log(`[harness:smoke] ${result.ok ? 'HEALTHY' : 'BROKEN'} — ${result.root}`);
+  for (const c of result.checks) {
+    const mark = c.status === 'pass' ? '✓' : c.status === 'skip' ? '·' : '✗';
+    console.log(`  [${mark}] ${c.name}: ${c.message}`);
+    if (c.details) {
+      for (const d of c.details) console.log(`        - ${d}`);
+    }
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await runSmoke(opts.root, { full: opts.full, live: opts.live });
+  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(`[harness:smoke] ${err.message}`);
+    process.exit(1);
+  });
+}

package/project-template/skills/_shared/scripts/lib/validator-artifacts.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Programmatic validator artifact persistence — all rings.
+ * All writes are script-owned — LLM must not echo results into these files.
+ */
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+// ── Ring-generic helpers ────────────────────────────────────────────────────
+
+/** @param {number} ring */
+export function ringArtifactDir(root, ring) {
+  return join(resolve(root), `validate/ring${ring}`);
+}
+
+/** @param {number} ring */
+export function ringAutoplayMp4(ring, label = 'autoplay') {
+  return `validate/ring${ring}/${label}.mp4`;
+}
+
+// ── Async write (for use inside individual verifier scripts) ────────────────
+
+/**
+ * Write a validator artifact JSON envelope.
+ * @param {string} root
+ * @param {string} name  Basename without extension (e.g. 'contract')
+ * @param {unknown} data
+ * @param {number} [ring=1]  Target ring number
+ */
+export async function writeValidatorArtifact(root, name, data, ring = 1) {
+  const dir = ringArtifactDir(root, ring);
+  await mkdir(dir, { recursive: true });
+  const relPath = `validate/ring${ring}/${name}.json`;
+  const path = join(resolve(root), relPath);
+  const payload = makeEnvelope(name, data);
+  await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return { path, relPath };
+}
+
+// ── Sync write (for use inside gate-runner which runs fully sync) ───────────
+
+/**
+ * Write a validator artifact synchronously.
+ * @param {string} root
+ * @param {number} ring
+ * @param {string} name
+ * @param {unknown} data
+ */
+export function writeRingArtifactSync(root, ring, name, data) {
+  const dir = ringArtifactDir(root, ring);
+  mkdirSync(dir, { recursive: true });
+  const relPath = `validate/ring${ring}/${name}.json`;
+  const absPath = join(resolve(root), relPath);
+  const payload = makeEnvelope(name, data);
+  writeFileSync(absPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return { path: absPath, relPath };
+}
+
+function makeEnvelope(name, data) {
+  return {
+    generatedAt: new Date().toISOString(),
+    name,
+    ok: typeof data === 'object' && data !== null && 'ok' in data ? Boolean(data.ok) : undefined,
+    result: data,
+  };
+}
+
+// ── Artifact path collection ────────────────────────────────────────────────
+
+const RING_ARTIFACT_JSON_NAMES = {
+  1: ['contract', 'lifecycle', 'firstwin', 'placeholders'],
+  2: ['contract', 'lifecycle', 'firstwin', 'fusion', 'placeholders', 'record-one-click', 'record-full-playthrough', 'ui'],
+  3: ['contract', 'lifecycle', 'firstwin', 'fusion', 'placeholders', 'record-one-click', 'record-full-playthrough', 'ui'],
+  4: ['contract', 'lifecycle', 'firstwin', 'fusion', 'placeholders', 'record-one-click', 'record-full-playthrough', 'ui', 'ui-assets', 'visual-diff', 'bg-clean', 'tile-consistency', 'text-overlap', 'asset-code-sync', 'atom-conformance'],
+};
+
+const RING_MP4_LABELS = {
+  1: [],
+  2: ['one-click', 'full-playthrough'],
+  3: ['one-click', 'full-playthrough'],
+  4: ['one-click', 'full-playthrough'],
+};
+
+/** Collect all existing artifact paths under validate/ring{N}.
+ * @param {string} root
+ * @param {number} ring
+ * @returns {Record<string, string>}
+ */
+export function collectRingArtifactPaths(root, ring) {
+  const out = {};
+  const jsonNames = RING_ARTIFACT_JSON_NAMES[ring] ?? [];
+  for (const name of jsonNames) {
+    const rel = `validate/ring${ring}/${name}.json`;
+    if (existsSync(join(resolve(root), rel))) out[name] = rel;
+  }
+  // review.json (Tier B — parsed from review-report.md)
+  const reviewRel = `validate/ring${ring}/review.json`;
+  if (existsSync(join(resolve(root), reviewRel))) out.review = reviewRel;
+  // mp4 artifacts
+  const mp4Labels = RING_MP4_LABELS[ring] ?? [];
+  for (const label of mp4Labels) {
+    const rel = ringAutoplayMp4(ring, label);
+    if (existsSync(join(resolve(root), rel))) out[`mp4-${label}`] = rel;
+  }
+  // Ring 1 frames
+  if (ring === 1) {
+    for (let i = 1; i <= 3; i += 1) {
+      const frameRel = `validate/ring1/frames/0${i}.png`;
+      if (existsSync(join(resolve(root), frameRel))) out[`frame0${i}`] = frameRel;
+    }
+  }
+  return out;
+}
+
+// ── Ring 1 legacy aliases (backward compat) ─────────────────────────────────
+export const RING1_ARTIFACT_DIR = 'validate/ring1';
+export const RING1_FRAMES_DIR = 'validate/ring1/frames';
+export const RING1_AUTOPLAY_MP4 = 'validate/ring1/autoplay.mp4';
+
+export function ring1ArtifactDir(root) {
+  return ringArtifactDir(root, 1);
+}
+
+/** @deprecated Use collectRingArtifactPaths(root, 1) */
+export function collectRing1ArtifactPaths(root) {
+  return collectRingArtifactPaths(root, 1);
+}

package/project-template/skills/_shared/scripts/placeholder-pack-sheet.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Pack Ring 1 placeholder PNGs into a reference-only sprite sheet under assets/references/.
+ * Usage: reference for step ③ regen — NOT for runtime load (verify:asset-code-sync fails runtime refs).
+ *
+ * Usage:
+ *   npm run placeholder:pack-sheet -- --manifest placeholders.json --output assets/references/placeholder_grid.png
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), manifest: null, output: 'assets/references/placeholder_grid.png', columns: 4 };
+  for (let i = 2; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (t === '--root') opts.root = path.resolve(argv[++i]);
+    else if (t.startsWith('--root=')) opts.root = path.resolve(t.slice(7));
+    else if (t === '--manifest') opts.manifest = argv[++i];
+    else if (t === '--output') opts.output = argv[++i];
+    else if (t === '--columns') opts.columns = Number(argv[++i]);
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const root = opts.root;
+  if (!opts.manifest) {
+    console.error('Error: --manifest required (JSON array of { path, id })');
+    process.exit(1);
+  }
+  const manifestPath = path.isAbsolute(opts.manifest) ? opts.manifest : path.join(root, opts.manifest);
+  const rows = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const inputs = rows.map((r) => path.join(root, r.path)).filter((p) => fs.existsSync(p));
+  if (!inputs.length) {
+    console.error('Error: no input files from manifest');
+    process.exit(1);
+  }
+  const outRel = opts.output.replace(/^\.\//, '');
+  const outAbs = path.join(root, outRel);
+  fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+  const jsonOut = outAbs.replace(/\.(png|webp)$/i, '.json');
+  const args = [
+    'image',
+    'sprite-sheet',
+    '--inputs',
+    inputs.join(','),
+    '--output',
+    outAbs,
+    '--columns',
+    String(opts.columns),
+  ];
+  const r = spawnSync('playcraft', args, { cwd: root, encoding: 'utf8', stdio: 'inherit' });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+  const sidecar = {
+    usage: 'referenceOnly',
+    role: 'placeholder_reference_sheet',
+    paths: inputs.map((p) => path.relative(root, p)),
+    output: outRel,
+    generatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(jsonOut, JSON.stringify(sidecar, null, 2));
+  console.log(`Reference-only sheet: ${outRel} (+ ${path.relative(root, jsonOut)})`);
+}
+
+main();

package/project-template/skills/_shared/scripts/placeholder_audio_lib.py

@@ -0,0 +1,142 @@
+"""Spectral (ANS-style) audio placeholder synthesis for develop-stage stubs."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+try:
+    from PIL import Image, ImageDraw
+except ImportError:  # pragma: no cover - Pillow optional for score PNG
+    Image = None  # type: ignore[assignment,misc]
+    ImageDraw = None  # type: ignore[assignment,misc]
+
+AudioMode = str  # spectral | silent | tone
+
+SPECTROGRAM_MIN_HZ = 80
+SPECTROGRAM_MAX_HZ = 4000
+
+
+@dataclass(frozen=True)
+class SpectralStroke:
+    freq_hz: float
+    t0: float
+    t1: float
+    amp: float
+
+
+def label_seed(label: str) -> int:
+    return int(hashlib.sha256((label or "asset").encode("utf-8")).hexdigest()[:12], 16)
+
+
+def _pick_freq(seed: int, slot: int, *, low: int, high: int) -> float:
+    span = max(high - low, 1)
+    value = (seed >> (slot * 5)) & 0xFFFF
+    return float(low + (value % span))
+
+
+def build_spectral_strokes(label: str, audio_type: str, duration: float) -> list[SpectralStroke]:
+    """Deterministic ANS-like spectrogram strokes derived from label."""
+    seed = label_seed(label)
+    duration = max(0.05, float(duration))
+    strokes: list[SpectralStroke] = []
+
+    if audio_type == "bgm":
+        band_count = 3 + (seed % 2)
+        for index in range(band_count):
+            freq = _pick_freq(seed, index, low=90, high=520)
+            amp = 0.045 + (index * 0.01)
+            strokes.append(SpectralStroke(freq_hz=freq, t0=0.0, t1=duration, amp=amp))
+        # gentle beating layer
+        strokes.append(
+            SpectralStroke(
+                freq_hz=_pick_freq(seed, 7, low=520, high=980),
+                t0=0.0,
+                t1=duration,
+                amp=0.03,
+            )
+        )
+        return strokes
+
+    burst_count = 3 + (seed % 3)
+    for index in range(burst_count):
+        t0 = (index / max(burst_count, 1)) * duration * 0.55
+        width = min(0.05 + (index * 0.015), duration * 0.35)
+        t1 = min(duration, t0 + width)
+        freq = _pick_freq(seed, index + 1, low=280, high=2200)
+        if seed & (1 << index):
+            # occasional upward chirp feel: second partial
+            strokes.append(SpectralStroke(freq_hz=freq * 1.5, t0=t0, t1=t1, amp=0.05))
+        strokes.append(SpectralStroke(freq_hz=freq, t0=t0, t1=t1, amp=0.11))
+    return strokes
+
+
+def strokes_to_sidecar(strokes: list[SpectralStroke]) -> list[dict]:
+    return [
+        {
+            "freqHz": round(stroke.freq_hz, 1),
+            "t0": round(stroke.t0, 3),
+            "t1": round(stroke.t1, 3),
+            "amp": round(stroke.amp, 3),
+        }
+        for stroke in strokes
+    ]
+
+
+def _aeval_term(stroke: SpectralStroke) -> str:
+    f = stroke.freq_hz
+    a = stroke.amp
+    t0 = stroke.t0
+    t1 = stroke.t1
+    span = max(t1 - t0, 0.001)
+    attack = f"min(max((t-{t0})/{span},0),1)"
+    release = f"min(max(({t1}-t)/{span},0),1)"
+    return f"{a}*sin(2*PI*{f}*t)*between(t,{t0},{t1})*sin(PI*{attack})*sin(PI*{release})"
+
+
+def build_aevalsrc_expression(strokes: list[SpectralStroke], duration: float) -> str:
+    if not strokes:
+        return "0"
+    terms = [_aeval_term(stroke) for stroke in strokes]
+    expr = "+".join(terms)
+    # soft limiter
+    return f"tanh({expr})"
+
+
+def hz_to_y(freq_hz: float, height: int) -> int:
+    freq_hz = max(SPECTROGRAM_MIN_HZ, min(SPECTROGRAM_MAX_HZ, freq_hz))
+    lo = SPECTROGRAM_MIN_HZ
+    hi = SPECTROGRAM_MAX_HZ
+    ratio = (freq_hz - lo) / (hi - lo)
+    return int((1.0 - ratio) * (height - 1))
+
+
+def render_spectrogram_score_png(
+    *,
+    label: str,
+    strokes: list[SpectralStroke],
+    duration: float,
+    output_path: str,
+    width: int = 480,
+    height: int = 160,
+) -> None:
+    if Image is None or ImageDraw is None:
+        return
+    image = Image.new("RGB", (width, height), (8, 10, 18))
+    draw = ImageDraw.Draw(image)
+    draw.text((8, 6), label, fill=(180, 190, 210))
+    for stroke in strokes:
+        x0 = int((stroke.t0 / max(duration, 0.001)) * (width - 1))
+        x1 = max(x0 + 1, int((stroke.t1 / max(duration, 0.001)) * (width - 1)))
+        y = hz_to_y(stroke.freq_hz, height)
+        color = (70, 210, 255) if stroke.amp >= 0.08 else (120, 140, 255)
+        draw.rectangle((x0, y - 1, x1, y + 1), fill=color)
+    image.save(output_path, format="PNG")
+
+
+def spectrogram_score_path_for(audio_path: str) -> str:
+    from pathlib import Path
+
+    path = Path(audio_path)
+    return str(path.with_suffix(".spectrogram.png"))
+