@statewalker/webrun-files-composite 0.7.0

package/README.md

@@ -0,0 +1,184 @@
+# @statewalker/webrun-files-composite
+
+A `FilesApi` adapter that composes multiple `FilesApi` instances into a unified virtual filesystem with **mount points** and **access guards**.
+
+## Features
+
+- **Mount multiple backends** at different paths under a single `FilesApi` interface
+- **Base path remapping** — use a subdirectory of any backend as its mount root
+- **Access guards** to enforce per-operation, per-path access control
+- **Cross-mount operations** — copy and move files transparently across different backends
+- **Mount-point protection** — mounted directories cannot be removed
+- **Longest-prefix routing** — deeper mounts take precedence (e.g. `/a/b` before `/a`)
+- **Synthetic directory entries** — mount points appear as directories in listings
+
+## Installation
+
+```bash
+pnpm add @statewalker/webrun-files-composite
+```
+
+## Usage
+
+### Basic composition
+
+```typescript
+import { CompositeFilesApi } from "@statewalker/webrun-files-composite";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+
+const composite = new CompositeFilesApi(new MemFilesApi())
+  .mount("/docs", new MemFilesApi())
+  .mount("/cache", new MemFilesApi());
+
+const encoder = new TextEncoder();
+await composite.write("/readme.txt", [encoder.encode("Hello")]);
+await composite.write("/docs/guide.md", [encoder.encode("# Guide")]);
+```
+
+### Base path remapping
+
+Each mount can specify which subdirectory of the backing filesystem to use as its root. The constructor also accepts an optional `rootPath`:
+
+```typescript
+import { NodeFilesApi } from "@statewalker/webrun-files-node";
+import { S3FilesApi } from "@statewalker/webrun-files-s3";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+
+const fsMain = new NodeFilesApi({ ... });
+const fsS3 = new S3FilesApi({ ... });
+const fsMem = new MemFilesApi();
+
+// Use "/projects" as the root of the composite file system:
+const composite = new CompositeFilesApi(fsMain, "./projects")
+  .mount("/docs", fsS3, "/documentation") // use the "/documentation" folder on S3
+  .mount("/cache", fsMem);               // use the root of the in-memory FS
+
+// Writes to /readme.txt go to fsMain at /projects/readme.txt
+await composite.write("/readme.txt", [encoder.encode("Hello")]);
+
+// Writes to /docs/guide.md go to fsS3 at /documentation/guide.md
+await composite.write("/docs/guide.md", [encoder.encode("# Guide")]);
+
+// Writes to /cache/tmp.dat go to fsMem at /tmp.dat
+await composite.write("/cache/tmp.dat", [encoder.encode("temp")]);
+```
+
+### Access guards
+
+```typescript
+composite
+  .guard(
+    ["write", "remove", "move"],
+    (path) => !path.startsWith("/.private/"),
+    "Cannot modify private files"
+  )
+  .guard(
+    ["write"],
+    (path) => !path.includes(".."),
+    "Path traversal not allowed"
+  );
+```
+
+Guards are checked before each operation. The first failing guard throws an error with its message.
+
+### Cross-mount operations
+
+```typescript
+// Copy from one mount to another
+await composite.copy("/docs/file.txt", "/archive/file.txt");
+
+// Move across mounts (implemented as copy + delete)
+await composite.move("/cache/temp.txt", "/docs/temp.txt");
+```
+
+### Listing
+
+Mount points appear as synthetic directory entries:
+
+```typescript
+const entries = [];
+for await (const entry of composite.list("/")) {
+  entries.push(entry);
+}
+// Includes: { name: "docs", path: "/docs", kind: "directory" }
+
+// Recursive listing spans all mounts
+for await (const entry of composite.list("/", { recursive: true })) {
+  // entries from root, /docs, /cache, and all subdirectories
+}
+```
+
+## API
+
+### `CompositeFilesApi`
+
+Implements the `FilesApi` interface from `@statewalker/webrun-files`.
+
+#### Constructor
+
+```typescript
+new CompositeFilesApi(root: FilesApi, rootPath?: string)
+```
+
+Creates a composite filesystem with `root` as the default backend for `/`. If `rootPath` is provided, all root operations are remapped to that subdirectory in the backing filesystem.
+
+#### `mount(path: string, api: FilesApi, fsPath?: string): this`
+
+Mounts a `FilesApi` backend at the given path. If `fsPath` is provided, operations on this mount are remapped to that subdirectory in the backing filesystem. Paths are normalized (leading `/`, no trailing `/`). Returns `this` for chaining.
+
+#### `guard(operations: FileOperation[], check: (path: string) => boolean, message?: string): this`
+
+Adds an access guard. Before each matching operation, `check(path)` is called. If it returns `false`, the operation throws an error with the optional `message`. Returns `this` for chaining.
+
+#### FilesApi methods
+
+| Method | Description |
+|--------|-------------|
+| `read(path, options?)` | Read file content as `AsyncIterable<Uint8Array>` |
+| `write(path, content)` | Write content to a file |
+| `mkdir(path)` | Create a directory |
+| `list(path, options?)` | List directory entries (supports `{ recursive: true }`) |
+| `stats(path)` | Get file/directory stats, returns `undefined` if not found |
+| `exists(path)` | Check if a path exists |
+| `remove(path)` | Remove a file or directory (throws on mount points) |
+| `move(source, target)` | Move a file or directory (cross-mount supported) |
+| `copy(source, target)` | Copy a file or directory (cross-mount supported) |
+
+### Types
+
+```typescript
+type FileOperation = "read" | "write" | "remove" | "move" | "copy" | "list" | "mkdir";
+
+interface FileGuard {
+  operations: FileOperation[];
+  check: (path: string) => boolean;
+  message?: string;
+}
+```
+
+## Path resolution
+
+1. All input paths are normalized (forward slashes, leading `/`, no trailing `/`)
+2. The mount with the **longest matching prefix** handles the operation
+3. The mount prefix is stripped and the `fsPath` (base path) is prepended — e.g. `/docs/guide.md` with mount at `/docs` and `fsPath="/documentation"` resolves to `/documentation/guide.md` on the mounted backend
+4. Guards always operate on **composite paths** (before remapping), not backing filesystem paths
+
+## Design constraints
+
+- The root mount (`/`) is set at construction time and cannot be remounted
+- Mount points are immutable — `remove()` on a mount point throws an error
+- Cross-mount move is implemented as copy + delete (no atomic guarantee)
+- Guards are evaluated in the order they were added; first denial wins
+
+## Related packages
+
+| Package | Role |
+|---------|------|
+| `@statewalker/webrun-files` | Core `FilesApi` interface and path utilities |
+| `@statewalker/webrun-files-mem` | In-memory `FilesApi` backend |
+| `@statewalker/webrun-files-node` | Node.js filesystem backend |
+| `@statewalker/webrun-files-tests` | Shared parametrized test suites |
+
+## License
+
+MIT

