feat: add tree-aware VFS methods to prevent recursion in file explorers

Add safe tree operations that guarantee no directory appears as its own child:
- getDirectChildren() returns only immediate children
- getTreeStructure() builds safe tree with recursion protection
- getDescendants() gets all descendants efficiently
- inspect() provides comprehensive path information

Also includes VFSTreeUtils for building and validating tree structures.

This resolves the common infinite recursion issue when building file
explorers, as discovered by the Soulcraft Studio team.

Co-Authored-By: User <noreply@user.local>

src/vfs/types.ts

@@ -386,6 +386,24 @@ export interface IVirtualFileSystem {
   rmdir(path: string, options?: { recursive?: boolean }): Promise<void>
   readdir(path: string, options?: ReaddirOptions): Promise<string[] | VFSDirent[]>
 
+  // Tree operations (NEW - prevents recursion issues)
+  getDirectChildren(path: string): Promise<VFSEntity[]>
+  getTreeStructure(path: string, options?: {
+    maxDepth?: number
+    includeHidden?: boolean
+    sort?: 'name' | 'modified' | 'size'
+  }): Promise<any>
+  getDescendants(path: string, options?: {
+    includeAncestor?: boolean
+    type?: 'file' | 'directory'
+  }): Promise<VFSEntity[]>
+  inspect(path: string): Promise<{
+    node: VFSEntity
+    children: VFSEntity[]
+    parent: VFSEntity | null
+    stats: VFSStats
+  }>
+
   // Metadata operations
   stat(path: string): Promise<VFSStats>
   lstat(path: string): Promise<VFSStats>