@playcraft/cli 0.0.43 → 0.0.46

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

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+asset-manifest loader + validator — the structured contract between art assets and
+the visual gates.
+
+test11 root cause was not "the image tools are broken" but "the tools had no
+structured contract": nothing declared whether a given image is a runtime
+background, a CTA, a tile, or a reference-only composite, nor which text is
+legitimately allowed on screen. This module loads `assets/asset-manifest.json`
+(hand-authored by the TA) and validates it, so the visual gates can consume
+`role` / `usage` / `roi` / `allowedText` instead of guessing.
+
+Schema (assets/asset-manifest.json):
+{
+  "version": 1,
+  "assets": {
+    "<numericId>": {                       # key MUST be a numericId (digits only)
+      "path": "assets/images/bg/bg_game.webp",
+      "role": "background",                # background|tile|cta|logo|decoration|character|prop|ui|fx|reference
+      "usage": "runtime",                  # runtime | reference-only  (default: runtime)
+      "roi": { "board": [0.08, 0.22, 0.92, 0.72] },  # optional, normalized 0..1 [x1,y1,x2,y2]
+      "allowedText": ["Play"]              # optional whitelist of legit on-asset text
+    }
+  },
+  "screen": { "allowedText": ["INSTALL", "立即下载"] }   # optional screen-level whitelist
+}
+
+This module is pure stdlib (no Pillow / OCR) so it can run and be tested anywhere.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+MANIFEST_REL = "assets/asset-manifest.json"
+
+ALLOWED_ROLES = {
+    "background",
+    "tile",
+    "cta",
+    "logo",
+    "decoration",
+    "character",
+    "prop",
+    "ui",
+    "fx",
+    "reference",
+}
+ALLOWED_USAGE = {"runtime", "reference-only"}
+
+
+def manifest_path(root: Path) -> Path:
+    return root / MANIFEST_REL
+
+
+def _valid_roi_box(box: Any) -> bool:
+    if not (isinstance(box, (list, tuple)) and len(box) == 4):
+        return False
+    if not all(isinstance(v, (int, float)) and 0.0 <= float(v) <= 1.0 for v in box):
+        return False
+    x1, y1, x2, y2 = box
+    return x1 < x2 and y1 < y2
+
+
+def validate_manifest(data: Any, root: Path) -> list[str]:
+    """Schema check + reconcile against files on disk. Returns a list of errors."""
+    errors: list[str] = []
+    if not isinstance(data, dict):
+        return ["asset-manifest.json: top-level must be an object"]
+
+    assets = data.get("assets")
+    if not isinstance(assets, dict):
+        errors.append("asset-manifest.json: 'assets' must be an object keyed by numericId")
+    else:
+        for key, entry in assets.items():
+            if not str(key).isdigit():
+                errors.append(
+                    f"asset-manifest.json: asset key {key!r} is not a numericId (digits only)"
+                )
+            if not isinstance(entry, dict):
+                errors.append(f"asset-manifest.json: asset {key} must be an object")
+                continue
+
+            role = entry.get("role")
+            if role not in ALLOWED_ROLES:
+                errors.append(
+                    f"asset-manifest.json: asset {key} role {role!r} not in {sorted(ALLOWED_ROLES)}"
+                )
+
+            usage = entry.get("usage", "runtime")
+            if usage not in ALLOWED_USAGE:
+                errors.append(
+                    f"asset-manifest.json: asset {key} usage {usage!r} not in {sorted(ALLOWED_USAGE)}"
+                )
+
+            p = entry.get("path")
+            if not isinstance(p, str) or not p:
+                errors.append(f"asset-manifest.json: asset {key} missing 'path'")
+            elif not (root / p).exists():
+                # reconcile: a declared asset that is not on disk is a stale manifest
+                errors.append(
+                    f"asset-manifest.json: asset {key} path {p!r} does not exist on disk"
+                )
+
+            roi = entry.get("roi")
+            if roi is not None:
+                if not isinstance(roi, dict):
+                    errors.append(
+                        f"asset-manifest.json: asset {key} roi must be an object of name->[x1,y1,x2,y2]"
+                    )
+                else:
+                    for rn, box in roi.items():
+                        if not _valid_roi_box(box):
+                            errors.append(
+                                f"asset-manifest.json: asset {key} roi[{rn}] must be 4 normalized "
+                                f"values [x1,y1,x2,y2] in 0..1 with x1<x2, y1<y2"
+                            )
+
+            at = entry.get("allowedText")
+            if at is not None and not (
+                isinstance(at, list) and all(isinstance(s, str) for s in at)
+            ):
+                errors.append(
+                    f"asset-manifest.json: asset {key} allowedText must be a list of strings"
+                )
+
+    screen = data.get("screen")
+    if screen is not None:
+        if not isinstance(screen, dict):
+            errors.append("asset-manifest.json: 'screen' must be an object")
+        else:
+            at = screen.get("allowedText")
+            if at is not None and not (
+                isinstance(at, list) and all(isinstance(s, str) for s in at)
+            ):
+                errors.append("asset-manifest.json: screen.allowedText must be a list of strings")
+
+    return errors
+
+
+def load_manifest(root: Path) -> tuple[dict | None, list[str]]:
+    """Load + validate the manifest.
+
+    Returns (manifest, errors):
+      - (None, [])            → no manifest file (optional; gates fall back to defaults)
+      - (None, [err, ...])    → present but invalid JSON
+      - (data, [])            → present and valid
+      - (data, [err, ...])    → present but failed schema/reconcile
+    """
+    path = manifest_path(root)
+    if not path.exists():
+        return None, []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        return None, [f"asset-manifest.json: invalid JSON ({e})"]
+    return data, validate_manifest(data, root)
+
+
+def entry_for_path(manifest: dict | None, rel_path: str) -> dict | None:
+    """Return the manifest entry whose declared path matches rel_path (with its id)."""
+    if not manifest:
+        return None
+    rel_norm = rel_path.replace("\\", "/")
+    for key, entry in (manifest.get("assets") or {}).items():
+        if isinstance(entry, dict) and str(entry.get("path", "")).replace("\\", "/") == rel_norm:
+            return {"id": str(key), **entry}
+    return None
+
+
+def assets_with_role(manifest: dict | None, role: str) -> list[dict]:
+    out: list[dict] = []
+    if not manifest:
+        return out
+    for key, entry in (manifest.get("assets") or {}).items():
+        if isinstance(entry, dict) and entry.get("role") == role:
+            out.append({"id": str(key), **entry})
+    return out
+
+
+def is_reference_entry(entry: Any) -> bool:
+    """True if an asset is a reference (not a runtime asset).
+
+    An asset counts as a reference when it is explicitly ``usage=reference-only``
+    OR declared with ``role=reference`` (which defaults to reference-only — a
+    reference asset that forgot the usage field must not be treated as runtime).
+    """
+    if not isinstance(entry, dict):
+        return False
+    return entry.get("usage") == "reference-only" or entry.get("role") == "reference"
+
+
+def _declared_paths(manifest: dict | None, predicate) -> list[str]:
+    out: list[str] = []
+    if not manifest:
+        return out
+    for entry in (manifest.get("assets") or {}).values():
+        if isinstance(entry, dict) and predicate(entry):
+            p = entry.get("path")
+            if isinstance(p, str) and p:
+                out.append(p.replace("\\", "/"))
+    return out
+
+
+def reference_paths(manifest: dict | None) -> list[str]:
+    """Declared paths that are references (usage=reference-only or role=reference)."""
+    return _declared_paths(manifest, is_reference_entry)
+
+
+def runtime_paths(manifest: dict | None) -> list[str]:
+    """Declared paths that are runtime assets (everything that is not a reference)."""
+    return _declared_paths(manifest, lambda e: not is_reference_entry(e))
+
+
+def allowed_text_set(manifest: dict | None) -> set[str]:
+    """Union of screen-level + per-asset allowedText, normalized to lowercase/stripped."""
+    texts: set[str] = set()
+    if not manifest:
+        return texts
+    screen = manifest.get("screen") or {}
+    for t in screen.get("allowedText", []) or []:
+        if isinstance(t, str):
+            texts.add(t.strip().lower())
+    for entry in (manifest.get("assets") or {}).values():
+        if not isinstance(entry, dict):
+            continue
+        for t in entry.get("allowedText", []) or []:
+            if isinstance(t, str):
+                texts.add(t.strip().lower())
+    return texts

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

