feat: US-011 - Add copy and readDirStat optimizations

Author: NathanFlurry

packages/core/src/index.ts

@@ -37,6 +37,7 @@ export { KernelError, defaultTermios, noopKernelLogger } from "./kernel/types.js
 export type {
 	VirtualFileSystem,
 	VirtualDirEntry,
+	VirtualDirStatEntry,
 	VirtualStat,
 } from "./kernel/vfs.js";
 

packages/core/src/kernel/mount-table.ts

@@ -7,7 +7,7 @@
  */
 
 import { KernelError } from "./types.js";
-import type { VirtualDirEntry, VirtualFileSystem, VirtualStat } from "./vfs.js";
+import type { VirtualDirEntry, VirtualDirStatEntry, VirtualFileSystem, VirtualStat } from "./vfs.js";
 
 export interface MountOptions {
 	readOnly?: boolean;
@@ -382,6 +382,50 @@ export class MountTable implements VirtualFileSystem {
 		await mount.fs.fsync?.(relativePath);
 	}
 
+	async copy(srcPath: string, dstPath: string): Promise<void> {
+		const srcResolved = this.resolve(srcPath);
+		const dstResolved = this.resolve(dstPath);
+
+		if (srcResolved.mount !== dstResolved.mount) {
+			throw new KernelError(
+				"EXDEV",
+				`copy across mounts: ${srcPath} -> ${dstPath}`,
+			);
+		}
+
+		this.assertWritable(srcResolved.mount, dstPath);
+
+		if (srcResolved.mount.fs.copy) {
+			return srcResolved.mount.fs.copy(
+				srcResolved.relativePath,
+				dstResolved.relativePath,
+			);
+		}
+
+		// Fallback: readFile + writeFile.
+		const content = await srcResolved.mount.fs.readFile(srcResolved.relativePath);
+		await srcResolved.mount.fs.writeFile(dstResolved.relativePath, content);
+	}
+
+	async readDirStat(path: string): Promise<VirtualDirStatEntry[]> {
+		const { mount, relativePath } = this.resolve(path);
+
+		if (mount.fs.readDirStat) {
+			return mount.fs.readDirStat(relativePath);
+		}
+
+		// Fallback: readDirWithTypes + stat for each entry.
+		const entries = await mount.fs.readDirWithTypes(relativePath);
+		const normalized = normalizePath(path);
+		const results: VirtualDirStatEntry[] = [];
+		for (const entry of entries) {
+			const entryPath = normalized === "/" ? `/${entry.name}` : `${normalized}/${entry.name}`;
+			const stat = await mount.fs.stat(entryPath);
+			results.push({ ...entry, stat });
+		}
+		return results;
+	}
+
 	// -----------------------------------------------------------------------
 	// Helpers
 	// -----------------------------------------------------------------------

packages/core/src/kernel/vfs.ts

@@ -13,6 +13,10 @@ export interface VirtualDirEntry {
 	ino?: number;
 }
 
+export interface VirtualDirStatEntry extends VirtualDirEntry {
+	stat: VirtualStat;
+}
+
 export interface VirtualStat {
 	mode: number;
 	size: number;
@@ -72,4 +76,10 @@ export interface VirtualFileSystem {
 
 	/** Flush buffered writes for the given path to durable storage. */
 	fsync?(path: string): Promise<void>;
+
+	/** Copy a file within the same filesystem. */
+	copy?(srcPath: string, dstPath: string): Promise<void>;
+
+	/** Combined readdir + stat. Avoids N+1 queries for directory listings. */
+	readDirStat?(path: string): Promise<VirtualDirStatEntry[]>;
 }

packages/core/src/vfs/chunked-vfs.ts

@@ -12,7 +12,7 @@
  */
 
 import { KernelError } from "../kernel/types.js";
-import type { VirtualDirEntry, VirtualFileSystem, VirtualStat } from "../kernel/vfs.js";
+import type { VirtualDirEntry, VirtualDirStatEntry, VirtualFileSystem, VirtualStat } from "../kernel/vfs.js";
 import type { FsBlockStore, FsMetadataStore, InodeMeta } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -1202,5 +1202,78 @@ export function createChunkedVfs(options: ChunkedVfsOptions): VirtualFileSystem
 		};
 	}
 
