@remixmate/cli 0.1.0

package/skills/template-bind/scripts/check_contracts.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Cross-module contract checker: template-library ↔ remotion-renderer.
+
+Verifies that every `compositionId` referenced from the @ab-templates/metadata
+registry.json is:
+  1. Registered in `<monorepo-root>/remotion-renderer/src/core/compositions/manifest.ts`
+  2. Mapped there to the SAME `templateId` as the template entry's
+     top-level `templateId` field
+
+Exit non-zero with a useful diff if the two sides disagree.
+
+Usage:
+    python3 scripts/check_contracts.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Iterator
+
+from template_paths import monorepo_registry_path, monorepo_root
+
+_REGISTRY_PATH = monorepo_registry_path()
+_MANIFEST_PATH = os.path.abspath(
+    os.path.join(
+        monorepo_root(),
+        "remotion-renderer",
+        "src",
+        "core",
+        "compositions",
+        "manifest.ts",
+    )
+)
+
+
+# Matches a single manifest row:
+#   SomeCompositionId: { component: Foo, templateId: "t-id", slot: "opening" },
+_MANIFEST_ROW_RE = re.compile(
+    r'^\s*(?P<cid>[A-Za-z0-9_]+)\s*:\s*\{\s*'
+    r'component\s*:\s*[A-Za-z0-9_]+\s*,\s*'
+    r'templateId\s*:\s*"(?P<tid>[^"]+)"\s*,\s*'
+    r'slot\s*:\s*"(?P<slot>[^"]+)"\s*\}\s*,?\s*$'
+)
+
+
+def parse_manifest(path: str) -> dict[str, dict[str, str]]:
+    """Parse manifest.ts and return {compositionId: {templateId, slot}}."""
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"manifest.ts not found at {path}")
+
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    start_marker = "// MANIFEST_ENTRIES:START"
+    end_marker = "// MANIFEST_ENTRIES:END"
+    start = text.find(start_marker)
+    end = text.find(end_marker)
+    if start == -1 or end == -1 or end < start:
+        raise ValueError(
+            f"manifest.ts is missing {start_marker} / {end_marker} markers"
+        )
+
+    block = text[start:end]
+    entries: dict[str, dict[str, str]] = {}
+    for line in block.splitlines():
+        m = _MANIFEST_ROW_RE.match(line)
+        if not m:
+            continue
+        entries[m.group("cid")] = {
+            "templateId": m.group("tid"),
+            "slot": m.group("slot"),
+        }
+
+    if not entries:
+        raise ValueError(
+            f"No manifest entries parsed from {path}. Did the format change?"
+        )
+    return entries
+
+
+def _iter_composition_ids(node: object) -> Iterator[str]:
+    """Walk an arbitrary JSON tree and yield every `compositionId` value."""
+    if isinstance(node, dict):
+        cid = node.get("compositionId")
+        if isinstance(cid, str):
+            yield cid
+        for v in node.values():
+            yield from _iter_composition_ids(v)
+    elif isinstance(node, list):
+        for v in node:
+            yield from _iter_composition_ids(v)
+
+
+def collect_template_references(registry_path: str) -> list[dict[str, str]]:
+    """Return a list of {templateId, compositionId, file} for every reference in the registry."""
+    refs: list[dict[str, str]] = []
+    if not os.path.isfile(registry_path):
+        print(f"WARN: registry.json not found at {registry_path}", file=sys.stderr)
+        return refs
+
+    with open(registry_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    for tpl in data.get("templates", []):
+        tid = tpl.get("templateId")
+        if not tid:
+            continue
+        for cid in _iter_composition_ids(tpl):
+            refs.append({"templateId": tid, "compositionId": cid, "file": registry_path})
+    return refs
+
+
+def main() -> int:
+    try:
+        manifest = parse_manifest(_MANIFEST_PATH)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"FAIL: {e}", file=sys.stderr)
+        return 2
+
+    refs = collect_template_references(_REGISTRY_PATH)
+
+    errors: list[str] = []
+    seen: set[str] = set()
+
+    for ref in refs:
+        cid = ref["compositionId"]
+        tid = ref["templateId"]
+        rel = os.path.relpath(ref["file"], monorepo_root())
+        seen.add(cid)
+
+        entry = manifest.get(cid)
+        if entry is None:
+            errors.append(
+                f"{rel}: compositionId '{cid}' is referenced but not in manifest.ts"
+            )
+            continue
+        if entry["templateId"] != tid:
+            errors.append(
+                f"{rel}: compositionId '{cid}' is registered under templateId "
+                f"'{entry['templateId']}' in manifest.ts, but template.json declares "
+                f"templateId '{tid}'"
+            )
+
+    # Warn (non-fatal) about manifest entries never referenced by any template.
+    unused = sorted(set(manifest.keys()) - seen)
+    for cid in unused:
+        print(
+            f"WARN: manifest.ts entry '{cid}' is not referenced by any "
+            f"template.json (templateId={manifest[cid]['templateId']})",
+            file=sys.stderr,
+        )
+
+    # P1.1 nudge (warning only): compositionId should be prefixed with
+    # `<templateId>/` so the 300-400 names we'll have at 100+ templates can't
+    # collide in the flat global namespace. The actual migration touches
+    # remotion-renderer/manifest.ts and every template.json, so we ship the
+    # warning first to surface the gap without breaking builds.
+    unprefixed: list[tuple[str, str]] = []
+    for ref in refs:
+        cid = ref["compositionId"]
+        tid = ref["templateId"]
+        expected_prefix = f"{tid}/"
+        # Allow either `<tid>/Cover` or `<tid>.Cover` (TS member access form).
+        if not (cid.startswith(expected_prefix) or cid.startswith(f"{tid}.")):
+            unprefixed.append((tid, cid))
+    if unprefixed:
+        print(
+            "WARN (P1.1): the following compositionIds are not prefixed with their "
+            "templateId — at 100+ templates this flat namespace will collide. "
+            "Migration plan: rename `<cid>` to `<templateId>/<cid>` in both "
+            "template.json and remotion-renderer/manifest.ts.",
+            file=sys.stderr,
+        )
+        for tid, cid in unprefixed[:10]:
+            print(f"  - {tid}: '{cid}' → suggested '{tid}/{cid}'", file=sys.stderr)
+        if len(unprefixed) > 10:
+            print(f"  ... ({len(unprefixed)} total)", file=sys.stderr)
+
+    if errors:
+        print("FAIL: contract check found inconsistencies:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        return 1
+
+    print(
+        f"OK: {len(refs)} compositionId references across "
+        f"{len({r['templateId'] for r in refs})} templates match manifest.ts "
+        f"({len(manifest)} entries)."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/template-bind/scripts/match_template.py

@@ -0,0 +1,215 @@
+"""
+template-bind 库模块 — DSL → TemplateBinding 的纯函数实现。
+
+仅作为 Python library 被 render-video 的 render_video.py / gen-script 的
+gen_script.py 通过 `sys.path.insert` 后 `import match_template` 引入；
+对外不再暴露 CLI（template-bind skill 已迁移到 ab-skill CLI 的 builtin
+handler，由 src/handlers/template-bind.ts 处理 --list-templates）。
+
+提供的公共接口：
+  load_registry()                 → list[dict]   模板列表
+  load_full_template(template)    → dict         模板完整定义（registry 自带，原样返回）
+  build_binding(template, dsl)    → dict         DSL → TemplateBinding
+"""
+
+from registry_loader import load_registry_data
+
+
+def load_registry() -> list:
+    """Load template list via the unified registry loader."""
+    return load_registry_data().get("templates", [])
+
+
+def load_full_template(template: dict) -> dict:
+    """Load the full template definition.
+
+    Since the metadata registry.json now contains the complete template
+    definition (including slotMapping, compositions, etc.), this simply
+    returns the template as-is.
+    """
+    return template
+
+
+def _resolve_slot_def(slot_mapping: dict, purpose: str) -> dict:
+    """Resolve a slotMapping entry, following $ref chains (max depth 10)."""
+    slot_def = slot_mapping.get(purpose) or slot_mapping.get("default") or {}
+    visited: set = set()
+    while "$ref" in slot_def:
+        ref = slot_def["$ref"]
+        if ref in visited:
+            break
+        visited.add(ref)
+        slot_def = slot_mapping.get(ref) or {}
+    return slot_def
+
+
+def _extract_prop(scene: dict, extractor: dict):
+    """Extract a single prop value from a scene using an extractor definition.
+
+    Supports two extractor patterns:
+      { "from": "textLayers", "role": "headline" }   – search textLayers by role
+      { "from": "visuals.background.assetRef" }      – dotted-path traversal
+    """
+    source = extractor.get("from", "")
+
+    # textLayers extractor
+    if source == "textLayers":
+        role = extractor.get("role", "")
+        for tl in scene.get("textLayers") or []:
+            if tl.get("role") == role:
+                return tl.get("content")
+        return None
+
+    # Dotted-path extractor
+    val = scene
+    for part in source.split("."):
+        if not isinstance(val, dict):
+            return None
+        val = val.get(part)
+    return val
+
+
+def build_binding(template: dict, dsl: dict) -> dict:
+    """Build a TemplateBinding from template and DSL."""
+    bindings = []
+    slot_mapping = template.get("slotMapping", {})
+
+    for idx, scene in enumerate(dsl.get("scenes", [])):
+        scene_id = scene.get("id") or scene.get("sceneId") or f"scene-{idx:03d}"
+        purpose = scene.get("purpose", "point")
+
+        slot_def = _resolve_slot_def(slot_mapping, purpose)
+        comp_id = slot_def.get("compositionId", "GenericScene")
+        slot_id = slot_def.get("slotId", f"{purpose}-slot")
+
+        # 用模板的 propExtractors 提取 props
+        props = {}
+        for prop_name, extractor in slot_def.get("propExtractors", {}).items():
+            val = _extract_prop(scene, extractor)
+            if val is not None:
+                props[prop_name] = val
+
+        # P1.3: props 提取仅保留两条路径——
+        #   (1) 显式 propExtractors（上面的 _extract_prop 调用）
+        #   (4) customPayload 全字段透传（顶层 + templateData）— 模板内部 schema
+        # 去掉了原来的"白名单同名隐式透传"两层 fallback，因为它们让"字段写在哪"
+        # 这个问题变得不可预测：同一字段写在 optionalProps + propExtractors
+        # 里时优先级会冲突，让 AI 反复出错。
+        #
+        # 顶层透传是必要的：DSL 示例（hermes-agent-purple / vibe-coding 等）以
+        # `customPayload.slideId` 顶层声明 slide id，而 html-slide 模板的
+        # `propExtractors.slideId` 只声明从 templateData.slideId 取值。如果不
+        # 同时透传顶层，slideId 就会缺失，html-slide 的 `point` slot 把
+        # slideId 设为 requiredProps，缺失会导致 React 端回退到通用「标题 +
+        # 字幕」兜底样式，所有场景看起来都是同一个布局。
+        custom = scene.get("customPayload") or {}
+        template_data = custom.get("templateData") or scene.get("templateData") or {}
+        # 先注入 templateData.* 再注入顶层 customPayload.*，让顶层覆盖同名值
+        for k, v in template_data.items():
+            if k not in props:
+                props[k] = v
+        for k, v in custom.items():
+            if k == "templateData":
+                continue
+            if k not in props:
+                props[k] = v
+
+        # animationHints 可能为 null
+        anim = scene.get("animationHints") or {}
+        entrance = anim.get("entrance", "fade")
+        transition_type = entrance if entrance != "none" else "cut"
+
+        bindings.append({
+            "sceneId": scene_id,
+            "slotId": slot_id,
+            "compositionId": comp_id,
+            "layoutVariant": scene.get("layout", "full-visual"),
+            "props": props,
+            "transitionIn": {"type": transition_type, "durationFrames": 15},
+            "transitionOut": {"type": "fade", "durationFrames": 15},
+        })
+
+    # P1.2: 不再做 screen-walkthrough 专属的截断 / 兜底。模板的 propExtractors
+    # 已声明 titleText ← textLayers[role=headline]、projectName ← textLayers[role=subheadline]，
+    # gen_script 在每个场景都填入了 headline / subheadline，因此 props 由提取器
+    # 直接产出，不再需要后处理。
+
+    typography = template.get("defaultTypography", {})
+    motion = template.get("defaultMotionPreset", "smooth")
+    colors = template.get("defaultColorScheme", [])
+
+    # --- variant selection ---
+    # 优先级：
+    #   1) DSL 显式声明 — meta.templateVariant / renderHints.templateVariant
+    #   2) DSL meta.style / renderHints.brandColors 与 variant.styleTags 的子串/包含匹配
+    # 显式声明优先是因为：
+    #   - 风格名（如 "紫色科技"）在不同 variant 的 styleTags 里可能多义；
+    #   - meta.style 经常是一整串短语而非单 tag，旧的"逐 tag 拼成空格 → 子串匹配"
+    #     会被 split 后的整段短语漏过（例如 "紫色科技" 不是 "紫色 科技 purple ..."
+    #     的子串）。显式 templateVariant 让作者可以一锤定音。
+    variant_id = None
+    meta = dsl.get("meta", {}) or {}
+    render_hints = dsl.get("renderHints", {}) or {}
+    explicit_variant = (
+        meta.get("templateVariant")
+        or meta.get("variant")
+        or render_hints.get("templateVariant")
+    )
+    variants = template.get("variants", {}) or {}
+
+    if explicit_variant and explicit_variant in variants:
+        variant_id = explicit_variant
+    else:
+        # Fallback: 把 meta.style 拆成更细的 token（按逗号 / 空白 / 中英标点 / 单字）
+        # 再到 variant.styleTags 里找任一包含或被包含关系。这样 "紫色科技" 既能命中
+        # ["紫色","科技"] 这种细粒度 tag，也能命中 ["紫色科技"] 这种整段 tag。
+        raw_style = (meta.get("style") or "").strip().lower()
+        if raw_style:
+            # 整段 + 逗号/分号/空白拆分 + 单中文字符级 token，统一去重
+            style_tokens = {raw_style}
+            for sep in [",", "，", ";", "；", " ", "/", "·"]:
+                raw_style = raw_style.replace(sep, ",")
+            for tok in raw_style.split(","):
+                tok = tok.strip()
+                if not tok:
+                    continue
+                style_tokens.add(tok)
+                # 中文按字拆，命中如 "紫"/"色"/"科"/"技" 这种单字 tag 的场景
+                for ch in tok:
+                    if "\u4e00" <= ch <= "\u9fff":
+                        style_tokens.add(ch)
+            for vid, variant in variants.items():
+                vtags = [str(t).strip().lower() for t in variant.get("styleTags", [])]
+                # 任一 tag 与任一 style token 互为子串即视为匹配
+                if any(any(tok in tag or tag in tok for tag in vtags) for tok in style_tokens if tok):
+                    variant_id = vid
+                    break
+
+    if variant_id and variant_id in variants:
+        variant = variants[variant_id]
+        vtypo = variant.get("defaultTypography")
+        if vtypo:
+            typography = {**typography, **vtypo}
+        vmotion = variant.get("defaultMotionPreset")
+        if vmotion:
+            motion = vmotion
+        vcolors = variant.get("defaultColorScheme")
+        if vcolors:
+            colors = vcolors
+
+    result = {
+        "version": "v1alpha1",
+        "templateId": template.get("templateId", ""),
+        "templateName": template.get("name", ""),
+        "globalOverrides": {
+            "typography": typography,
+            "motionPreset": motion,
+            "colorScheme": colors,
+        },
+        "bindings": bindings,
+    }
+    if variant_id:
+        result["variantId"] = variant_id
+    return result
+
+