Propagate cwd and env options in executeCommand (#42)

* feat: add support for cwd and env vars in execute commands

* Create wet-jars-double.md

---------

Co-authored-by: Sunil Pai <[email protected]>

Author: jonasnobile

.changeset/wet-jars-double.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+Propagate `cwd` and `env` options in `executeCommand`

packages/sandbox/container_src/handler/exec.ts

@@ -1,11 +1,10 @@
 import { type SpawnOptions, spawn } from "node:child_process";
-import type { ExecuteRequest, SessionData } from "../types";
+import type { ExecuteOptions, ExecuteRequest, SessionData } from "../types";
 
 function executeCommand(
   sessions: Map<string, SessionData>,
   command: string,
-  sessionId?: string,
-  background?: boolean
+  options: ExecuteOptions,
 ): Promise<{
   success: boolean;
   stdout: string;
@@ -16,14 +15,16 @@ function executeCommand(
     const spawnOptions: SpawnOptions = {
       shell: true,
       stdio: ["pipe", "pipe", "pipe"] as const,
-      detached: background || false,
+      detached: options.background || false,
+      cwd: options.cwd,
+      env: options.env ? { ...process.env, ...options.env } : process.env
     };
 
     const child = spawn(command, spawnOptions);
 
     // Store the process reference for cleanup if sessionId is provided
-    if (sessionId && sessions.has(sessionId)) {
-      const session = sessions.get(sessionId)!;
+    if (options.sessionId && sessions.has(options.sessionId)) {
+      const session = sessions.get(options.sessionId)!;
       session.activeProcess = child;
     }
 
@@ -38,7 +39,7 @@ function executeCommand(
       stderr += data.toString();
     });
 
-    if (background) {
+    if (options.background) {
       // For background processes, unref and return quickly
       child.unref();
 
@@ -61,8 +62,8 @@ function executeCommand(
       // Normal synchronous execution
       child.on("close", (code) => {
         // Clear the active process reference
-        if (sessionId && sessions.has(sessionId)) {
-          const session = sessions.get(sessionId)!;
+        if (options.sessionId && sessions.has(options.sessionId)) {
+          const session = sessions.get(options.sessionId)!;
           session.activeProcess = null;
         }
 
@@ -78,8 +79,8 @@ function executeCommand(
 
       child.on("error", (error) => {
         // Clear the active process reference
-        if (sessionId && sessions.has(sessionId)) {
-          const session = sessions.get(sessionId)!;
+        if (options.sessionId && sessions.has(options.sessionId)) {
+          const session = sessions.get(options.sessionId)!;
           session.activeProcess = null;
         }
 
@@ -96,7 +97,7 @@ export async function handleExecuteRequest(
 ): Promise<Response> {
   try {
     const body = (await req.json()) as ExecuteRequest;
-    const { command, sessionId, background } = body;
+    const { command, sessionId, background, cwd, env } = body;
 
     if (!command || typeof command !== "string") {
       return new Response(
@@ -115,7 +116,7 @@ export async function handleExecuteRequest(
 
     console.log(`[Server] Executing command: ${command}`);
 
-    const result = await executeCommand(sessions, command, sessionId, background);
+    const result = await executeCommand(sessions, command, { sessionId, background, cwd, env });
 
     return new Response(
       JSON.stringify({

packages/sandbox/container_src/types.ts

@@ -38,10 +38,15 @@ export interface StartProcessRequest {
   };
 }
 
-export interface ExecuteRequest {
-  command: string;
-  sessionId?: string;
+export interface ExecuteOptions {
+  sessionId?: string | null;
   background?: boolean;
+  cwd?: string | URL;
+  env?: Record<string, string>;
+}
+
+export interface ExecuteRequest extends ExecuteOptions {
+  command: string;
 }
 
 export interface GitCheckoutRequest {

packages/sandbox/src/client.ts

@@ -1,17 +1,14 @@
+import type { ExecuteRequest } from "../container_src/types";
 import type { Sandbox } from "./index";
 import type {
+  BaseExecOptions,
   GetProcessLogsResponse,
   GetProcessResponse,
   ListProcessesResponse,
   StartProcessRequest,
   StartProcessResponse
 } from "./types";
 
-interface ExecuteRequest {
-  command: string;
-  sessionId?: string;
-}
-
 export interface ExecuteResponse {
   success: boolean;
   stdout: string;
@@ -255,16 +252,19 @@ export class HttpClient {
 
   async execute(
     command: string,
-    sessionId?: string
+    options: Pick<BaseExecOptions, 'sessionId' | 'cwd' | 'env'>
   ): Promise<ExecuteResponse> {
     try {
-      const targetSessionId = sessionId || this.sessionId;
+      const targetSessionId = options.sessionId || this.sessionId;
+      const executeRequest = {
+        command,
+        sessionId: targetSessionId,
+        cwd: options.cwd,
+        env: options.env,
+      } satisfies ExecuteRequest;
 
       const response = await this.doFetch(`/api/execute`, {
-        body: JSON.stringify({
-          command,
-          sessionId: targetSessionId,
-        } as ExecuteRequest),
+        body: JSON.stringify(executeRequest),
         headers: {
           "Content-Type": "application/json",
         },

packages/sandbox/src/sandbox.ts

@@ -150,7 +150,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
         // Regular execution
         const response = await this.client.execute(
           command,
-          options?.sessionId
+          {
+            sessionId: options?.sessionId,
+            cwd: options?.cwd,
+            env: options?.env,
+          }
         );
 
         const duration = Date.now() - startTime;