Add listFiles method (#57)

* Add listFiles method

* Update ISandbox type

* Fix types

* Fix crash due to pre-warming

* Support relative paths

* Create changeset

Author: ghostwriternr

.changeset/puny-teams-doubt.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+Add listFiles method

examples/basic/app/index.tsx

@@ -3,6 +3,35 @@ import { useEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import "./style.css";
 
+// Type definitions
+interface FileInfo {
+  name: string;
+  absolutePath: string;
+  relativePath: string;
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  modifiedAt: string;
+  mode: string;
+  permissions: {
+    readable: boolean;
+    writable: boolean;
+    executable: boolean;
+  };
+}
+
+interface ListFilesOptions {
+  recursive?: boolean;
+  includeHidden?: boolean;
+}
+
+interface ListFilesResponse {
+  success: boolean;
+  path: string;
+  files: FileInfo[];
+  count: number;
+  timestamp: string;
+}
+
 // Simple API client to replace direct HttpClient usage
 class SandboxApiClient {
   private baseUrl: string;
@@ -244,6 +273,13 @@ class SandboxApiClient {
     });
   }
 
+  async listFiles(path: string, options: ListFilesOptions = {}): Promise<ListFilesResponse> {
+    return this.doFetch("/api/list-files", {
+      method: "POST",
+      body: JSON.stringify({ path, options }),
+    });
+  }
+
   async mkdir(path: string, options: any = {}) {
     return this.doFetch("/api/mkdir", {
       method: "POST",
@@ -1385,6 +1421,10 @@ function FilesTab({
   const [moveSourcePath, setMoveSourcePath] = useState("");
   const [moveDestPath, setMoveDestPath] = useState("");
   const [deleteFilePath, setDeleteFilePath] = useState("");
+  const [listPath, setListPath] = useState("/workspace");
+  const [listRecursive, setListRecursive] = useState(false);
+  const [listHidden, setListHidden] = useState(false);
+  const [listedFiles, setListedFiles] = useState<FileInfo[]>([]);
 
   // Git Operations
   const [gitRepoUrl, setGitRepoUrl] = useState("");
@@ -1468,6 +1508,63 @@ function FilesTab({
     }
   };
 
+  const handleListFiles = async () => {
+    if (!client || !listPath.trim()) return;
+    try {
+      const result = await client.listFiles(listPath, {
+        recursive: listRecursive,
+        includeHidden: listHidden,
+      });
+      
+      // Sort files for proper tree display using relativePath
+      const sortedFiles = (result.files || []).sort((a, b) => {
+        // Use relativePath for cleaner sorting
+        const aSegments = a.relativePath.split('/').filter(s => s);
+        const bSegments = b.relativePath.split('/').filter(s => s);
+        
+        // Compare segment by segment
+        const minLength = Math.min(aSegments.length, bSegments.length);
+        
+        for (let i = 0; i < minLength; i++) {
+          // If we're at the last segment for either path
+          const aIsLast = i === aSegments.length - 1;
+          const bIsLast = i === bSegments.length - 1;
+          
+          // If one is a parent of the other
+          if (aIsLast && !bIsLast) {
+            // a is a parent directory of b (if a is a directory)
+            return a.type === 'directory' ? -1 : 1;
+          }
+          if (!aIsLast && bIsLast) {
+            // b is a parent directory of a (if b is a directory)
+            return b.type === 'directory' ? 1 : -1;
+          }
+          
+          // If both are at the same level (both last or both not last)
+          if (aIsLast && bIsLast) {
+            // Same directory level - directories first, then alphabetical
+            if (a.type === 'directory' && b.type !== 'directory') return -1;
+            if (a.type !== 'directory' && b.type === 'directory') return 1;
+          }
+          
+          // Compare the segments alphabetically
+          const segmentCompare = aSegments[i].localeCompare(bSegments[i]);
+          if (segmentCompare !== 0) return segmentCompare;
+        }
+        
+        // If we get here, one path is a prefix of the other
+        // The shorter path (parent) should come first
+        return aSegments.length - bSegments.length;
+      });
+      
+      setListedFiles(sortedFiles);
+      addResult("success", `Listed ${result.count || 0} files in: ${listPath}`);
+    } catch (error: any) {
+      addResult("error", `Failed to list files: ${error.message}`);
+      setListedFiles([]);
+    }
+  };
+
   const handleGitCheckout = async () => {
     if (!client || !gitRepoUrl.trim()) return;
     try {
@@ -1658,6 +1755,91 @@ function FilesTab({
             </button>
           </div>
         </div>
+
+        {/* List Files */}
+        <div className="operation-group">
+          <h3>List Files</h3>
+          <div className="input-group">
+            <input
+              type="text"
+              placeholder="Directory path (e.g., /workspace)"
+              value={listPath}
+              onChange={(e) => setListPath(e.target.value)}
+              className="file-input"
+            />
+            <button
+              onClick={handleListFiles}
+              disabled={!listPath.trim() || connectionStatus !== "connected"}
+              className="action-button"
+            >
+              List Files
+            </button>
+          </div>
+          <div className="list-options">
+            <label>
+              <input
+                type="checkbox"
+                checked={listRecursive}
+                onChange={(e) => setListRecursive(e.target.checked)}
+              />
+              Recursive
+            </label>
+            <label>
+              <input
+                type="checkbox"
+                checked={listHidden}
+                onChange={(e) => setListHidden(e.target.checked)}
+              />
+              Include Hidden
+            </label>
+          </div>
+          {listedFiles.length > 0 && (
+            <div className="file-list-results">
+              <h4>Files ({listedFiles.length}):</h4>
+              <div className="file-list">
+                {listedFiles.map((file, index) => {
+                  // Calculate indentation level using the relativePath field
+                  const depth = listRecursive ? (file.relativePath.split('/').filter(s => s).length - 1) : 0;
+                  
+                  // For directories, add a trailing slash for clarity
+                  const displayName = file.type === 'directory' ? `${file.name}/` : file.name;
+                  
+                  // Add tree-like prefix for better hierarchy visualization
+                  const treePrefix = depth > 0 ? '├── ' : '';
+                  
+                  return (
+                    <div 
+                      key={index} 
+                      className="file-item"
+                      style={{ 
+                        paddingLeft: `${depth * 16 + 8}px`,
+                        fontWeight: file.type === 'directory' ? '500' : 'normal'
+                      }}
+                    >
+                      {depth > 0 && <span className="tree-prefix">{treePrefix}</span>}
+                      <span className="file-icon">
+                        {file.type === 'directory' ? '📁' : 
+                         file.permissions.executable ? '⚙️' : '📄'}
+                      </span>
+                      <span className="file-mode">{file.mode}</span>
+                      <span className="file-name" title={file.absolutePath}>
+                        {displayName}
+                      </span>
+                      <span className="file-details">
+                        {file.type === 'file' && (
+                          <span className="file-size">{file.size.toLocaleString()} bytes</span>
+                        )}
+                        <span className="file-date">
+                          {new Date(file.modifiedAt).toLocaleDateString()}
+                        </span>
+                      </span>
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          )}
+        </div>
       </div>
       {/* Git Operations */}
       <div className="git-section">
@@ -3047,7 +3229,7 @@ result = x / y`,
 }
 
 function SandboxTester() {
-  const [activeTab, setActiveTab] = useState<TabType>("notebook");
+  const [activeTab, setActiveTab] = useState<TabType>("commands");
   const [client, setClient] = useState<SandboxApiClient | null>(null);
   const [connectionStatus, setConnectionStatus] = useState<
     "disconnected" | "connecting" | "connected"

examples/basic/app/style.css

@@ -10,6 +10,113 @@ body {
   -moz-osx-font-smoothing: grayscale;
 }
 
+/* List Files Styles */
+.list-options {
+  display: flex;
+  gap: 1rem;
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.list-options label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9rem;
+  color: #8b949e;
+  cursor: pointer;
+}
+
+.list-options input[type="checkbox"] {
+  cursor: pointer;
+}
+
+.file-list-results {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  max-height: 400px;
+  overflow-y: auto;
+}
+
+.file-list-results h4 {
+  margin-top: 0;
+  margin-bottom: 0.75rem;
+  color: #58a6ff;
+  font-size: 0.95rem;
+}
+
+.file-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.file-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem;
+  border-radius: 4px;
+  transition: background-color 0.2s;
+  position: relative;
+}
+
+.file-item:hover {
+  background-color: #161b22;
+}
+
+.file-item::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 1px;
+  background: linear-gradient(to bottom, transparent, #30363d, transparent);
+}
+
+.tree-prefix {
+  color: #30363d;
+  font-family: "Fira Code", monospace;
+  margin-right: 0.25rem;
+}
+
+.file-icon {
+  font-size: 1.1rem;
+  flex-shrink: 0;
+}
+
+.file-mode {
+  font-family: "Fira Code", monospace;
+  font-size: 0.85rem;
+  color: #7ee83f;
+  margin-right: 0.75rem;
+}
+
+.file-name {
+  flex: 1;
+  font-family: "Fira Code", monospace;
+  font-size: 0.9rem;
+}
+
+.file-details {
+  display: flex;
+  gap: 1rem;
+  font-size: 0.85rem;
+  color: #8b949e;
+}
+
+.file-size {
+  flex-shrink: 0;
+}
+
+.file-date {
+  flex-shrink: 0;
+}
+
 /* Main Container */
 .sandbox-tester-container {
   max-width: 1280px;

examples/basic/src/endpoints/fileList.ts

@@ -0,0 +1,25 @@
+import type { Sandbox } from "@cloudflare/sandbox";
+import { errorResponse, jsonResponse, parseJsonBody } from "../http";
+
+export async function listFiles(sandbox: Sandbox<unknown>, request: Request) {
+  try {
+    const body = await parseJsonBody(request);
+    const { path, options } = body;
+
+    if (!path) {
+      return errorResponse("Path is required");
+    }
+
+    const result = await sandbox.listFiles(path, options);
+    return jsonResponse({ 
+      success: true,
+      path, 
+      files: result.files,
+      count: result.files.length,
+      timestamp: new Date().toISOString()
+    });
+  } catch (error: any) {
+    console.error("Error listing files:", error);
+    return errorResponse(`Failed to list files: ${error.message}`);
+  }
+}

examples/basic/src/endpoints/index.ts

@@ -7,6 +7,7 @@ export { listProcesses } from "./processList";
 export { getProcessLogs, streamProcessLogs } from "./processLogs";
 export { startProcess } from "./processStart";
 export { readFile } from "./fileRead";
+export { listFiles } from "./fileList";
 export { deleteFile } from "./fileDelete";
 export { renameFile } from "./fileRename";
 export { moveFile } from "./fileMove";