@statewalker/webrun-files-composite 0.7.1 → 0.8.1

package/dist/cjs/index.cjs

@@ -22,11 +22,63 @@ function normalizePath(filePath) {
 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);
+}
+/**
+* Returns the filename portion of a path.
+*/
+function basename(path, ext) {
+	const normalized = normalizePath(path);
+	const lastSlash = normalized.lastIndexOf("/");
+	const name = lastSlash === -1 ? normalized : normalized.substring(lastSlash + 1);
+	if (ext && name.endsWith(ext)) return name.substring(0, name.length - ext.length);
+	return name;
+}
 //#endregion
 //#region src/composite-files-api.ts
+/**
+* Composite `FilesApi` that routes calls to one of several backends based
+* on a path prefix. Mounts are matched by **longest prefix wins**, so a
+* mount at `/a/b` takes precedence over a mount at `/a` for paths under
+* `/a/b/...`. The mount point itself appears in listings as a synthetic
+* directory and cannot be removed.
+*
+* Each backend can use a sub-directory of its own filesystem as the mount
+* root via `fsPath` (constructor `rootPath` for the implicit root mount,
+* `fsPath` argument for additional mounts). Cross-mount `move` is
+* implemented as copy-then-delete; there is no atomicity guarantee.
+*
+* Access control and visibility filtering are intentionally **not** part of
+* this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
+* (or both) instead.
+*
+* @example
+* ```ts
+* const fs = new CompositeFilesApi(localFs, "/projects")
+*   .mount("/docs", s3Fs, "/documentation")
+*   .mount("/cache", memFs);
+* await fs.write("/readme.md", data); // → localFs:/projects/readme.md
+* await fs.write("/docs/api.md", data); // → s3Fs:/documentation/api.md
+* ```
+*/
 var CompositeFilesApi = class {
 	mounts;
-	guards = [];
+	/**
+	* @param root Default backend used for any path that does not match a
+	*   more specific mount. All paths are routed here unless `mount()`
+	*   intercepts them.
+	* @param rootPath Optional sub-directory of the root backend to use as
+	*   the composite filesystem's `/`. For example, `rootPath = "/projects"`
+	*   makes the composite path `/readme.md` resolve to `/projects/readme.md`
+	*   in the root backend. Defaults to `"/"` (no remapping).
+	*/
 	constructor(root, rootPath) {
 		this.mounts = [{
 			prefix: "/",
@@ -34,6 +86,22 @@ var CompositeFilesApi = class {
 			basePath: normalizePath(rootPath ?? "/")
 		}];
 	}
+	/**
+	* Attaches a backend to handle every composite path under `path`. The
+	* mount prefix is normalized; paths under it are resolved against the
+	* mount's `fsPath` sub-directory (defaulting to `"/"`).
+	*
+	* @param path Composite-namespace prefix (e.g. `"/docs"`). Mounting at
+	*   `"/"` is forbidden — use the constructor `root` argument instead.
+	* @param api The backend `FilesApi` to delegate to for paths under
+	*   `path`. Wrap it in {@link FilteredFilesApi} / {@link GuardedFilesApi}
+	*   first if you want mount-local filtering or guards.
+	* @param fsPath Sub-directory of the mounted backend used as its mount
+	*   root, e.g. `mount("/docs", s3, "/documentation")` makes
+	*   `/docs/api.md` resolve to `/documentation/api.md` on `s3`.
+	* @returns `this`, for chaining.
+	* @throws If `path` normalizes to `"/"`.
+	*/
 	mount(path, api, fsPath) {
 		const prefix = normalizePath(path);
 		if (prefix === "/") throw new Error("Cannot mount at root — root is set via constructor");
@@ -45,14 +113,6 @@ var CompositeFilesApi = class {
 		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) {
@@ -90,33 +150,19 @@ var CompositeFilesApi = class {
 		}
 		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);
@@ -181,13 +227,10 @@ var CompositeFilesApi = class {
 	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);
@@ -196,8 +239,6 @@ var CompositeFilesApi = class {
 		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);
@@ -236,4 +277,705 @@ var CompositeFilesApi = class {
 	}
 };
 //#endregion
+//#region src/cow-files-api.ts
+/**
+* Copy-on-write view: a writable layer over a read-only `base`. The `base`
+* is **never** mutated — every change (write, delete, move) is recorded in
+* the `writable` layer, using marker files to record deletions.
+*
+* Resolution precedence for any path:
+* 1. a covering whiteout / opaque marker ⇒ the path is absent;
+* 2. otherwise the `writable` layer, if it has the path;
+* 3. otherwise fall through to `base`.
+*
+* Deletions are persisted as marker files inside the writable layer, so they
+* survive across process restarts and work over any `FilesApi` backend.
+* Markers are hidden from `read` / `list` / `stats` / `exists`.
+*
+* Use {@link cow} to construct one.
+*/
+var CowFilesApi = class {
+	base;
+	writable;
+	whiteoutPrefix;
+	opaqueName;
+	constructor(base, writable, opts) {
+		this.base = base;
+		this.writable = writable;
+		this.whiteoutPrefix = opts?.whiteoutPrefix ?? ".wh.";
+		this.opaqueName = opts?.opaqueName ?? ".wh..opq";
+	}
+	whiteoutPath(path) {
+		const p = normalizePath(path);
+		return joinPath(dirname(p), `${this.whiteoutPrefix}${basename(p)}`);
+	}
+	opaquePath(dir) {
+		return joinPath(normalizePath(dir), this.opaqueName);
+	}
+	isMarker(name) {
+		return name.startsWith(this.whiteoutPrefix) || name === this.opaqueName;
+	}
+	*ancestorsInclusive(dir) {
+		let cur = normalizePath(dir);
+		yield cur;
+		while (cur !== "/") {
+			cur = dirname(cur);
+			yield cur;
+		}
+	}
+	async hasDirectWhiteout(path) {
+		return this.writable.exists(this.whiteoutPath(path));
+	}
+	/** True when an opaque marker on `dir` or any ancestor hides base content. */
+	async isBaseContentHidden(dir) {
+		for (const ancestor of this.ancestorsInclusive(dir)) if (await this.writable.exists(this.opaquePath(ancestor))) return true;
+		return false;
+	}
+	/** True when the base version of `path` is hidden by a marker. */
+	async isBaseHidden(path) {
+		if (await this.hasDirectWhiteout(path)) return true;
+		return this.isBaseContentHidden(dirname(normalizePath(path)));
+	}
+	async resolveLayer(path) {
+		if (await this.writable.exists(path)) return "writable";
+		if (await this.isBaseHidden(path)) return "absent";
+		if (await this.base.exists(path)) return "base";
+		return "absent";
+	}
+	/** Removes a covering whiteout marker so a write/mkdir resurrects the path. */
+	async clearWhiteout(path) {
+		const marker = this.whiteoutPath(path);
+		if (await this.writable.exists(marker)) await this.writable.remove(marker);
+	}
+	async *read(path, options) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") yield* this.writable.read(path, options);
+		else if (layer === "base") yield* this.base.read(path, options);
+	}
+	async write(path, content) {
+		await this.clearWhiteout(path);
+		await this.writable.write(path, content);
+	}
+	async mkdir(path) {
+		await this.clearWhiteout(path);
+		await this.writable.mkdir(path);
+	}
+	async stats(path) {
+		const layer = await this.resolveLayer(path);
+		if (layer === "writable") return this.writable.stats(path);
+		if (layer === "base") return this.base.stats(path);
+	}
+	async exists(path) {
+		return await this.resolveLayer(path) !== "absent";
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`: writable entries win, base entries fill in. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		if ((await this.writable.stats(dir))?.kind === "directory") for await (const entry of this.writable.list(dir)) {
+			if (this.isMarker(entry.name)) continue;
+			merged.set(entry.name, entry);
+		}
+		if (!await this.isBaseContentHidden(dir) && (await this.base.stats(dir))?.kind === "directory") for await (const entry of this.base.list(dir)) {
+			if (merged.has(entry.name)) continue;
+			if (await this.hasDirectWhiteout(entry.path)) continue;
+			merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async remove(path) {
+		if (await this.resolveLayer(path) === "absent") return false;
+		if (await this.writable.exists(path)) await this.writable.remove(path);
+		const baseStats = await this.base.stats(path);
+		if (baseStats) {
+			const marker = baseStats.kind === "directory" ? this.opaquePath(path) : this.whiteoutPath(path);
+			await this.writable.write(marker, []);
+		}
+		return true;
+	}
+	async move(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		await this.remove(source);
+		return true;
+	}
+	async copy(source, target) {
+		const stats = await this.stats(source);
+		if (!stats) return false;
+		await this.copyInto(source, target, stats);
+		return true;
+	}
+	/** Copies the composite view of `src` into the writable layer at `tgt`. */
+	async copyInto(src, tgt, stats) {
+		if (stats.kind === "file") {
+			await this.write(tgt, this.read(src));
+			return;
+		}
+		await this.mkdir(tgt);
+		for await (const entry of this.list(src)) await this.copyInto(entry.path, joinPath(tgt, entry.name), entry);
+	}
+};
+/**
+* Builds a copy-on-write `FilesApi`: a `writable` layer over a read-only
+* `base`. Reads fall through to `base`; every write goes to `writable`;
+* `base` is never mutated. Deletions are persisted as marker files in
+* `writable` (a per-path whiteout for files, one opaque marker for a deleted
+* base directory), so they survive over any backend and across restarts.
+*
+* @param base The read-only lower layer. Never mutated.
+* @param writable The upper layer that captures all changes and markers.
+* @param opts Marker naming overrides (see {@link CowOptions}).
+* @returns A read/write `FilesApi` composing the two layers.
+*
+* @example
+* ```ts
+* const fs = cow(releaseFiles, new MemFilesApi());
+* await fs.write("/a.txt", data); // captured in the writable layer
+* await fs.remove("/base-only");  // whiteout marker; base untouched
+* ```
+*/
+function cow(base, writable, opts) {
+	return new CowFilesApi(base, writable, opts);
+}
+//#endregion
+//#region src/glob-to-regexp.ts
+/**
+* Compiles a glob pattern into a `RegExp`.
+*
+* @example
+* ```ts
+* globToRegExp("*.js");                       // /^.*\.js$/
+* globToRegExp("*.js", { globstar: true });   // /^([^/]*)\.js$/
+* globToRegExp("/foo/**", { globstar: true }) // /^\/foo\/((?:[^/]*(?:\/|$))*)$/
+* globToRegExp("foo{bar,baz}", { extended: true }); // /^foo(bar|baz)$/
+* ```
+*/
+function globToRegExp(glob, opts = {}) {
+	if (typeof glob !== "string") throw new TypeError("Expected a string");
+	const str = String(glob);
+	let reStr = "";
+	const extended = !!opts.extended;
+	const globstar = !!opts.globstar;
+	let inGroup = false;
+	const flags = typeof opts.flags === "string" ? opts.flags : "";
+	for (let i = 0; i < str.length; i++) {
+		const c = str[i];
+		switch (c) {
+			case "/":
+			case "$":
+			case "^":
+			case "+":
+			case ".":
+			case "(":
+			case ")":
+			case "=":
+			case "!":
+			case "|":
+				reStr += `\\${c}`;
+				break;
+			case "?":
+				reStr += extended ? "." : `\\${c}`;
+				break;
+			case "[":
+			case "]":
+				reStr += extended ? c : `\\${c}`;
+				break;
+			case "{":
+				if (extended) {
+					inGroup = true;
+					reStr += "(";
+				} else reStr += `\\${c}`;
+				break;
+			case "}":
+				if (extended) {
+					inGroup = false;
+					reStr += ")";
+				} else reStr += `\\${c}`;
+				break;
+			case ",":
+				if (inGroup) reStr += "|";
+				else reStr += `\\${c}`;
+				break;
+			case "*": {
+				const prevChar = str[i - 1];
+				let starCount = 1;
+				while (str[i + 1] === "*") {
+					starCount++;
+					i++;
+				}
+				const nextChar = str[i + 1];
+				if (!globstar) reStr += ".*";
+				else if (starCount > 1 && (prevChar === "/" || prevChar === void 0) && (nextChar === "/" || nextChar === void 0)) {
+					reStr += "((?:[^/]*(?:\\/|$))*)";
+					i++;
+				} else reStr += "([^/]*)";
+				break;
+			}
+			default: reStr += c;
+		}
+	}
+	if (!flags?.includes("g")) reStr = `^${reStr}$`;
+	return new RegExp(reStr, flags);
+}
+//#endregion
+//#region src/filtered-files-api.ts
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* equals one of the provided prefixes or lives under `${prefix}/`.
+*
+* Prefixes are normalized through `normalizePath` (so `"foo"`, `"/foo"`, and
+* `"/foo/"` are equivalent). Empty / root entries are dropped — they would
+* otherwise hide every path.
+*
+* Matching is **boundary-aware**: the prefix `"/priv"` does not match the
+* path `"/private"` because there is no `/` boundary between them.
+*
+* @param pathPrefixes Path prefixes whose contents (and the prefix itself)
+*   should be hidden. Pass none to hide nothing.
+*
+* @example
+* ```ts
+* const filter = newPathFilter("/.git", "/node_modules");
+* filter("/src/index.ts"); // true
+* filter("/.git");         // false
+* filter("/.git/HEAD");    // false
+* filter("/notgit");       // true (boundary-aware, no false match)
+* ```
+*/
+function newPathFilter(...pathPrefixes) {
+	const normalized = pathPrefixes.map((p) => normalizePath(p)).filter((p) => p !== "/");
+	return (path) => {
+		const target = normalizePath(path);
+		for (const prefix of normalized) {
+			if (target === prefix) return false;
+			if (target.startsWith(`${prefix}/`)) return false;
+		}
+		return true;
+	};
+}
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* matches at least one of the provided regular expressions.
+*
+* The path is normalized through `normalizePath` before matching, so a
+* regexp anchored on `^/` always sees a leading slash and never a trailing
+* one. The regexp's `lastIndex` is irrelevant — the filter calls `test`
+* via a fresh evaluation each time, but stateful (`/g`, `/y`) regexps
+* still mutate `lastIndex` across calls; pass non-stateful regexps unless
+* you know what you are doing.
+*
+* @param pathRegexps Regular expressions whose match means "hide this
+*   path". Pass none to hide nothing.
+*
+* @example
+* ```ts
+* // Hide every dotfile and every *.log file
+* const filter = newRegexpPathFilter(/\/\.[^/]+$/, /\.log$/);
+* filter("/src/index.ts"); // true
+* filter("/.env");         // false (matches /\/\.[^/]+$/)
+* filter("/build.log");    // false (matches /\.log$/)
+* ```
+*/
+function newRegexpPathFilter(...pathRegexps) {
+	return (path) => {
+		const target = normalizePath(path);
+		for (const regexp of pathRegexps) if (regexp.test(target)) return false;
+		return true;
+	};
+}
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* matches at least one of the provided glob patterns.
+*
+* Each glob is compiled with `extended: true` and `globstar: true`, the
+* standard "filesystem-style" mode:
+*
+* - `*` matches any number of characters within a single path segment
+*   (does **not** cross `/`).
+* - `**` between slashes matches zero or more whole path segments.
+* - `?` matches exactly one character.
+* - `[abc]` / `[a-z]` matches a single character in the set / range.
+* - `{a,b,c}` matches one of the alternatives.
+*
+* Because matching is done on the **normalized** path (which always starts
+* with `/`), patterns that should match anywhere in the tree need a
+* leading `**​/`, e.g. `**​/*.log` to hide every `.log` file at any depth.
+*
+* Gotcha: `/foo/**` matches descendants of `/foo` but **not** `/foo`
+* itself, because the glob requires a `/` after `foo` before `**` can
+* match. To hide both the directory and its contents, list both prefixes:
+* `newGlobPathFilter("/foo", "/foo/**")`. {@link newPathFilter} doesn't
+* have this problem and may be a better fit for prefix-only hiding.
+*
+* @param pathGlobs Glob patterns whose match means "hide this path". Pass
+*   none to hide nothing.
+*
+* @example
+* ```ts
+* const filter = newGlobPathFilter("**​/*.log", "/.git", "/.git/**");
+* filter("/src/index.ts"); // true
+* filter("/build.log");    // false (matches **​/*.log)
+* filter("/.git");         // false (matches /.git)
+* filter("/.git/HEAD");    // false (matches /.git/**)
+* ```
+*/
+function newGlobPathFilter(...pathGlobs) {
+	return newRegexpPathFilter(...pathGlobs.map((glob) => globToRegExp(glob, {
+		extended: true,
+		globstar: true
+	})));
+}
+/**
+* `FilesApi` decorator that hides every path the supplied {@link PathFilter}
+* rejects. Hidden paths are treated as if they do not exist:
+*
+* - `read` / `list` yield empty iterables.
+* - `stats` returns `undefined`; `exists` returns `false`.
+* - `remove` returns `false` (no error, nothing changed).
+* - `move` / `copy` return `false` if either endpoint is hidden.
+* - `write` / `mkdir` reject with an `Error` (since silently dropping a
+*   write would lose data).
+* - `list` recursively skips entries whose paths are hidden, so iterating a
+*   visible parent never reveals a hidden child.
+*
+* Wrap any `FilesApi` to scope its visibility without changing the
+* underlying storage; the wrapped instance still holds the data, it is just
+* not reachable through this decorator.
+*
+* Pair with one of the built-in {@link PathFilter} factories
+* ({@link newPathFilter}, {@link newRegexpPathFilter},
+* {@link newGlobPathFilter}) or pass any predicate of shape
+* `(path) => boolean | Promise<boolean>`.
+*
+* @example
+* ```ts
+* import {
+*   FilteredFilesApi,
+*   newGlobPathFilter,
+*   newPathFilter,
+*   newRegexpPathFilter,
+* } from "@statewalker/webrun-files-composite";
+*
+* // Hide by path prefix
+* const noVcs = new FilteredFilesApi(sourceFiles, newPathFilter("/.git", "/.cache"));
+* await noVcs.exists("/.git");        // false
+* await noVcs.write("/.git/x", data); // throws "Path is hidden"
+*
+* // Hide by regexp
+* const noLogs = new FilteredFilesApi(sourceFiles, newRegexpPathFilter(/\.log$/));
+*
+* // Hide by glob (extended + globstar mode)
+* const noJunk = new FilteredFilesApi(
+*   sourceFiles,
+*   newGlobPathFilter("**​/*.log", "/.git", "/.git/**"),
+* );
+* ```
+*/
+var FilteredFilesApi = class {
+	source;
+	pathFilter;
+	/**
+	* @param source The underlying `FilesApi` whose paths will be selectively
+	*   hidden. Operations always delegate to this instance; the decorator
+	*   only adds the visibility check.
+	* @param pathFilter Predicate that decides per-call whether a normalized
+	*   path is visible. See {@link PathFilter}.
+	*/
+	constructor(source, pathFilter) {
+		this.source = source;
+		this.pathFilter = pathFilter;
+	}
+	async isHidden(path) {
+		return await this.pathFilter(normalizePath(path)) === false;
+	}
+	async *read(path, options) {
+		if (await this.isHidden(path)) return;
+		yield* this.source.read(path, options);
+	}
+	async write(path, content) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		await this.source.write(path, content);
+	}
+	async mkdir(path) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		await this.source.mkdir(path);
+	}
+	async *list(path, options) {
+		if (await this.isHidden(path)) return;
+		for await (const entry of this.source.list(path, options)) {
+			if (await this.isHidden(entry.path)) continue;
+			yield entry;
+		}
+	}
+	async stats(path) {
+		if (await this.isHidden(path)) return void 0;
+		return this.source.stats(path);
+	}
+	async exists(path) {
+		if (await this.isHidden(path)) return false;
+		return this.source.exists(path);
+	}
+	async remove(path) {
+		if (await this.isHidden(path)) return false;
+		return this.source.remove(path);
+	}
+	async move(source, target) {
+		if (await this.isHidden(source) || await this.isHidden(target)) return false;
+		return this.source.move(source, target);
+	}
+	async copy(source, target) {
+		if (await this.isHidden(source) || await this.isHidden(target)) return false;
+		return this.source.copy(source, target);
+	}
+};
+//#endregion
+//#region src/guarded-files-api.ts
+/**
+* `FilesApi` decorator that runs every call through an ordered list of
+* {@link FileGuard}s. A guard fires when its `operations` set intersects the
+* effective operation(s) for the current call. The first guard whose
+* `check` returns `false` aborts the call by throwing an `Error` with that
+* guard's `message` (defaulting to `"Access denied"`) followed by the
+* normalized path.
+*
+* Effective operations per call:
+*
+* | Method        | Operations checked                                  |
+* | ------------- | --------------------------------------------------- |
+* | `read`        | `read`                                              |
+* | `write`       | `write`                                             |
+* | `mkdir`       | `mkdir`                                             |
+* | `remove`      | `remove`                                            |
+* | `list`        | `list` on the path AND on each directory entry      |
+* | `stats`       | `list` (a stat reveals existence like a tiny list)  |
+* | `exists`      | `read` (existence is a read of metadata)            |
+* | `move(s, t)`  | `move`+`read` on source; `move`+`write` on target   |
+* | `copy(s, t)`  | `copy`+`read` on source; `copy`+`write` on target   |
+*
+* The expanded checks for `move`/`copy` mean a guard that blocks `read` on
+* a path also prevents move/copy *from* that path, and a `write`-blocking
+* guard prevents move/copy *to* it. Likewise, an `exists` call respects any
+* read guard, and `stats` respects any list guard.
+*
+* @example
+* ```ts
+* const api = new GuardedFilesApi(source, [
+*   {
+*     operations: ["write", "remove", "move", "mkdir"],
+*     check: (p) => !p.startsWith("/.system/"),
+*     message: "system folder is read-only",
+*   },
+* ]);
+* await api.write("/.system/cfg", data); // throws "system folder is read-only: /.system/cfg"
+* ```
+*/
+var GuardedFilesApi = class {
+	source;
+	guards;
+	/**
+	* @param source The underlying `FilesApi` whose calls will be policed.
+	*   Allowed operations delegate straight through.
+	* @param guards Ordered list of access policies. The wrapper takes a
+	*   defensive copy, so mutating the array afterwards has no effect.
+	*   An empty list disables every check (the wrapper becomes a passthrough).
+	*/
+	constructor(source, guards) {
+		this.source = source;
+		this.guards = [...guards];
+	}
+	checkGuard(path, ...operations) {
+		const normalized = normalizePath(path);
+		for (const guard of this.guards) {
+			if (!operations.some((op) => guard.operations.includes(op))) continue;
+			if (!guard.check(normalized)) {
+				const msg = guard.message ?? "Access denied";
+				throw new Error(`${msg}: ${normalized}`);
+			}
+		}
+	}
+	read(path, options) {
+		this.checkGuard(path, "read");
+		return this.source.read(path, options);
+	}
+	async write(path, content) {
+		this.checkGuard(path, "write");
+		return this.source.write(path, content);
+	}
+	async mkdir(path) {
+		this.checkGuard(path, "mkdir");
+		return this.source.mkdir(path);
+	}
+	async *list(path, options) {
+		this.checkGuard(path, "list");
+		for await (const info of this.source.list(path, options)) {
+			if (info.kind === "directory") this.checkGuard(info.path, "list");
+			yield info;
+		}
+	}
+	stats(path) {
+		this.checkGuard(path, "list");
+		return this.source.stats(path);
+	}
+	exists(path) {
+		this.checkGuard(path, "read");
+		return this.source.exists(path);
+	}
+	async remove(path) {
+		this.checkGuard(path, "remove");
+		return this.source.remove(path);
+	}
+	async move(source, target) {
+		this.checkGuard(source, "move", "read");
+		this.checkGuard(target, "move", "write");
+		return this.source.move(source, target);
+	}
+	async copy(source, target) {
+		this.checkGuard(source, "copy", "read");
+		this.checkGuard(target, "copy", "write");
+		return this.source.copy(source, target);
+	}
+};
+//#endregion
+//#region src/overlay-files-api.ts
+/**
+* Read-only union of several `FilesApi` layers. A path is resolved
+* **top → bottom**: the first layer that has it wins for
+* `read` / `stats` / `exists`, and its entry (including `kind`) wins any
+* name clash in `list`. Listings merge and dedupe across every layer.
+*
+* The union never writes — every mutating call throws. Use
+* {@link overlay} to construct one.
+*/
+var OverlayFilesApi = class {
+	layers;
+	constructor(layers) {
+		this.layers = layers;
+	}
+	deny(op, path) {
+		throw new Error(`overlay is read-only (${op}): ${normalizePath(path)}`);
+	}
+	async *read(path, options) {
+		for (const layer of this.layers) if (await layer.exists(path)) {
+			yield* layer.read(path, options);
+			return;
+		}
+	}
+	async stats(path) {
+		for (const layer of this.layers) {
+			const stats = await layer.stats(path);
+			if (stats) return stats;
+		}
+	}
+	async exists(path) {
+		for (const layer of this.layers) if (await layer.exists(path)) return true;
+		return false;
+	}
+	async *list(path, options) {
+		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
+	}
+	async *listDir(dir, recursive) {
+		if ((await this.stats(dir))?.kind !== "directory") return;
+		for (const entry of await this.mergeChildren(dir)) {
+			yield entry;
+			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
+		}
+	}
+	/** Direct children of `dir`, deduped by name with the topmost layer winning. */
+	async mergeChildren(dir) {
+		const merged = /* @__PURE__ */ new Map();
+		for (const layer of this.layers) {
+			if ((await layer.stats(dir))?.kind !== "directory") continue;
+			for await (const entry of layer.list(dir)) if (!merged.has(entry.name)) merged.set(entry.name, entry);
+		}
+		return [...merged.values()];
+	}
+	async write(path) {
+		this.deny("write", path);
+	}
+	async mkdir(path) {
+		this.deny("mkdir", path);
+	}
+	async remove(path) {
+		return this.deny("remove", path);
+	}
+	async move(source) {
+		return this.deny("move", source);
+	}
+	async copy(source) {
+		return this.deny("copy", source);
+	}
+};
+/**
+* Builds a **read-only** union view over `top` and any number of `lower`
+* layers. Reads resolve top → bottom (first layer that has the path wins);
+* `list` merges and dedupes across all layers with `top` winning a clash
+* (including a file-vs-directory `kind` clash). Every write is denied.
+*
+* @param top The highest-priority layer; its entries shadow the rest.
+* @param lower Additional layers, consulted in order after `top`.
+* @returns A read-only `FilesApi` union.
+*
+* @example
+* ```ts
+* const view = overlay(userFiles, defaultFiles);
+* await view.read("/config.json"); // userFiles if present, else defaultFiles
+* await view.write("/x", data);    // throws (read-only)
+* ```
+*/
+function overlay(top, ...lower) {
+	return new OverlayFilesApi([top, ...lower]);
+}
+//#endregion
+//#region src/read-only-files-api.ts
+/**
+* Wraps a `FilesApi` in a read-only view: every mutating operation
+* (`write`, `mkdir`, `remove`, `move`, `copy`) throws, while reads
+* (`read`, `list`, `stats`, `exists`) pass straight through to `api`.
+*
+* Implemented as a {@link GuardedFilesApi} with a single deny-all guard on
+* the mutating operations, so `move`/`copy` are blocked on either endpoint.
+*
+* @param api The underlying `FilesApi` to expose read-only.
+* @returns A `FilesApi` that never mutates `api`.
+*
+* @example
+* ```ts
+* const ro = readOnly(sourceFiles);
+* await ro.read("/a.txt");          // ok
+* await ro.write("/a.txt", data);   // throws "read-only: /a.txt"
+* ```
+*/
+function readOnly(api) {
+	return new GuardedFilesApi(api, [{
+		operations: [
+			"write",
+			"mkdir",
+			"remove",
+			"move",
+			"copy"
+		],
+		check: () => false,
+		message: "read-only"
+	}]);
+}
+//#endregion
 exports.CompositeFilesApi = CompositeFilesApi;
+exports.FilteredFilesApi = FilteredFilesApi;
+exports.GuardedFilesApi = GuardedFilesApi;
+exports.cow = cow;
+exports.globToRegExp = globToRegExp;
+exports.newGlobPathFilter = newGlobPathFilter;
+exports.newPathFilter = newPathFilter;
+exports.newRegexpPathFilter = newRegexpPathFilter;
+exports.overlay = overlay;
+exports.readOnly = readOnly;