@ucdjs/fs-bridge 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+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,119 @@
+# @ucdjs/fs-bridge
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![codecov][codecov-src]][codecov-href]
+
+A collection of filesystem bridge implementations for the UCD project, providing both Node.js and HTTP-based file system access.
+
+## Installation
+
+```bash
+npm install @ucdjs/fs-bridge
+```
+
+## Usage
+
+You can create your own filesystem bridge or use the preconfigured ones provided by this package.
+
+### Creating a Custom Bridge
+
+You can define a custom filesystem bridge using the `defineFileSystemBridge` function. This allows you to implement your own file system operations.
+
+```typescript
+import { defineFileSystemBridge } from "@ucdjs/fs-bridge";
+
+const MyFileSystemBridge = defineFileSystemBridge({
+  read: async (path) => {
+    // Implement your read logic here
+  },
+  write: async (path, content) => {
+    // Implement your write logic here
+  },
+  listdir: async (path, recursive = false) => {
+    // Implement your directory listing logic here
+  },
+  mkdir: async (path) => {
+    // Implement your directory creation logic here
+  },
+  exists: async (path) => {
+    // Implement your existence check logic here
+  },
+  stat: async (path) => {
+    // Implement your file stats retrieval logic here
+  },
+  rm: async (path, options) => {
+    // Implement your file/directory removal logic here
+  }
+});
+```
+
+### Predefined Bridges
+
+#### Node.js File System Bridge
+
+```typescript
+import NodeFileSystemBridge from "@ucdjs/fs-bridge/bridges/node";
+
+// Read a file
+const content = await NodeFileSystemBridge.read("/path/to/file.txt");
+
+// Write a file
+await NodeFileSystemBridge.write("/path/to/file.txt", "Hello World");
+
+// List directory contents
+const files = await NodeFileSystemBridge.listdir("/path/to/dir");
+const allFiles = await NodeFileSystemBridge.listdir("/path/to/dir", true); // recursive
+
+// Create directory
+await NodeFileSystemBridge.mkdir("/path/to/new/dir");
+
+// Check if file exists
+const exists = await NodeFileSystemBridge.exists("/path/to/file.txt");
+
+// Get file stats
+const stats = await NodeFileSystemBridge.stat("/path/to/file.txt");
+console.log(stats.isFile()); // true/false
+console.log(stats.isDirectory()); // true/false
+console.log(stats.size); // file size in bytes
+console.log(stats.mtime); // last modified date
+
+// Remove file/directory
+await NodeFileSystemBridge.rm("/path/to/file.txt");
+await NodeFileSystemBridge.rm("/path/to/dir", { recursive: true, force: true });
+```
+
+#### HTTP File System Bridge
+
+Read-only filesystem bridge for accessing files over HTTP/HTTPS:
+
+```typescript
+import HTTPFileSystemBridge from "@ucdjs/fs-bridge/bridges/http";
+
+const httpFS = HTTPFileSystemBridge({
+  baseUrl: "https://example.com/files/"
+});
+
+// Read remote file
+const content = await httpFS.read("/data/file.txt");
+
+// List remote directory
+const files = await httpFS.listdir("/data/");
+
+// Check if remote file exists
+const exists = await httpFS.exists("/data/file.txt");
+
+// Get remote file stats
+const stats = await httpFS.stat("/data/file.txt");
+```
+
+## 📄 License
+
+Published under [MIT License](./LICENSE).
+
+[npm-version-src]: https://img.shields.io/npm/v/@ucdjs/fs-bridge?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@ucdjs/fs-bridge
+[npm-downloads-src]: https://img.shields.io/npm/dm/@ucdjs/fs-bridge?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@ucdjs/fs-bridge
+[codecov-src]: https://img.shields.io/codecov/c/gh/ucdjs/ucd?style=flat&colorA=18181B&colorB=4169E1
+[codecov-href]: https://codecov.io/gh/ucdjs/ucd

package/dist/bridges/http.d.mts

@@ -0,0 +1,12 @@
+import { i as FileSystemBridgeFactory } from "../types-BRcSW-lJ.mjs";
+import "../guards-CXuUenP_.mjs";
+import "../index.mjs";
+import { z } from "zod";
+
+//#region src/bridges/http.d.ts
+declare const kHttpBridgeSymbol: unique symbol;
+declare const HTTPFileSystemBridge: FileSystemBridgeFactory<z.ZodObject<{
+  baseUrl: z.ZodDefault<z.ZodCodec<z.ZodURL, z.ZodCustom<URL, URL>>>;
+}, z.core.$strip>>;
+//#endregion
+export { HTTPFileSystemBridge as default, kHttpBridgeSymbol };

package/dist/bridges/http.mjs

