@playcraft/cli 0.1.28 → 0.1.29

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

@@ -1,61 +0,0 @@
----
-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

@@ -1,14 +0,0 @@
-# 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

@@ -1,63 +0,0 @@
----
-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

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

package/project-template-v2/skills/playable-verify-ui/scripts/lib/config_expr.js

@@ -1,218 +0,0 @@
-'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

@@ -1,51 +0,0 @@
-'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

@@ -1,59 +0,0 @@
-"""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

@@ -1,106 +0,0 @@
-"""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)