Add idempotent native release installer with external ASR boundary

scripts/install_payload.py

@@ -0,0 +1,455 @@
+"""FrameYap installer implementation. Embedded verbatim in install.sh for piped installs."""
+import argparse
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from urllib.parse import quote
+
+KEY = "local.frameyap.overlay"
+MARKER = "# FrameYap managed launcher v1\n"
+ARCHIVE_LIMIT = 12 * 1024**3
+MEMBER_LIMIT = 50000
+VERSION_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,95}\Z")
+DIGEST_RE = re.compile(r"[a-fA-F0-9]{64}\Z")
+
+
+def fail(message):
+    raise ValueError(message)
+
+
+def json_atomic(path, value):
+    atomic_write(path, (json.dumps(value, indent=2, sort_keys=True) + "\n").encode())
+
+
+def atomic_write(path, content, mode=0o600):
+    fd, name = tempfile.mkstemp(prefix=".frameyap-", dir=path.parent)
+    try:
+        os.fchmod(fd, mode)
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def owned_dir(path):
+    if path.is_symlink():
+        fail(f"refusing symlink directory: {path}")
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if not path.is_dir():
+        fail(f"not a directory: {path}")
+
+
+def check_host():
+    if sys.platform != "linux" or platform.machine().lower() not in ("aarch64", "arm64"):
+        fail("release requires Linux AArch64 (ARM64); no cross-architecture install")
+    if platform.libc_ver()[0] != "glibc":
+        fail("release requires glibc Linux; libc compatibility still requires native testing")
+
+
+def digest_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def check_digest(value):
+    if not DIGEST_RE.fullmatch(value):
+        fail("--sha256 must be a 64-character hex SHA-256")
+    return value.lower()
+
+
+def check_version(value):
+    if not VERSION_RE.fullmatch(value) or value in (".", ".."):
+        fail("invalid release version/tag")
+    return value
+
+
+def release_name(version):
+    return f"frameyap-{version}-linux-aarch64.tar.gz"
+
+
+def download(url, destination):
+    subprocess.run(["curl", "--fail", "--silent", "--show-error", "--location", "--proto", "=https",
+                    "--proto-redir", "=https", "--tlsv1.2", "--max-filesize",
+                    str(4096 if url.endswith(".sha256") else ARCHIVE_LIMIT),
+                    "--output", str(destination), url], check=True)
+
+
+def verify_members(archive):
+    seen = set()
+    total = 0
+    count = 0
+    for member in archive:
+        count += 1
+        if count > MEMBER_LIMIT:
+            fail("too many archive members")
+        name = member.name
+        parts = name.rstrip("/").split("/")
+        if (not name or name.startswith("/") or len(name) > 1024 or len(parts) > 32
+                or any(x in ("", ".", "..") for x in parts)
+                or "\\" in name or "\x00" in name):
+            fail(f"unsafe archive path: {name!r}")
+        if name in seen:
+            fail(f"duplicate archive member: {name}")
+        seen.add(name)
+        if not (member.isfile() or member.isdir()):
+            fail(f"archive links and special files forbidden: {name}")
+        if member.size < 0 or member.size > ARCHIVE_LIMIT:
+            fail("oversized archive member")
+        if name == "release.json" and member.size > 8192:
+            fail("oversized release metadata")
+        total += member.size
+        if total > ARCHIVE_LIMIT:
+            fail("archive uncompressed limit exceeded")
+        if (parts[0] not in ("release.json", "bin", "lib", "assets", "python", "runtime", "model", "fonts", "licenses")
+                or (parts[0] == "release.json" and (len(parts) != 1 or not member.isfile()))
+                or (len(parts) == 1 and parts[0] != "release.json" and not member.isdir())):
+            fail(f"unexpected archive path: {name}")
+
+
+def extract(archive_path, destination):
+    with tarfile.open(archive_path, "r:gz") as archive:
+        verify_members(archive)
+    with tarfile.open(archive_path, "r:gz") as archive:
+        for member in archive:
+            target = destination.joinpath(*member.name.rstrip("/").split("/"))
+            if member.isdir():
+                owned_dir(target)
+            else:
+                owned_dir(target.parent)
+                # Never follow a pre-existing link, including one created by the archive.
+                with target.open("xb") as out, archive.extractfile(member) as source:
+                    shutil.copyfileobj(source, out, 1024 * 1024)
+                # Retain executable helpers/shared libraries; discard all other mode bits.
+                target.chmod(0o700 if member.mode & 0o111 else 0o600)
+
+
+def validate_payload(root, version, without_model=False, installed=False):
+    meta = json.loads((root / "release.json").read_text())
+    if not isinstance(meta, dict):
+        fail("invalid release metadata")
+    if meta.get("schema") != 1 or meta.get("version") != version or meta.get("arch") != "linux-aarch64":
+        fail("release metadata version/architecture/schema mismatch")
+    if meta.get("runtime") not in ("bundled-cpu-python", "external-authorized-python") or not isinstance(meta.get("model_revision"), str) or not meta["model_revision"]:
+        fail("missing runtime/model revision declaration")
+    has_model = meta.get("includes_model")
+    if not isinstance(has_model, bool) or (not installed and not has_model and (root / "model").exists()):
+        fail("inconsistent model declaration")
+    if has_model and not (root / "model").is_dir() and not (installed and without_model and not (root / "model").exists()):
+        fail("missing declared model")
+    if meta["runtime"] == "external-authorized-python" and (root / "runtime").exists():
+        fail("external runtime payload must not include a runtime")
+    for name in ("bin/frameyap", "runtime/bin/python3", "python/frameyap/worker.py", "assets/actions.json", "fonts/font.ttf"):
+        if name == "runtime/bin/python3" and meta["runtime"] == "external-authorized-python":
+            continue
+        if not (root / name).is_file():
+            fail(f"missing payload file: {name}")
+    for name in ("lib", "fonts"):
+        if not (root / name).is_dir() or not any((root / name).iterdir()):
+            fail(f"missing payload directory: {name}")
+    return meta
+
+
+def selected(root, link):
+    path = root / link
+    if not path.is_symlink():
+        if path.exists():
+            fail(f"refusing foreign selection path: {path}")
+        return None
+    value = os.readlink(path)
+    if not re.fullmatch(r"versions/[A-Za-z0-9][A-Za-z0-9._-]{0,95}", value):
+        fail(f"invalid {link} selection")
+    if not (root / value).is_dir():
+        fail(f"broken {link} selection")
+    return value
+
+
+def select(root, link, target):
+    path = root / link
+    temp = root / ("." + link + "-" + str(os.getpid()))
+    try:
+        os.symlink(target, temp)
+        os.replace(temp, path)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def desired_launcher(root):
+    import shlex
+    q = lambda path: shlex.quote(str(path))
+    font = root / "current/fonts/font.ttf"
+    base = root / "current"
+    flags = ["--assets", base / "assets", "--font", font,
+             "--worker", base / "python/frameyap/worker.py"]
+    args = " ".join(q(item) for item in flags)
+    return ("#!/bin/sh\n" + MARKER + 'export PYTHONDONTWRITEBYTECODE=1\n'
+            + f'export FRAMEYAP_INSTALL_ROOT={q(root)}\n'
+            + f'export LD_LIBRARY_PATH={q(base / "lib")}${{LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}}\n'
+            + f'PYTHON=${{FRAMEYAP_PYTHON:-{q(base / "runtime/bin/python3")}}}\n'
+            + f'MODEL=${{FRAMEYAP_MODEL:-{q(base / "model")}}}\n'
+            + 'if [ "$#" -eq 0 ]; then set -- --run; fi\n'
+            + 'case "$1" in\n'
+            + '  --run)\n'
+            + '    if [ -n "${GAMESCOPE_SOCKET:-}" ]; then set -- "$@" --socket "$GAMESCOPE_SOCKET"; fi\n'
+            + f"    shift; exec {q(base / 'bin/frameyap')} --run {args} --python \"$PYTHON\" --model \"$MODEL\" \"$@\";;\n"
+            + f"  --check-overlay|--check-controls) mode=$1; shift; exec {q(base / 'bin/frameyap')} \"$mode\" --assets {q(base / 'assets')} --font {q(font)} \"$@\";;\n"
+            + f"  *) exec {q(base / 'bin/frameyap')} \"$@\";;\n"
+            + 'esac\n').encode()
+
+
+def desired_manifest(launcher):
+    return {"source": "builtin", "applications": [{"app_key": KEY, "launch_type": "binary",
+            "binary_path_linux": str(launcher), "binary_path_linux_arm": str(launcher),
+            "is_dashboard_overlay": True,
+            "strings": {"en_us": {"name": "FrameYap"}}}]}
+
+
+def check_owned_file(path, expected):
+    if path.is_symlink():
+        fail(f"refusing foreign symlink: {path}")
+    if path.exists():
+        if not path.is_file():
+            fail(f"refusing foreign path: {path}")
+        data = path.read_bytes()
+        if data != expected:
+            fail(f"refusing to replace modified/foreign file: {path}")
+
+
+def check_wrappers(root, launcher):
+    manifest = root / "frameyap.vrmanifest"
+    desired = (json.dumps(desired_manifest(launcher), sort_keys=True, indent=2) + "\n").encode()
+    check_owned_file(launcher, desired_launcher(root))
+    check_owned_file(manifest, desired)
+    return manifest, desired
+
+
+def install_files(root, installed, launcher):
+    owned_dir(launcher.parent)
+    manifest, desired = check_wrappers(root, launcher)
+    atomic_write(launcher, desired_launcher(root), 0o755)
+    atomic_write(manifest, desired)
+
+
+def receipt(path):
+    marker = path / ".archive-sha256"
+    if marker.is_symlink() or not marker.is_file() or not DIGEST_RE.fullmatch(marker.read_text().strip()):
+        fail(f"refusing unowned installation directory: {path}")
+    return marker.read_text().strip()
+
+
+def inventory(path):
+    return sorted(p.relative_to(path).as_posix() for p in path.rglob("*")
+                  if p.relative_to(path).parts[0] != "model"
+                  and p.relative_to(path).as_posix() not in (".archive-sha256", ".installed-files.json", ".install-options.json"))
+
+
+def check_inventory(path):
+    index = path / ".installed-files.json"
+    if not index.is_file() or index.is_symlink():
+        fail(f"missing installation inventory: {path}")
+    declared = json.loads(index.read_text())
+    if not isinstance(declared, list) or inventory(path) != declared:
+        fail(f"refusing to remove untracked files in: {path}")
+    for p in path.rglob("*"):
+        if p.is_symlink() and p.relative_to(path).parts[0] != "model":
+            fail(f"refusing link inside installation: {p}")
+
+
+def installed_choice(path):
+    receipt(path)
+    options = path / ".install-options.json"
+    if not options.is_file() or options.is_symlink():
+        fail(f"missing installation options: {path}")
+    choice = json.loads(options.read_text())
+    if not isinstance(choice, dict) or set(choice) != {"without_model"} or not isinstance(choice["without_model"], bool):
+        fail(f"invalid installation options: {path}")
+    return choice["without_model"]
+
+
+def do_install(args, root, launcher):
+    version = check_version(args.version)
+    versions = root / "versions"
+    owned_dir(versions)
+    current = selected(root, "current")
+    selected(root, "previous")
+    # Refuse foreign wrappers/launcher directories before installing a new version.
+    owned_dir(launcher.parent)
+    check_wrappers(root, launcher)
+    if args.archive:
+        archive = Path(args.archive).expanduser().resolve(strict=True)
+        expected = check_digest(args.sha256)
+        do_download = False
+    else:
+        do_download = True
+        archive = None
+    with tempfile.TemporaryDirectory(prefix=".download-", dir=root) as td:
+        if do_download:
+            name = release_name(version)
+            url = f"https://github.com/{args.repo}/releases/download/{quote(version)}/{name}"
+            archive = Path(td) / name
+            sidecar = Path(td) / (name + ".sha256")
+            download(url + ".sha256", sidecar)
+            if sidecar.stat().st_size > 4096:
+                fail("oversized SHA-256 sidecar")
+            line = sidecar.read_text().strip()
+            match = re.fullmatch(r"([a-fA-F0-9]{64})  " + re.escape(name), line)
+            if not match:
+                fail("invalid versioned SHA-256 sidecar")
+            expected = match.group(1).lower()
+            download(url, archive)
+        if archive.stat().st_size > ARCHIVE_LIMIT:
+            fail("compressed archive exceeds limit")
+        if not do_download:
+            local_copy = Path(td) / "local-archive.tar.gz"
+            shutil.copyfile(archive, local_copy)
+            archive = local_copy
+        if digest_file(archive) != expected:
+            fail("archive SHA-256 mismatch")
+        target = versions / version
+        if target.exists() or target.is_symlink():
+            if target.is_symlink() or receipt(target) != expected:
+                fail("same version already installed with different archive digest")
+            if installed_choice(target) != args.without_model:
+                fail("same version already installed with different --without-model choice")
+            check_inventory(target)
+            validate_payload(target, version, args.without_model, installed=True)
+        else:
+            temp = Path(tempfile.mkdtemp(prefix=".staging-", dir=versions))
+            try:
+                extract(archive, temp)
+                validate_payload(temp, version)
+                if args.without_model and (temp / "model").exists():
+                    shutil.rmtree(temp / "model")
+                json_atomic(temp / ".installed-files.json", inventory(temp))
+                json_atomic(temp / ".install-options.json", {"without_model": args.without_model})
+                (temp / ".archive-sha256").write_text(expected + "\n")
+                os.replace(temp, target)
+            finally:
+                if temp.exists():
+                    shutil.rmtree(temp)
+        install_files(root, target, launcher)
+        if current == f"versions/{version}":
+            print(f"FrameYap {version}: already installed (same digest); wrappers verified")
+            return
+        if current and current != f"versions/{version}":
+            select(root, "previous", current)
+        select(root, "current", f"versions/{version}")
+        print(f"FrameYap {version} installed. OpenVR registration is NOT automatic; see docs/packaging.md.")
+        if json.loads((target / "release.json").read_text())["runtime"] == "external-authorized-python":
+            print("ASR runtime is NOT included. Supply an independently authorized environment with FRAMEYAP_PYTHON or --python; no packages are downloaded.")
+
+
+def uninstall(root, launcher):
+    current = selected(root, "current")
+    previous = selected(root, "previous")
+    manifest = root / "frameyap.vrmanifest"
+    desired = (json.dumps(desired_manifest(launcher), sort_keys=True, indent=2) + "\n").encode()
+    check_owned_file(manifest, desired)
+    check_owned_file(launcher, desired_launcher(root))
+    versions = root / "versions"
+    if versions.exists():
+        if versions.is_symlink():
+            fail("refusing symlink versions directory")
+        for item in versions.iterdir():
+            if not item.is_dir() or item.is_symlink() or item.name.startswith("."):
+                fail(f"unexpected versions entry: {item}")
+            choice = installed_choice(item)
+            check_inventory(item)
+            validate_payload(item, item.name, choice, installed=True)
+            if (item / "model").exists() or (item / "model").is_symlink():
+                saved = root / "saved-models"
+                owned_dir(saved)
+                target = saved / item.name
+                if target.exists() or target.is_symlink():
+                    fail(f"saved model already exists: {target}")
+        for item in versions.iterdir():
+            if (item / "model").exists() or (item / "model").is_symlink():
+                os.replace(item / "model", root / "saved-models" / item.name)
+            shutil.rmtree(item)
+    for link in ("current", "previous"):
+        (root / link).unlink(missing_ok=True)
+    if launcher.exists():
+        launcher.unlink()
+    if manifest.exists():
+        manifest.unlink()
+    print("FrameYap removed; config and saved models preserved. OpenVR unregister acknowledgement was required.")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="install.sh", description="User-local FrameYap release installer (no SteamVR actions)")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--archive", help="local release archive (requires --sha256 and --version)")
+    mode.add_argument("--rollback", action="store_true")
+    mode.add_argument("--uninstall", action="store_true")
+    parser.add_argument("--sha256")
+    parser.add_argument("--version")
+    parser.add_argument("--repo", default="baketnk/frame-yap")
+    parser.add_argument("--without-model", action="store_true")
+    parser.add_argument("--unregistered", action="store_true", help="acknowledge explicit OpenVR removal before uninstall")
+    args = parser.parse_args(argv)
+    if args.repo != "baketnk/frame-yap":
+        parser.error("only the pinned baketnk/frame-yap release repository is supported")
+    if args.archive and (not args.sha256 or not args.version):
+        parser.error("--archive requires --sha256 and --version")
+    if not args.archive and args.sha256:
+        parser.error("--sha256 only applies to --archive")
+    if not (args.rollback or args.uninstall or args.archive) and not args.version:
+        parser.error("--version TAG is required; no moving/latest release")
+    if args.uninstall and not args.unregistered:
+        parser.error("uninstall requires --unregistered after explicit OpenVR unregister")
+    if args.unregistered and not args.uninstall:
+        parser.error("--unregistered only applies to --uninstall")
+    if args.version:
+        check_version(args.version)
+    check_host()
+    data = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local/share").expanduser().absolute()
+    root = data / "frameyap"
+    launcher = Path.home() / ".local/bin/frameyap"
+    owned_dir(root)
+    lock = root / ".lock"
+    if lock.is_symlink():
+        fail("refusing symlink lock")
+    with lock.open("a+b") as fd:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            fail("FrameYap installer or application is running (.lock held); try again later")
+        if args.uninstall:
+            uninstall(root, launcher)
+        elif args.rollback:
+            owned_dir(root / "versions")
+            current, previous = selected(root, "current"), selected(root, "previous")
+            if not current or not previous:
+                fail("no previous installation to roll back to")
+            check_wrappers(root, launcher)
+            choice = installed_choice(root / previous)
+            check_inventory(root / previous)
+            validate_payload(root / previous, Path(previous).name, choice, installed=True)
+            select(root, "current", previous)
+            select(root, "previous", current)
+            print(f"Rolled back to {previous}")
+        else:
+            do_install(args, root, launcher)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, OSError, subprocess.CalledProcessError, tarfile.TarError, json.JSONDecodeError) as exc:
+        print(f"frameyap installer: {exc}", file=sys.stderr)
+        sys.exit(1)

