@statewalker/webrun-files-node 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @statewalker/webrun-files-node
+
+Node.js filesystem implementation of the `FilesApi` interface from `@statewalker/webrun-files`.
+
+## Overview
+
+This package provides a `FilesApi` implementation that works with the real filesystem using Node.js `fs/promises`. It maps virtual paths (starting with `/`) to a root directory on disk.
+
+## Installation
+
+```bash
+npm install @statewalker/webrun-files-node @statewalker/webrun-files
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { NodeFilesApi } from '@statewalker/webrun-files-node';
+import { readText, writeText } from '@statewalker/webrun-files';
+
+// Create API rooted at a specific directory
+const files = new NodeFilesApi({ rootDir: '/var/app/data' });
+
+// Write a file - creates /var/app/data/config.json
+await writeText(files, '/config.json', '{"debug": true}');
+
+// Read it back
+const content = await readText(files, '/config.json');
+console.log(content); // {"debug": true}
+
+// List files
+for await (const entry of files.list('/')) {
+  console.log(entry.name, entry.kind, entry.size);
+}
+```
+
+### Default Root Directory
+
+If no `rootDir` is specified, the current working directory is used:
+
+```typescript
+import { NodeFilesApi } from '@statewalker/webrun-files-node';
+
+const files = new NodeFilesApi();
+// Virtual path /data/file.txt maps to ./data/file.txt
+```
+
+### Path Mapping
+
+Virtual paths are mapped directly to the filesystem:
+
+```
+rootDir: "/var/app/data"
+virtual path: "/users/alice.json"
+real path: "/var/app/data/users/alice.json"
+```
+
+## API Reference
+
+### NodeFilesApi
+
+```typescript
+interface NodeFilesApiOptions {
+  /**
+   * Root directory for file operations.
+   * All paths are resolved relative to this directory.
+   * Defaults to current working directory if not specified.
+   */
+  rootDir?: string;
+}
+
+class NodeFilesApi implements FilesApi {
+  constructor(options?: NodeFilesApiOptions);
+
+  // All FilesApi methods
+  read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+  write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+  stats(path: string): Promise<FileStats | undefined>;
+  exists(path: string): Promise<boolean>;
+  remove(path: string): Promise<boolean>;
+  move(source: string, target: string): Promise<boolean>;
+  copy(source: string, target: string): Promise<boolean>;
+}
+```
+
+## Features
+
+### Efficient Streaming
+
+Large files are read in chunks without loading entirely into memory:
+
+```typescript
+// Stream a large file
+for await (const chunk of files.read('/large-video.mp4')) {
+  // Process each chunk (default 8KB chunks)
+}
+
+// Read a specific range
+for await (const chunk of files.read('/large-file.bin', { start: 1000, length: 500 })) {
+  // Only bytes 1000-1499
+}
+```
+
+### Automatic Directory Creation
+
+Parent directories are created automatically when writing files:
+
+```typescript
+// Creates /var/app/data/deep/nested/path/ automatically
+await writeText(files, '/deep/nested/path/file.txt', 'content');
+```
+
+### Recursive Operations
+
+Copy and remove work recursively on directories:
+
+```typescript
+// Copy entire directory tree
+await files.copy('/source', '/destination');
+
+// Remove directory and all contents
+await files.remove('/old-data');
+```
+
+## Testing with Temporary Directories
+
+```typescript
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { NodeFilesApi } from '@statewalker/webrun-files-node';
+
+// Create a temp directory for testing
+const tempDir = await mkdtemp(join(tmpdir(), 'test-'));
+const files = new NodeFilesApi({ rootDir: tempDir });
+
+try {
+  // Run tests...
+  await writeText(files, '/test.txt', 'test content');
+} finally {
+  // Cleanup
+  await rm(tempDir, { recursive: true, force: true });
+}
+```
+
+## License
+
+MIT

package/dist/cjs/index.cjs