@@ -0,0 +1 @@
+# Playable UI verification library

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

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * Safely evaluate layout expressions against GAME_CONFIG + profile.safeArea.
+ * Only allows numeric literals, + - * /, parentheses, and dotted identifiers.
+ */
+
+const TOKEN_RE = /(\d+(?:\.\d+)?|[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*|[+\-*/()]|\s+)/g;
+
+function getPathValue(root, path) {
+  const parts = path.split('.');
+  let cur = root;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object' || !(part in cur)) {
+      throw new Error(`Unknown path: ${path}`);
+    }
+    cur = cur[part];
+  }
+  if (typeof cur !== 'number' || !Number.isFinite(cur)) {
+    throw new Error(`Path is not a finite number: ${path}`);
+  }
+  return cur;
+}
+
+function resolveRef(expr, gameConfig, profile) {
+  const trimmed = expr.trim();
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+  if (trimmed.startsWith('safeArea.')) {
+    const key = trimmed.slice('safeArea.'.length);
+    const safe = profile && profile.safeArea;
+    if (!safe || !(key in safe)) {
+      throw new Error(`Unknown safeArea key: ${key}`);
+    }
+    return Number(safe[key]);
+  }
+  return getPathValue(gameConfig, trimmed);
+}
+
+function tokenize(expr) {
+  const tokens = [];
+  let m;
+  TOKEN_RE.lastIndex = 0;
+  while ((m = TOKEN_RE.exec(expr)) !== null) {
+    const t = m[0];
+    if (/^\s+$/.test(t)) continue;
+    tokens.push(t);
+  }
+  return tokens;
+}
+
+function parseExpression(tokens, gameConfig, profile) {
+  let pos = 0;
+
+  function peek() {
+    return tokens[pos];
+  }
+
+  function consume(expected) {
+    const t = tokens[pos++];
+    if (expected && t !== expected) {
+      throw new Error(`Expected '${expected}' but got '${t}'`);
+    }
+    return t;
+  }
+
+  function parsePrimary() {
+    const t = peek();
+    if (t === '(') {
+      consume('(');
+      const val = parseAddSub();
+      consume(')');
+      return val;
+    }
+    if (/^\d+(?:\.\d+)?$/.test(t)) {
+      consume();
+      return Number(t);
+    }
+    if (/^[A-Za-z_]/.test(t)) {
+      consume();
+      return resolveRef(t, gameConfig, profile);
+    }
+    throw new Error(`Unexpected token: ${t}`);
+  }
+
+  function parseMulDiv() {
+    let left = parsePrimary();
+    while (peek() === '*' || peek() === '/') {
+      const op = consume();
+      const right = parsePrimary();
+      left = op === '*' ? left * right : left / right;
+    }
+    return left;
+  }
+
+  function parseAddSub() {
+    let left = parseMulDiv();
+    while (peek() === '+' || peek() === '-') {
+      const op = consume();
+      const right = parseMulDiv();
+      left = op === '+' ? left + right : left - right;
+    }
+    return left;
+  }
+
+  const result = parseAddSub();
+  if (pos !== tokens.length) {
+    throw new Error(`Unexpected trailing tokens at position ${pos}`);
+  }
+  return result;
+}
+
+function evaluate(expr, gameConfig, profile) {
+  if (expr == null) {
+    throw new Error('Expression is required');
+  }
+  if (typeof expr === 'number') return expr;
+  const str = String(expr).trim();
+  if (/^\d+(?:\.\d+)?$/.test(str)) {
+    return Number(str);
+  }
+  if (/^[A-Za-z_][A-Za-z0-9_.]*$/.test(str) && !/[+\-*/()]/.test(str)) {
+    return resolveRef(str, gameConfig, profile);
+  }
+  const tokens = tokenize(str);
+  return parseExpression(tokens, gameConfig, profile);
+}
+
+function regionBounds(regionDef, gameConfig, profile) {
+  if (regionDef.cy != null && regionDef.h != null) {
+    const cy = evaluate(regionDef.cy, gameConfig, profile);
+    const h = evaluate(regionDef.h, gameConfig, profile);
+    return { y0: cy - h / 2, y1: cy + h / 2 };
+  }
+  if (regionDef.y0 != null && regionDef.y1 != null) {
+    return {
+      y0: evaluate(regionDef.y0, gameConfig, profile),
+      y1: evaluate(regionDef.y1, gameConfig, profile),
+    };
+  }
+  throw new Error('Region must define y0/y1 or cy/h');
+}
+
+/**
+ * Load GAME_CONFIG from the project's single source of truth.
+ *
+ * Supports TypeScript (`.ts`/`.tsx`) directly so the project keeps ONE config
+ * file — verify reads exactly what the game runs, making drift structurally
+ * impossible. Legacy plain `.js` configs remain supported.
+ *
+ * Extraction order (robust to authoring style):
+ *   1. `module.exports.GAME_CONFIG` (CJS / esbuild output / current stub)
+ *   2. bare top-level `const GAME_CONFIG = {...}` (legacy hand-written JS)
+ */
+function loadGameConfig(configPath) {
+  const fs = require('fs');
+  const vm = require('vm');
+  const path = require('path');
+
+  let code = fs.readFileSync(configPath, 'utf8');
+  const ext = path.extname(configPath).toLowerCase();
+
+  if (ext === '.ts' || ext === '.tsx' || ext === '.mts' || ext === '.cts') {
+    let esbuild;
+    try {
+      esbuild = require('esbuild');
+    } catch (err) {
+      throw new Error(
+        `Loading ${path.basename(configPath)} needs esbuild (bundled with vite). ` +
+          `Run "npm install" in the project root. Original: ${err.message}`,
+      );
+    }
+    code = esbuild.transformSync(code, {
+      loader: ext === '.tsx' ? 'tsx' : 'ts',
+      format: 'cjs',
+      target: 'es2020',
+    }).code;
+  }
+
+  const moduleObj = { exports: {} };
+  const sandbox = {
+    module: moduleObj,
+    exports: moduleObj.exports,
+    require,
+    console,
+    __DEV__: false,
+    globalThis: undefined,
+  };
+  vm.createContext(sandbox);
+  sandbox.globalThis = sandbox;
+
+  // Capture a bare top-level `const GAME_CONFIG` (block-scoped, won't leak to
+  // the sandbox object on its own) by re-exposing it after the script body.
+  const wrapped = `${code}\n;try{ globalThis.__GAME_CONFIG__ = (typeof GAME_CONFIG !== 'undefined') ? GAME_CONFIG : undefined; }catch(_e){}`;
+  vm.runInContext(wrapped, sandbox, { filename: configPath });
+
+  const exported = moduleObj.exports || {};
+  const cfg =
+    exported.GAME_CONFIG ||
+    (exported.default && exported.default.GAME_CONFIG) ||
+    sandbox.__GAME_CONFIG__;
+
+  if (!cfg || typeof cfg !== 'object') {
+    throw new Error(
+      `GAME_CONFIG not found after loading ${path.basename(configPath)} — ` +
+        `export a GAME_CONFIG object (e.g. "export const GAME_CONFIG = { ... }").`,
+    );
+  }
+  return cfg;
+}
+
+module.exports = {
+  evaluate,
+  regionBounds,
+  loadGameConfig,
+  resolveRef,
+};

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

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function loadProfile(profilePath) {
+  const out = execFileSync(
+    'python3',
+    [
+      '-c',
+      'import json, sys, yaml; print(json.dumps(yaml.safe_load(open(sys.argv[1], encoding="utf-8"))))',
+      profilePath,
+    ],
+    { encoding: 'utf8' },
+  );
+  return JSON.parse(out);
+}
+
+function walkFiles(root, matcher) {
+  const results = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (matcher(full)) {
+        results.push(full);
+      }
+    }
+  }
+  walk(root);
+  return results;
+}
+
+function globFiles(projectRoot, pattern) {
+  // Supports patterns like game/**/*.js, game/**/*.ts, game/**/*.tsx
+  const normalized = pattern.replace(/\\/g, '/');
+  const recursive = normalized.match(/^(.*)\/\*\*\/\*\.([A-Za-z0-9]+)$/);
+  if (recursive) {
+    const base = recursive[1];
+    const ext = `.${recursive[2]}`;
+    const baseDir = path.join(projectRoot, base);
+    return walkFiles(baseDir, (f) => f.endsWith(ext));
+  }
+  const direct = path.join(projectRoot, normalized);
+  return fs.existsSync(direct) ? [direct] : [];
+}
+
+module.exports = { loadProfile, globFiles };

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

