@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/skills/playable-validate/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: playable-validate
+description: >-
+  Validation loop for template-v2. Use after game code is runnable to verify
+  runtime contract, lifecycle phase path, first-win, fusion, placeholders, asset
+  sync, MP4 recording, and VLM video review. Iteration-2 optimize adds lifecycle
+  to the standard DoD sequence. UI layout validation is in playable-verify-ui.
+---
+
+# Playable Validate
+
+## Iteration-1 DoD 序列
+
+```bash
+npm run verify:env          # 环境预检 (Node/Python/Playwright)
+npm run verify:contract     # window.__playable 合约接线
+npm run verify:firstwin     # autoPlay() 能到达 ENDCARD
+npm run verify:fusion       # 多玩法融合接线 (单玩法自动 no-op)
+npm run record:mp4 -- --headed --fps=60
+npm run verify:vlm-video -- --record-first
+```
+
+## Iteration-2 DoD 序列（在 iter-1 序列基础上新增）
+
+```bash
+npm run verify:lifecycle    # phasePath: HOOK→TUTORIAL→GAMEPLAY→WIN/FAIL→ENDCARD 完整无跳跃
+```
+
+lifecycle 失败时：检查 phasePath 输出，定位哪个 phase 缺失，路由回 generate 修复状态机骨架。
+
+## 辅助检查（generate / optimize 阶段可按需运行）
+
+```bash
+npm run verify:placeholders      # ✅ 可用：代码引用的资产路径实际存在于磁盘
+npm run verify:asset-sync        # ✅ 可用：资产文件与代码引用双向一致
+npm run verify:runtime-contract  # ✅ 可用：静态合约检查（无需浏览器）
+
+# ⚠️ 暂不可用——需先创建 playable.ui.profile.yaml：
+# npm run verify:hardcoded-layout
+# python3 skills/playable-verify-ui/scripts/verify_fetch_antipatterns.py --root .
+```
+
+## Scope
+
+| 命令                      | 检查内容                                                      | 产出                      |
+| ------------------------- | ------------------------------------------------------------- | ------------------------- |
+| `verify:env`              | Node ≥20 / Python3 / Pillow / Playwright Chromium             | 控制台报告                |
+| `verify:contract`         | `window.__playable` 动态接线                                  | `validate/contract.json`  |
+| `verify:lifecycle`        | phasePath 顺序完整性（HOOK 开头，ENDCARD 结尾，中间节点存在） | `validate/lifecycle.json` |
+| `verify:firstwin`         | autoPlay 到达 ENDCARD + isGameOver                            | `validate/firstwin.json`  |
+| `verify:fusion`           | 多玩法 atom 融合类型 + 源码接线                               | `validate/fusion.json`    |
+| `verify:placeholders`     | 代码 load.image/atlas 路径磁盘存在                            | 控制台                    |
+| `verify:asset-sync`       | 资产↔代码双向引用一致                                         | 控制台                    |
+| `verify:runtime-contract` | 静态合约（无浏览器）                                          | 控制台                    |
+| `verify:hardcoded-layout` | 硬编码 px 宽高                                                | 控制台                    |
+| `record:mp4`              | headed 60fps MP4                                              | `recordings/*.mp4`        |
+| `verify:vlm-video`        | VLM 语义视频评审                                              | `validate/vlm-video.json` |
+
+## UI 布局验证
+
+文字叠加、fetch 反模式、布局区域规则等 UI 检查在 `playable-verify-ui` skill。

package/project-template-v2/skills/playable-validate/validation-rules.md

@@ -0,0 +1,14 @@
+# Validation Rules
+
+Current template-v2 iteration 1 validates the runtime/video path only.
+
+| Check            | Command                    | Pass condition                                                                          |
+| ---------------- | -------------------------- | --------------------------------------------------------------------------------------- |
+| Runtime contract | `npm run verify:contract`  | `window.__playable.autoPlay()` and `getState()` exist; initial phase is `HOOK`          |
+| First win        | `npm run verify:firstwin`  | Auto-play reaches `ENDCARD` with `isGameOver=true`                                      |
+| Fusion           | `npm run verify:fusion`    | Single gameplay atom no-ops; multi-atom projects document fusion and show source wiring |
+| Recording        | `npm run record:mp4`       | MP4 is produced without contract/runtime timeout                                        |
+| Video semantics  | `npm run verify:vlm-video` | No P0/fail findings in `vlm-video.json`                                                 |
+
+UI, atlas, layout, focus playground, and visual ring checks are deferred until
+their migration stage.

