Add exists() method to check file/directory existence (#152)

* 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]>

* Fix exists() type safety and error handling

Address code review feedback on PR #152:
- Fix TypeScript compilation by importing FileExistsRequest from @repo/shared
- Add sessionId parameter to ISandbox.exists() for API consistency
- Fix error handling to propagate execution failures properly

Co-authored-by: Naresh <[email protected]>

* Fix exists() to handle execution failures defensively

Revert error propagation change from c6c6068. The exists() method
should treat command execution failures as 'file does not exist'
rather than propagating errors, matching standard behavior in
Python's os.path.exists() and JavaScript's fs.existsSync().

This fixes the failing unit test:
FileService > exists > should handle execution failures gracefully

Co-authored-by: Naresh <[email protected]>

* Add missing /api/exists route registration

The exists() endpoint handler was implemented but the route was never
registered in the container's router setup, causing e2e tests to fail
with HTTP 500 errors.

This adds the missing route registration for POST /api/exists to the
file handler in routes/setup.ts.

Co-authored-by: Naresh <[email protected]>

* Use patch

Add exists() method to check if a file or directory exists

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Naresh <[email protected]>

Author: ghostwriternr

.changeset/add-exists-method.md

@@ -0,0 +1,13 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+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,9 @@
 import type {
   DeleteFileResult,
+  FileExistsRequest,
+  FileExistsResult,
   FileStreamEvent,
-  ListFilesResult,Logger, 
+  ListFilesResult,Logger,
   MkdirResult,
   MoveFileResult,
   ReadFileResult,
@@ -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/src/routes/setup.ts

@@ -91,6 +91,13 @@ export function setupRoutes(router: Router, container: Container): void {
     middleware: [container.get('loggingMiddleware')],
   });
 
+  router.register({
+    method: 'POST',
+    path: '/api/exists',
+    handler: async (req, ctx) => container.get('fileHandler').handle(req, ctx),
+    middleware: [container.get('loggingMiddleware')],
+  });
+
   // Port management routes
   router.register({
     method: 'POST',

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, sessionId?: string): Promise<FileExistsResult>;
 
   // Git operations
   gitCheckout(repoUrl: string, options?: { branch?: string; targetDir?: string }): Promise<GitCheckoutResult>;