scripts/package-release.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Produce an offline release archive from an independently vetted ARM64 staging tree.
+
+This tool does not build/download a runtime, model, native libraries, or licenses.
+"""
+import argparse
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tarfile
+import tempfile
+
+ARCH = "linux-aarch64"
+ALLOWED = {"bin", "lib", "assets", "python", "runtime", "model", "fonts", "licenses"}
+REQUIRED = ("bin/frameyap", "runtime/bin/python3", "python/frameyap/worker.py",
+            "assets/actions.json", "fonts/font.ttf", "licenses/THIRD_PARTY_NOTICES.txt")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--stage", type=Path, required=True, help="vetted standalone payload directory")
+    p.add_argument("--output", type=Path, required=True, help="existing output directory")
+    p.add_argument("--version", required=True)
+    p.add_argument("--arch", choices=[ARCH], required=True)
+    p.add_argument("--model-revision", required=True, help="exact vetted model revision identifier")
+    p.add_argument("--external-runtime", action="store_true", help="omit ASR runtime; user must supply an independently authorized Python environment")
+    args = p.parse_args(argv)
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,95}", args.version) or args.version in (".", ".."):
+        p.error("invalid version")
+    if not args.model_revision.strip():
+        p.error("model revision must be nonempty")
+    stage = args.stage.resolve(strict=True)
+    if not stage.is_dir() or args.stage.is_symlink():
+        p.error("stage must be a real directory")
+    if not args.output.is_dir() or args.output.is_symlink():
+        p.error("output must be an existing real directory")
+    if any(item.name not in ALLOWED for item in stage.iterdir()):
+        p.error("stage has unknown root entries or preexisting release.json")
+    for name in REQUIRED:
+        if args.external_runtime and name == "runtime/bin/python3":
+            continue
+        if not (stage / name).is_file() or (stage / name).is_symlink():
+            p.error(f"missing file: {name}")
+    if args.external_runtime and (stage / "runtime").exists():
+        p.error("external-runtime package must not contain a runtime directory")
+    for name in (("bin/frameyap",) if args.external_runtime else ("bin/frameyap", "runtime/bin/python3")):
+        if not os.access(stage / name, os.X_OK):
+            p.error(f"not executable: {name}")
+    for name in ("lib", "fonts", "licenses"):
+        if not (stage / name).is_dir() or not any((stage / name).iterdir()):
+            p.error(f"missing directory or empty: {name}")
+    if not (stage / "licenses/THIRD_PARTY_NOTICES.txt").read_text().strip():
+        p.error("third-party notices must not be empty; review redistribution licenses")
+    if (stage / "model").exists() and not any((stage / "model").rglob("*")):
+        p.error("model directory is empty")
+    entries = sorted(stage.rglob("*"), key=lambda item: item.relative_to(stage).as_posix())
+    if len(entries) > 49999:
+        p.error("too many payload members")
+    total = 0
+    for entry in entries:
+        name = entry.relative_to(stage).as_posix()
+        if (len(name) > 1024 or len(name.split("/")) > 32 or "\\" in name
+                or name.endswith("/") or any(part in ("", ".", "..") for part in name.split("/"))):
+            p.error(f"unsupported archive member path: {name}")
+        if entry.is_symlink() or not (entry.is_dir() or entry.is_file()):
+            p.error(f"links and special files forbidden (copy vetted files into stage): {entry}")
+        if entry.is_file():
+            total += entry.stat().st_size
+    if total > 12 * 1024**3:
+        p.error("payload exceeds 12 GiB uncompressed limit")
+    name = f"frameyap-{args.version}-{ARCH}.tar.gz"
+    target = args.output / name
+    sidecar = args.output / (name + ".sha256")
+    if target.exists() or sidecar.exists() or target.is_symlink() or sidecar.is_symlink():
+        p.error("release output exists; refusing to replace it")
+    meta = {"schema": 1, "version": args.version, "arch": ARCH,
+            "runtime": "external-authorized-python" if args.external_runtime else "bundled-cpu-python", "model_revision": args.model_revision,
+            "includes_model": (stage / "model").is_dir()}
+    fd, temp = tempfile.mkstemp(prefix=".frameyap-package-", dir=args.output)
+    os.close(fd)
+    try:
+        with tarfile.open(temp, "w:gz", format=tarfile.PAX_FORMAT, compresslevel=1) as tar:
+            payload = (json.dumps(meta, sort_keys=True, indent=2) + "\n").encode()
+            info = tarfile.TarInfo("release.json")
+            info.size = len(payload)
+            info.mode = 0o600
+            tar.addfile(info, io.BytesIO(payload))
+            for entry in entries:
+                tar.add(entry, arcname=entry.relative_to(stage).as_posix(), recursive=False)
+        digest = hashlib.sha256()
+        with open(temp, "rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+        os.replace(temp, target)
+        sidecar.write_text(f"{digest.hexdigest()}  {name}\n")
+        print(f"Wrote {target} and {sidecar}")
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+if __name__ == "__main__":
+    main()

scripts/stage-native-poc.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Stage a native-only POC from an explicit native build and licensed files.
+
+No downloads, compiler invocation, proprietary ASR runtime, registration or launch.
+System Wayland/FreeType/libstdc++/glibc remain platform prerequisites.
+"""
+import argparse
+from pathlib import Path
+import shutil
+import subprocess
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--build", type=Path, required=True)
+    p.add_argument("--destination", type=Path, required=True, help="new staging directory")
+    for name in ("openvr-library", "openvr-license", "sdl-library", "sdl-license", "font", "font-license"):
+        p.add_argument("--" + name, type=Path, required=True)
+    args = p.parse_args()
+    root = Path(__file__).resolve().parents[1]
+    dest = args.destination.absolute()
+    if dest.exists() or dest.is_symlink():
+        p.error("destination already exists; use a new staging directory")
+    for name in ("openvr_library", "openvr_license", "sdl_library", "sdl_license", "font", "font_license"):
+        if not getattr(args, name).is_file():
+            p.error(f"missing explicit input {name}")
+    cache = (args.build / "CMakeCache.txt").read_text()
+    if "FRAMEYAP_NATIVE:BOOL=ON" not in cache:
+        p.error("build must explicitly enable FRAMEYAP_NATIVE")
+    dest.mkdir(mode=0o700, parents=True)
+    subprocess.run(["cmake", "--install", str(args.build.absolute()), "--prefix", str(dest)], check=True)
+    for directory in ("lib", "fonts", "licenses"):
+        (dest / directory).mkdir()
+    shutil.copyfile(args.openvr_library, dest / "lib/libopenvr_api.so", follow_symlinks=True)
+    shutil.copyfile(args.sdl_library, dest / "lib/libSDL3.so.0", follow_symlinks=True)
+    shutil.copyfile(args.font, dest / "fonts/font.ttf")
+    notices = ["FrameYap native-only POC. No ASR runtime or model is included.\n",
+               "Original FrameYap code: MIT. System Wayland/FreeType/libstdc++/glibc are not bundled.\n",
+               "Bundled libraries: Valve OpenVR and unmodified SDL3; font supplied explicitly below.\n",
+               "This package does not grant any rights to kestrel-kernels or provide a functioning ASR environment.\n"]
+    for label, file in (("FrameYap", root / "LICENSE"), ("OpenVR", args.openvr_license),
+                        ("SDL3", args.sdl_license), ("Font", args.font_license)):
+        notices.extend([f"\n--- {label} ---\n", file.read_text()])
+    notices.extend(["\n--- Gamescope protocol: embedded copyright/license ---\n",
+                    (root / "protocol/gamescope-input-method.xml").read_text()])
+    (dest / "licenses/THIRD_PARTY_NOTICES.txt").write_text("\n".join(notices))
+    print(f"Native-only stage: {dest}. Package with --external-runtime; do not claim bundled ASR.")
+
+
+if __name__ == "__main__":
+    main()

scripts/sync-installer.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Developer helper: synchronize the standalone piped installer payload."""
+from pathlib import Path
+root = Path(__file__).resolve().parents[1]
+wrapper = root / "install.sh"
+header = wrapper.read_text().split("<<'PY'\n", 1)[0] + "<<'PY'\n"
+payload = (root / "scripts/install_payload.py").read_text()
+if "\nPY\n" in payload:
+    raise ValueError("heredoc delimiter appears in payload")
+wrapper.write_text(header + payload + "\nPY\n")