package/dist/cjs/index.cjs

@@ -0,0 +1,239 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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("/"));
+}
+//#endregion
+//#region src/composite-files-api.ts
+var CompositeFilesApi = class {
+	mounts;
+	guards = [];
+	constructor(root, rootPath) {
+		this.mounts = [{
+			prefix: "/",
+			api: root,
+			basePath: normalizePath(rootPath ?? "/")
+		}];
+	}
+	mount(path, api, fsPath) {
+		const prefix = normalizePath(path);
+		if (prefix === "/") throw new Error("Cannot mount at root — root is set via constructor");
+		this.mounts.push({
+			prefix,
+			api,
+			basePath: normalizePath(fsPath ?? "/")
+		});
+		this.mounts.sort((a, b) => b.prefix.length - a.prefix.length);
+		return this;
+	}
+	guard(operations, check, message) {
+		this.guards.push({
+			operations,
+			check,
+			message
+		});
+		return this;
+	}
+	resolve(path) {
+		const normalized = normalizePath(path);
+		for (const mount of this.mounts) {
+			if (mount.prefix === "/") return {
+				api: mount.api,
+				resolvedPath: joinPath(mount.basePath, normalized)
+			};
+			if (normalized === mount.prefix || normalized.startsWith(`${mount.prefix}/`)) {
+				const localPath = normalized.slice(mount.prefix.length) || "/";
+				return {
+					api: mount.api,
+					resolvedPath: joinPath(mount.basePath, localPath)
+				};
+			}
+		}
+		const rootMount = this.mounts[this.mounts.length - 1];
+		return {
+			api: rootMount.api,
+			resolvedPath: joinPath(rootMount.basePath, normalizePath(path))
+		};
+	}
+	isMountPoint(path) {
+		const normalized = normalizePath(path);
+		return this.mounts.some((m) => m.prefix === normalized && m.prefix !== "/");
+	}
+	/** Returns mount prefixes that are direct children of the given path. */
+	childMountPrefixes(parentPath) {
+		const normalized = normalizePath(parentPath);
+		const prefix = normalized === "/" ? "/" : `${normalized}/`;
+		const result = [];
+		for (const mount of this.mounts) {
+			if (mount.prefix === "/") continue;
+			if (!mount.prefix.startsWith(prefix)) continue;
+			if (!mount.prefix.slice(prefix.length).includes("/")) result.push(mount.prefix);
+		}
+		return result;
+	}
+	checkGuard(operation, path) {
+		const normalized = normalizePath(path);
+		for (const guard of this.guards) {
+			if (!guard.operations.includes(operation)) continue;
+			if (!guard.check(normalized)) {
+				const msg = guard.message ?? "Access denied";
+				throw new Error(`${msg}: ${normalized}`);
+			}
+		}
+	}
+	read(path, options) {
+		this.checkGuard("read", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.read(resolvedPath, options);
+	}
+	async write(path, content) {
+		this.checkGuard("write", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.write(resolvedPath, content);
+	}
+	async mkdir(path) {
+		this.checkGuard("mkdir", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.mkdir(resolvedPath);
+	}
+	async *list(path, options) {
+		this.checkGuard("list", path);
+		const normalized = normalizePath(path);
+		const { api, resolvedPath } = this.resolve(path);
+		const childMounts = this.childMountPrefixes(normalized);
+		const yieldedNames = /* @__PURE__ */ new Set();
+		if (options?.recursive) {
+			for await (const entry of api.list(resolvedPath, options)) {
+				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+				if (this.isUnderChildMount(compositePath, childMounts)) continue;
+				yieldedNames.add(entry.name);
+				yield {
+					...entry,
+					path: compositePath
+				};
+			}
+			for (const mountPrefix of childMounts) {
+				const mount = this.mounts.find((m) => m.prefix === mountPrefix);
+				if (!mount) continue;
+				yield {
+					name: mountPrefix.split("/").pop() ?? "",
+					path: mountPrefix,
+					kind: "directory"
+				};
+				for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
+					const localPath = this.stripBasePath(entry.path, mount.basePath);
+					yield {
+						...entry,
+						path: `${mountPrefix}${localPath === "/" ? "" : localPath}`
+					};
+				}
+			}
+		} else {
+			for await (const entry of api.list(resolvedPath)) {
+				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+				yieldedNames.add(entry.name);
+				yield {
+					...entry,
+					path: compositePath
+				};
+			}
+			for (const mountPrefix of childMounts) {
+				const mountName = mountPrefix.split("/").pop() ?? "";
+				if (!yieldedNames.has(mountName)) yield {
+					name: mountName,
+					path: mountPrefix,
+					kind: "directory"
+				};
+			}
+		}
+	}
+	async stats(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) return { kind: "directory" };
+		const { api, resolvedPath } = this.resolve(path);
+		return api.stats(resolvedPath);
+	}
+	async exists(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) return true;
+		const { api, resolvedPath } = this.resolve(path);
+		return api.exists(resolvedPath);
+	}
+	async remove(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) throw new Error(`Cannot remove mount point: ${normalized}`);
+		this.checkGuard("remove", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.remove(resolvedPath);
+	}
+	async move(source, target) {
+		this.checkGuard("move", source);
+		this.checkGuard("move", target);
+		const src = this.resolve(source);
+		const tgt = this.resolve(target);
+		if (src.api === tgt.api) return src.api.move(src.resolvedPath, tgt.resolvedPath);
+		const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+		if (copied) await src.api.remove(src.resolvedPath);
+		return copied;
+	}
+	async copy(source, target) {
+		this.checkGuard("copy", source);
+		this.checkGuard("copy", target);
+		const src = this.resolve(source);
+		const tgt = this.resolve(target);
+		if (src.api === tgt.api) return src.api.copy(src.resolvedPath, tgt.resolvedPath);
+		return this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+	}
+	stripBasePath(path, basePath) {
+		if (basePath === "/") return path;
+		if (path === basePath) return "/";
+		if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
+		return path;
+	}
+	async crossCopy(srcApi, srcPath, tgtApi, tgtPath) {
+		const srcStats = await srcApi.stats(srcPath);
+		if (!srcStats) return false;
+		if (srcStats.kind === "file") {
+			await tgtApi.write(tgtPath, srcApi.read(srcPath));
+			return true;
+		}
+		await tgtApi.mkdir(tgtPath);
+		for await (const entry of srcApi.list(srcPath)) {
+			const childSrc = srcPath === "/" ? `/${entry.name}` : `${srcPath}/${entry.name}`;
+			const childTgt = tgtPath === "/" ? `/${entry.name}` : `${tgtPath}/${entry.name}`;
+			if (entry.kind === "file") await tgtApi.write(childTgt, srcApi.read(childSrc));
+			else await this.crossCopy(srcApi, childSrc, tgtApi, childTgt);
+		}
+		return true;
+	}
+	remapPath(compositeParent, resolvedParent, resolvedChild) {
+		const relative = resolvedChild.startsWith(resolvedParent) ? resolvedChild.slice(resolvedParent.length) : resolvedChild;
+		if (compositeParent === "/") return relative.startsWith("/") ? relative : `/${relative}`;
+		return `${compositeParent}${relative.startsWith("/") ? relative : `/${relative}`}`;
+	}
+	isUnderChildMount(compositePath, childMounts) {
+		for (const mount of childMounts) if (compositePath === mount || compositePath.startsWith(`${mount}/`)) return true;
+		return false;
+	}
+};
+//#endregion
+exports.CompositeFilesApi = CompositeFilesApi;

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