@@ -0,0 +1,59 @@
+"""Load and validate playable.ui.profile.yaml against JSON Schema."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+SKILL_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_SCHEMA = SKILL_ROOT / "schema" / "playable-ui-profile.schema.json"
+
+
+def load_schema(schema_path: Path | None = None) -> dict[str, Any]:
+    path = schema_path or DEFAULT_SCHEMA
+    with path.open(encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def load_profile(
+    profile_path: Path,
+    *,
+    schema_path: Path | None = None,
+    validate: bool = True,
+) -> dict[str, Any]:
+    with profile_path.open(encoding="utf-8") as fh:
+        profile = yaml.safe_load(fh)
+
+    if not isinstance(profile, dict):
+        raise ValueError(f"Profile must be a mapping: {profile_path}")
+
+    if validate:
+        validate_profile(profile, schema_path=schema_path)
+
+    return profile
+
+
+def validate_profile(profile: dict[str, Any], *, schema_path: Path | None = None) -> None:
+    try:
+        import jsonschema
+    except ImportError as exc:
+        raise RuntimeError("jsonschema is required: pip install jsonschema") from exc
+
+    schema = load_schema(schema_path)
+    jsonschema.validate(instance=profile, schema=schema)
+
+
+def resolve_project_path(profile_path: Path, relative: str) -> Path:
+    return (profile_path.parent / relative).resolve()
+
+
+def get_paths(profile: dict[str, Any], profile_path: Path) -> dict[str, Path]:
+    paths_cfg = profile.get("paths", {})
+    return {
+        key: resolve_project_path(profile_path, value)
+        for key, value in paths_cfg.items()
+        if isinstance(value, str)
+    }

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

@@ -0,0 +1,106 @@
+"""Unified pass / warn / fail reporting for UI verification scripts."""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Status(str, Enum):
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass
+class Finding:
+    check: str
+    status: Status
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Report:
+    findings: list[Finding] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def add(self, check: str, status: Status | str, message: str, **details: Any) -> None:
+        if isinstance(status, str):
+            status = Status(status)
+        self.findings.append(Finding(check=check, status=status, message=message, details=details))
+
+    def pass_(self, check: str, message: str, **details: Any) -> None:
+        self.add(check, Status.PASS, message, **details)
+
+    def warn(self, check: str, message: str, **details: Any) -> None:
+        self.add(check, Status.WARN, message, **details)
+
+    def fail(self, check: str, message: str, **details: Any) -> None:
+        self.add(check, Status.FAIL, message, **details)
+
+    @property
+    def worst(self) -> Status:
+        order = {Status.PASS: 0, Status.WARN: 1, Status.FAIL: 2}
+        if not self.findings:
+            return Status.PASS
+        return max(self.findings, key=lambda f: order[f.status]).status
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if self.worst == Status.FAIL else 0
+
+    def counts(self) -> dict[str, int]:
+        counts = {s.value: 0 for s in Status}
+        for finding in self.findings:
+            counts[finding.status.value] += 1
+        return counts
+
+    def merge(self, other: Report) -> None:
+        self.findings.extend(other.findings)
+
+    def print_summary(self, title: str = "Playable UI Verification") -> None:
+        counts = self.counts()
+        print(f"\n=== {title} ===")
+        for finding in self.findings:
+            icon = {"pass": "✓", "warn": "!", "fail": "✗"}[finding.status.value]
+            print(f"  [{icon}] {finding.check}: {finding.message}")
+        print(
+            f"\nSummary: {counts['pass']} pass, {counts['warn']} warn, {counts['fail']} fail"
+        )
+        if self.worst == Status.FAIL:
+            print("Result: FAIL")
+        elif self.worst == Status.WARN:
+            print("Result: PASS (with warnings)")
+        else:
+            print("Result: PASS")
+
+    def to_json(self) -> dict[str, Any]:
+        payload = {
+            "summary": self.counts(),
+            "worst": self.worst.value,
+            "findings": [
+                {**asdict(f), "status": f.status.value}
+                for f in self.findings
+            ],
+        }
+        payload.update(self.metadata)
+        return payload
+
+    def write_json(self, path: str) -> None:
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(self.to_json(), fh, indent=2, ensure_ascii=False)
+
+
+def exit_with_report(report: Report, *, json_path: str | None = None, json_stdout: bool = False) -> None:
+    if json_stdout:
+        print(json.dumps(report.to_json(), ensure_ascii=False))
+    elif json_path:
+        report.write_json(json_path)
+        report.print_summary()
+    else:
+        report.print_summary()
+    sys.exit(report.exit_code)