package/project-template-v2/skills/playable-verify-ui/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: playable-verify-ui
+description: >-
+  UI integrity checks for playable ads: static runtime contract and text overlap
+  detection. Use during iteration-2 generate/optimize when adding overlay UI
+  layers. verify:hardcoded-layout and verify_fetch_antipatterns require
+  playable.ui.profile.yaml and are NOT usable until that file is created.
+---
+
+# Playable Verify UI
+
+布局层和 UI 层的静态完整性检查。部分工具不需要浏览器或 profile 配置；部分工具依赖 `playable.ui.profile.yaml`，在 v2 模板中该文件尚未创建，标记为暂不可用。
+
+## 何时使用
+
+- 包装层新增 Tutorial 引导层、HUD、EndCard 等 UI 覆盖层时
+- optimize 阶段完整游戏评价前的 UI 快速自检
+
+## ✅ 可用命令
+
+```bash
+npm run verify:runtime-contract   # 静态合约：扫描 game/ 确认 window.__playable 接口声明存在
+python3 skills/playable-verify-ui/scripts/verify_text_overlap.py --root .
+# 文字叠加检测（需 Python3；无 tesseract 时 degraded pass，不 block）
+```
+
+## ⚠️ 暂不可用（需要 playable.ui.profile.yaml）
+
+下列工具依赖项目根目录的 `playable.ui.profile.yaml`，v2 模板尚未提供该文件。
+直接运行会报 profile 缺失错误，**不要在 DoD 中引用这两个命令**：
+
+```bash
+# ❌ 暂不可用
+npm run verify:hardcoded-layout
+python3 skills/playable-verify-ui/scripts/verify_fetch_antipatterns.py --root .
+```
+
+启用方式：参考 project-template 的 `examples/mahjong-match.profile.yaml`，
+创建并填写本项目的 `playable.ui.profile.yaml`，然后这两个命令才可使用。
+
+## 检查内容
+
+| 脚本                           | 状态          | 检查内容                                             | 失败含义                                  |
+| ------------------------------ | ------------- | ---------------------------------------------------- | ----------------------------------------- |
+| `verify_runtime_contract.js`   | ✅ 可用       | 静态扫描 game/ 确认 `window.__playable` 接口声明存在 | 接口未声明，动态 verify:contract 必然失败 |
+| `verify_text_overlap.py`       | ✅ 可用       | OCR 检测 CTA 区域文字是否重叠                        | Tutorial 文字 + HUD 文字在同区域叠加      |
+| `verify_hardcoded_layout.js`   | ⚠️ 需 profile | 检测 game/ 中直接写死的 px 宽高                      | 多分辨率适配和包装层叠加会错位            |
+| `verify_fetch_antipatterns.py` | ⚠️ 需 profile | 扫描是否有 placehold.co 等外部 fetch 引用            | 所有渠道禁止外部请求                      |
+
+## 与 verify:contract 的关系
+
+`verify:runtime-contract`（静态，无浏览器）和 `verify:contract`（动态，需 dev server）互补：
+
+- 静态版在 generate 阶段写完代码后即可运行，快速确认接口声明
+- 动态版在 optimize 阶段作为 DoD 项运行
+
+## 依赖
+
+- Node.js（`verify_runtime_contract.js`）
+- Python3（`verify_text_overlap.py`）
+- tesseract（可选，无 OCR 时 degraded pass）
+
+运行 `npm run verify:env` 确认环境满足要求。

package/project-template-v2/skills/playable-verify-ui/scripts/lib/__init__.py

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

package/project-template-v2/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-template-v2/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-template-v2/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-template-v2/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)