From 6e4b84a60d0f94ba772b9872385d1c4021090786 Mon Sep 17 00:00:00 2001
From: Abhi <43648792+abhipatel12@users.noreply.github.com>
Date: Sun, 8 Jun 2025 01:04:20 -0400
Subject: [PATCH] Fix Build Failure - Build fails in sandbox due to missing
 build toolchain (#831)

---
 CONTRIBUTING.md                   | 23 +++++++++++++++++++++++
 Dockerfile                        |  3 +++
 packages/cli/src/utils/sandbox.ts |  2 +-
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5fc08070..e8aef8aa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -97,6 +97,29 @@ npm run test
 
 This will run tests located in the `packages/core` and `packages/cli` directories. Ensure tests pass before submitting any changes.
 
+#### Important Note for Sandbox Users on macOS/Windows
+
+This project uses native dependencies (e.g., `tree-sitter`) that are compiled for a specific operating system.
+
+When you run the application in the development sandbox via `npm start`, these dependencies are automatically rebuilt for the container's Linux environment.
+
+Because of this, if you then try to run `npm run test` directly on your host machine (e.g., macOS), the tests will fail with an error similar to `dlopen` or `not a valid mach-o file`. This is because the test runner on your Mac cannot load the Linux-compiled dependencies from your `node_modules` folder.
+
+#### The Solution:
+
+To fix this, you must rebuild the native dependencies for your host machine's architecture before running the tests.
+
+```bash
+npm rebuild
+```
+
+#### Recommended Workflow:
+
+1. After using the sandboxed `npm start`, and before you want to run tests locally, run `npm rebuild` in your terminal.
+2. Then, run `npm run test` as usual.
+
+You will need to repeat the npm rebuild step any time you switch from running the sandboxed application back to running local tests.
+
 ### Linting and Preflight Checks
 
 To ensure code quality, formatting consistency, and run final checks before committing:
diff --git a/Dockerfile b/Dockerfile
index 97a963b6..d6e8c2ae 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,6 +5,9 @@ ENV SANDBOX="$SANDBOX_NAME"
 
 # install minimal set of packages, then clean up
 RUN apt-get update && apt-get install -y --no-install-recommends \
+  python3 \
+  make \
+  g++ \
   man-db \
   curl \
   dnsutils \
diff --git a/packages/cli/src/utils/sandbox.ts b/packages/cli/src/utils/sandbox.ts
index 8b75660e..3a8914ee 100644
--- a/packages/cli/src/utils/sandbox.ts
+++ b/packages/cli/src/utils/sandbox.ts
@@ -209,7 +209,7 @@ function entrypoint(workdir: string): string[] {
     process.env.NODE_ENV === 'development'
       ? process.env.DEBUG
         ? 'npm run debug --'
-        : 'npm run start --'
+        : 'npm rebuild && npm run start --'
       : process.env.DEBUG // for production binary debugging
         ? `node --inspect-brk=0.0.0.0:${process.env.DEBUG_PORT || '9229'} $(which gemini)`
         : 'gemini';