Add exists() method to check file/directory existence

Implements a new exists() method across the entire SDK stack that checks
whether a file or directory exists at a given path. The method returns a
boolean similar to Python's os.path.exists() and JavaScript's
fs.existsSync().

Implementation:
- Add FileExistsResult and FileExistsRequest types to shared package
- Add /api/exists endpoint handler in container layer
- Add exists() method to FileClient in SDK layer
- Expose exists() through Sandbox class and ExecutionSession wrapper
- Update ISandbox and ExecutionSession interfaces

Testing:
- Add unit tests for FileClient.exists()
- Add unit tests for FileHandler.handleExists()
- Add E2E test for file and directory existence checks
- Add endpoint to E2E test worker

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

Co-Authored-By: Naresh <[email protected]>

Author: github-actions[bot]

.changeset/add-exists-method.md

@@ -0,0 +1,13 @@
+---
+"@cloudflare/sandbox": minor
+---
+
+Add exists() method to check if a file or directory exists
+
+This adds a new `exists()` method to the SDK that checks whether a file or directory exists at a given path. The method returns a boolean indicating existence, similar to Python's `os.path.exists()` and JavaScript's `fs.existsSync()`.
+
+The implementation is end-to-end:
+- New `FileExistsResult` and `FileExistsRequest` types in shared package
+- Handler endpoint at `/api/exists` in container layer
+- Client method in `FileClient` and `Sandbox` classes
+- Full test coverage (unit tests and E2E tests)

packages/sandbox-container/src/handlers/file-handler.ts