@@ -0,0 +1,28 @@
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
+import type { FileOperation } from "./types.js";
+export declare class CompositeFilesApi implements FilesApi {
+    private mounts;
+    private guards;
+    constructor(root: FilesApi, rootPath?: string);
+    mount(path: string, api: FilesApi, fsPath?: string): this;
+    guard(operations: FileOperation[], check: (path: string) => boolean, message?: string): this;
+    private resolve;
+    private isMountPoint;
+    /** Returns mount prefixes that are direct children of the given path. */
+    private childMountPrefixes;
+    private checkGuard;
+    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>;
+    private stripBasePath;
+    private crossCopy;
+    private remapPath;
+    private isUnderChildMount;
+}
+//# sourceMappingURL=composite-files-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,YAAY,CAAC;AAQ3D,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAmB;gBAErB,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI7C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAWzD,KAAK,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAO5F,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,UAAU;IAalB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IAM9D,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAMV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IA+CnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IASnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAStC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmBtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB5D,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/esm/index.js

@@ -0,0 +1,238 @@
+//#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("/"));
+}
+//#endregion
+//#region src/composite-files-api.ts
+var CompositeFilesApi = class {
+	mounts;
+	guards = [];
+	constructor(root, rootPath) {
+		this.mounts = [{
+			prefix: "/",
+			api: root,
+			basePath: normalizePath(rootPath ?? "/")
+		}];
+	}
+	mount(path, api, fsPath) {
+		const prefix = normalizePath(path);
+		if (prefix === "/") throw new Error("Cannot mount at root — root is set via constructor");
+		this.mounts.push({
+			prefix,
+			api,
+			basePath: normalizePath(fsPath ?? "/")
+		});
+		this.mounts.sort((a, b) => b.prefix.length - a.prefix.length);
+		return this;
+	}
+	guard(operations, check, message) {
+		this.guards.push({
+			operations,
+			check,
+			message
+		});
+		return this;
+	}
+	resolve(path) {
+		const normalized = normalizePath(path);
+		for (const mount of this.mounts) {
+			if (mount.prefix === "/") return {
+				api: mount.api,
+				resolvedPath: joinPath(mount.basePath, normalized)
+			};
+			if (normalized === mount.prefix || normalized.startsWith(`${mount.prefix}/`)) {
+				const localPath = normalized.slice(mount.prefix.length) || "/";
+				return {
+					api: mount.api,
+					resolvedPath: joinPath(mount.basePath, localPath)
+				};
+			}
+		}
+		const rootMount = this.mounts[this.mounts.length - 1];
+		return {
+			api: rootMount.api,
+			resolvedPath: joinPath(rootMount.basePath, normalizePath(path))
+		};
+	}
+	isMountPoint(path) {
+		const normalized = normalizePath(path);
+		return this.mounts.some((m) => m.prefix === normalized && m.prefix !== "/");
+	}
+	/** Returns mount prefixes that are direct children of the given path. */
+	childMountPrefixes(parentPath) {
+		const normalized = normalizePath(parentPath);
+		const prefix = normalized === "/" ? "/" : `${normalized}/`;
+		const result = [];
+		for (const mount of this.mounts) {
+			if (mount.prefix === "/") continue;
+			if (!mount.prefix.startsWith(prefix)) continue;
+			if (!mount.prefix.slice(prefix.length).includes("/")) result.push(mount.prefix);
+		}
+		return result;
+	}
+	checkGuard(operation, path) {
+		const normalized = normalizePath(path);
+		for (const guard of this.guards) {
+			if (!guard.operations.includes(operation)) continue;
+			if (!guard.check(normalized)) {
+				const msg = guard.message ?? "Access denied";
+				throw new Error(`${msg}: ${normalized}`);
+			}
+		}
+	}
+	read(path, options) {
+		this.checkGuard("read", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.read(resolvedPath, options);
+	}
+	async write(path, content) {
+		this.checkGuard("write", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.write(resolvedPath, content);
+	}
+	async mkdir(path) {
+		this.checkGuard("mkdir", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.mkdir(resolvedPath);
+	}
+	async *list(path, options) {
+		this.checkGuard("list", path);
+		const normalized = normalizePath(path);
+		const { api, resolvedPath } = this.resolve(path);
+		const childMounts = this.childMountPrefixes(normalized);
+		const yieldedNames = /* @__PURE__ */ new Set();
+		if (options?.recursive) {
+			for await (const entry of api.list(resolvedPath, options)) {
+				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+				if (this.isUnderChildMount(compositePath, childMounts)) continue;
+				yieldedNames.add(entry.name);
+				yield {
+					...entry,
+					path: compositePath
+				};
+			}
+			for (const mountPrefix of childMounts) {
+				const mount = this.mounts.find((m) => m.prefix === mountPrefix);
+				if (!mount) continue;
+				yield {
+					name: mountPrefix.split("/").pop() ?? "",
+					path: mountPrefix,
+					kind: "directory"
+				};
+				for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
+					const localPath = this.stripBasePath(entry.path, mount.basePath);
+					yield {
+						...entry,
+						path: `${mountPrefix}${localPath === "/" ? "" : localPath}`
+					};
+				}
+			}
+		} else {
+			for await (const entry of api.list(resolvedPath)) {
+				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+				yieldedNames.add(entry.name);
+				yield {
+					...entry,
+					path: compositePath
+				};
+			}
+			for (const mountPrefix of childMounts) {
+				const mountName = mountPrefix.split("/").pop() ?? "";
+				if (!yieldedNames.has(mountName)) yield {
+					name: mountName,
+					path: mountPrefix,
+					kind: "directory"
+				};
+			}
+		}
+	}
+	async stats(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) return { kind: "directory" };
+		const { api, resolvedPath } = this.resolve(path);
+		return api.stats(resolvedPath);
+	}
+	async exists(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) return true;
+		const { api, resolvedPath } = this.resolve(path);
+		return api.exists(resolvedPath);
+	}
+	async remove(path) {
+		const normalized = normalizePath(path);
+		if (this.isMountPoint(normalized)) throw new Error(`Cannot remove mount point: ${normalized}`);
+		this.checkGuard("remove", path);
+		const { api, resolvedPath } = this.resolve(path);
+		return api.remove(resolvedPath);
+	}
+	async move(source, target) {
+		this.checkGuard("move", source);
+		this.checkGuard("move", target);
+		const src = this.resolve(source);
+		const tgt = this.resolve(target);
+		if (src.api === tgt.api) return src.api.move(src.resolvedPath, tgt.resolvedPath);
+		const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+		if (copied) await src.api.remove(src.resolvedPath);
+		return copied;
+	}
+	async copy(source, target) {
+		this.checkGuard("copy", source);
+		this.checkGuard("copy", target);
+		const src = this.resolve(source);
+		const tgt = this.resolve(target);
+		if (src.api === tgt.api) return src.api.copy(src.resolvedPath, tgt.resolvedPath);
+		return this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+	}
+	stripBasePath(path, basePath) {
+		if (basePath === "/") return path;
+		if (path === basePath) return "/";
+		if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
+		return path;
+	}
+	async crossCopy(srcApi, srcPath, tgtApi, tgtPath) {
+		const srcStats = await srcApi.stats(srcPath);
+		if (!srcStats) return false;
+		if (srcStats.kind === "file") {
+			await tgtApi.write(tgtPath, srcApi.read(srcPath));
+			return true;
+		}
+		await tgtApi.mkdir(tgtPath);
+		for await (const entry of srcApi.list(srcPath)) {
+			const childSrc = srcPath === "/" ? `/${entry.name}` : `${srcPath}/${entry.name}`;
+			const childTgt = tgtPath === "/" ? `/${entry.name}` : `${tgtPath}/${entry.name}`;
+			if (entry.kind === "file") await tgtApi.write(childTgt, srcApi.read(childSrc));
+			else await this.crossCopy(srcApi, childSrc, tgtApi, childTgt);
+		}
+		return true;
+	}
+	remapPath(compositeParent, resolvedParent, resolvedChild) {
+		const relative = resolvedChild.startsWith(resolvedParent) ? resolvedChild.slice(resolvedParent.length) : resolvedChild;
+		if (compositeParent === "/") return relative.startsWith("/") ? relative : `/${relative}`;
+		return `${compositeParent}${relative.startsWith("/") ? relative : `/${relative}`}`;
+	}
+	isUnderChildMount(compositePath, childMounts) {
+		for (const mount of childMounts) if (compositePath === mount || compositePath.startsWith(`${mount}/`)) return true;
+		return false;
+	}
+};
+//#endregion
+export { CompositeFilesApi };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CompositeFilesApi } from "./composite-files-api.js";
+export type { FileGuard, FileOperation } from "./types.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,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+export type FileOperation = "read" | "write" | "remove" | "move" | "copy" | "list" | "mkdir";
+export interface FileGuard {
+    /** Which filesystem operations this guard intercepts. */
+    operations: FileOperation[];
+    /** Returns true to allow, false to deny. */
+    check: (path: string) => boolean;
+    /** Error message when access is denied. */
+    message?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7F,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,4CAA4C;IAC5C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@statewalker/webrun-files-composite",
+  "version": "0.7.0",
+  "private": false,
+  "type": "module",
+  "description": "Composite FilesApi with mount points and access guards",
+  "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"
+  ],
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
+  },
+  "dependencies": {
+    "@statewalker/webrun-files": "workspace:*"
+  },
+  "devDependencies": {
+    "@statewalker/webrun-files-tests": "workspace:*",
+    "@statewalker/webrun-files-mem": "workspace:*",
+    "@types/node": "catalog:",
+    "rimraf": "catalog:",
+    "rolldown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/composite-files-api.ts

@@ -0,0 +1,286 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import { joinPath, normalizePath } from "@statewalker/webrun-files";
+import type { FileGuard, FileOperation } from "./types.js";
+
+interface MountEntry {
+  prefix: string;
+  api: FilesApi;
+  basePath: string;
+}
+
+export class CompositeFilesApi implements FilesApi {
+  private mounts: MountEntry[];
+  private guards: FileGuard[] = [];
+
+  constructor(root: FilesApi, rootPath?: string) {
+    this.mounts = [{ prefix: "/", api: root, basePath: normalizePath(rootPath ?? "/") }];
+  }
+
+  mount(path: string, api: FilesApi, fsPath?: string): this {
+    const prefix = normalizePath(path);
+    if (prefix === "/") {
+      throw new Error("Cannot mount at root — root is set via constructor");
+    }
+    this.mounts.push({ prefix, api, basePath: normalizePath(fsPath ?? "/") });
+    // Sort by prefix length descending so longest match comes first
+    this.mounts.sort((a, b) => b.prefix.length - a.prefix.length);
+    return this;
+  }
+
+  guard(operations: FileOperation[], check: (path: string) => boolean, message?: string): this {
+    this.guards.push({ operations, check, message });
+    return this;
+  }
+
+  // --- Mount resolution ---
+
+  private resolve(path: string): { api: FilesApi; resolvedPath: string } {
+    const normalized = normalizePath(path);
+    for (const mount of this.mounts) {
+      if (mount.prefix === "/") {
+        return { api: mount.api, resolvedPath: joinPath(mount.basePath, normalized) };
+      }
+      if (normalized === mount.prefix || normalized.startsWith(`${mount.prefix}/`)) {
+        const localPath = normalized.slice(mount.prefix.length) || "/";
+        return { api: mount.api, resolvedPath: joinPath(mount.basePath, localPath) };
+      }
+    }
+    // Fallback to root (always last after sort)
+    const rootMount = this.mounts[this.mounts.length - 1];
+    return { api: rootMount.api, resolvedPath: joinPath(rootMount.basePath, normalizePath(path)) };
+  }
+
+  private isMountPoint(path: string): boolean {
+    const normalized = normalizePath(path);
+    return this.mounts.some((m) => m.prefix === normalized && m.prefix !== "/");
+  }
+
+  /** Returns mount prefixes that are direct children of the given path. */
+  private childMountPrefixes(parentPath: string): string[] {
+    const normalized = normalizePath(parentPath);
+    const prefix = normalized === "/" ? "/" : `${normalized}/`;
+    const result: string[] = [];
+    for (const mount of this.mounts) {
+      if (mount.prefix === "/") continue;
+      if (!mount.prefix.startsWith(prefix)) continue;
+      // Check if this mount is a direct child (no further slashes after the prefix)
+      const relative = mount.prefix.slice(prefix.length);
+      if (!relative.includes("/")) {
+        result.push(mount.prefix);
+      }
+    }
+    return result;
+  }
+
+  // --- Guard checking ---
+
+  private checkGuard(operation: FileOperation, path: string): void {
+    const normalized = normalizePath(path);
+    for (const guard of this.guards) {
+      if (!guard.operations.includes(operation)) continue;
+      if (!guard.check(normalized)) {
+        const msg = guard.message ?? "Access denied";
+        throw new Error(`${msg}: ${normalized}`);
+      }
+    }
+  }
+
+  // --- FilesApi implementation ---
+
+  read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    this.checkGuard("read", path);
+    const { api, resolvedPath } = this.resolve(path);
+    return api.read(resolvedPath, options);
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    this.checkGuard("write", path);
+    const { api, resolvedPath } = this.resolve(path);
+    return api.write(resolvedPath, content);
+  }
+
+  async mkdir(path: string): Promise<void> {
+    this.checkGuard("mkdir", path);
+    const { api, resolvedPath } = this.resolve(path);
+    return api.mkdir(resolvedPath);
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    this.checkGuard("list", path);
+    const normalized = normalizePath(path);
+    const { api, resolvedPath } = this.resolve(path);
+
+    const childMounts = this.childMountPrefixes(normalized);
+    const yieldedNames = new Set<string>();
+
+    if (options?.recursive) {
+      // Yield entries from the primary mount
+      for await (const entry of api.list(resolvedPath, options)) {
+        // Remap path back to composite namespace
+        const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+        // Skip if this path falls under a child mount
+        if (this.isUnderChildMount(compositePath, childMounts)) continue;
+        yieldedNames.add(entry.name);
+        yield { ...entry, path: compositePath };
+      }
+      // Recursively yield from child mounts
+      for (const mountPrefix of childMounts) {
+        const mount = this.mounts.find((m) => m.prefix === mountPrefix);
+        if (!mount) continue;
+        const mountName = mountPrefix.split("/").pop() ?? "";
+        // Yield the mount directory entry itself
+        yield { name: mountName, path: mountPrefix, kind: "directory" };
+        for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
+          const localPath = this.stripBasePath(entry.path, mount.basePath);
+          yield { ...entry, path: `${mountPrefix}${localPath === "/" ? "" : localPath}` };
+        }
+      }
+    } else {
+      // Non-recursive: yield direct children from the primary mount
+      for await (const entry of api.list(resolvedPath)) {
+        const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
+        yieldedNames.add(entry.name);
+        yield { ...entry, path: compositePath };
+      }
+      // Add synthetic directory entries for child mounts not already present
+      for (const mountPrefix of childMounts) {
+        const mountName = mountPrefix.split("/").pop() ?? "";
+        if (!yieldedNames.has(mountName)) {
+          yield { name: mountName, path: mountPrefix, kind: "directory" };
+        }
+      }
+    }
+  }
+
+  async stats(path: string): Promise<FileStats | undefined> {
+    const normalized = normalizePath(path);
+    if (this.isMountPoint(normalized)) {
+      return { kind: "directory" };
+    }
+    const { api, resolvedPath } = this.resolve(path);
+    return api.stats(resolvedPath);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const normalized = normalizePath(path);
+    if (this.isMountPoint(normalized)) {
+      return true;
+    }
+    const { api, resolvedPath } = this.resolve(path);
+    return api.exists(resolvedPath);
+  }
+
+  async remove(path: string): Promise<boolean> {
+    const normalized = normalizePath(path);
+    if (this.isMountPoint(normalized)) {
+      throw new Error(`Cannot remove mount point: ${normalized}`);
+    }
+    this.checkGuard("remove", path);
+    const { api, resolvedPath } = this.resolve(path);
+    return api.remove(resolvedPath);
+  }
+
+  async move(source: string, target: string): Promise<boolean> {
+    this.checkGuard("move", source);
+    this.checkGuard("move", target);
+    const src = this.resolve(source);
+    const tgt = this.resolve(target);
+
+    // Same mount: delegate directly
+    if (src.api === tgt.api) {
+      return src.api.move(src.resolvedPath, tgt.resolvedPath);
+    }
+
+    // Cross-mount: copy then remove
+    const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+    if (copied) {
+      await src.api.remove(src.resolvedPath);
+    }
+    return copied;
+  }
+
+  async copy(source: string, target: string): Promise<boolean> {
+    this.checkGuard("copy", source);
+    this.checkGuard("copy", target);
+    const src = this.resolve(source);
+    const tgt = this.resolve(target);
+
+    // Same mount: delegate directly
+    if (src.api === tgt.api) {
+      return src.api.copy(src.resolvedPath, tgt.resolvedPath);
+    }
+
+    // Cross-mount copy
+    return this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
+  }
+
+  // --- Helpers ---
+
+  private stripBasePath(path: string, basePath: string): string {
+    if (basePath === "/") return path;
+    if (path === basePath) return "/";
+    if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
+    return path;
+  }
+
+  private async crossCopy(
+    srcApi: FilesApi,
+    srcPath: string,
+    tgtApi: FilesApi,
+    tgtPath: string,
+  ): Promise<boolean> {
+    const srcStats = await srcApi.stats(srcPath);
+    if (!srcStats) return false;
+
+    if (srcStats.kind === "file") {
+      await tgtApi.write(tgtPath, srcApi.read(srcPath));
+      return true;
+    }
+
+    // Directory: recursive copy
+    await tgtApi.mkdir(tgtPath);
+    for await (const entry of srcApi.list(srcPath)) {
+      const childSrc = srcPath === "/" ? `/${entry.name}` : `${srcPath}/${entry.name}`;
+      const childTgt = tgtPath === "/" ? `/${entry.name}` : `${tgtPath}/${entry.name}`;
+      if (entry.kind === "file") {
+        await tgtApi.write(childTgt, srcApi.read(childSrc));
+      } else {
+        await this.crossCopy(srcApi, childSrc, tgtApi, childTgt);
+      }
+    }
+    return true;
+  }
+
+  private remapPath(
+    compositeParent: string,
+    resolvedParent: string,
+    resolvedChild: string,
+  ): string {
+    // Convert a resolved path back into composite namespace
+    const relative = resolvedChild.startsWith(resolvedParent)
+      ? resolvedChild.slice(resolvedParent.length)
+      : resolvedChild;
+    if (compositeParent === "/") {
+      return relative.startsWith("/") ? relative : `/${relative}`;
+    }
+    return `${compositeParent}${relative.startsWith("/") ? relative : `/${relative}`}`;
+  }
+
+  private isUnderChildMount(compositePath: string, childMounts: string[]): boolean {
+    for (const mount of childMounts) {
+      if (compositePath === mount || compositePath.startsWith(`${mount}/`)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { CompositeFilesApi } from "./composite-files-api.js";
+export type { FileGuard, FileOperation } from "./types.js";

package/src/types.ts

@@ -0,0 +1,10 @@
+export type FileOperation = "read" | "write" | "remove" | "move" | "copy" | "list" | "mkdir";
+
+export interface FileGuard {
+  /** Which filesystem operations this guard intercepts. */
+  operations: FileOperation[];
+  /** Returns true to allow, false to deny. */
+  check: (path: string) => boolean;
+  /** Error message when access is denied. */
+  message?: string;
+}