@seanhogg/builderforce-webcontainers-core 2026.10.5 → 2026.10.7

package/src/vfs.ts

@@ -2,13 +2,22 @@ import { normalizePath, join, dirname } from './paths.js';
 
 export type FileContent = string | Uint8Array;
 
-/** The nested tree shape `@webcontainer/api`'s `mount()` takes — accepted as-is. */
-export interface FileSystemTree {
-  [name: string]: { file: { contents: FileContent } } | { directory: FileSystemTree };
+/** A flat `{ 'src/main.tsx': '...' }` map: path → contents. */
+export type FlatFiles = Record<string, FileContent>;
+
+/**
+ * Files to write: a name maps to contents (a file) or to another tree (a
+ * directory). Names may hold slashes, so a {@link FlatFiles} map is a tree too,
+ * and the two styles mix freely: `{ src: { 'main.tsx': '…' }, 'public/a.svg': '…' }`.
+ */
+export interface FileTree {
+  [name: string]: FileContent | FileTree;
 }
 
-/** A flat `{ 'src/main.tsx': '...' }` map, the other shape callers commonly hold. */
-export type FlatFiles = Record<string, FileContent>;
+export interface DirectoryEntry {
+  name: string;
+  kind: 'file' | 'directory';
+}
 
 export interface FsChange {
   /** `mkdir` is an explicitly created (possibly empty) directory. */
@@ -94,6 +103,39 @@ export class VirtualFileSystem {
     return [...(this.children.get(normalizePath(path)) ?? [])].sort();
   }
 
+  /** Direct children with their kind, sorted by name — `readdir` for callers that render a tree. */
+  entries(path: string): DirectoryEntry[] {
+    const dir = normalizePath(path);
+    return this.readdir(dir).map((name) => ({ name, kind: this.children.has(join(dir, name)) ? 'directory' : 'file' }));
+  }
+
+  /**
+   * Move a file or a directory (with everything under it). Throws when `from` is
+   * missing or `to` already exists. Watchers see the old paths removed and the
+   * new ones written, which is what every consumer (dev server, process sync) needs.
+   */
+  rename(from: string, to: string): void {
+    const source = normalizePath(from);
+    const target = normalizePath(to);
+    if (source === target) return;
+    if (!this.exists(source)) throw new Error(`ENOENT: no such file or directory, rename '${source}' -> '${target}'`);
+    if (this.exists(target)) throw new Error(`EEXIST: file already exists, rename '${source}' -> '${target}'`);
+    if (target.startsWith(source + '/')) throw new Error(`EINVAL: cannot move '${source}' into itself`);
+    if (this.files.has(source)) {
+      const contents = this.files.get(source)!;
+      this.removeFile(source);
+      this.writeFile(target, contents);
+      return;
+    }
+    const prefix = source + '/';
+    const moved = [...this.files].filter(([path]) => path.startsWith(prefix));
+    const dirs = [...this.explicit].filter((dir) => dir === source || dir.startsWith(prefix));
+    this.rm(source);
+    this.mkdir(target);
+    for (const dir of dirs) this.mkdir(target + dir.slice(source.length));
+    for (const [path, contents] of moved) this.writeFile(target + path.slice(source.length), contents);
+  }
+
   /** Every file path, sorted. */
   list(): string[] {
     return [...this.files.keys()].sort();
@@ -129,18 +171,14 @@ export class VirtualFileSystem {
     return this.mtimes.get(normalizePath(path));
   }
 
-  /**
-   * Write many files at once. Takes either the nested WebContainer tree or a flat
-   * path→contents map — or a mix, since each entry is judged on its own.
-   */
-  mount(files: FileSystemTree | FlatFiles, at = '/'): void {
+  /** Write many files at once, under `at` (default `/`). A nested object is a directory, created even when empty. */
+  writeTree(files: FileTree, at = '/'): void {
     for (const [name, entry] of Object.entries(files)) {
       const path = join(at, name);
       if (typeof entry === 'string' || entry instanceof Uint8Array) this.writeFile(path, entry);
-      else if ('file' in entry) this.writeFile(path, entry.file.contents);
       else {
         this.mkdir(path);
-        this.mount(entry.directory, path);
+        this.writeTree(entry, path);
       }
     }
   }
@@ -152,9 +190,14 @@ export class VirtualFileSystem {
     return out;
   }
 
-  watch(listener: (change: FsChange) => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+  /** Every change, or with `under` only changes at or below that path. */
+  watch(listener: (change: FsChange) => void, options: { under?: string } = {}): () => void {
+    const root = options.under === undefined ? undefined : normalizePath(options.under);
+    const filtered = root === undefined || root === '/'
+      ? listener
+      : (change: FsChange) => (change.path === root || change.path.startsWith(root + '/')) && listener(change);
+    this.listeners.add(filtered);
+    return () => this.listeners.delete(filtered);
   }
 
   private removeFile(key: string): void {