@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_atlas_frames.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Verify atlas JSON frame names and sizes vs profile."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify atlas JSON frames")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    atlas_root = paths["atlasRoot"]
+    report = Report()
+    errors: list[str] = []
+
+    for atlas in profile.get("assets", {}).get("atlases", []):
+        name = atlas["name"]
+        json_path = atlas_root / atlas["json"]
+        png_path = atlas_root / atlas["png"]
+
+        if not json_path.is_file():
+            errors.append(f"{name}: missing {json_path.name}")
+            continue
+        if not png_path.is_file():
+            errors.append(f"{name}: missing {png_path.name}")
+            continue
+
+        with json_path.open(encoding="utf-8") as fh:
+            data = json.load(fh)
+
+        frames_obj = data.get("frames", {})
+        if isinstance(frames_obj, list):
+            atlas_frames = {f.get("filename", f.get("name", "")): f for f in frames_obj}
+        else:
+            atlas_frames = frames_obj
+
+        expected = {f["name"]: (f["width"], f["height"]) for f in atlas.get("frames", [])}
+
+        for frame_name, (ew, eh) in expected.items():
+            if frame_name not in atlas_frames:
+                errors.append(f"{name}: frame '{frame_name}' missing in JSON")
+                continue
+            entry = atlas_frames[frame_name]
+            frame_data = entry.get("frame", entry)
+            fw = frame_data.get("w", frame_data.get("width"))
+            fh = frame_data.get("h", frame_data.get("height"))
+            if fw != ew or fh != eh:
+                errors.append(f"{name}/{frame_name}: JSON {fw}x{fh} != profile {ew}x{eh}")
+
+        extra = set(atlas_frames.keys()) - set(expected.keys())
+        for frame_name in sorted(extra):
+            if frame_name:
+                errors.append(f"{name}: unexpected frame '{frame_name}' in JSON")
+
+    if errors:
+        report.fail("verify_atlas_frames", f"{len(errors)} atlas issue(s)", issues=errors[:25], total=len(errors))
+    else:
+        report.pass_("verify_atlas_frames", "All atlas JSON frames match profile")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_bg_clean.py

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+"""
+Background cleanliness gate — detects text-like regions and rule grid patterns in bg assets.
+
+Pure local CV (PIL + optional pytesseract). Fails when background plates contain baked UI
+(board grids, HUD numbers, button clusters) per test11 B11.
+
+Usage:
+  python3 skills/playable-verify-ui/scripts/verify_bg_clean.py [--root .]
+
+Exit 0 = pass or skip (no bg assets)
+Exit 2 = fail
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+# Run-as-script: the manifest helper lives next to this file.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from asset_manifest import entry_for_path, load_manifest  # noqa: E402
+
+
+def make_issue(
+    *,
+    issue_id: str,
+    class_name: str,
+    message: str,
+    source_path: str,
+    box: tuple[int, int, int, int] | list[float] | None = None,
+    severity: str = "P1",
+    metrics: dict | None = None,
+) -> dict:
+    issue = {
+        "id": issue_id,
+        "status": "fail",
+        "severity": severity,
+        "className": class_name,
+        "message": message,
+        "evidenceType": "asset",
+        "sourcePath": source_path,
+        "recommendedSkill": "playable-verify-ui",
+        "alphaStrategy": "n-a",
+    }
+    if box is not None:
+        issue["box"] = [float(v) for v in box]
+    if metrics:
+        issue["metrics"] = metrics
+    return issue
+
+
+def manifest_issue(message: str, source_path: str = "assets/asset-manifest.json") -> dict:
+    return make_issue(
+        issue_id=f"asset_manifest:{source_path}",
+        class_name="asset_manifest_invalid",
+        message=message,
+        source_path=source_path,
+        severity="P1",
+    )
+
+
+def load_pil() -> Any | None:
+    try:
+        from PIL import Image
+
+        return Image
+    except ImportError:
+        return None
+
+
+def region_box(w: int, h: int, name: str) -> tuple[int, int, int, int]:
+    """ROI by role — avoid full-image false positives on decorative edges."""
+    if name == "top":
+        return (0, 0, w, int(h * 0.18))
+    if name == "bottom":
+        return (0, int(h * 0.82), w, h)
+    if name == "board":
+        return (int(w * 0.08), int(h * 0.22), int(w * 0.92), int(h * 0.72))
+    return (0, 0, w, h)
+
+
+def horizontal_line_score(gray_data: list[int], w: int, h: int) -> float:
+    """High score = many rows with low variance (rule lines / grid)."""
+    if h < 4 or w < 4:
+        return 0.0
+    row_vars: list[float] = []
+    for y in range(h):
+        row = gray_data[y * w : (y + 1) * w]
+        mean = sum(row) / len(row)
+        var = sum((x - mean) ** 2 for x in row) / len(row)
+        row_vars.append(var)
+    if not row_vars:
+        return 0.0
+    low_var_rows = sum(1 for v in row_vars if v < 120.0)
+    return low_var_rows / h
+
+
+def vertical_line_score(gray_data: list[int], w: int, h: int) -> float:
+    if h < 4 or w < 4:
+        return 0.0
+    low_var_cols = 0
+    for x in range(w):
+        col = [gray_data[y * w + x] for y in range(h)]
+        mean = sum(col) / len(col)
+        var = sum((v - mean) ** 2 for v in col) / len(col)
+        if var < 120.0:
+            low_var_cols += 1
+    return low_var_cols / w
+
+
+def grid_pattern_score(image_mod: Any, crop: Any) -> float:
+    g = crop.convert("L")
+    w, h = g.size
+    data = list(g.getdata())
+    h_score = horizontal_line_score(data, w, h)
+    v_score = vertical_line_score(data, w, h)
+    return (h_score + v_score) / 2.0
+
+
+def edge_density(crop: Any, max_w: int = 360, thr: int = 32) -> float:
+    """Fraction of pixels with a strong local gradient (downscaled for speed/stability).
+
+    A finished composite baked into the background (full tile board, HUD, button
+    cluster — test11 B11) is dense with hard edges, whereas a clean background plate
+    (gradient sky / soft scene) is smooth. Measured ~0.08 for test11's baked board
+    ROI vs ~0.003 for clean plates, so it separates the two with a wide margin.
+    """
+    g = crop.convert("L")
+    w, h = g.size
+    if w > max_w:
+        nh = max(1, int(h * max_w / w))
+        g = g.resize((max_w, nh))
+        w, h = g.size
+    if w < 2 or h < 2:
+        return 0.0
+    px = g.load()
+    cnt = 0
+    tot = 0
+    for y in range(h - 1):
+        for x in range(w - 1):
+            grad = abs(px[x, y] - px[x + 1, y]) + abs(px[x, y] - px[x, y + 1])
+            if grad > thr:
+                cnt += 1
+            tot += 1
+    return cnt / tot if tot else 0.0
+
+
+def ocr_text_boxes(image_mod: Any, crop: Any) -> list[str]:
+    try:
+        import pytesseract
+        from pytesseract import Output
+
+        data = pytesseract.image_to_data(crop, output_type=Output.DICT, config="--psm 11")
+        texts: list[str] = []
+        for i, conf in enumerate(data.get("conf", [])):
+            try:
+                c = int(conf)
+            except (TypeError, ValueError):
+                continue
+            if c < 40:
+                continue
+            t = str(data["text"][i]).strip()
+            if len(t) >= 2:
+                texts.append(t)
+        return texts
+    except Exception:
+        return []
+
+
+def analyze_bg(
+    image_mod: Any,
+    path: Path,
+    root: Path,
+    edge_threshold: float = 0.04,
+    board_roi: tuple[float, float, float, float] | None = None,
+) -> dict:
+    img = image_mod.open(path)
+    w, h = img.size
+    failures: list[str] = []
+    issues: list[dict] = []
+    checks: list[dict] = []
+
+    for region in ("board", "top", "bottom"):
+        if region == "board" and board_roi is not None:
+            x1, y1, x2, y2 = board_roi
+            box = (int(w * x1), int(h * y1), int(w * x2), int(h * y2))
+        else:
+            box = region_box(w, h, region)
+        crop = img.crop(box)
+        grid = grid_pattern_score(image_mod, crop)
+        edges = edge_density(crop)
+        texts = ocr_text_boxes(image_mod, crop)
+        checks.append(
+            {
+                "region": region,
+                "gridScore": round(grid, 4),
+                "edgeDensity": round(edges, 4),
+                "textSnippets": texts[:5],
+            }
+        )
+
+        # A high grid score alone is ambiguous — a flat/solid background also has
+        # uniform (low-variance) rows. Only treat it as a baked grid when there is
+        # also real structure (edges), so clean gradient/solid plates are not flagged.
+        if region == "board" and grid > 0.35 and edges > 0.015:
+            message = (
+                f"{path.relative_to(root)}: board ROI grid score {grid:.2f} (edge density {edges:.3f}) "
+                "— possible baked tile grid in background"
+            )
+            failures.append(message)
+            issues.append(
+                make_issue(
+                    issue_id=f"bg_baked_ui:{path.relative_to(root)}:board_grid",
+                    class_name="bg_baked_ui",
+                    message=message,
+                    source_path=str(path.relative_to(root)),
+                    box=box,
+                    metrics={"region": region, "gridScore": round(grid, 4), "edgeDensity": round(edges, 4)},
+                )
+            )
+        if region == "board" and edges > edge_threshold:
+            message = (
+                f"{path.relative_to(root)}: board ROI edge density {edges:.3f} > {edge_threshold} — "
+                "background looks like a baked finished composite (tile board / HUD), not a clean plate"
+            )
+            failures.append(message)
+            issues.append(
+                make_issue(
+                    issue_id=f"bg_baked_ui:{path.relative_to(root)}:board_edges",
+                    class_name="bg_baked_ui",
+                    message=message,
+                    source_path=str(path.relative_to(root)),
+                    box=box,
+                    metrics={"region": region, "gridScore": round(grid, 4), "edgeDensity": round(edges, 4)},
+                )
+            )
+        if region == "top" and texts:
+            message = f"{path.relative_to(root)}: top ROI OCR detected text {texts[:3]!r} — HUD/title in background"
+            failures.append(message)
+            issues.append(
+                make_issue(
+                    issue_id=f"bg_baked_text:{path.relative_to(root)}:top",
+                    class_name="bg_baked_text",
+                    message=message,
+                    source_path=str(path.relative_to(root)),
+                    box=box,
+                    metrics={"region": region, "textSnippets": texts[:5]},
+                )
+            )
+        if region == "bottom" and len(texts) >= 2:
+            message = (
+                f"{path.relative_to(root)}: bottom ROI multiple text regions {texts[:3]!r} — "
+                "possible fake button cluster"
+            )
+            failures.append(message)
+            issues.append(
+                make_issue(
+                    issue_id=f"bg_baked_text:{path.relative_to(root)}:bottom",
+                    class_name="bg_baked_text",
+                    message=message,
+                    source_path=str(path.relative_to(root)),
+                    box=box,
+                    metrics={"region": region, "textSnippets": texts[:5]},
+                )
+            )
+
+    return {"path": str(path.relative_to(root)), "checks": checks, "failures": failures, "issues": issues}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--grid-threshold", type=float, default=0.35)
+    parser.add_argument("--edge-threshold", type=float, default=0.04)
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    bg_dir = root / "assets" / "images" / "bg"
+    image_mod = load_pil()
+    if image_mod is None:
+        issue = make_issue(
+            issue_id="bg_clean:pillow_missing",
+            class_name="validator_dependency_missing",
+            message="Pillow required",
+            source_path="project",
+            severity="P0",
+        )
+        print(json.dumps({"ok": False, "issues": [issue], "failures": ["Pillow required"]}))
+        return 2
+
+    # A malformed/stale manifest is itself a contract failure — surface it before
+    # the "no assets" early return so it is always caught by this (always-on) gate.
+    manifest, manifest_errors = load_manifest(root)
+    if manifest_errors:
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "manifestErrors": manifest_errors,
+                    "issues": [manifest_issue(err) for err in manifest_errors],
+                    "failures": manifest_errors,
+                },
+                indent=2,
+            )
+        )
+        return 2
+
+    assets = sorted(bg_dir.glob("*.webp")) + sorted(bg_dir.glob("*.png"))
+    if not assets:
+        print(json.dumps({"ok": True, "skipped": True, "note": "no bg assets under assets/images/bg/"}))
+        return 0
+
+    all_failures: list[str] = []
+    all_issues: list[dict] = []
+    results: list[dict] = []
+    for path in assets:
+        rel = str(path.relative_to(root))
+        entry = entry_for_path(manifest, rel)
+
+        # With a manifest, only runtime backgrounds are subject to the bg-clean gate.
+        if manifest is not None:
+            if entry is None:
+                message = (
+                    f"{rel}: present under assets/images/bg/ but not declared in asset-manifest.json "
+                    "(every runtime background must declare role/usage)"
+                )
+                all_failures.append(message)
+                all_issues.append(
+                    make_issue(
+                        issue_id=f"asset_manifest_undeclared:{rel}",
+                        class_name="asset_manifest_undeclared",
+                        message=message,
+                        source_path=rel,
+                    )
+                )
+                results.append({"path": rel, "skipped": True, "reason": "undeclared"})
+                continue
+            if entry.get("usage", "runtime") == "reference-only":
+                results.append({"path": rel, "skipped": True, "reason": "reference-only", "id": entry.get("id")})
+                continue
+            if entry.get("role") != "background":
+                results.append({"path": rel, "skipped": True, "reason": f"role={entry.get('role')}", "id": entry.get("id")})
+                continue
+
+        board_roi = None
+        if entry and isinstance(entry.get("roi"), dict) and isinstance(entry["roi"].get("board"), (list, tuple)):
+            board_roi = tuple(entry["roi"]["board"])  # type: ignore[assignment]
+
+        r = analyze_bg(image_mod, path, root, edge_threshold=args.edge_threshold, board_roi=board_roi)
+        if entry:
+            r["id"] = entry.get("id")
+        results.append(r)
+        all_failures.extend(r["failures"])
+        all_issues.extend(r.get("issues", []))
+
+    out = {"ok": len(all_failures) == 0, "assets": results, "issues": all_issues, "failures": all_failures}
+    print(json.dumps(out, indent=2))
+    return 0 if out["ok"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_doc_asset_sync.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Warn when docs/asset-naming.md sizes drift from profile."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+SIZE_RE = re.compile(r"(\d+)\s*[×x]\s*(\d+)")
+
+
+def collect_profile_sizes(profile: dict) -> dict[str, tuple[int, int]]:
+    sizes: dict[str, tuple[int, int]] = {}
+    for item in profile.get("assets", {}).get("standalone", []):
+        sizes[item["key"]] = (item["width"], item["height"])
+    for atlas in profile.get("assets", {}).get("atlases", []):
+        for frame in atlas.get("frames", []):
+            sizes[frame["name"]] = (frame["width"], frame["height"])
+    return sizes
+
+
+def parse_doc_table(doc_text: str) -> dict[str, tuple[int, int]]:
+    sizes: dict[str, tuple[int, int]] = {}
+    for line in doc_text.splitlines():
+        if "|" not in line or "Frame" in line or "---" in line:
+            continue
+        cols = [c.strip().strip("`") for c in line.split("|")]
+        cols = [c for c in cols if c]
+        if len(cols) < 3:
+            continue
+        key = cols[0]
+        if "…" in key or "..." in key:
+            continue
+        size_match = SIZE_RE.search(cols[2] if len(cols) > 2 else "")
+        if not size_match:
+            continue
+        sizes[key] = (int(size_match.group(1)), int(size_match.group(2)))
+    return sizes
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify asset naming doc sync")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    doc_path = paths.get("assetNamingDoc")
+
+    report = Report()
+    if not doc_path or not doc_path.is_file():
+        report.warn("verify_doc_asset_sync", "assetNamingDoc not configured or missing")
+        exit_with_report(report, json_stdout=args.json)
+        return
+
+    profile_sizes = collect_profile_sizes(profile)
+    doc_sizes = parse_doc_table(doc_path.read_text(encoding="utf-8"))
+    drifts: list[str] = []
+
+    for key, (pw, ph) in profile_sizes.items():
+        if key not in doc_sizes:
+            continue
+        dw, dh = doc_sizes[key]
+        if (pw, ph) != (dw, dh):
+            drifts.append(f"{key}: doc {dw}x{dh} vs profile {pw}x{ph}")
+
+    if drifts:
+        report.warn(
+            "verify_doc_asset_sync",
+            f"{len(drifts)} doc/profile size drift(s)",
+            drifts=drifts[:20],
+        )
+    else:
+        report.pass_("verify_doc_asset_sync", "Documented sizes match profile (where listed)")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_fetch_antipatterns.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Warn when fetch/build scripts use placehold.co for UI/rewards assets."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+PLACEHOLD_RE = re.compile(r"placehold\.co", re.IGNORECASE)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Detect placehold.co antipatterns")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    report = Report()
+    hits: list[str] = []
+
+    candidates = [
+        paths.get("fetchAssetsScript"),
+        paths.get("buildAtlasScript"),
+        profile_path.parent / "scripts" / "generate-ui-placeholders.py",
+    ]
+
+    for path in candidates:
+        if not path or not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if PLACEHOLD_RE.search(text):
+            rel = path.relative_to(profile_path.parent) if path.is_relative_to(profile_path.parent) else path
+            hits.append(str(rel))
+
+    if hits:
+        report.warn(
+            "verify_fetch_antipatterns",
+            f"placehold.co references in {len(hits)} script(s)",
+            scripts=hits,
+        )
+    else:
+        report.pass_("verify_fetch_antipatterns", "No placehold.co references in asset scripts")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_game_config_load.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { loadGameConfig } = require('./lib/config_expr');
+const { loadProfile } = require('./lib/node_utils');
+
+function parseArgs() {
+  const args = { profile: path.resolve('playable.ui.profile.yaml') };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--profile' && process.argv[i + 1]) {
+      args.profile = path.resolve(process.argv[++i]);
+    }
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs();
+  const profilePath = args.profile;
+  const projectRoot = path.dirname(profilePath);
+  const profile = loadProfile(profilePath);
+  const configPath = path.resolve(projectRoot, profile.paths.gameConfig);
+
+  const findings = [];
+  const add = (check, status, message, details = {}) => findings.push({ check, status, message, details });
+
+  try {
+    const cfg = loadGameConfig(configPath);
+    const keys = profile.layout?.configKeys || [];
+    const bad = [];
+
+    for (const key of keys) {
+      const val = cfg[key];
+      if (typeof val !== 'number' || !Number.isFinite(val) || val <= 0) {
+        bad.push(`${key}=${val}`);
+      }
+    }
+
+    if (bad.length) {
+      add('verify_game_config_load', 'fail', `${bad.length} config key(s) not positive finite numbers`, { bad });
+    } else {
+      add('verify_game_config_load', 'pass', `GAME_CONFIG loaded; ${keys.length} layout keys OK`);
+    }
+  } catch (err) {
+    add('verify_game_config_load', 'fail', err.message);
+  }
+
+  const worst = findings.some((f) => f.status === 'fail') ? 'fail' : 'pass';
+  console.log(JSON.stringify({ worst, findings }));
+  process.exit(worst === 'fail' ? 1 : 0);
+}
+
+main();