@@ -1,7 +1,8 @@
 import type {
   DeleteFileResult,
+  FileExistsResult,
   FileStreamEvent,
-  ListFilesResult,Logger, 
+  ListFilesResult,Logger,
   MkdirResult,
   MoveFileResult,
   ReadFileResult,
@@ -12,6 +13,7 @@ import { ErrorCode } from '@repo/shared/errors';
 
 import type {
   DeleteFileRequest,
+  FileExistsRequest,
   ListFilesRequest,
   MkdirRequest,
   MoveFileRequest,
@@ -52,6 +54,8 @@ export class FileHandler extends BaseHandler<Request, Response> {
         return await this.handleMkdir(request, context);
       case '/api/list-files':
         return await this.handleListFiles(request, context);
+      case '/api/exists':
+        return await this.handleExists(request, context);
       default:
         return this.createErrorResponse({
           message: 'Invalid file endpoint',
@@ -277,4 +281,23 @@ export class FileHandler extends BaseHandler<Request, Response> {
       return this.createErrorResponse(result.error, context);
     }
   }
+
+  private async handleExists(request: Request, context: RequestContext): Promise<Response> {
+    const body = await this.parseRequestBody<FileExistsRequest>(request);
+
+    const result = await this.fileService.exists(body.path, body.sessionId);
+
+    if (result.success) {
+      const response: FileExistsResult = {
+        success: true,
+        path: body.path,
+        exists: result.data,
+        timestamp: new Date().toISOString(),
+      };
+
+      return this.createTypedResponse(response, context);
+    } else {
+      return this.createErrorResponse(result.error, context);
+    }
+  }
 }

packages/sandbox-container/tests/handlers/file-handler.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "bun:test";
 import type {
   DeleteFileResult,
+  FileExistsResult,
   MkdirResult,
   MoveFileResult,
   ReadFileResult,
@@ -486,6 +487,90 @@ describe('FileHandler', () => {
     });
   });
 
+  describe('handleExists - POST /api/exists', () => {
+    it('should return true when file exists', async () => {
+      const existsData = {
+        path: '/tmp/test.txt',
+        sessionId: 'session-123'
+      };
+
+      (mockFileService.exists as any).mockResolvedValue({
+        success: true,
+        data: true
+      });
+
+      const request = new Request('http://localhost:3000/api/exists', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(existsData)
+      });
+
+      const response = await fileHandler.handle(request, mockContext);
+
+      expect(response.status).toBe(200);
+      const responseData = await response.json() as FileExistsResult;
+      expect(responseData.success).toBe(true);
+      expect(responseData.exists).toBe(true);
+      expect(responseData.path).toBe('/tmp/test.txt');
+      expect(responseData.timestamp).toBeDefined();
+
+      expect(mockFileService.exists).toHaveBeenCalledWith('/tmp/test.txt', 'session-123');
+    });
+
+    it('should return false when file does not exist', async () => {
+      const existsData = {
+        path: '/tmp/nonexistent.txt',
+        sessionId: 'session-123'
+      };
+
+      (mockFileService.exists as any).mockResolvedValue({
+        success: true,
+        data: false
+      });
+
+      const request = new Request('http://localhost:3000/api/exists', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(existsData)
+      });
+
+      const response = await fileHandler.handle(request, mockContext);
+
+      expect(response.status).toBe(200);
+      const responseData = await response.json() as FileExistsResult;
+      expect(responseData.success).toBe(true);
+      expect(responseData.exists).toBe(false);
+    });
+
+    it('should handle errors when checking file existence', async () => {
+      const existsData = {
+        path: '/invalid/path',
+        sessionId: 'session-123'
+      };
+
+      (mockFileService.exists as any).mockResolvedValue({
+        success: false,
+        error: {
+          message: 'Invalid path',
+          code: 'VALIDATION_FAILED',
+          httpStatus: 400
+        }
+      });
+
+      const request = new Request('http://localhost:3000/api/exists', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(existsData)
+      });
+
+      const response = await fileHandler.handle(request, mockContext);
+
+      expect(response.status).toBe(400);
+      const responseData = await response.json() as ErrorResponse;
+      expect(responseData.code).toBe('VALIDATION_FAILED');
+    });
+  });
+
   describe('route handling', () => {
     it('should return 500 for invalid endpoints', async () => {
       const request = new Request('http://localhost:3000/api/invalid-operation', {

packages/sandbox/src/clients/file-client.ts

@@ -1,5 +1,6 @@
 import type {
   DeleteFileResult,
+  FileExistsResult,
   ListFilesOptions,
   ListFilesResult,
   MkdirResult,
@@ -266,4 +267,29 @@ export class FileClient extends BaseHttpClient {
       throw error;
     }
   }
+
+  /**
+   * Check if a file or directory exists
+   * @param path - Path to check
+   * @param sessionId - The session ID for this operation
+   */
+  async exists(
+    path: string,
+    sessionId: string
+  ): Promise<FileExistsResult> {
+    try {
+      const data = {
+        path,
+        sessionId,
+      };
+
+      const response = await this.post<FileExistsResult>('/api/exists', data);
+
+      this.logSuccess('Path existence checked', `${path} (exists: ${response.exists})`);
+      return response;
+    } catch (error) {
+      this.logError('exists', error);
+      throw error;
+    }
+  }
 }

packages/sandbox/src/sandbox.ts

@@ -697,6 +697,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     return this.client.files.listFiles(path, session, options);
   }
 
+  async exists(path: string, sessionId?: string) {
+    const session = sessionId ?? await this.ensureDefaultSession();
+    return this.client.files.exists(path, session);
+  }
+
   async exposePort(port: number, options: { name?: string; hostname: string }) {
     // Check if hostname is workers.dev domain (doesn't support wildcard subdomains)
     if (options.hostname.endsWith('.workers.dev')) {
@@ -934,6 +939,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       renameFile: (oldPath, newPath) => this.renameFile(oldPath, newPath, sessionId),
       moveFile: (sourcePath, destPath) => this.moveFile(sourcePath, destPath, sessionId),
       listFiles: (path, options) => this.client.files.listFiles(path, sessionId, options),
+      exists: (path) => this.exists(path, sessionId),
 
       // Git operations
       gitCheckout: (repoUrl, options) => this.gitCheckout(repoUrl, { ...options, sessionId }),

packages/sandbox/tests/file-client.test.ts

@@ -1,5 +1,6 @@
 import type {
   DeleteFileResult,
+  FileExistsResult,
   ListFilesResult,
   MkdirResult,
   MoveFileResult,
@@ -584,6 +585,81 @@ database:
     });
   });
 
+  describe('exists', () => {
+    it('should return true when file exists', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/test.txt',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/test.txt', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(true);
+      expect(result.path).toBe('/workspace/test.txt');
+    });
+
+    it('should return false when file does not exist', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/nonexistent.txt',
+        exists: false,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/nonexistent.txt', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(false);
+    });
+
+    it('should return true when directory exists', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/some-dir',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/some-dir', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(true);
+    });
+
+    it('should send correct request payload', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/test/path',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      await client.exists('/test/path', 'session-test');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('/api/exists'),
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            path: '/test/path',
+            sessionId: 'session-test',
+          })
+        })
+      );
+    });
+  });
+
   describe('error handling', () => {
     it('should handle network failures gracefully', async () => {
       mockFetch.mockRejectedValue(new Error('Network connection failed'));

packages/shared/src/index.ts

@@ -31,6 +31,7 @@ export type {
   DeleteFileRequest,
   ExecuteRequest,
   ExposePortRequest,
+  FileExistsRequest,
   GitCheckoutRequest,
   MkdirRequest,
   MoveFileRequest,
@@ -53,6 +54,7 @@ export type {
   ExecOptions,
   ExecResult,
   ExecutionSession,
+  FileExistsResult,
   // File streaming types
   FileChunk,
   FileInfo,

packages/shared/src/request-types.ts

@@ -85,6 +85,14 @@ export interface MkdirRequest {
   sessionId?: string;
 }
 
+/**
+ * Request to check if a file or directory exists
+ */
+export interface FileExistsRequest {
+  path: string;
+  sessionId?: string;
+}
+
 /**
  * Request to expose a port
  */

packages/shared/src/types.ts

@@ -343,6 +343,13 @@ export interface MoveFileResult {
   exitCode?: number;
 }
 
+export interface FileExistsResult {
+  success: boolean;
+  path: string;
+  exists: boolean;
+  timestamp: string;
+}
+
 export interface FileInfo {
   name: string;
   absolutePath: string;
@@ -603,6 +610,7 @@ export interface ExecutionSession {
   renameFile(oldPath: string, newPath: string): Promise<RenameFileResult>;
   moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
   listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string): Promise<FileExistsResult>;
 
   // Git operations
   gitCheckout(repoUrl: string, options?: { branch?: string; targetDir?: string }): Promise<GitCheckoutResult>;
@@ -647,6 +655,7 @@ export interface ISandbox {
   renameFile(oldPath: string, newPath: string): Promise<RenameFileResult>;
   moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
   listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string): Promise<FileExistsResult>;
 
   // Git operations
   gitCheckout(repoUrl: string, options?: { branch?: string; targetDir?: string }): Promise<GitCheckoutResult>;