@@ -0,0 +1,161 @@
+import { t as defineFileSystemBridge } from "../define-BfE46g0d.mjs";
+import { createDebugger } from "@ucdjs-internal/shared";
+import { z } from "zod";
+import { joinURL } from "@luxass/utils/path";
+import { UCDJS_STORE_BASE_URL } from "@ucdjs/env";
+import { FileEntrySchema } from "@ucdjs/schemas";
+
+//#region src/bridges/http.ts
+const debug = createDebugger("ucdjs:fs-bridge:http");
+const kHttpBridgeSymbol = Symbol.for("@ucdjs/fs-bridge:http");
+const API_BASE_URL_SCHEMA = z.codec(z.url({
+	protocol: /^https?$/,
+	hostname: z.regexes.hostname,
+	normalize: true
+}), z.instanceof(URL), {
+	decode: (urlString) => new URL(urlString),
+	encode: (url) => url.href
+}).default(new URL("/", UCDJS_STORE_BASE_URL));
+const HTTPFileSystemBridge = defineFileSystemBridge({
+	meta: {
+		name: "HTTP File System Bridge",
+		description: "A file system bridge that interacts with a remote HTTP API to perform file system operations."
+	},
+	optionsSchema: z.object({ baseUrl: API_BASE_URL_SCHEMA }),
+	symbol: kHttpBridgeSymbol,
+	setup({ options, resolveSafePath }) {
+		const baseUrl = options.baseUrl;
+		return {
+			async read(path) {
+				debug?.("Reading file", { path });
+				const trimmedPath = path.trim();
+				if (trimmedPath.endsWith("/") && trimmedPath !== "/" && trimmedPath !== "./" && trimmedPath !== "../") {
+					debug?.("Rejected file path ending with '/'", { path });
+					throw new Error("Cannot read file: path ends with '/'");
+				}
+				const url = joinURL(baseUrl.origin, resolveSafePath(baseUrl.pathname, path));
+				debug?.("Fetching remote file", { url });
+				const response = await fetch(url);
+				if (!response.ok) {
+					debug?.("Failed to read remote file", {
+						url,
+						status: response.status,
+						statusText: response.statusText
+					});
+					throw new Error(`Failed to read remote file: ${response.statusText}`);
+				}
+				debug?.("Successfully read remote file", { url });
+				return response.text();
+			},
+			async listdir(path, recursive = false) {
+				debug?.("Listing directory", {
+					path,
+					recursive
+				});
+				const url = joinURL(baseUrl.origin, resolveSafePath(baseUrl.pathname, `/${path}`));
+				debug?.("Fetching directory listing", { url });
+				const response = await fetch(url, {
+					method: "GET",
+					headers: { Accept: "application/json" }
+				});
+				if (!response.ok) {
+					if (response.status === 404) {
+						debug?.("Directory not found, returning empty array", { url });
+						return [];
+					}
+					if (response.status === 403) {
+						debug?.("Directory access forbidden, returning empty array", { url });
+						return [];
+					}
+					if (response.status === 500) {
+						debug?.("Server error while listing directory", {
+							url,
+							status: response.status
+						});
+						throw new Error(`Server error while listing directory: ${response.statusText}`);
+					}
+					debug?.("Failed to list directory", {
+						url,
+						status: response.status,
+						statusText: response.statusText
+					});
+					throw new Error(`Failed to list directory: ${response.statusText} (${response.status})`);
+				}
+				const json = await response.json();
+				const result = z.array(FileEntrySchema).safeParse(json);
+				if (!result.success) {
+					debug?.("Invalid response schema from directory listing", {
+						url,
+						error: result.error.message
+					});
+					throw new Error(`Invalid response schema: ${result.error.message}`);
+				}
+				const data = result.data;
+				if (!recursive) {
+					debug?.("Returning non-recursive directory listing", {
+						path,
+						entryCount: data.length
+					});
+					return data.map((entry) => {
+						if (entry.type === "directory") return {
+							type: "directory",
+							name: entry.name,
+							path: entry.path,
+							children: []
+						};
+						return {
+							type: entry.type,
+							name: entry.name,
+							path: entry.path
+						};
+					});
+				}
+				debug?.("Processing recursive directory listing", {
+					path,
+					entryCount: data.length
+				});
+				const entries = [];
+				for (const entry of data) if (entry.type === "directory") {
+					const children = await this.listdir(entry.path, true);
+					entries.push({
+						type: "directory",
+						name: entry.name,
+						path: entry.path,
+						children
+					});
+				} else entries.push({
+					type: "file",
+					name: entry.name,
+					path: entry.path
+				});
+				debug?.("Completed recursive directory listing", {
+					path,
+					totalEntries: entries.length
+				});
+				return entries;
+			},
+			async exists(path) {
+				debug?.("Checking file existence", { path });
+				const url = joinURL(baseUrl.origin, resolveSafePath(baseUrl.pathname, path));
+				debug?.("Sending HEAD request", { url });
+				return fetch(url, { method: "HEAD" }).then((response) => {
+					debug?.("File existence check result", {
+						url,
+						exists: response.ok
+					});
+					return response.ok;
+				}).catch((err) => {
+					if (err instanceof Error && err.message.startsWith("[MSW]")) throw err;
+					debug?.("Error checking file existence", {
+						url,
+						error: err instanceof Error ? err.message : String(err)
+					});
+					return false;
+				});
+			}
+		};
+	}
+});
+
+//#endregion
+export { HTTPFileSystemBridge as default, kHttpBridgeSymbol };

package/dist/bridges/node.d.mts

@@ -0,0 +1,11 @@
+import { i as FileSystemBridgeFactory } from "../types-BRcSW-lJ.mjs";
+import "../guards-CXuUenP_.mjs";
+import "../index.mjs";
+import { z } from "zod";
+
+//#region src/bridges/node.d.ts
+declare const NodeFileSystemBridge: FileSystemBridgeFactory<z.ZodObject<{
+  basePath: z.ZodString;
+}, z.core.$strip>>;
+//#endregion
+export { NodeFileSystemBridge as default };