@@ -0,0 +1,233 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+
+//#region ../webrun-files/dist/esm/index.js
+/**
+* Path manipulation utilities for virtual filesystem paths.
+* All paths use forward slashes and start with "/".
+*/
+/**
+* Normalizes a file path to a consistent format.
+* - Adds leading slash if missing
+* - Removes trailing slash
+* - Removes `.` segments
+* - Collapses multiple slashes
+*/
+function normalizePath(filePath) {
+	const segments = filePath.split("/").filter((s) => !!s && s !== ".");
+	if (segments.length === 0) return "/";
+	return `/${segments.join("/")}`;
+}
+/**
+* Joins path segments with proper normalization.
+*/
+function joinPath(...segments) {
+	return normalizePath(segments.join("/"));
+}
+/**
+* Returns the directory portion of a path.
+*/
+function dirname(path) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	if (lastSlash <= 0) return "/";
+	return normalized.substring(0, lastSlash);
+}
+
+//#endregion
+//#region src/node-files-api.ts
+/**
+* Node.js FilesApi implementation using fs/promises.
+* Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
+*/
+var NodeFilesApi = class {
+	rootDir;
+	constructor(options) {
+		this.rootDir = options?.rootDir ?? process.cwd();
+	}
+	resolvePath(virtualPath) {
+		const normalized = normalizePath(virtualPath);
+		return this.rootDir + normalized;
+	}
+	async *read(path, options) {
+		const realPath = this.resolvePath(path);
+		try {
+			const stat = await node_fs_promises.stat(realPath);
+			if (!stat.isFile()) return;
+			const handle = await node_fs_promises.open(realPath, "r");
+			try {
+				const start = options?.start ?? 0;
+				const length = options?.length;
+				const end = length !== void 0 ? start + length : stat.size;
+				if (start >= stat.size) return;
+				const bufferSize = 8192;
+				let position = start;
+				const actualEnd = Math.min(end, stat.size);
+				while (position < actualEnd) {
+					const remaining = actualEnd - position;
+					const toRead = Math.min(bufferSize, remaining);
+					const buffer = new Uint8Array(toRead);
+					const { bytesRead } = await handle.read(buffer, 0, toRead, position);
+					if (bytesRead === 0) break;
+					yield buffer.subarray(0, bytesRead);
+					position += bytesRead;
+				}
+			} finally {
+				await handle.close();
+			}
+		} catch {
+			return;
+		}
+	}
+	async write(path, content) {
+		const realPath = this.resolvePath(path);
+		const normalized = normalizePath(path);
+		const dir = this.rootDir + dirname(normalized);
+		await node_fs_promises.mkdir(dir, { recursive: true });
+		const chunks = [];
+		let totalLength = 0;
+		for await (const chunk of content) {
+			chunks.push(chunk);
+			totalLength += chunk.length;
+		}
+		const result = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) {
+			result.set(chunk, offset);
+			offset += chunk.length;
+		}
+		await node_fs_promises.writeFile(realPath, result);
+	}
+	async mkdir(path) {
+		const realPath = this.resolvePath(path);
+		await node_fs_promises.mkdir(realPath, { recursive: true });
+	}
+	async *list(path, options) {
+		const realPath = this.resolvePath(path);
+		const normalizedPath = normalizePath(path);
+		try {
+			const entries = await node_fs_promises.readdir(realPath, { withFileTypes: true });
+			for (const entry of entries) {
+				const entryPath = joinPath(normalizedPath, entry.name);
+				const fullPath = this.resolvePath(entryPath);
+				let stat;
+				try {
+					stat = await node_fs_promises.stat(fullPath);
+				} catch {
+					continue;
+				}
+				yield {
+					name: entry.name,
+					path: entryPath,
+					kind: entry.isDirectory() ? "directory" : "file",
+					size: stat.size,
+					lastModified: stat.mtimeMs
+				};
+				if (options?.recursive && entry.isDirectory()) yield* this.list(entryPath, options);
+			}
+		} catch {
+			return;
+		}
+	}
+	async stats(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			const stat = await node_fs_promises.stat(realPath);
+			return {
+				kind: stat.isDirectory() ? "directory" : "file",
+				size: stat.size,
+				lastModified: stat.mtimeMs
+			};
+		} catch {
+			return;
+		}
+	}
+	async exists(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			await node_fs_promises.access(realPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async remove(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			if ((await node_fs_promises.stat(realPath)).isDirectory()) await node_fs_promises.rm(realPath, {
+				recursive: true,
+				force: true
+			});
+			else await node_fs_promises.unlink(realPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async move(source, target) {
+		const sourcePath = this.resolvePath(source);
+		const targetPath = this.resolvePath(target);
+		const normalizedTarget = normalizePath(target);
+		try {
+			await node_fs_promises.access(sourcePath);
+		} catch {
+			return false;
+		}
+		try {
+			const targetDir = this.rootDir + dirname(normalizedTarget);
+			await node_fs_promises.mkdir(targetDir, { recursive: true });
+			await node_fs_promises.rename(sourcePath, targetPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async copy(source, target) {
+		const sourcePath = this.resolvePath(source);
+		const targetPath = this.resolvePath(target);
+		const normalizedTarget = normalizePath(target);
+		try {
+			await node_fs_promises.access(sourcePath);
+		} catch {
+			return false;
+		}
+		try {
+			const targetDir = this.rootDir + dirname(normalizedTarget);
+			await node_fs_promises.mkdir(targetDir, { recursive: true });
+			await node_fs_promises.cp(sourcePath, targetPath, { recursive: true });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+
+//#endregion
+exports.NodeFilesApi = NodeFilesApi;

package/dist/esm/index.js

@@ -0,0 +1,205 @@
+import * as fs from "node:fs/promises";
+
+//#region ../webrun-files/dist/esm/index.js
+/**
+* Path manipulation utilities for virtual filesystem paths.
+* All paths use forward slashes and start with "/".
+*/
+/**
+* Normalizes a file path to a consistent format.
+* - Adds leading slash if missing
+* - Removes trailing slash
+* - Removes `.` segments
+* - Collapses multiple slashes
+*/
+function normalizePath(filePath) {
+	const segments = filePath.split("/").filter((s) => !!s && s !== ".");
+	if (segments.length === 0) return "/";
+	return `/${segments.join("/")}`;
+}
+/**
+* Joins path segments with proper normalization.
+*/
+function joinPath(...segments) {
+	return normalizePath(segments.join("/"));
+}
+/**
+* Returns the directory portion of a path.
+*/
+function dirname(path) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	if (lastSlash <= 0) return "/";
+	return normalized.substring(0, lastSlash);
+}
+
+//#endregion
+//#region src/node-files-api.ts
+/**
+* Node.js FilesApi implementation using fs/promises.
+* Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
+*/
+var NodeFilesApi = class {
+	rootDir;
+	constructor(options) {
+		this.rootDir = options?.rootDir ?? process.cwd();
+	}
+	resolvePath(virtualPath) {
+		const normalized = normalizePath(virtualPath);
+		return this.rootDir + normalized;
+	}
+	async *read(path, options) {
+		const realPath = this.resolvePath(path);
+		try {
+			const stat = await fs.stat(realPath);
+			if (!stat.isFile()) return;
+			const handle = await fs.open(realPath, "r");
+			try {
+				const start = options?.start ?? 0;
+				const length = options?.length;
+				const end = length !== void 0 ? start + length : stat.size;
+				if (start >= stat.size) return;
+				const bufferSize = 8192;
+				let position = start;
+				const actualEnd = Math.min(end, stat.size);
+				while (position < actualEnd) {
+					const remaining = actualEnd - position;
+					const toRead = Math.min(bufferSize, remaining);
+					const buffer = new Uint8Array(toRead);
+					const { bytesRead } = await handle.read(buffer, 0, toRead, position);
+					if (bytesRead === 0) break;
+					yield buffer.subarray(0, bytesRead);
+					position += bytesRead;
+				}
+			} finally {
+				await handle.close();
+			}
+		} catch {
+			return;
+		}
+	}
+	async write(path, content) {
+		const realPath = this.resolvePath(path);
+		const normalized = normalizePath(path);
+		const dir = this.rootDir + dirname(normalized);
+		await fs.mkdir(dir, { recursive: true });
+		const chunks = [];
+		let totalLength = 0;
+		for await (const chunk of content) {
+			chunks.push(chunk);
+			totalLength += chunk.length;
+		}
+		const result = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) {
+			result.set(chunk, offset);
+			offset += chunk.length;
+		}
+		await fs.writeFile(realPath, result);
+	}
+	async mkdir(path) {
+		const realPath = this.resolvePath(path);
+		await fs.mkdir(realPath, { recursive: true });
+	}
+	async *list(path, options) {
+		const realPath = this.resolvePath(path);
+		const normalizedPath = normalizePath(path);
+		try {
+			const entries = await fs.readdir(realPath, { withFileTypes: true });
+			for (const entry of entries) {
+				const entryPath = joinPath(normalizedPath, entry.name);
+				const fullPath = this.resolvePath(entryPath);
+				let stat;
+				try {
+					stat = await fs.stat(fullPath);
+				} catch {
+					continue;
+				}
+				yield {
+					name: entry.name,
+					path: entryPath,
+					kind: entry.isDirectory() ? "directory" : "file",
+					size: stat.size,
+					lastModified: stat.mtimeMs
+				};
+				if (options?.recursive && entry.isDirectory()) yield* this.list(entryPath, options);
+			}
+		} catch {
+			return;
+		}
+	}
+	async stats(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			const stat = await fs.stat(realPath);
+			return {
+				kind: stat.isDirectory() ? "directory" : "file",
+				size: stat.size,
+				lastModified: stat.mtimeMs
+			};
+		} catch {
+			return;
+		}
+	}
+	async exists(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			await fs.access(realPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async remove(path) {
+		const realPath = this.resolvePath(path);
+		try {
+			if ((await fs.stat(realPath)).isDirectory()) await fs.rm(realPath, {
+				recursive: true,
+				force: true
+			});
+			else await fs.unlink(realPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async move(source, target) {
+		const sourcePath = this.resolvePath(source);
+		const targetPath = this.resolvePath(target);
+		const normalizedTarget = normalizePath(target);
+		try {
+			await fs.access(sourcePath);
+		} catch {
+			return false;
+		}
+		try {
+			const targetDir = this.rootDir + dirname(normalizedTarget);
+			await fs.mkdir(targetDir, { recursive: true });
+			await fs.rename(sourcePath, targetPath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async copy(source, target) {
+		const sourcePath = this.resolvePath(source);
+		const targetPath = this.resolvePath(target);
+		const normalizedTarget = normalizePath(target);
+		try {
+			await fs.access(sourcePath);
+		} catch {
+			return false;
+		}
+		try {
+			const targetDir = this.rootDir + dirname(normalizedTarget);
+			await fs.mkdir(targetDir, { recursive: true });
+			await fs.cp(sourcePath, targetPath, { recursive: true });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+
+//#endregion
+export { NodeFilesApi };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { NodeFilesApi, type NodeFilesApiOptions } from "./node-files-api.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/node-files-api.d.ts

@@ -0,0 +1,27 @@
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
+export interface NodeFilesApiOptions {
+    /**
+     * Root directory for file operations. All paths are resolved relative to this.
+     * Defaults to current working directory if not specified.
+     */
+    rootDir?: string;
+}
+/**
+ * Node.js FilesApi implementation using fs/promises.
+ * Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
+ */
+export declare class NodeFilesApi implements FilesApi {
+    private rootDir;
+    constructor(options?: NodeFilesApiOptions);
+    private resolvePath;
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    stats(path: string): Promise<FileStats | undefined>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<boolean>;
+    move(source: string, target: string): Promise<boolean>;
+    copy(source: string, target: string): Promise<boolean>;
+}
+//# sourceMappingURL=node-files-api.d.ts.map

package/dist/node-files-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,mBAAmB;IAIzC,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IA2CrE,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAyBV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAsCnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAenD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAoB7D"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@statewalker/webrun-files-node",
+  "version": "0.7.0",
+  "private": false,
+  "type": "module",
+  "description": "Node.js FilesApi implementation",
+  "homepage": "https://github.com/statewalker/webrun-files",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-files.git"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "rimraf": "^6.1.2",
+    "rolldown": "^1.0.0-beta.53",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.12",
+    "@statewalker/webrun-files-tests": "1.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { NodeFilesApi, type NodeFilesApiOptions } from "./node-files-api.js";

package/src/node-files-api.ts

@@ -0,0 +1,233 @@
+import type { Stats } from "node:fs";
+import * as fs from "node:fs/promises";
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
+
+export interface NodeFilesApiOptions {
+  /**
+   * Root directory for file operations. All paths are resolved relative to this.
+   * Defaults to current working directory if not specified.
+   */
+  rootDir?: string;
+}
+
+/**
+ * Node.js FilesApi implementation using fs/promises.
+ * Maps virtual paths (starting with /) to the filesystem rooted at rootDir.
+ */
+export class NodeFilesApi implements FilesApi {
+  private rootDir: string;
+
+  constructor(options?: NodeFilesApiOptions) {
+    this.rootDir = options?.rootDir ?? process.cwd();
+  }
+
+  private resolvePath(virtualPath: string): string {
+    const normalized = normalizePath(virtualPath);
+    return this.rootDir + normalized;
+  }
+
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    const realPath = this.resolvePath(path);
+
+    try {
+      const stat = await fs.stat(realPath);
+      if (!stat.isFile()) {
+        return;
+      }
+
+      const handle = await fs.open(realPath, "r");
+      try {
+        const start = options?.start ?? 0;
+        const length = options?.length;
+        const end = length !== undefined ? start + length : stat.size;
+
+        if (start >= stat.size) {
+          return;
+        }
+
+        const bufferSize = 8192;
+        let position = start;
+        const actualEnd = Math.min(end, stat.size);
+
+        while (position < actualEnd) {
+          const remaining = actualEnd - position;
+          const toRead = Math.min(bufferSize, remaining);
+          const buffer = new Uint8Array(toRead);
+
+          const { bytesRead } = await handle.read(buffer, 0, toRead, position);
+          if (bytesRead === 0) break;
+
+          yield buffer.subarray(0, bytesRead);
+          position += bytesRead;
+        }
+      } finally {
+        await handle.close();
+      }
+    } catch {
+      // File doesn't exist or can't be read
+      return;
+    }
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    const realPath = this.resolvePath(path);
+    const normalized = normalizePath(path);
+    const dir = this.rootDir + dirname(normalized);
+
+    await fs.mkdir(dir, { recursive: true });
+
+    const chunks: Uint8Array[] = [];
+    let totalLength = 0;
+
+    for await (const chunk of content) {
+      chunks.push(chunk);
+      totalLength += chunk.length;
+    }
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    await fs.writeFile(realPath, result);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    const realPath = this.resolvePath(path);
+    await fs.mkdir(realPath, { recursive: true });
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    const realPath = this.resolvePath(path);
+    const normalizedPath = normalizePath(path);
+
+    try {
+      const entries = await fs.readdir(realPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const entryPath = joinPath(normalizedPath, entry.name);
+        const fullPath = this.resolvePath(entryPath);
+
+        let stat: Stats;
+        try {
+          stat = await fs.stat(fullPath);
+        } catch {
+          continue;
+        }
+
+        const info: FileInfo = {
+          name: entry.name,
+          path: entryPath,
+          kind: entry.isDirectory() ? "directory" : "file",
+          size: stat.size,
+          lastModified: stat.mtimeMs,
+        };
+
+        yield info;
+
+        if (options?.recursive && entry.isDirectory()) {
+          yield* this.list(entryPath, options);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or can't be read
+      return;
+    }
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    const realPath = this.resolvePath(path);
+
+    try {
+      const stat = await fs.stat(realPath);
+      return {
+        kind: stat.isDirectory() ? "directory" : "file",
+        size: stat.size,
+        lastModified: stat.mtimeMs,
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const realPath = this.resolvePath(path);
+
+    try {
+      await fs.access(realPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async remove(path: string): Promise<boolean> {
+    const realPath = this.resolvePath(path);
+
+    try {
+      const stat = await fs.stat(realPath);
+      if (stat.isDirectory()) {
+        await fs.rm(realPath, { recursive: true, force: true });
+      } else {
+        await fs.unlink(realPath);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async move(source: string, target: string): Promise<boolean> {
+    const sourcePath = this.resolvePath(source);
+    const targetPath = this.resolvePath(target);
+    const normalizedTarget = normalizePath(target);
+
+    try {
+      await fs.access(sourcePath);
+    } catch {
+      return false;
+    }
+
+    try {
+      const targetDir = this.rootDir + dirname(normalizedTarget);
+      await fs.mkdir(targetDir, { recursive: true });
+      await fs.rename(sourcePath, targetPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async copy(source: string, target: string): Promise<boolean> {
+    const sourcePath = this.resolvePath(source);
+    const targetPath = this.resolvePath(target);
+    const normalizedTarget = normalizePath(target);
+
+    try {
+      await fs.access(sourcePath);
+    } catch {
+      return false;
+    }
+
+    try {
+      const targetDir = this.rootDir + dirname(normalizedTarget);
+      await fs.mkdir(targetDir, { recursive: true });
+      await fs.cp(sourcePath, targetPath, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}