feat(daemon,sdk): add depth-aware recursive file listing

Signed-off-by: MDzaja <mirkodzaja0@gmail.com>

Author: MDzaja

apps/daemon/pkg/toolbox/docs/docs.go

@@ -4,52 +4,138 @@
 package fs
 
 import (
+	"errors"
+	iofs "io/fs"
 	"net/http"
 	"os"
 	"path/filepath"
+	"strconv"
+	"strings"
 
+	"github.com/daytonaio/daemon/internal/util"
 	"github.com/gin-gonic/gin"
 )
 
 // ListFiles godoc
 //
 //	@Summary		List files and directories
-//	@Description	List files and directories in the specified path
+//	@Description	List files and directories in the specified path. Use the optional depth
+//	@Description	parameter to list recursively: depth=1 (default) lists the directory's
+//	@Description	entries, depth=2 also includes their children, and so on.
 //	@Tags			file-system
 //	@Produce		json
 //	@Param			path	query	string	false	"Directory path to list (defaults to working directory)"
+//	@Param			depth	query	int		false	"How many levels deep to list (default: 1, must be >= 1)"
 //	@Success		200		{array}	FileInfo
 //	@Router			/files [get]
 //
 //	@id				ListFiles
 func ListFiles(c *gin.Context) {
-	path := c.Query("path")
-	if path == "" {
-		path = "."
+	root := c.Query("path")
+	if root == "" {
+		root = "."
 	}
 
-	files, err := os.ReadDir(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			c.AbortWithError(http.StatusNotFound, err)
+	depth := 1
+	if depthStr := c.Query("depth"); depthStr != "" {
+		parsed, err := strconv.Atoi(depthStr)
+		if err != nil || parsed < 1 {
+			c.AbortWithError(http.StatusBadRequest, errors.New("depth must be an integer >= 1"))
 			return
 		}
-		if os.IsPermission(err) {
-			c.AbortWithError(http.StatusForbidden, err)
-			return
-		}
-		c.AbortWithError(http.StatusBadRequest, err)
+		depth = parsed
+	}
+
+	stripPath := util.ClientRejectsUnknownResponseFields(c.Request.Header)
+
+	// depth=1 uses the original os.ReadDir code path to avoid behavioural
+	// regressions for the default (most common) case.
+	if depth == 1 {
+		listFilesShallow(c, root, stripPath)
 		return
 	}
+	listFilesRecursive(c, root, depth, stripPath)
+}
 
-	var fileInfos = make([]FileInfo, 0)
+func listFilesShallow(c *gin.Context, path string, stripPath bool) {
+	files, err := os.ReadDir(path)
+	if err != nil {
+		abortWithFsError(c, err)
+		return
+	}
+
+	fileInfos := make([]FileInfo, 0)
 	for _, file := range files {
-		info, err := getFileInfo(filepath.Join(path, file.Name()))
+		fullPath := filepath.Join(path, file.Name())
+		info, err := getFileInfo(fullPath)
 		if err != nil {
 			continue
 		}
+		if !stripPath {
+			info.Path = fullPath
+		}
 		fileInfos = append(fileInfos, info)
 	}
 
 	c.JSON(http.StatusOK, fileInfos)
 }
+
+// listFilesRecursive returns a flat listing up to depth levels below root;
+// unreadable subtrees are skipped and symlinks are not followed.
+func listFilesRecursive(c *gin.Context, root string, depth int, stripPath bool) {
+	if _, err := os.ReadDir(root); err != nil {
+		abortWithFsError(c, err)
+		return
+	}
+
+	fileInfos := make([]FileInfo, 0)
+	_ = filepath.WalkDir(root, func(entryPath string, d iofs.DirEntry, err error) error {
+		if err != nil {
+			if d != nil && d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if entryPath == root {
+			return nil
+		}
+
+		rel, relErr := filepath.Rel(root, entryPath)
+		if relErr != nil {
+			return nil
+		}
+		entryDepth := strings.Count(rel, string(os.PathSeparator)) + 1
+		if entryDepth > depth {
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+
+		if info, infoErr := getFileInfo(entryPath); infoErr == nil {
+			if !stripPath {
+				info.Path = entryPath
+			}
+			fileInfos = append(fileInfos, info)
+		}
+
+		if d.IsDir() && entryDepth >= depth {
+			return filepath.SkipDir
+		}
+		return nil
+	})
+
+	c.JSON(http.StatusOK, fileInfos)
+}
+
+func abortWithFsError(c *gin.Context, err error) {
+	if os.IsNotExist(err) {
+		c.AbortWithError(http.StatusNotFound, err)
+		return
+	}
+	if os.IsPermission(err) {
+		c.AbortWithError(http.StatusForbidden, err)
+		return
+	}
+	c.AbortWithError(http.StatusBadRequest, err)
+}

apps/daemon/pkg/toolbox/docs/swagger.json

@@ -7,6 +7,8 @@ import "time"
 
 type FileInfo struct {
 	Name string `json:"name" validate:"required"`
+	// Full path of the entry
+	Path string `json:"path,omitempty"`
 	Size int64  `json:"size" validate:"required"`
 	Mode string `json:"mode" validate:"required"`
 	// Deprecated: ModTime uses Go's time.String() layout which is not a standard format.

apps/daemon/pkg/toolbox/docs/swagger.yaml

@@ -149,7 +149,7 @@ result, err := sandbox.Process.ExecuteCommand(ctx, "ls -la")
   - [func \(f \*FileSystemService\) DownloadFileStream\(ctx context.Context, remotePath string, opts ...DownloadStreamOption\) \(io.ReadCloser, error\)](<#FileSystemService.DownloadFileStream>)
   - [func \(f \*FileSystemService\) FindFiles\(ctx context.Context, path, pattern string\) \(any, error\)](<#FileSystemService.FindFiles>)
   - [func \(f \*FileSystemService\) GetFileInfo\(ctx context.Context, path string\) \(\*types.FileInfo, error\)](<#FileSystemService.GetFileInfo>)
-  - [func \(f \*FileSystemService\) ListFiles\(ctx context.Context, path string\) \(\[\]\*types.FileInfo, error\)](<#FileSystemService.ListFiles>)
+  - [func \(f \*FileSystemService\) ListFiles\(ctx context.Context, path string, opts ...func\(\*options.ListFiles\)\) \(\[\]\*types.FileInfo, error\)](<#FileSystemService.ListFiles>)
   - [func \(f \*FileSystemService\) MoveFiles\(ctx context.Context, source, destination string\) error](<#FileSystemService.MoveFiles>)
   - [func \(f \*FileSystemService\) ReplaceInFiles\(ctx context.Context, files \[\]string, pattern, newValue string\) \(any, error\)](<#FileSystemService.ReplaceInFiles>)
   - [func \(f \*FileSystemService\) SearchFiles\(ctx context.Context, path, pattern string\) \(any, error\)](<#FileSystemService.SearchFiles>)
@@ -1737,7 +1737,7 @@ Returns an error if the path doesn't exist.
 ### func \(\*FileSystemService\) ListFiles
 
 ```go
-func (f *FileSystemService) ListFiles(ctx context.Context, path string) ([]*types.FileInfo, error)
+func (f *FileSystemService) ListFiles(ctx context.Context, path string, opts ...func(*options.ListFiles)) ([]*types.FileInfo, error)
 ```
 
 ListFiles lists files and directories in the specified path.

apps/daemon/pkg/toolbox/fs/list_files.go

@@ -52,6 +52,7 @@ opts := options.Apply(
 - [func WithCreatePtySize\(ptySize types.PtySize\) func\(\*CreatePty\)](<#WithCreatePtySize>)
 - [func WithCustomContext\(contextID string\) func\(\*RunCode\)](<#WithCustomContext>)
 - [func WithCwd\(cwd string\) func\(\*ExecuteCommand\)](<#WithCwd>)
+- [func WithDepth\(depth int32\) func\(\*ListFiles\)](<#WithDepth>)
 - [func WithEnv\(env map\[string\]string\) func\(\*RunCode\)](<#WithEnv>)
 - [func WithExecuteTimeout\(timeout time.Duration\) func\(\*ExecuteCommand\)](<#WithExecuteTimeout>)
 - [func WithExtraIndexURLs\(urls ...string\) func\(\*PipInstall\)](<#WithExtraIndexURLs>)
@@ -87,6 +88,7 @@ opts := options.Apply(
 - [type GitDeleteBranch](<#GitDeleteBranch>)
 - [type GitPull](<#GitPull>)
 - [type GitPush](<#GitPush>)
+- [type ListFiles](<#ListFiles>)
 - [type PipInstall](<#PipInstall>)
 - [type PtySession](<#PtySession>)
 - [type RunCode](<#RunCode>)
@@ -289,6 +291,23 @@ result, err := sandbox.Process.ExecuteCommand(ctx, "ls -la",
 )
 ```
 
+<a name="WithDepth"></a>
+## func WithDepth
+
+```go
+func WithDepth(depth int32) func(*ListFiles)
+```
+
+WithDepth sets how many levels deep to list. Depth 1 \(the default\) lists the directory's entries, depth 2 also includes their children, and so on.
+
+Example:
+
+```
+files, err := sandbox.FileSystem.ListFiles(ctx, "/home/user",
+    options.WithDepth(3),
+)
+```
+
 <a name="WithEnv"></a>
 ## func WithEnv
 
@@ -891,6 +910,17 @@ type GitPush struct {
 }
 ```
 
+<a name="ListFiles"></a>
+## type ListFiles
+
+ListFiles holds optional parameters for \[daytona.FileSystemService.ListFiles\].
+
+```go
+type ListFiles struct {
+    Depth *int32 // How many levels deep to list (default: 1, must be >= 1)
+}
+```
+
 <a name="PipInstall"></a>
 ## type PipInstall
 

apps/daemon/pkg/toolbox/fs/types.go

@@ -231,6 +231,7 @@ FileInfo represents file metadata
 ```go
 type FileInfo struct {
     Name         string
+    Path         string
     Size         int64
     Mode         string
     ModifiedTime time.Time

apps/docs/src/content/docs/en/go-sdk/daytona.mdx

@@ -194,6 +194,26 @@ Lists files and directories under a path.
 
 - `io.daytona.sdk.exception.DaytonaException` - if listing fails
 
+#### listFiles()
+```java
+public List<FileInfo> listFiles(String path, Integer depth)
+```
+
+Lists files and directories under a path, optionally recursing into subdirectories.
+
+**Parameters**:
+
+- `path` _String_ - directory path
+- `depth` _Integer_ - how many levels deep to list: depth=1 (default) lists the directory's entries, depth=2 also includes their children, and so on; must be >= 1. Each returned entry carries a full path field.
+
+**Returns**:
+
+- `List\<FileInfo\>` - file metadata entries
+
+**Throws**:
+
+- `io.daytona.sdk.exception.DaytonaException` - if listing fails
+
 #### getFileDetails()
 ```java
 public FileInfo getFileDetails(String path)