package/dist/bridges/node.mjs

@@ -0,0 +1,115 @@
+import { t as defineFileSystemBridge } from "../define-BfE46g0d.mjs";
+import { createDebugger } from "@ucdjs-internal/shared";
+import { assertNotUNCPath } from "@ucdjs/path-utils";
+import { z } from "zod";
+import { appendTrailingSlash, prependLeadingSlash } from "@luxass/utils/path";
+import fsp from "node:fs/promises";
+import nodePath from "node:path";
+
+//#region src/bridges/node.ts
+const debug = createDebugger("ucdjs:fs-bridge:node");
+/**
+* Normalizes path separators to forward slashes for cross-platform consistency.
+* On Windows, converts backslashes to forward slashes.
+*/
+function normalizePathSeparators(path) {
+	return path.replace(/\\/g, "/");
+}
+async function safeExists(path) {
+	try {
+		await fsp.stat(path);
+		return true;
+	} catch {
+		debug?.("File existence check failed", { path });
+		return false;
+	}
+}
+const NodeFileSystemBridge = defineFileSystemBridge({
+	meta: {
+		name: "Node.js File System Bridge",
+		description: "A file system bridge that uses Node.js fs module to interact with the local file system."
+	},
+	optionsSchema: z.object({ basePath: z.string() }),
+	setup({ options, resolveSafePath }) {
+		assertNotUNCPath(options.basePath);
+		const basePath = nodePath.resolve(options.basePath);
+		return {
+			async read(path) {
+				const trimmedPath = path.trim();
+				if (trimmedPath.endsWith("/") && trimmedPath !== "/" && trimmedPath !== "./" && trimmedPath !== "../") throw new Error("Cannot read file: path ends with '/'");
+				const resolvedPath = resolveSafePath(basePath, path);
+				return fsp.readFile(resolvedPath, "utf-8");
+			},
+			async exists(path) {
+				return safeExists(resolveSafePath(basePath, path));
+			},
+			async listdir(path, recursive = false) {
+				const targetPath = resolveSafePath(basePath, path);
+				function formatEntryPath(relativeToRoot, isDirectory) {
+					const withLeadingSlash = prependLeadingSlash(relativeToRoot);
+					return isDirectory ? appendTrailingSlash(withLeadingSlash) : withLeadingSlash;
+				}
+				function createFSEntry(entry, relativeToRoot) {
+					const formattedPath = formatEntryPath(relativeToRoot, entry.isDirectory());
+					return entry.isDirectory() ? {
+						type: "directory",
+						name: entry.name,
+						path: formattedPath,
+						children: []
+					} : {
+						type: "file",
+						name: entry.name,
+						path: formattedPath
+					};
+				}
+				if (!recursive) return (await fsp.readdir(targetPath, { withFileTypes: true })).map((entry) => {
+					const absEntryPath = nodePath.join(targetPath, entry.name);
+					return createFSEntry(entry, normalizePathSeparators(nodePath.relative(basePath, absEntryPath)));
+				});
+				const allEntries = await fsp.readdir(targetPath, {
+					withFileTypes: true,
+					recursive: true
+				});
+				const entryMap = /* @__PURE__ */ new Map();
+				const rootEntries = [];
+				for (const entry of allEntries) {
+					const entryDirPath = entry.parentPath || entry.path;
+					const relativeToTargetDir = nodePath.relative(targetPath, entryDirPath);
+					const absEntryPath = nodePath.join(entryDirPath, entry.name);
+					const normalized = normalizePathSeparators(nodePath.relative(basePath, absEntryPath));
+					const fsEntry = createFSEntry(entry, normalized);
+					entryMap.set(normalized, fsEntry);
+					if (!relativeToTargetDir) rootEntries.push(fsEntry);
+				}
+				for (const [entryPath, entry] of entryMap) {
+					const parentPath = nodePath.dirname(entryPath);
+					if (parentPath && parentPath !== ".") {
+						const parent = entryMap.get(parentPath);
+						if (parent?.type === "directory") parent.children.push(entry);
+					}
+				}
+				return rootEntries;
+			},
+			async write(path, data, encoding = "utf-8") {
+				const trimmedPath = path.trim();
+				if (trimmedPath.endsWith("/") && trimmedPath !== "/" && trimmedPath !== "./" && trimmedPath !== "../") throw new Error("Cannot write file: path ends with '/'");
+				const resolvedPath = resolveSafePath(basePath, path);
+				const parentDir = nodePath.dirname(resolvedPath);
+				if (!await safeExists(parentDir)) await fsp.mkdir(parentDir, { recursive: true });
+				return fsp.writeFile(resolvedPath, data, { encoding });
+			},
+			async mkdir(path) {
+				await fsp.mkdir(resolveSafePath(basePath, path), { recursive: true });
+			},
+			async rm(path, options) {
+				return fsp.rm(resolveSafePath(basePath, path), {
+					recursive: options?.recursive ?? false,
+					force: options?.force ?? false
+				});
+			}
+		};
+	}
+});
+
+//#endregion
+export { NodeFileSystemBridge as default };

package/dist/define-BfE46g0d.mjs

