env flags SANDBOX_{MOUNTS,ENV}, improved debugging through sandbox that should now work in all scenarios (#201)

* env flags SANDBOX_{MOUNTS,ENV}, improved debugging through sandbox that should now work in all scenarios

* Merge remote-tracking branch 'origin/main' into sandbox_flags_improved_debugging

3 files changed, 116 insertions, 44 deletions

diff --git a/.vscode/launch.json b/.vscode/launch.json
index cc8b3ef6..b4cdfd70 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -10,11 +10,9 @@
       "request": "attach",
       "skipFiles": ["<node_internals>/**"],
       "type": "node",
-      // fix source mapping when debugging in sandbox
-      // we assume debugging is done on gemini-code project itself (see CLI_PATH setup in start_sandbox.sh)
-      // there seems to be no way to map two distinct remoteRoots to same localRoot under same configuration
-      // "remoteRoot": "/usr/local/share/npm-global/lib/node_modules/@gemini-code",
-      "remoteRoot": "/sandbox/gemini-code/packages",
+      // fix source mapping when debugging in sandbox using global installation
+      // note this does not interfere when remoteRoot is also ${workspaceFolder}/packages
+      "remoteRoot": "/usr/local/share/npm-global/lib/node_modules/@gemini-code",
       "localRoot": "${workspaceFolder}/packages"
     },
     {
diff --git a/packages/cli/src/gemini.ts b/packages/cli/src/gemini.ts
index fa78c67a..25d092c9 100644
--- a/packages/cli/src/gemini.ts
+++ b/packages/cli/src/gemini.ts
@@ -16,7 +16,7 @@ import { GeminiClient } from '@gemini-code/server';
 import { readPackageUp } from 'read-package-up';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
-import { execSync, spawnSync } from 'child_process';
+import { execSync, spawnSync, spawn } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -53,36 +53,18 @@ function sandbox_command(): string {
 }
 
 // node.js equivalent of scripts/start_sandbox.sh
-function start_sandbox(sandbox: string) {
+async function start_sandbox(sandbox: string) {
   // determine full path for gemini-code to distinguish linked vs installed setting
   const gcPath = execSync(`realpath $(which gemini-code)`).toString().trim();
 
-  // stop if debugging in sandbox using linked/installed gemini-code
-  // note this is because it does not work (unclear why, parent process interferes somehow)
-  // note `npm run debug` runs sandbox directly and avoids any interference from parent process
-  if (process.env.DEBUG) {
-    console.error(
-      'ERROR: cannot debug in sandbox using linked/installed gemini-code; ' +
-        'use `npm run debug` under gemini-code repo instead',
-    );
-    process.exit(1);
-  }
-
   // if project is gemini-code, then switch to -dev image & run CLI from ${workdir}/packages/cli
   let image = 'gemini-code-sandbox';
   const project = path.basename(process.cwd());
-  const workdir = `/sandbox/${project}`;
+  const workdir = process.cwd();
   let cliPath = '/usr/local/share/npm-global/lib/node_modules/@gemini-code/cli';
   if (project === 'gemini-code') {
     image += '-dev';
     cliPath = `${workdir}/packages/cli`;
-  } else {
-    // refuse to debug using global installation for now (can be added later)
-    // (requires a separate attach config, see comments in launch.json around remoteRoot)
-    if (process.env.DEBUG) {
-      console.error('ERROR: cannot debug in sandbox outside gemini-code repo');
-      process.exit(1);
-    }
   }
 
   // if BUILD_SANDBOX is set, then call scripts/build_sandbox.sh under gemini-code repo
@@ -123,6 +105,35 @@ function start_sandbox(sandbox: string) {
   // mount os.tmpdir() as /tmp inside container
   args.push('-v', `${os.tmpdir()}:/tmp`);
 
+  // mount paths listed in SANDBOX_MOUNTS
+  if (process.env.SANDBOX_MOUNTS) {
+    for (let mount of process.env.SANDBOX_MOUNTS.split(',')) {
+      if (mount.trim()) {
+        // parse mount as from:to:opts
+        let [from, to, opts] = mount.trim().split(':');
+        to = to || from; // default to mount at same path inside container
+        opts = opts || 'ro'; // default to read-only
+        mount = `${from}:${to}:${opts}`;
+        // check that from path is absolute
+        if (!path.isAbsolute(from)) {
+          console.error(
+            `ERROR: path '${from}' listed in SANDBOX_MOUNTS must be absolute`,
+          );
+          process.exit(1);
+        }
+        // check that from path exists on host
+        if (!fs.existsSync(from)) {
+          console.error(
+            `ERROR: missing mount path '${from}' listed in SANDBOX_MOUNTS`,
+          );
+          process.exit(1);
+        }
+        console.log(`SANDBOX_MOUNTS: ${from} -> ${to} (${opts})`);
+        args.push('-v', mount);
+      }
+    }
+  }
+
   // name container after image, plus numeric suffix to avoid conflicts
   let index = 0;
   while (
@@ -159,6 +170,23 @@ function start_sandbox(sandbox: string) {
     args.push('--env', `COLORTERM=${process.env.COLORTERM}`);
   }
 
+  // copy additional environment variables from SANDBOX_ENV
+  if (process.env.SANDBOX_ENV) {
+    for (let env of process.env.SANDBOX_ENV.split(',')) {
+      if ((env = env.trim())) {
+        if (env.includes('=')) {
+          console.log(`SANDBOX_ENV: ${env}`);
+          args.push('--env', env);
+        } else {
+          console.error(
+            'ERROR: SANDBOX_ENV must be a comma-separated list of key=value pairs',
+          );
+          process.exit(1);
+        }
+      }
+    }
+  }
+
   // set SANDBOX as container name
   args.push('--env', `SANDBOX=${image}-${index}`);
 
@@ -172,14 +200,23 @@ function start_sandbox(sandbox: string) {
   const debugPort = process.env.DEBUG_PORT || '9229';
   if (process.env.DEBUG) {
     args.push('-p', `${debugPort}:${debugPort}`);
-    nodeArgs.push('--inspect-brk', `0.0.0.0:${debugPort}`);
+    nodeArgs.push(`--inspect-brk=0.0.0.0:${debugPort}`);
   }
 
   // append remaining args (image, node, node args, cli path, cli args)
   args.push(image, 'node', ...nodeArgs, cliPath, ...process.argv.slice(2));
 
   // spawn child and let it inherit stdio
-  spawnSync(sandbox, args, { stdio: 'inherit' });
+  const child = spawn(sandbox, args, {
+    stdio: 'inherit',
+    detached: true,
+  });
+
+  // uncomment this line (and comment the await on following line) to let parent exit
+  // child.unref();
+  await new Promise((resolve) => {
+    child.on('close', resolve);
+  });
 }
 
 async function main() {
@@ -190,7 +227,7 @@ async function main() {
   const sandbox = sandbox_command();
   if (sandbox && !process.env.SANDBOX) {
     console.log('hopping into sandbox ...');
-    start_sandbox(sandbox);
+    await start_sandbox(sandbox);
     process.exit(0);
   }
 
diff --git a/scripts/start_sandbox.sh b/scripts/start_sandbox.sh
index 89046fbe..5db6203e 100755
--- a/scripts/start_sandbox.sh
+++ b/scripts/start_sandbox.sh
@@ -22,20 +22,15 @@ fi
 
 CMD=$(scripts/sandbox_command.sh)
 IMAGE=gemini-code-sandbox
-DEBUG_PORT=9229
+DEBUG_PORT=${DEBUG_PORT:-9229}
 PROJECT=$(basename "$PWD")
-WORKDIR=/sandbox/$PROJECT
+WORKDIR=$PWD
 CLI_PATH=/usr/local/share/npm-global/lib/node_modules/\@gemini-code/cli
 
 # if project is gemini-code, then switch to -dev image & run CLI from $WORKDIR/packages/cli
 if [[ "$PROJECT" == "gemini-code" ]]; then
     IMAGE+="-dev"
     CLI_PATH="$WORKDIR/packages/cli"
-elif [ -n "${DEBUG:-}" ]; then
-    # refuse to debug using global installation for now (can be added later)
-    # (requires a separate attach config, see comments in launch.json around remoteRoot)
-    echo "ERROR: debugging is sandbox is not supported when target/root is not gemini-code"
-    exit 1
 fi
 
 # stop if image is missing
@@ -53,14 +48,7 @@ run_args+=(-v "$PWD:$WORKDIR")
 # mount $TMPDIR as /tmp inside container
 run_args+=(-v "${TMPDIR:-/tmp/}:/tmp")
 
-# name container after image, plus numeric suffix to avoid conflicts
-INDEX=0
-while $CMD ps -a --format "{{.Names}}" | grep -q "$IMAGE-$INDEX"; do
-    INDEX=$((INDEX + 1))
-done
-run_args+=(--name "$IMAGE-$INDEX" --hostname "$IMAGE-$INDEX")
-
-# if .env exists, source it before variable existence checks below
+# if .env exists, source it before checking/parsing environment variables below
 # allow .env to be in any ancestor directory (same as findEnvFile in config.ts)
 current_dir=$(pwd)
 while [ "$current_dir" != "/" ]; do
@@ -71,6 +59,39 @@ while [ "$current_dir" != "/" ]; do
     current_dir=$(dirname "$current_dir")
 done
 
+# mount paths listed in SANDBOX_MOUNTS
+if [ -n "${SANDBOX_MOUNTS:-}" ]; then
+    mounts=$(echo "$SANDBOX_MOUNTS" | tr ',' '\n')
+    for mount in $mounts; do
+        if [ -n "$mount" ]; then
+            # parse mount as from:to:opts
+            IFS=':' read -r from to opts <<<"$mount"
+            to=${to:-"$from"}  # default to mount at same path inside container
+            opts=${opts:-"ro"} # default to read-only
+            mount="$from:$to:$opts"
+            # check that $from is absolute
+            if [[ "$from" != /* ]]; then
+                echo "ERROR: path '$from' listed in SANDBOX_MOUNTS must be absolute"
+                exit 1
+            fi
+            # check that $from path exists on host
+            if [ ! -e "$from" ]; then
+                echo "ERROR: missing mount path '$from' listed in SANDBOX_MOUNTS"
+                exit 1
+            fi
+            echo "SANDBOX_MOUNTS: $from -> $to ($opts)"
+            run_args+=(-v "$mount")
+        fi
+    done
+fi
+
+# name container after image, plus numeric suffix to avoid conflicts
+INDEX=0
+while $CMD ps -a --format "{{.Names}}" | grep -q "$IMAGE-$INDEX"; do
+    INDEX=$((INDEX + 1))
+done
+run_args+=(--name "$IMAGE-$INDEX" --hostname "$IMAGE-$INDEX")
+
 # copy GEMINI_API_KEY
 if [ -n "${GEMINI_API_KEY:-}" ]; then run_args+=(--env GEMINI_API_KEY="$GEMINI_API_KEY"); fi
 
@@ -84,6 +105,22 @@ if [ -n "${SHELL_TOOL:-}" ]; then run_args+=(--env SHELL_TOOL="$SHELL_TOOL"); fi
 if [ -n "${TERM:-}" ]; then run_args+=(--env TERM="$TERM"); fi
 if [ -n "${COLORTERM:-}" ]; then run_args+=(--env COLORTERM="$COLORTERM"); fi
 
+# copy additional environment variables from SANDBOX_ENV
+if [ -n "${SANDBOX_ENV:-}" ]; then
+    envs=$(echo "$SANDBOX_ENV" | tr ',' '\n')
+    for env in $envs; do
+        if [ -n "$env" ]; then
+            if [[ "$env" == *=* ]]; then
+                echo "SANDBOX_ENV: $env"
+                run_args+=(--env "$env")
+            else
+                echo "ERROR: SANDBOX_ENV must be a comma-separated list of key=value pairs"
+                exit 1
+            fi
+        fi
+    done
+fi
+
 # set SANDBOX environment variable as container name
 # this is the preferred mechanism to detect if inside container/sandbox
 run_args+=(--env "SANDBOX=$IMAGE-$INDEX")