From 28f5d83d67187eb74619415b13f40b45833e988d Mon Sep 17 00:00:00 2001
From: Michael Mainguy <mike.mainguy@gmail.com>
Date: Sun, 23 Nov 2025 10:41:05 -0600
Subject: [PATCH] Add Alpine Linux support via stub onnxruntime-node module
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The @xenova/transformers package unconditionally imports both
onnxruntime-node and onnxruntime-web at module load time. This
causes immediate failure on Alpine Linux (musl libc) because
onnxruntime-node requires glibc.

Solution: Created alpine:setup script that replaces onnxruntime-node
with a stub module after npm install. The transformers library will
automatically fall back to onnxruntime-web (WASM backend).

Usage on Alpine:
  npm install
  npm run alpine:setup
  npm run build
  npm run index:all

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md               | 12 ++++++++++++
 package.json            |  1 +
 scripts/alpine-setup.sh | 28 ++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+)
 create mode 100755 scripts/alpine-setup.sh

diff --git a/README.md b/README.md
index de42af4..848e5a1 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,18 @@ npm install
 npm run build
 ```
 
+### Alpine Linux Setup
+
+If you're running on Alpine Linux (musl libc), you need an additional setup step after installing dependencies:
+
+```bash
+npm install
+npm run alpine:setup
+npm run build
+```
+
+This removes the incompatible `onnxruntime-node` native module and configures the system to use the WASM backend instead. The WASM backend is slightly slower but works on all platforms.
+
 ## Initial Setup
 
 Before using the MCP server, you need to index the Babylon.js repositories. This is a one-time setup process.
diff --git a/package.json b/package.json
index 0b410d0..535cb88 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "alpine:setup": "sh scripts/alpine-setup.sh",
     "index:docs": "tsx scripts/index-docs.ts",
     "index:api": "tsx scripts/index-api.ts",
     "index:source": "tsx scripts/index-source.ts",
diff --git a/scripts/alpine-setup.sh b/scripts/alpine-setup.sh
new file mode 100755
index 0000000..90e8102
--- /dev/null
+++ b/scripts/alpine-setup.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+# Alpine Linux setup script
+# Removes onnxruntime-node to prevent glibc dependency errors
+# The transformers library will fall back to onnxruntime-web (WASM)
+
+echo "Removing onnxruntime-node for Alpine Linux compatibility..."
+
+# Remove the onnxruntime-node directory
+rm -rf node_modules/onnxruntime-node
+
+# Create a stub module so imports don't fail
+mkdir -p node_modules/onnxruntime-node
+cat > node_modules/onnxruntime-node/package.json << 'EOF'
+{
+  "name": "onnxruntime-node",
+  "version": "0.0.0-stub",
+  "main": "index.js",
+  "type": "module"
+}
+EOF
+
+cat > node_modules/onnxruntime-node/index.js << 'EOF'
+// Stub module for Alpine Linux
+// @xenova/transformers will use onnxruntime-web instead
+export default {};
+EOF
+
+echo "✓ Alpine Linux setup complete - WASM backend will be used"