@@ -0,0 +1,205 @@
+import { BridgeBaseError, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation } from "./errors.mjs";
+import { createDebugger } from "@ucdjs-internal/shared";
+import { PathUtilsBaseError, resolveSafePath } from "@ucdjs/path-utils";
+import { HookableCore } from "hookable";
+import { z } from "zod";
+
+//#region ../../node_modules/.pnpm/@luxass+msw-utils@0.6.0_msw@2.12.10_@types+node@25.2.2_typescript@5.9.3_/node_modules/@luxass/msw-utils/dist/runtime-guards.mjs
+/**
+* Checks if an error is an MSW internal error.
+*
+* MSW throws internal errors with the name "InternalError" and
+* prefixes error messages with "[MSW]".
+*
+* @param {unknown} error - The error to check
+* @returns {boolean} true if the error is from MSW
+*
+* @example
+* ```ts
+* try {
+*   // some code that might throw MSW errors
+* } catch (error) {
+*   if (isMSWError(error)) {
+*     console.log("This is an MSW error:", error.message);
+*   }
+* }
+* ```
+*/
+function isMSWError(error) {
+	return error instanceof Error && (error.name === "InternalError" || error.message.startsWith("[MSW]"));
+}
+
+//#endregion
+//#region src/utils.ts
+const debug$1 = createDebugger("ucdjs:fs-bridge:utils");
+/**
+* @internal
+*/
+function inferOptionalCapabilitiesFromOperations(ops) {
+	return {
+		write: "write" in ops && typeof ops.write === "function",
+		mkdir: "mkdir" in ops && typeof ops.mkdir === "function",
+		rm: "rm" in ops && typeof ops.rm === "function"
+	};
+}
+/**
+* Constructs a hook payload object for a given file system bridge operation.
+*
+* This function normalizes arguments and results from different file system operations
+* into their corresponding hook payload structures. It supports both "before" and "after"
+* phases for operations that distinguish between them.
+*
+* @param {string} property - The name of the file system operation (e.g., "read", "write", "listdir", "exists", "mkdir", "rm")
+* @param {string} phase - The hook execution phase: "before" runs before the operation, "after" runs after
+* @param {unknown[]} args - The arguments passed to the original operation
+* @param {unknown} result - The result from the operation (only used for "after" phase hooks)
+* @returns A {@link HookPayload} object containing normalized data for the hook
+*/
+function getPayloadForHook(property, phase, args, result) {
+	debug$1?.(`Constructing hook payload for '${property}:${phase}'`);
+	switch (property) {
+		case "read": if (phase === "before") return { path: args[0] };
+		else return {
+			path: args[0],
+			content: result
+		};
+		case "write": if (phase === "before") return {
+			path: args[0],
+			content: args[1],
+			encoding: args[2]
+		};
+		else return { path: args[0] };
+		case "listdir": if (phase === "before") return {
+			path: args[0],
+			recursive: args[1] ?? false
+		};
+		else return {
+			path: args[0],
+			recursive: args[1] ?? false,
+			entries: result
+		};
+		case "exists": if (phase === "before") return { path: args[0] };
+		else return {
+			path: args[0],
+			exists: result
+		};
+		case "mkdir": return { path: args[0] };
+		case "rm": return {
+			path: args[0],
+			...args[1]
+		};
+		default: throw new BridgeGenericError(`Failed to construct hook payload for '${property}:${phase}' hook`);
+	}
+}
+/**
+* @internal
+*/
+function createOperationWrapper(operationName, { hooks, operations }) {
+	const operation = operations[operationName];
+	if (operation == null || typeof operation !== "function") return async (...args) => {
+		debug$1?.("Attempted to call unsupported operation", { operation: operationName });
+		const error = new BridgeUnsupportedOperation(operationName);
+		await hooks.callHook("error", {
+			method: operationName,
+			path: args[0],
+			error,
+			args
+		});
+		throw error;
+	};
+	return async (...args) => {
+		try {
+			const beforePayload = getPayloadForHook(operationName, "before", args);
+			await hooks.callHook(`${operationName}:before`, beforePayload);
+			const result = await operation.apply(operations, args);
+			const afterPayload = getPayloadForHook(operationName, "after", args, result);
+			await hooks.callHook(`${operationName}:after`, afterPayload);
+			return result;
+		} catch (err) {
+			return handleError(operationName, args, err, hooks);
+		}
+	};
+}
+async function handleError(operation, args, err, hooks) {
+	const normalizedError = (() => {
+		if (err instanceof Error) return err;
+		debug$1?.("Non-Error thrown in bridge operation", {
+			operation: String(operation),
+			error: String(err)
+		});
+		return new BridgeGenericError(`Non-Error thrown in '${String(operation)}' operation: ${String(err)}`, { cause: err });
+	})();
+	if (isMSWError(normalizedError)) {
+		debug$1?.("MSW error detected in bridge operation", {
+			operation: String(operation),
+			error: normalizedError.message
+		});
+		throw normalizedError;
+	}
+	await hooks.callHook("error", {
+		method: operation,
+		path: args[0],
+		error: normalizedError,
+		args
+	});
+	if (normalizedError instanceof BridgeBaseError || normalizedError instanceof PathUtilsBaseError) {
+		debug$1?.("Known error thrown in bridge operation", {
+			operation: String(operation),
+			error: normalizedError.message
+		});
+		throw normalizedError;
+	}
+	debug$1?.("Unexpected error in bridge operation", {
+		operation: String(operation),
+		error: normalizedError.message
+	});
+	throw new BridgeGenericError(`Unexpected error in '${String(operation)}' operation: ${normalizedError.message}`, { cause: normalizedError });
+}
+
+//#endregion
+//#region src/define.ts
+const debug = createDebugger("ucdjs:fs-bridge:define");
+function defineFileSystemBridge(fsBridge) {
+	return (...args) => {
+		const parsedOptions = (fsBridge.optionsSchema ?? z.never().optional()).safeParse(args[0]);
+		if (!parsedOptions.success) {
+			debug?.("Invalid options provided to file system bridge", { error: parsedOptions.error.message });
+			throw new Error(`Invalid options provided to file system bridge: ${parsedOptions.error.message}`);
+		}
+		const options = parsedOptions.data;
+		const { state } = fsBridge;
+		let bridgeOperations = null;
+		try {
+			bridgeOperations = fsBridge.setup({
+				options,
+				state: structuredClone(state) ?? {},
+				resolveSafePath
+			});
+		} catch (err) {
+			debug?.("Failed to setup file system bridge", { error: err instanceof Error ? err.message : String(err) });
+			throw new BridgeSetupError("Failed to setup file system bridge", err instanceof Error ? err : void 0);
+		}
+		const hooks = new HookableCore();
+		const optionalCapabilities = inferOptionalCapabilitiesFromOperations(bridgeOperations);
+		const baseWrapperOptions = {
+			hooks,
+			operations: bridgeOperations
+		};
+		const bridge = {
+			meta: fsBridge.meta,
+			optionalCapabilities,
+			hook: hooks.hook.bind(hooks),
+			read: createOperationWrapper("read", baseWrapperOptions),
+			exists: createOperationWrapper("exists", baseWrapperOptions),
+			listdir: createOperationWrapper("listdir", baseWrapperOptions),
+			write: createOperationWrapper("write", baseWrapperOptions),
+			mkdir: createOperationWrapper("mkdir", baseWrapperOptions),
+			rm: createOperationWrapper("rm", baseWrapperOptions)
+		};
+		if (fsBridge.symbol) bridge[fsBridge.symbol] = true;
+		return bridge;
+	};
+}
+
+//#endregion
+export { defineFileSystemBridge as t };