+	// Add copy method.
+	vfs.copy = async (srcPath: string, dstPath: string): Promise<void> => {
+		const srcIno = await resolveIno(srcPath);
+		const srcMeta = await requireInode(srcIno);
+		if (srcMeta.type === "directory") {
+			throw new KernelError("EISDIR", `illegal operation on a directory: '${srcPath}'`);
+		}
+
+		const { parentIno, name } = await ensureParents(dstPath);
+		const existingDstIno = await metadata.lookup(parentIno, name);
+		if (existingDstIno !== null) {
+			throw new KernelError("EEXIST", `file already exists: '${dstPath}'`);
+		}
+
+		await metadata.transaction(async () => {
+			const dstIno = await metadata.createInode({
+				type: "file",
+				mode: srcMeta.mode,
+				uid: srcMeta.uid,
+				gid: srcMeta.gid,
+			});
+			await metadata.createDentry(parentIno, name, dstIno, "file");
+
+			if (srcMeta.storageMode === "inline") {
+				const content = srcMeta.inlineContent
+					? new Uint8Array(srcMeta.inlineContent)
+					: new Uint8Array(0);
+				await metadata.updateInode(dstIno, {
+					nlink: 1,
+					size: srcMeta.size,
+					storageMode: "inline",
+					inlineContent: content,
+				});
+			} else {
+				// Chunked: copy each block.
+				const chunkEntries = await metadata.getAllChunkKeys(srcIno);
+				for (const entry of chunkEntries) {
+					const newKey = blockKey(dstIno, entry.chunkIndex);
+					if (blocks.copy) {
+						await blocks.copy(entry.key, newKey);
+					} else {
+						const data = await blocks.read(entry.key);
+						await blocks.write(newKey, data);
+					}
+					await metadata.setChunkKey(dstIno, entry.chunkIndex, newKey);
+				}
+				await metadata.updateInode(dstIno, {
+					nlink: 1,
+					size: srcMeta.size,
+					storageMode: "chunked",
+					inlineContent: null,
+				});
+			}
+		});
+	};
+
+	// Add readDirStat method.
+	vfs.readDirStat = async (path: string): Promise<VirtualDirStatEntry[]> => {
+		const ino = await resolveIno(path);
+		const meta = await requireInode(ino);
+		if (meta.type !== "directory") {
+			throw new KernelError("ENOTDIR", `not a directory: '${path}'`);
+		}
+		const entries = await metadata.listDirWithStats(ino);
+		return entries.map((e) => ({
+			name: e.name,
+			isDirectory: e.type === "directory",
+			isSymbolicLink: e.type === "symlink",
+			ino: e.ino,
+			stat: inodeMetaToStat(e.stat),
+		}));
+	};
+
 	return vfs;
 }

packages/core/test/vfs/chunked-vfs-conformance.test.ts

@@ -27,8 +27,8 @@ defineVfsConformanceTests({
 		mkdir: true,
 		removeDir: true,
 		fsync: false,
-		copy: false,
-		readDirStat: false,
+		copy: true,
+		readDirStat: true,
 	},
 	inlineThreshold: INLINE_THRESHOLD,
 	chunkSize: CHUNK_SIZE,
@@ -56,8 +56,8 @@ defineVfsConformanceTests({
 		mkdir: true,
 		removeDir: true,
 		fsync: true,
-		copy: false,
-		readDirStat: false,
+		copy: true,
+		readDirStat: true,
 	},
 	inlineThreshold: INLINE_THRESHOLD,
 	chunkSize: CHUNK_SIZE,

packages/core/test/vfs/host-chunked-vfs-conformance.test.ts

@@ -39,8 +39,8 @@ defineVfsConformanceTests({
 		mkdir: true,
 		removeDir: true,
 		fsync: false,
-		copy: false,
-		readDirStat: false,
+		copy: true,
+		readDirStat: true,
 	},
 	inlineThreshold: INLINE_THRESHOLD,
 	chunkSize: CHUNK_SIZE,

packages/core/test/vfs/sqlite-chunked-vfs-conformance.test.ts

@@ -27,8 +27,8 @@ defineVfsConformanceTests({
 		mkdir: true,
 		removeDir: true,
 		fsync: false,
-		copy: false,
-		readDirStat: false,
+		copy: true,
+		readDirStat: true,
 	},
 	inlineThreshold: INLINE_THRESHOLD,
 	chunkSize: CHUNK_SIZE,