From 7b569df2025b05b44e829c7ca10f3c4aed6d81b1 Mon Sep 17 00:00:00 2001
From: francois <francois@beafrancois.fr>
Date: Tue, 19 May 2026 23:16:05 +0200
Subject: [PATCH 1/2] flatpak: route gitpython through flatpak-spawn for host
 git

Inside a Flatpak the host /usr/bin/git is reachable at
/run/host/usr/bin/git but linked against host glibc/zlib, which the
sandbox cannot load (libz-ng.so.2 missing). gitpython resolves git
eagerly on import and crashed the whole validation run.

Install a tiny shell wrapper under /tmp at module load
(``exec flatpak-spawn --host git "$@"``) and point gitpython at it via
GIT_PYTHON_GIT_EXECUTABLE so test_version / test_modifs work in
flatpak mode. No-op outside Flatpak.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/testium/interpreter/utils/version.py | 44 ++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/src/testium/interpreter/utils/version.py b/src/testium/interpreter/utils/version.py
index 8508b95..cec153c 100644
--- a/src/testium/interpreter/utils/version.py
+++ b/src/testium/interpreter/utils/version.py
@@ -1,10 +1,54 @@
+import atexit
 import os
+import stat
 import sys
+import tempfile
 from importlib import import_module
 
 import interpreter.utils.settings as prefs
 import api.testium as tm
 
+
+# When running inside a Flatpak, the host /usr/bin/git is reachable at
+# /run/host/usr/bin/git but linked against host glibc/zlib, which the
+# sandbox can't load (``libz-ng.so.2`` not found). gitpython resolves git
+# eagerly on import and would crash the whole test run. We install a
+# tiny shell wrapper under /tmp that forwards to ``flatpak-spawn --host
+# git``, and point gitpython at it via ``GIT_PYTHON_GIT_EXECUTABLE``.
+_HOST_GIT_WRAPPER = None
+
+
+def _setup_flatpak_git():
+    global _HOST_GIT_WRAPPER
+    if not os.path.isfile("/.flatpak-info"):
+        return
+    if _HOST_GIT_WRAPPER is not None:
+        return
+    fd, path = tempfile.mkstemp(prefix="testium-git-host-", suffix=".sh", dir="/tmp")
+    with os.fdopen(fd, "w") as f:
+        f.write('#!/bin/sh\nexec flatpak-spawn --host git "$@"\n')
+    os.chmod(path, stat.S_IRWXU)
+    _HOST_GIT_WRAPPER = path
+    atexit.register(_cleanup_flatpak_git)
+    os.environ["GIT_PYTHON_GIT_EXECUTABLE"] = path
+    # Silence gitpython's warning if its refresh probe ever still fails;
+    # the wrapper itself should make the probe succeed.
+    os.environ.setdefault("GIT_PYTHON_REFRESH", "quiet")
+
+
+def _cleanup_flatpak_git():
+    global _HOST_GIT_WRAPPER
+    if _HOST_GIT_WRAPPER and os.path.isfile(_HOST_GIT_WRAPPER):
+        try:
+            os.unlink(_HOST_GIT_WRAPPER)
+        except OSError:
+            pass
+        _HOST_GIT_WRAPPER = None
+
+
+_setup_flatpak_git()
+
+
 _cached_versions = {}
 
 def repo_rev(path):

From 63467c17c399c9a0d527d26e3019432986fac6d3 Mon Sep 17 00:00:00 2001
From: francois <francois@beafrancois.fr>
Date: Tue, 19 May 2026 23:16:10 +0200
Subject: [PATCH 2/2] readme: document AppImage channel + libfuse2 requirement

The Pre-built releases section had no AppImage entry. Add one with
the per-distro libfuse2 package names and an APPIMAGE_EXTRACT_AND_RUN
escape hatch for hosts that no longer ship FUSE 2 by default.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 969a125..5c0b1b3 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,27 @@ Pre-built artifacts are published at
   runnable directly, no Python installation required on the host. Lua
   support still needs a system `lua` interpreter and the `lua-socket` /
   `lua-cjson` modules.
+* **AppImage** (`Testium-<version>-x86_64.AppImage`) — single-file
+  Linux binary, runnable directly:
+
+  ```sh
+  chmod +x Testium-*-x86_64.AppImage
+  ./Testium-*-x86_64.AppImage
+  ```
+
+  Requires `libfuse2` on the host (FUSE 2 — distinct from `fuse3`, which
+  most distros now ship by default):
+
+  | Distro | Package |
+  |--------|---------|
+  | Arch / CachyOS / Manjaro | `fuse2` |
+  | Debian trixie / Ubuntu 24.04+ | `libfuse2t64` |
+  | Debian bookworm / Ubuntu 22.04 | `libfuse2` |
+  | Fedora | `fuse-libs` |
+
+  If you can't install libfuse2 (e.g. minimal container), prefix the
+  invocation with `APPIMAGE_EXTRACT_AND_RUN=1` — the AppImage will
+  self-extract to `/tmp` on each run instead of FUSE-mounting.
 * **Flatpak bundle** (`testium.flatpak`) — install with:
 
   ```sh