package/dist/errors.d.mts

@@ -0,0 +1,27 @@
+import { u as OptionalCapabilityKey } from "./types-BRcSW-lJ.mjs";
+
+//#region src/errors.d.ts
+declare abstract class BridgeBaseError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class BridgeGenericError extends BridgeBaseError {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class BridgeSetupError extends BridgeBaseError {
+  readonly originalError?: Error;
+  constructor(message: string, originalError?: Error);
+}
+declare class BridgeUnsupportedOperation extends BridgeBaseError {
+  readonly capability: OptionalCapabilityKey;
+  constructor(capability: OptionalCapabilityKey);
+}
+declare class BridgeFileNotFound extends BridgeBaseError {
+  readonly path: string;
+  constructor(path: string);
+}
+declare class BridgeEntryIsDir extends BridgeBaseError {
+  readonly path: string;
+  constructor(path: string);
+}
+//#endregion
+export { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation };

package/dist/errors.mjs

@@ -0,0 +1,48 @@
+//#region src/errors.ts
+var BridgeBaseError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "BridgeBaseError";
+	}
+};
+var BridgeGenericError = class extends BridgeBaseError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "BridgeGenericError";
+	}
+};
+var BridgeSetupError = class extends BridgeBaseError {
+	originalError;
+	constructor(message, originalError) {
+		super(message, { cause: originalError });
+		this.name = "BridgeSetupError";
+		this.originalError = originalError;
+	}
+};
+var BridgeUnsupportedOperation = class extends BridgeBaseError {
+	capability;
+	constructor(capability) {
+		super(`File system bridge does not support the '${capability}' capability.`);
+		this.name = "BridgeUnsupportedOperation";
+		this.capability = capability;
+	}
+};
+var BridgeFileNotFound = class extends BridgeBaseError {
+	path;
+	constructor(path) {
+		super(`File or directory not found: ${path}`);
+		this.name = "BridgeFileNotFound";
+		this.path = path;
+	}
+};
+var BridgeEntryIsDir = class extends BridgeBaseError {
+	path;
+	constructor(path) {
+		super(`Expected file but found directory: ${path}`);
+		this.name = "BridgeEntryIsDir";
+		this.path = path;
+	}
+};
+
+//#endregion
+export { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation };

package/dist/guards-CXuUenP_.d.mts

