[Storage] Require explicit recursive flag for mkdir (and tweak the semantics of writeFile and listFiles) (#2969)

## Summary

This PR changes the filesystem backends to require explicit `recursive:
true` when creating nested directories, matching standard filesystem
semantics.

Previously, `mkdir('/a/b/c')` would silently create all parent
directories. Now it throws if `/a/b` doesn't exist, unless you pass
`recursive: true`.

Similarly, `writeFile('/a/b/file.txt')` now throws if `/a/b` doesn't
exist, instead of creating it.

**Changes:**
- `mkdir(path, recursive?)` - only creates parent dirs when
`recursive=true`
- `writeFile(path, data)` - throws if parent directory doesn't exist
- `listFiles(path)` - returns `[]` for non-existent paths (consistent
with FSHelpers)
- `mkdir('/')` - now a no-op instead of throwing

**Updated interfaces:**
- `WritableFilesystemBackend.mkdir(path, recursive?: boolean)`
- `AsyncWritableFilesystem.mkdir(path, options?: { recursive?: boolean
})`

## Test plan

- [x] Added tests for `mkdir` throwing without recursive flag
- [x] Added tests for `mkdir` with recursive flag creating nested dirs  
- [x] Added tests for `writeFile` throwing when parent doesn't exist
- [x] Added tests for `listFiles` returning `[]` for non-existent paths
- [x] Updated Blueprint Editor to use `{ recursive: true }` when
creating parent dirs

Author: adamziel

packages/playground/storage/src/lib/filesystems.spec.ts

@@ -469,7 +469,7 @@ describe('InMemoryFilesystemBackend', () => {
 		});
 
 		it('should return true for nested directories', async () => {
-			await backend.mkdir('/parent/child');
+			await backend.mkdir('/parent/child', true);
 			expect(await backend.fileExists('/parent')).toBe(true);
 			expect(await backend.fileExists('/parent/child')).toBe(true);
 		});
@@ -501,8 +501,14 @@ describe('InMemoryFilesystemBackend', () => {
 			expect(await backend.isDir('/newdir')).toBe(true);
 		});
 
-		it('should create nested directories', async () => {
-			await backend.mkdir('/parent/child/grandchild');
+		it('should throw when creating nested directories without recursive flag', async () => {
+			await expect(
+				backend.mkdir('/parent/child/grandchild')
+			).rejects.toThrow();
+		});
+
+		it('should create nested directories with recursive flag', async () => {
+			await backend.mkdir('/parent/child/grandchild', true);
 			expect(await backend.isDir('/parent')).toBe(true);
 			expect(await backend.isDir('/parent/child')).toBe(true);
 			expect(await backend.isDir('/parent/child/grandchild')).toBe(true);
@@ -513,6 +519,12 @@ describe('InMemoryFilesystemBackend', () => {
 			await backend.mkdir('/mydir');
 			expect(await backend.isDir('/mydir')).toBe(true);
 		});
+
+		it('should be a no-op for root directory', async () => {
+			// mkdir('/') should not throw, root always exists
+			await backend.mkdir('/');
+			expect(await backend.isDir('/')).toBe(true);
+		});
 	});
 
 	describe('writeFile and read', () => {
@@ -525,12 +537,17 @@ describe('InMemoryFilesystemBackend', () => {
 			expect(content).toEqual(data);
 		});
 
-		it('should create parent directories when writing a file', async () => {
+		it('should throw when parent directory does not exist', async () => {
 			const data = new Uint8Array([1, 2, 3]);
-			await backend.writeFile('/deep/nested/file.txt', data);
+			await expect(
+				backend.writeFile('/nonexistent/file.txt', data)
+			).rejects.toThrow();
+		});
 
-			expect(await backend.isDir('/deep')).toBe(true);
-			expect(await backend.isDir('/deep/nested')).toBe(true);
+		it('should write to existing nested directory', async () => {
+			await backend.mkdir('/deep/nested', true);
+			const data = new Uint8Array([1, 2, 3]);
+			await backend.writeFile('/deep/nested/file.txt', data);
 			expect(await backend.fileExists('/deep/nested/file.txt')).toBe(
 				true
 			);
@@ -556,6 +573,17 @@ describe('InMemoryFilesystemBackend', () => {
 			const files = await backend.listFiles('/mydir');
 			expect(files).toContain('nested.txt');
 		});
+
+		it('should return empty array for non-existent paths', async () => {
+			const files = await backend.listFiles('/nonexistent');
+			expect(files).toEqual([]);
+		});
+
+		it('should return empty array when listing a file path', async () => {
+			await backend.writeFile('/file.txt', new Uint8Array([1]));
+			const files = await backend.listFiles('/file.txt');
+			expect(files).toEqual([]);
+		});
 	});
 
 	describe('unlink', () => {
@@ -576,7 +604,7 @@ describe('InMemoryFilesystemBackend', () => {
 		});
 
 		it('should delete a directory recursively', async () => {
-			await backend.mkdir('/parent/child');
+			await backend.mkdir('/parent/child', true);
 			await backend.writeFile(
 				'/parent/child/file.txt',
 				new Uint8Array([1])

packages/playground/storage/src/lib/filesystems.ts

@@ -23,7 +23,7 @@ export interface TraversableFilesystemBackend extends ReadableFilesystemBackend
 export interface WritableFilesystemBackend extends TraversableFilesystemBackend {
 	fileExists(absolutePath: string): Promise<boolean>;
 	writeFile(absolutePath: string, data: Uint8Array): Promise<void>;
-	mkdir(absolutePath: string): Promise<void>;
+	mkdir(absolutePath: string, recursive?: boolean): Promise<void>;
 	rmdir(absolutePath: string, recursive: boolean): Promise<void>;
 	mv(absoluteSource: string, absoluteDestination: string): Promise<void>;
 	unlink(absolutePath: string): Promise<void>;
@@ -41,7 +41,7 @@ export interface AsyncWritableFilesystem extends EventTarget {
 	readFileAsText(path: string): Promise<string>;
 	listFiles(path: string): Promise<string[]>;
 	writeFile(path: string, data: Uint8Array | string): Promise<void>;
-	mkdir(path: string): Promise<void>;
+	mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
 	rmdir(path: string, options?: { recursive?: boolean }): Promise<void>;
 	mv(source: string, destination: string): Promise<void>;
 	unlink(path: string): Promise<void>;
@@ -121,8 +121,11 @@ export class EventedFilesystem
 		this.dispatchEvent(new Event('change'));
 	}
 
-	async mkdir(path: string): Promise<void> {
-		await this.backend.mkdir(path);
+	async mkdir(
+		path: string,
+		options?: { recursive?: boolean }
+	): Promise<void> {
+		await this.backend.mkdir(path, options?.recursive ?? false);
 		this.dispatchEvent(new Event('change'));
 	}
 
@@ -596,21 +599,27 @@ export class OpfsFilesystemBackend implements WritableFilesystemBackend {
 		if (!fileName) {
 			throw new Error(`Invalid file path: ${absolutePath}`);
 		}
+		// Navigate to parent directory without creating it
 		let dir = this.opfsRoot;
 		for (const segment of segments) {
-			dir = await dir.getDirectoryHandle(segment, { create: true });
+			dir = await dir.getDirectoryHandle(segment);
 		}
 		const handle = await dir.getFileHandle(fileName, { create: true });
 		const writable = await handle.createWritable();
 		await writable.write(data);
 		await writable.close();
 	}
 
-	async mkdir(absolutePath: string): Promise<void> {
+	async mkdir(absolutePath: string, recursive = false): Promise<void> {
 		const segments = absolutePath.split('/').filter(Boolean);
 		let dir = this.opfsRoot;
-		for (const segment of segments) {
-			dir = await dir.getDirectoryHandle(segment, { create: true });
+		for (let i = 0; i < segments.length; i++) {
+			const segment = segments[i];
+			const isLast = i === segments.length - 1;
+			// Only create the final directory; parent dirs must exist unless recursive
+			dir = await dir.getDirectoryHandle(segment, {
+				create: recursive || isLast,
+			});
 		}
 	}
 
@@ -733,16 +742,25 @@ export class InMemoryFilesystemBackend implements WritableFilesystemBackend {
 	}
 
 	async listFiles(absolutePath: string): Promise<string[]> {
-		const dir = this.getDir(absolutePath);
-		return Object.keys(dir.children);
+		const node = this.getNode(absolutePath);
+		if (!node || node.type !== 'dir') {
+			return [];
+		}
+		return Object.keys(node.children);
 	}
 
 	async writeFile(absolutePath: string, data: Uint8Array): Promise<void> {
 		this.writeFileSync(absolutePath, data);
 	}
 
-	async mkdir(absolutePath: string): Promise<void> {
-		const { parent, name } = this.getParent(absolutePath);
+	async mkdir(absolutePath: string, recursive = false): Promise<void> {
+		// Root always exists, nothing to create
+		if (absolutePath === '/') {
+			return;
+		}
+		const { parent, name } = recursive
+			? this.getOrCreateParent(absolutePath)
+			: this.getParent(absolutePath);
 		if (!parent.children[name]) {
 			parent.children[name] = { type: 'dir', children: {} };
 		}
@@ -833,14 +851,37 @@ export class InMemoryFilesystemBackend implements WritableFilesystemBackend {
 		return node;
 	}
 
+	/**
+	 * Get parent directory, throwing if it doesn't exist.
+	 */
 	private getParent(absolutePath: string): { parent: DirNode; name: string } {
 		const segments = absolutePath.split('/').filter(Boolean);
 		const name = segments.pop();
+		if (!name) {
+			throw new Error(`Invalid path: ${absolutePath}`);
+		}
 		const parentPath = segments.length ? `/${segments.join('/')}` : '/';
-		const parent = this.ensureDir(parentPath);
+		const parent = this.getNode(parentPath);
+		if (!parent || parent.type !== 'dir') {
+			throw new Error(`Parent directory not found: ${parentPath}`);
+		}
+		return { parent, name };
+	}
+
+	/**
+	 * Get parent directory, creating it if it doesn't exist.
+	 */
+	private getOrCreateParent(absolutePath: string): {
+		parent: DirNode;
+		name: string;
+	} {
+		const segments = absolutePath.split('/').filter(Boolean);
+		const name = segments.pop();
 		if (!name) {
 			throw new Error(`Invalid path: ${absolutePath}`);
 		}
+		const parentPath = segments.length ? `/${segments.join('/')}` : '/';
+		const parent = this.ensureDir(parentPath);
 		return { parent, name };
 	}
 

packages/playground/website/src/components/blueprint-editor/AutosavedBlueprintBundleEditor.tsx

@@ -88,7 +88,7 @@ async function populateFilesystemFromBlueprint(
 			}
 			const parent = dirname(absolutePath);
 			if (!(await fs.fileExists(parent))) {
-				await fs.mkdir(parent);
+				await fs.mkdir(parent, { recursive: true });
 			}
 			await fs.writeFile(absolutePath, content);
 		}