tirtc-device-builder 0.4.0 → 0.6.0

package/skills/tirtc-esp32-builder/scripts/install_audio_gate.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Install the portable audio semantic gate into a generated ESP-IDF project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+MARKER = "# tirtc-audio-semantic-gate-v1"
+BLOCK = f"""
+
+{MARKER}
+add_custom_target(tirtc_audio_semantic_gate ALL
+    COMMAND "${{PYTHON}}"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tools/verify_audio_contract.py"
+            "${{CMAKE_CURRENT_LIST_DIR}}/board-audio-contract.json"
+            --project "${{CMAKE_CURRENT_LIST_DIR}}"
+            --evidence-out "${{CMAKE_BINARY_DIR}}/audio-contract-evidence.json"
+    COMMENT "Validating codec clocks, I2S topology, slots and shared-signal handoff"
+    VERBATIM
+)
+add_dependencies(${{CMAKE_PROJECT_NAME}}.elf tirtc_audio_semantic_gate)
+"""
+
+
+def install(project: Path) -> None:
+    project = project.expanduser().resolve()
+    cmake = project / "CMakeLists.txt"
+    contract = project / "board-audio-contract.json"
+    if not cmake.is_file():
+        raise ValueError(f"ESP-IDF project CMakeLists.txt not found: {cmake}")
+    if not contract.is_file():
+        raise ValueError(
+            f"audio contract not found: {contract}; create and verify it before installing the gate"
+        )
+    tools = project / "tools"
+    tools.mkdir(parents=True, exist_ok=True)
+    destination = tools / "verify_audio_contract.py"
+    source = Path(__file__).resolve().with_name("audio_contract.py")
+    if destination.exists() and destination.read_bytes() != source.read_bytes():
+        raise ValueError(f"refusing to overwrite a different gate: {destination}")
+    if not destination.exists():
+        shutil.copyfile(source, destination)
+    text = cmake.read_text(encoding="utf-8")
+    if MARKER not in text:
+        cmake.write_text(text.rstrip() + BLOCK + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    args = parser.parse_args()
+    try:
+        install(args.project)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"installed TiRTC audio semantic gate: {args.project.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tirtc-esp32-builder/scripts/install_video_gate.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Install the portable TiRTC video semantic gate into an ESP-IDF project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+MARKER = "# tirtc-video-semantic-gate-v1"
+BLOCK = f"""
+
+{MARKER}
+add_custom_target(tirtc_video_semantic_gate ALL
+    COMMAND "${{PYTHON}}"
+            "${{CMAKE_CURRENT_LIST_DIR}}/tools/verify_video_contract.py"
+            "${{CMAKE_CURRENT_LIST_DIR}}/board-video-contract.json"
+            --project "${{CMAKE_CURRENT_LIST_DIR}}"
+            --evidence-out "${{CMAKE_BINARY_DIR}}/video-contract-evidence.json"
+    COMMENT "Validating camera lock, CPU isolation, complete JPEG framing, backpressure and memory"
+    VERBATIM
+)
+add_dependencies(${{CMAKE_PROJECT_NAME}}.elf tirtc_video_semantic_gate)
+"""
+
+
+def install(project: Path) -> None:
+    project = project.expanduser().resolve()
+    cmake = project / "CMakeLists.txt"
+    contract = project / "board-video-contract.json"
+    if not cmake.is_file():
+        raise ValueError(f"ESP-IDF project CMakeLists.txt not found: {cmake}")
+    if not contract.is_file():
+        raise ValueError(
+            f"video contract not found: {contract}; create and verify it before installing the gate"
+        )
+    tools = project / "tools"
+    tools.mkdir(parents=True, exist_ok=True)
+    destination = tools / "verify_video_contract.py"
+    source = Path(__file__).resolve().with_name("video_contract.py")
+    if destination.exists() and destination.read_bytes() != source.read_bytes():
+        raise ValueError(f"refusing to overwrite a different gate: {destination}")
+    if not destination.exists():
+        shutil.copyfile(source, destination)
+    text = cmake.read_text(encoding="utf-8")
+    if MARKER not in text:
+        cmake.write_text(text.rstrip() + BLOCK + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    args = parser.parse_args()
+    try:
+        install(args.project)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"installed TiRTC video semantic gate: {args.project.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tirtc-esp32-builder/scripts/project_portability.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Check that a generated TiRTC ESP32 source package can move to another machine."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ABSOLUTE_PATH = re.compile(r"(?:^|[\s\"'])(?:/home/|/root/|[A-Za-z]:[\\/])")
+BUILD_INPUT_NAMES = {"CMakeLists.txt", "idf_component.yml", "idf_component.yaml"}
+BUILD_INPUT_SUFFIXES = {".c", ".h", ".cmake", ".py", ".sh"}
+SKIP_PARTS = {"build", "managed_components", ".git"}
+
+
+def source_files(project: Path):
+    for path in project.rglob("*"):
+        relative = path.relative_to(project)
+        if not path.is_file() or SKIP_PARTS.intersection(relative.parts):
+            continue
+        if path.name in BUILD_INPUT_NAMES or path.suffix.lower() in BUILD_INPUT_SUFFIXES:
+            yield path
+
+
+def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    errors: list[str] = []
+    if not (project / "CMakeLists.txt").is_file():
+        return {"ok": False, "errors": ["CMakeLists.txt is missing"]}
+    if not (project / "dependencies.lock").is_file():
+        errors.append("dependencies.lock is missing")
+    sdk_required = (
+        project / "third_party" / "tirtc" / "include" / "tirtc" / "tiRTC.h",
+        project / "third_party" / "tirtc" / "lib" / "libTiRTC.a",
+        project / "third_party" / "tirtc" / "manifest" / "build-contract.env",
+    )
+    missing_sdk = [str(path.relative_to(project)) for path in sdk_required if not path.is_file()]
+    if missing_sdk:
+        errors.append("bundled TiRTC SDK is incomplete: " + ", ".join(missing_sdk))
+    if export and (project / "build" / "CMakeCache.txt").exists():
+        errors.append("export source contains build/CMakeCache.txt from another machine")
+
+    for path in source_files(project):
+        relative = path.relative_to(project)
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if ABSOLUTE_PATH.search(text):
+            errors.append(f"build input contains a machine-specific absolute path: {relative}")
+        if path.name == "CMakeLists.txt" or path.suffix.lower() == ".cmake":
+            for number, line in enumerate(text.splitlines(), 1):
+                stripped = line.strip()
+                if stripped.startswith("COMMAND ") and ".sh" in stripped:
+                    command = stripped[len("COMMAND ") :].lstrip('"')
+                    if not command.startswith("bash ") and not command.startswith("${BASH"):
+                        errors.append(
+                            f"shell gate relies on executable permission: {relative}:{number}"
+                        )
+    return {"ok": not errors, "errors": errors}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("project", type=Path)
+    parser.add_argument(
+        "--export",
+        action="store_true",
+        help="also reject a carried build/CMakeCache.txt",
+    )
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    result = check_project(args.project, export=args.export)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print("PASS: project source is relocatable")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tirtc-esp32-builder/scripts/video_contract.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Verify a project-local TiRTC video pipeline contract."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VIDEO_MEDIA = {
+    "mjpeg": "TIRTC_VIDEO_JPEG",
+    "h264": "TIRTC_VIDEO_H264",
+    "h265": "TIRTC_VIDEO_H265",
+}
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def project_file(project: Path, value: Any, label: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a non-empty project-relative path")
+    relative = Path(value)
+    if relative.is_absolute():
+        raise ValueError(f"{label} must be project-relative, got {value!r}")
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        raise ValueError(f"{label} escapes project root: {value!r}")
+    return resolved
+
+
+def mapping(value: Any, label: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be an object")
+        return {}
+    return value
+
+
+def positive_int(value: Any, label: str, errors: list[str]) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        errors.append(f"{label} must be a positive integer")
+        return None
+    return value
+
+
+def lock_versions(lock_text: str) -> dict[str, str]:
+    versions: dict[str, str] = {}
+    current: str | None = None
+    for line in lock_text.splitlines():
+        match = re.match(r"^  ([^ ].*):$", line)
+        if match:
+            current = match.group(1)
+            continue
+        if current is not None:
+            version = re.match(r"^    version:\s*['\"]?([^'\"\s]+)", line)
+            if version:
+                versions[current] = version.group(1)
+                current = None
+    return versions
+
+
+def check_dependencies(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    dependencies = contract.get("dependencies")
+    if not isinstance(dependencies, dict) or not dependencies:
+        errors.append("dependencies must map component names to exact locked versions")
+        return
+    lock = project / "dependencies.lock"
+    if not lock.is_file():
+        errors.append("dependencies.lock is missing")
+        return
+    text = lock.read_text(encoding="utf-8", errors="replace")
+    inputs["dependencies.lock"] = sha256_file(lock)
+    locked = lock_versions(text)
+    for name, expected in dependencies.items():
+        if not isinstance(name, str) or not isinstance(expected, str) or not expected:
+            errors.append("dependencies entries must be non-empty string pairs")
+        elif locked.get(name) != expected:
+            errors.append(
+                f"locked dependency mismatch for {name}: "
+                f"expected {expected}, got {locked.get(name, 'missing')}"
+            )
+
+
+def check_scheduler(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    scheduler = mapping(contract.get("scheduler"), "scheduler", errors)
+    wifi_core = scheduler.get("wifi_core")
+    camera_core = scheduler.get("camera_core")
+    for value, label in ((wifi_core, "wifi_core"), (camera_core, "camera_core")):
+        if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+            errors.append(f"scheduler.{label} must be an integer >= 0")
+    if isinstance(wifi_core, int) and isinstance(camera_core, int) and wifi_core == camera_core:
+        errors.append("camera event processing must not share the configured Wi-Fi core")
+    config_files = scheduler.get("config_files")
+    if not isinstance(config_files, list) or not config_files:
+        errors.append("scheduler.config_files must be a non-empty array")
+        return
+    for index, value in enumerate(config_files):
+        try:
+            config = project_file(project, value, f"scheduler.config_files[{index}]")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not config.is_file():
+            errors.append(f"scheduler config does not exist: {config}")
+            continue
+        text = config.read_text(encoding="utf-8", errors="replace")
+        inputs[str(config.relative_to(project))] = sha256_file(config)
+        if isinstance(camera_core, int) and f"CONFIG_CAMERA_CORE{camera_core}=y" not in text:
+            errors.append(f"{config.relative_to(project)} does not select camera core {camera_core}")
+        if isinstance(wifi_core, int) and f"CONFIG_CAMERA_CORE{wifi_core}=y" in text:
+            errors.append(f"{config.relative_to(project)} pins camera processing to Wi-Fi core {wifi_core}")
+    wifi_config_files = scheduler.get("wifi_config_files")
+    if not isinstance(wifi_config_files, list) or not wifi_config_files:
+        errors.append("scheduler.wifi_config_files must be a non-empty array")
+        return
+    for index, value in enumerate(wifi_config_files):
+        try:
+            config = project_file(
+                project, value, f"scheduler.wifi_config_files[{index}]"
+            )
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not config.is_file():
+            errors.append(f"Wi-Fi scheduler config does not exist: {config}")
+            continue
+        text = config.read_text(encoding="utf-8", errors="replace")
+        inputs[str(config.relative_to(project))] = sha256_file(config)
+        if (
+            isinstance(wifi_core, int)
+            and f"CONFIG_ESP_WIFI_TASK_PINNED_TO_CORE_{wifi_core}=y" not in text
+        ):
+            errors.append(
+                f"{config.relative_to(project)} does not pin Wi-Fi task to core {wifi_core}"
+            )
+
+
+def check_pipeline(contract: dict[str, Any], errors: list[str]) -> None:
+    camera = mapping(contract.get("camera"), "camera", errors)
+    codec = camera.get("codec")
+    if codec not in VIDEO_MEDIA:
+        errors.append("camera.codec must be one of h264, h265, mjpeg")
+    else:
+        boundary_field = (
+            "complete_jpeg_per_send"
+            if codec == "mjpeg"
+            else "complete_access_unit_per_send"
+        )
+        if camera.get(boundary_field) is not True:
+            errors.append(f"camera.{boundary_field} must be true")
+        expected_media = VIDEO_MEDIA[codec]
+        if camera.get("media") != expected_media:
+            errors.append(f"camera.media must be {expected_media} for {codec}")
+    if camera.get("stream_id") != 11:
+        errors.append("camera.stream_id must be 11 for the H5 video contract")
+    frame_buffers = positive_int(camera.get("frame_buffers"), "camera.frame_buffers", errors)
+    if frame_buffers is not None and frame_buffers < 2:
+        errors.append("camera.frame_buffers must be at least 2 for the selected realtime pipeline")
+    accepted_pids = camera.get("accepted_sensor_pids")
+    if (
+        not isinstance(accepted_pids, list)
+        or not accepted_pids
+        or any(
+            isinstance(pid, bool)
+            or not isinstance(pid, int)
+            or pid < 0
+            or pid > 0xFFFF
+            for pid in accepted_pids
+        )
+        or len(set(accepted_pids)) != len(accepted_pids)
+    ):
+        errors.append(
+            "camera.accepted_sensor_pids must be a non-empty unique uint16 array"
+        )
+    if camera.get("unknown_sensor_policy") != "reject":
+        errors.append("camera.unknown_sensor_policy must be reject")
+
+    memory = mapping(contract.get("memory"), "memory", errors)
+    send_buffer = positive_int(
+        memory.get("max_send_buffer_bytes"), "memory.max_send_buffer_bytes", errors
+    )
+    frame_field = (
+        "max_complete_jpeg_bytes"
+        if codec == "mjpeg"
+        else "max_complete_access_unit_bytes"
+    )
+    complete_frame = positive_int(
+        memory.get(frame_field), f"memory.{frame_field}", errors
+    )
+    backpressure = positive_int(
+        memory.get("video_backpressure_bytes"), "memory.video_backpressure_bytes", errors
+    )
+    if None not in (send_buffer, complete_frame, backpressure):
+        if complete_frame > backpressure:
+            errors.append(
+                "one complete encoded frame/access unit must fit below the "
+                "video backpressure threshold"
+            )
+        if backpressure >= send_buffer:
+            errors.append("video backpressure threshold must be lower than max send buffer")
+
+
+def check_assertions(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    assertions = contract.get("implementation_assertions")
+    if not isinstance(assertions, list) or not assertions:
+        errors.append("implementation_assertions must be a non-empty array")
+        return
+    for index, item in enumerate(assertions):
+        label = f"implementation_assertions[{index}]"
+        assertion = mapping(item, label, errors)
+        try:
+            source = project_file(project, assertion.get("file"), f"{label}.file")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not source.is_file():
+            errors.append(f"{label}.file does not exist: {source}")
+            continue
+        text = source.read_text(encoding="utf-8", errors="replace")
+        compact = re.sub(r"\s+", "", text)
+        inputs[str(source.relative_to(project))] = sha256_file(source)
+        for field, haystack, should_exist in (
+            ("contains", text, True),
+            ("contains_compact", compact, True),
+            ("absent", text, False),
+            ("absent_compact", compact, False),
+        ):
+            needles = assertion.get(field, [])
+            if not isinstance(needles, list) or any(
+                not isinstance(needle, str) or not needle for needle in needles
+            ):
+                errors.append(f"{label}.{field} must be an array of non-empty strings")
+                continue
+            for needle in needles:
+                found = needle in haystack
+                if found != should_exist:
+                    verb = "missing" if should_exist else "contains forbidden"
+                    errors.append(f"{label} {verb} {field} token: {needle}")
+
+
+def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    contract_file = contract_path.expanduser().resolve()
+    if not project.is_dir():
+        return {"ok": False, "errors": [f"project directory does not exist: {project}"]}
+    if not contract_file.is_file():
+        return {"ok": False, "errors": [f"video contract does not exist: {contract_file}"]}
+    if project != contract_file and project not in contract_file.parents:
+        return {"ok": False, "errors": ["video contract must be inside the project"]}
+    try:
+        contract = json.loads(contract_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "errors": [f"invalid video contract: {exc}"]}
+    if not isinstance(contract, dict):
+        return {"ok": False, "errors": ["video contract root must be an object"]}
+    errors: list[str] = []
+    inputs = {str(contract_file.relative_to(project)): sha256_file(contract_file)}
+    if contract.get("schema_version") != 1:
+        errors.append("schema_version must be 1")
+    evidence = contract.get("evidence")
+    if not isinstance(evidence, list) or len(evidence) < 2 or any(
+        not isinstance(item, str) or not item for item in evidence
+    ):
+        errors.append("evidence must contain at least two non-empty source IDs")
+    check_dependencies(project, contract, errors, inputs)
+    check_scheduler(project, contract, errors, inputs)
+    check_pipeline(contract, errors)
+    check_assertions(project, contract, errors, inputs)
+    camera = contract.get("camera", {})
+    memory = contract.get("memory", {})
+    return {
+        "ok": not errors,
+        "summary": (
+            f"codec={camera.get('codec')} stream={camera.get('stream_id')} "
+            f"buffers={camera.get('frame_buffers')} "
+            f"send_buffer={memory.get('max_send_buffer_bytes')}"
+        ),
+        "inputs": inputs,
+        "errors": errors,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Verify locked camera dependencies, scheduler isolation, JPEG framing, memory, and adapter assertions."
+    )
+    parser.add_argument("contract", type=Path)
+    parser.add_argument("--project", type=Path, required=True)
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--evidence-out", type=Path)
+    args = parser.parse_args()
+    result = verify_contract(args.contract, args.project)
+    if args.evidence_out is not None:
+        output = args.evidence_out.expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print(f"PASS: video semantic contract: {result['summary']}")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())