@@ -0,0 +1,45 @@
+import { i as FileSystemBridgeFactory, n as FileSystemBridge, s as FileSystemBridgeObject, u as OptionalCapabilityKey } from "./types-BRcSW-lJ.mjs";
+import { z } from "zod";
+
+//#region src/assertions.d.ts
+/**
+ * Asserts that a file system bridge supports the specified capability or capabilities.
+ *
+ * This function performs a runtime check to ensure the bridge has the required capabilities
+ * and acts as a type guard to narrow the bridge type to include the specified capabilities.
+ *
+ * @template {OptionalCapabilityKey} T - The capability key(s) to check for, extending OptionalCapabilityKey
+ * @param {FileSystemBridge} bridge - The file system bridge to check capabilities for
+ * @param {T | T[]} capabilityOrCapabilities - A single capability or array of capabilities to verify
+ * @throws {BridgeUnsupportedOperation} When the bridge doesn't support one or more of the specified capabilities
+ */
+declare function assertCapability<T extends OptionalCapabilityKey = never>(bridge: FileSystemBridge, capabilityOrCapabilities: T | T[]): asserts bridge is FileSystemBridge & Required<Pick<FileSystemBridge, T>>;
+//#endregion
+//#region src/define.d.ts
+declare function defineFileSystemBridge<TOptionsSchema extends z.ZodType = z.ZodNever, TState extends Record<string, unknown> = Record<string, unknown>>(fsBridge: FileSystemBridgeObject<TOptionsSchema, TState> & {
+  symbol?: symbol;
+}): FileSystemBridgeFactory<TOptionsSchema>;
+//#endregion
+//#region src/guards.d.ts
+/**
+ * Checks whether a file system bridge supports the specified capability or capabilities.
+ *
+ * Performs a runtime check and acts as a type guard to narrow the bridge type
+ * when all required capabilities are present.
+ *
+ * @template {OptionalCapabilityKey} T - The capability key(s) to check for, extending OptionalCapabilityKey
+ * @param {FileSystemBridge} bridge - The file system bridge to check capabilities for
+ * @param {T | T[]} capabilityOrCapabilities - A single capability or array of capabilities to verify
+ */
+declare function hasCapability<T extends OptionalCapabilityKey = never>(bridge: FileSystemBridge, capabilityOrCapabilities: T | T[]): bridge is FileSystemBridge & Required<Pick<FileSystemBridge, T>>;
+/**
+ * Checks whether a file system bridge is the built-in HTTP File System Bridge.
+ *
+ * Uses a symbol to identify the bridge type, making it safe against name changes.
+ *
+ * @param {FileSystemBridge} fs - The file system bridge to check
+ * @returns {boolean} True if the bridge is the built-in HTTP File System Bridge, false otherwise
+ */
+declare function isBuiltinHttpBridge(fs: FileSystemBridge): boolean;
+//#endregion
+export { assertCapability as i, isBuiltinHttpBridge as n, defineFileSystemBridge as r, hasCapability as t };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { a as FileSystemBridgeHooks, c as FileSystemBridgeOperations, i as FileSystemBridgeFactory, l as FileSystemBridgeRmOptions, n as FileSystemBridge, o as FileSystemBridgeMetadata, r as FileSystemBridgeArgs, t as FSEntry } from "./types-BRcSW-lJ.mjs";
+import { i as assertCapability, n as isBuiltinHttpBridge, r as defineFileSystemBridge, t as hasCapability } from "./guards-CXuUenP_.mjs";
+import { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation } from "./errors.mjs";
+export { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation, type FSEntry, type FileSystemBridge, type FileSystemBridgeArgs, type FileSystemBridgeFactory, type FileSystemBridgeHooks, type FileSystemBridgeMetadata, type FileSystemBridgeOperations, type FileSystemBridgeRmOptions, assertCapability, defineFileSystemBridge, hasCapability, isBuiltinHttpBridge };

package/dist/index.mjs

@@ -0,0 +1,67 @@
+import { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation } from "./errors.mjs";
+import { t as defineFileSystemBridge } from "./define-BfE46g0d.mjs";
+import { kHttpBridgeSymbol } from "./bridges/http.mjs";
+import { createDebugger } from "@ucdjs-internal/shared";
+
+//#region src/assertions.ts
+const debug$1 = createDebugger("ucdjs:fs-bridge:assertions");
+/**
+* Asserts that a file system bridge supports the specified capability or capabilities.
+*
+* This function performs a runtime check to ensure the bridge has the required capabilities
+* and acts as a type guard to narrow the bridge type to include the specified capabilities.
+*
+* @template {OptionalCapabilityKey} T - The capability key(s) to check for, extending OptionalCapabilityKey
+* @param {FileSystemBridge} bridge - The file system bridge to check capabilities for
+* @param {T | T[]} capabilityOrCapabilities - A single capability or array of capabilities to verify
+* @throws {BridgeUnsupportedOperation} When the bridge doesn't support one or more of the specified capabilities
+*/
+function assertCapability(bridge, capabilityOrCapabilities) {
+	const capabilitiesToCheck = Array.isArray(capabilityOrCapabilities) ? capabilityOrCapabilities : [capabilityOrCapabilities];
+	for (const capability of capabilitiesToCheck) if (!bridge.optionalCapabilities[capability]) {
+		debug$1?.("Bridge capability check failed", {
+			capability,
+			availableCapabilities: Object.keys(bridge.optionalCapabilities).filter((k) => bridge.optionalCapabilities[k])
+		});
+		throw new BridgeUnsupportedOperation(capability);
+	}
+}
+
+//#endregion
+//#region src/guards.ts
+const debug = createDebugger("ucdjs:fs-bridge:guards");
+/**
+* Checks whether a file system bridge supports the specified capability or capabilities.
+*
+* Performs a runtime check and acts as a type guard to narrow the bridge type
+* when all required capabilities are present.
+*
+* @template {OptionalCapabilityKey} T - The capability key(s) to check for, extending OptionalCapabilityKey
+* @param {FileSystemBridge} bridge - The file system bridge to check capabilities for
+* @param {T | T[]} capabilityOrCapabilities - A single capability or array of capabilities to verify
+*/
+function hasCapability(bridge, capabilityOrCapabilities) {
+	const capabilitiesToCheck = Array.isArray(capabilityOrCapabilities) ? capabilityOrCapabilities : [capabilityOrCapabilities];
+	for (const capability of capabilitiesToCheck) if (!bridge.optionalCapabilities[capability]) {
+		debug?.("Bridge capability check failed", {
+			capability,
+			availableCapabilities: Object.keys(bridge.optionalCapabilities).filter((k) => bridge.optionalCapabilities[k])
+		});
+		return false;
+	}
+	return true;
+}
+/**
+* Checks whether a file system bridge is the built-in HTTP File System Bridge.
+*
+* Uses a symbol to identify the bridge type, making it safe against name changes.
+*
+* @param {FileSystemBridge} fs - The file system bridge to check
+* @returns {boolean} True if the bridge is the built-in HTTP File System Bridge, false otherwise
+*/
+function isBuiltinHttpBridge(fs) {
+	return kHttpBridgeSymbol in fs && fs[kHttpBridgeSymbol] === true;
+}
+
+//#endregion
+export { BridgeBaseError, BridgeEntryIsDir, BridgeFileNotFound, BridgeGenericError, BridgeSetupError, BridgeUnsupportedOperation, assertCapability, defineFileSystemBridge, hasCapability, isBuiltinHttpBridge };

package/dist/types-BRcSW-lJ.d.mts

@@ -0,0 +1,266 @@
+import { HookableCore } from "hookable";
+import { z } from "zod";
+
+//#region src/types.d.ts
+interface FileSystemBridgeRmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, ignores errors if the path doesn't exist
+   */
+  force?: boolean;
+}
+type FSEntry = {
+  type: "file";
+  name: string;
+  path: string;
+} | {
+  type: "directory";
+  name: string;
+  path: string;
+  children: FSEntry[];
+};
+interface RequiredFileSystemBridgeOperations {
+  /**
+   * Reads the contents of a file.
+   * @param {string} path - The path to the file to read
+   * @returns {Promise<string>} A promise that resolves to the file contents as a string
+   */
+  read: (path: string) => Promise<string>;
+  /**
+   * Lists the contents of a directory.
+   * @param {string} path - The path to the directory to list
+   * @param {boolean} [recursive=false] - If true, lists files in subdirectories as well
+   * @returns {Promise<FSEntry[]>} A promise that resolves to an array of file and directory entries
+   */
+  listdir: (path: string, recursive?: boolean) => Promise<FSEntry[]>;
+  /**
+   * Checks if a file or directory exists.
+   * @param {string} path - The path to check for existence
+   * @returns {Promise<boolean>} A promise that resolves to true if the path exists, false otherwise
+   */
+  exists: (path: string) => Promise<boolean>;
+}
+interface OptionalFileSystemBridgeOperations {
+  /**
+   * Writes data to a file.
+   * @param {string} path - The path to the file to write
+   * @param {string | Uint8Array} data - The data to write to the file
+   * @param {BufferEncoding} [encoding] - Optional encoding for the data (defaults to 'utf8')
+   * @returns {Promise<void>} A promise that resolves when the write operation is complete
+   */
+  write?: (path: string, data: string | Uint8Array, encoding?: BufferEncoding) => Promise<void>;
+  /**
+   * Creates a directory.
+   * @param {string} path - The path of the directory to create
+   * @returns {Promise<void>} A promise that resolves when the directory is created
+   */
+  mkdir?: (path: string) => Promise<void>;
+  /**
+   * Removes a file or directory.
+   * @param {string} path - The path to remove
+   * @param {FileSystemBridgeRmOptions} [options] - Optional configuration for removal
+   * @returns {Promise<void>} A promise that resolves when the removal is complete
+   */
+  rm?: (path: string, options?: FileSystemBridgeRmOptions) => Promise<void>;
+}
+type FileSystemBridgeOperations = OptionalFileSystemBridgeOperations & RequiredFileSystemBridgeOperations;
+type OptionalCapabilityKey = keyof OptionalFileSystemBridgeOperations;
+type HasOptionalCapabilityMap = Record<OptionalCapabilityKey, boolean>;
+type ResolveSafePathFn = (basePath: string, inputPath: string) => string;
+type FileSystemBridgeSetupFn<TOptionsSchema extends z.ZodType, TState extends Record<string, unknown> = Record<string, unknown>> = (ctx: {
+  options: z.infer<TOptionsSchema>;
+  state: TState;
+  resolveSafePath: ResolveSafePathFn;
+}) => FileSystemBridgeOperations;
+interface FileSystemBridgeMetadata {
+  /**
+   * A unique name for the file system bridge
+   */
+  name: string;
+  /**
+   * A brief description of the file system bridge
+   */
+  description: string;
+}
+interface FileSystemBridgeObject<TOptionsSchema extends z.ZodType = z.ZodNever, TState extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Metadata about the file system bridge
+   */
+  meta: FileSystemBridgeMetadata;
+  /**
+   * Zod schema for validating bridge options
+   */
+  optionsSchema?: TOptionsSchema;
+  /**
+   * Optional state object for the file system bridge.
+   * This can be used to store any relevant state information
+   * that the bridge implementation may need.
+   * @type {Record<string, unknown>}
+   * @default {}
+   * @example
+   * ```ts
+   * import { FileSystemBridge } from "@ucdjs/fs-bridge";
+   *
+   * const fsBridge: FileSystemBridge = {
+   *    state: {
+   *     lastReadPath: "",
+   *    },
+   *    setup({ options, state }) {
+   *      return {
+   *        async read(path) {
+   *          state.lastReadPath = path;
+   *          // ... implementation
+   *        }
+   *      }
+   *    }
+   * }
+   * ```
+   */
+  state?: TState;
+  /**
+   * Setup function that receives options, and state
+   * and returns the filesystem operations implementation
+   */
+  setup: FileSystemBridgeSetupFn<TOptionsSchema, TState>;
+}
+interface FileSystemBridge extends FileSystemBridgeOperations {
+  /**
+   * The capabilities of this file system bridge.
+   */
+  optionalCapabilities: HasOptionalCapabilityMap;
+  /**
+   * Metadata about this file system bridge.
+   */
+  meta: FileSystemBridgeMetadata;
+  /**
+   * Hook system for listening to file system events.
+   */
+  hook: HookableCore<FileSystemBridgeHooks>["hook"];
+}
+type FileSystemBridgeArgs<TOptionsSchema extends z.ZodType> = [z.input<TOptionsSchema>] extends [never] ? [] : undefined extends z.input<TOptionsSchema> ? [options?: z.input<TOptionsSchema>] : [options: z.input<TOptionsSchema>];
+type FileSystemBridgeFactory<TOptionsSchema extends z.ZodType> = (...args: FileSystemBridgeArgs<TOptionsSchema>) => FileSystemBridge;
+interface FileSystemBridgeHooks {
+  "error": (payload: {
+    /**
+     * The method that triggered the error.
+     */
+    method: keyof FileSystemBridgeOperations;
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * The error that occurred.
+     */
+    error: Error;
+    /**
+     * Optional arguments passed to the method.
+     */
+    args?: unknown[];
+  }) => void;
+  "read:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  }) => void;
+  "read:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * The content being read or written.
+     */
+    content: string;
+  }) => void;
+  "write:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * The content being read or written.
+     */
+    content: string;
+    /**
+     * Optional encoding for string content.
+     */
+    encoding?: BufferEncoding;
+  }) => void;
+  "write:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  }) => void;
+  "listdir:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * Whether the operation is recursive.
+     */
+    recursive: boolean;
+  }) => void;
+  "listdir:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * Whether the operation is recursive.
+     */
+    recursive: boolean;
+    /**
+     * The list of entries returned by the operation.
+     */
+    entries: FSEntry[];
+  }) => void;
+  "exists:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  }) => void;
+  "exists:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+    /**
+     * Whether the path exists.
+     */
+    exists: boolean;
+  }) => void;
+  "mkdir:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  }) => void;
+  "mkdir:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  }) => void;
+  "rm:before": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  } & FileSystemBridgeRmOptions) => void;
+  "rm:after": (payload: {
+    /**
+     * The path involved in the operation.
+     */
+    path: string;
+  } & FileSystemBridgeRmOptions) => void;
+}
+//#endregion
+export { FileSystemBridgeHooks as a, FileSystemBridgeOperations as c, FileSystemBridgeFactory as i, FileSystemBridgeRmOptions as l, FileSystemBridge as n, FileSystemBridgeMetadata as o, FileSystemBridgeArgs as r, FileSystemBridgeObject as s, FSEntry as t, OptionalCapabilityKey as u };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@ucdjs/fs-bridge",
+  "version": "0.1.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/fs-bridge"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "imports": {
+    "#internal:bridge/node": "./src/bridges/node.ts",
+    "#internal:bridge/http": "./src/bridges/http.ts"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./bridges/http": "./dist/bridges/http.mjs",
+    "./bridges/node": "./dist/bridges/node.mjs",
+    "./errors": "./dist/errors.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@luxass/utils": "2.7.3",
+    "defu": "6.1.4",
+    "hookable": "6.0.1",
+    "pathe": "2.0.3",
+    "zod": "4.3.6",
+    "@ucdjs-internal/shared": "0.1.1-beta.1",
+    "@ucdjs/env": "0.1.1-beta.1",
+    "@ucdjs/path-utils": "0.1.1-beta.1",
+    "@ucdjs/schemas": "0.1.1-beta.1"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "@luxass/msw-utils": "0.6.0",
+    "eslint": "10.0.0",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest-testdirs": "4.4.2",
+    "@ucdjs-internal/shared": "0.1.1-beta.1",
+    "@ucdjs-tooling/tsconfig": "1.0.0",
+    "@ucdjs-tooling/tsdown-config": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "playground:node": "tsx --tsconfig=./tsconfig.json ./playgrounds/node-playground.ts",
+    "playground:http": "tsx --tsconfig=./tsconfig.json ./playgrounds/http-playground.ts"
+  }
+}