@aigne/afs-testing 1.11.0-beta.7

package/dist/index.cjs

@@ -0,0 +1,2064 @@
+let bun_test = require("bun:test");
+let _aigne_afs = require("@aigne/afs");
+let ufo = require("ufo");
+
+//#region src/assertions.ts
+/**
+* Validate that a result conforms to AFSListResult structure.
+*/
+function validateListResult(result) {
+	(0, bun_test.expect)(result).toBeDefined();
+	(0, bun_test.expect)(result).toHaveProperty("data");
+	(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+	for (const entry of result.data) validateEntry(entry);
+	if (result.total !== void 0) (0, bun_test.expect)(typeof result.total).toBe("number");
+}
+/**
+* Validate that an object conforms to AFSEntry structure.
+*/
+function validateEntry(entry) {
+	(0, bun_test.expect)(entry).toBeDefined();
+	(0, bun_test.expect)(entry).toHaveProperty("id");
+	(0, bun_test.expect)(entry).toHaveProperty("path");
+	(0, bun_test.expect)(typeof entry.id).toBe("string");
+	(0, bun_test.expect)(typeof entry.path).toBe("string");
+	const e = entry;
+	if (e.content !== void 0) (0, bun_test.expect)(typeof e.content === "string" || Buffer.isBuffer(e.content) || typeof e.content === "object").toBe(true);
+	if (e.meta !== void 0 && e.meta !== null) (0, bun_test.expect)(typeof e.meta).toBe("object");
+	if (e.createdAt !== void 0) (0, bun_test.expect)(e.createdAt instanceof Date).toBe(true);
+	if (e.updatedAt !== void 0) (0, bun_test.expect)(e.updatedAt instanceof Date).toBe(true);
+}
+/**
+* Validate that a result conforms to AFSReadResult structure.
+*/
+function validateReadResult(result) {
+	(0, bun_test.expect)(result).toBeDefined();
+	const r = result;
+	if (r.data !== void 0) validateEntry(r.data);
+	if (r.message !== void 0) (0, bun_test.expect)(typeof r.message).toBe("string");
+}
+/**
+* Validate that a result conforms to AFSSearchResult structure.
+*/
+function validateSearchResult(result) {
+	(0, bun_test.expect)(result).toBeDefined();
+	(0, bun_test.expect)(result).toHaveProperty("data");
+	(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+	for (const entry of result.data) validateEntry(entry);
+}
+/**
+* Validate that a result conforms to AFSStatResult structure.
+*/
+function validateStatResult(result) {
+	(0, bun_test.expect)(result).toBeDefined();
+	const r = result;
+	if (r.data !== void 0) {
+		(0, bun_test.expect)(r.data).toHaveProperty("path");
+		(0, bun_test.expect)(typeof r.data.path).toBe("string");
+		if (r.data.meta?.size !== void 0) (0, bun_test.expect)(typeof r.data.meta.size).toBe("number");
+		if (r.data.meta?.childrenCount !== void 0) (0, bun_test.expect)(typeof r.data.meta.childrenCount).toBe("number");
+	}
+}
+
+//#endregion
+//#region src/suites/access-mode.ts
+/**
+* Run AccessMode test suite.
+* Tests that readonly providers reject write operations.
+*/
+function runAccessModeTests(getProvider, _config) {
+	(0, bun_test.describe)("access-mode", () => {
+		(0, bun_test.test)("readonly: write should throw AFSReadonlyError", async () => {
+			const provider = getProvider();
+			if (provider.accessMode !== "readonly" || !provider.write) return;
+			try {
+				await provider.write("/test-readonly.txt", { content: "test" });
+				(0, bun_test.expect)(true).toBe(false);
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSReadonlyError);
+				(0, bun_test.expect)(error.code).toBe("AFS_READONLY");
+			}
+		});
+		(0, bun_test.test)("readonly: delete should throw AFSReadonlyError", async () => {
+			const provider = getProvider();
+			if (provider.accessMode !== "readonly" || !provider.delete) return;
+			try {
+				await provider.delete("/test-readonly.txt");
+				(0, bun_test.expect)(true).toBe(false);
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSReadonlyError);
+				(0, bun_test.expect)(error.code).toBe("AFS_READONLY");
+			}
+		});
+		(0, bun_test.test)("readonly: exec should throw AFSReadonlyError", async () => {
+			const provider = getProvider();
+			if (provider.accessMode !== "readonly" || !provider.exec) return;
+			try {
+				await provider.exec("/test-action", {}, {});
+				(0, bun_test.expect)(true).toBe(false);
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSReadonlyError);
+				(0, bun_test.expect)(error.code).toBe("AFS_READONLY");
+			}
+		});
+		(0, bun_test.test)("readonly: rename should throw AFSReadonlyError", async () => {
+			const provider = getProvider();
+			if (provider.accessMode !== "readonly" || !provider.rename) return;
+			try {
+				await provider.rename("/old.txt", "/new.txt");
+				(0, bun_test.expect)(true).toBe(false);
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSReadonlyError);
+				(0, bun_test.expect)(error.code).toBe("AFS_READONLY");
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/actions.ts
+/**
+* Check if expected output is a validator function.
+*/
+function isValidator$2(expected) {
+	return typeof expected === "function";
+}
+/**
+* Check if expected output is a contains matcher.
+*/
+function isContainsMatcher$1(expected) {
+	return typeof expected === "object" && expected !== null && "contains" in expected;
+}
+/**
+* Check if expected output is a success-only matcher.
+*/
+function isSuccessMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "success" in expected && !("data" in expected) && !("contains" in expected);
+}
+/**
+* Check if expected output is a data matcher.
+*/
+function isDataMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "data" in expected;
+}
+/**
+* Deep check if target contains all keys/values from subset.
+*/
+function deepContains$1(target, subset) {
+	if (subset === null || subset === void 0) return target === subset;
+	if (typeof subset !== "object") return target === subset;
+	if (Array.isArray(subset)) {
+		if (!Array.isArray(target)) return false;
+		return subset.every((item, index) => deepContains$1(target[index], item));
+	}
+	if (typeof target !== "object" || target === null) return false;
+	const targetObj = target;
+	const subsetObj = subset;
+	for (const key of Object.keys(subsetObj)) {
+		if (!(key in targetObj)) return false;
+		if (!deepContains$1(targetObj[key], subsetObj[key])) return false;
+	}
+	return true;
+}
+/**
+* Run action test suite.
+* Tests input/output behavior of actions on nodes.
+*
+* Actions are executed via exec() on .actions paths and return
+* AFSActionResult with success/data/error fields.
+*/
+function runActionTests(getProvider, cases, _config) {
+	(0, bun_test.describe)("actions", () => {
+		for (const testCase of cases) (0, bun_test.test)(`action ${testCase.path}: ${testCase.name}`, async () => {
+			const provider = getProvider();
+			if (!provider.exec) return;
+			if (testCase.shouldThrow) {
+				let threw = false;
+				let errorMessage = "";
+				try {
+					await provider.exec(testCase.path, testCase.args, {});
+				} catch (error) {
+					threw = true;
+					errorMessage = error instanceof Error ? error.message : String(error);
+				}
+				(0, bun_test.expect)(threw).toBe(true);
+				if (typeof testCase.shouldThrow === "string") (0, bun_test.expect)(errorMessage).toContain(testCase.shouldThrow);
+				else if (testCase.shouldThrow instanceof RegExp) (0, bun_test.expect)(errorMessage).toMatch(testCase.shouldThrow);
+			} else {
+				const result = await provider.exec(testCase.path, testCase.args, {});
+				(0, bun_test.expect)(result).toBeDefined();
+				if (testCase.expected !== void 0) {
+					if (isValidator$2(testCase.expected)) testCase.expected(result, bun_test.expect);
+					else if (isSuccessMatcher(testCase.expected)) (0, bun_test.expect)(result.success).toBe(testCase.expected.success);
+					else if (isDataMatcher(testCase.expected)) {
+						(0, bun_test.expect)(result.success).toBe(true);
+						(0, bun_test.expect)(result.data).toEqual(testCase.expected.data);
+					} else if (isContainsMatcher$1(testCase.expected)) {
+						(0, bun_test.expect)(result.success).toBe(true);
+						(0, bun_test.expect)(deepContains$1(result.data, testCase.expected.contains)).toBe(true);
+					}
+				}
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/capabilities-operations.ts
+const OPERATION_KEYS = [
+	"read",
+	"list",
+	"write",
+	"delete",
+	"search",
+	"exec",
+	"stat",
+	"explain"
+];
+/**
+* Run capabilities operations validation suite.
+* Verifies that the provider's /.meta/.capabilities returns
+* a valid manifest with a complete operations declaration.
+*/
+function runCapabilitiesOperationsTests(getProvider, _structure, _config) {
+	(0, bun_test.describe)("capabilities-operations", () => {
+		(0, bun_test.test)("provider should return capabilities manifest via /.meta/.capabilities", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read("/.meta/.capabilities");
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.content).toBeDefined();
+		});
+		(0, bun_test.test)("capabilities manifest should have operations field", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const manifest = (await provider.read("/.meta/.capabilities")).data?.content;
+			(0, bun_test.expect)(manifest).toBeDefined();
+			(0, bun_test.expect)(manifest.operations).toBeDefined();
+			(0, bun_test.expect)(typeof manifest.operations).toBe("object");
+		});
+		(0, bun_test.test)("operations should declare all 8 operations as booleans", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const operations = ((await provider.read("/.meta/.capabilities")).data?.content)?.operations;
+			if (!operations) return;
+			for (const key of OPERATION_KEYS) {
+				(0, bun_test.expect)(operations[key]).toBeDefined();
+				(0, bun_test.expect)(typeof operations[key]).toBe("boolean");
+			}
+		});
+		(0, bun_test.test)("operations should not have missing operation declarations", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const operations = ((await provider.read("/.meta/.capabilities")).data?.content)?.operations;
+			if (!operations) return;
+			(0, bun_test.expect)(OPERATION_KEYS.filter((key) => !(key in operations))).toEqual([]);
+		});
+		(0, bun_test.test)("extra fields in operations should be ignored (forward-compatible)", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const operations = ((await provider.read("/.meta/.capabilities")).data?.content)?.operations;
+			if (!operations) return;
+			for (const key of OPERATION_KEYS) (0, bun_test.expect)(key in operations).toBe(true);
+		});
+	});
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* Check if a tree node represents a directory (has children).
+*/
+function isDirectory(node) {
+	return node.children !== void 0 && node.children.length > 0;
+}
+/**
+* Check if a tree node represents a file (has content or is a leaf without children).
+*/
+function isFile(node) {
+	return node.content !== void 0 || !isDirectory(node);
+}
+/**
+* Compute the full path for a node given its parent path.
+*/
+function computePath(parentPath, nodeName) {
+	if (parentPath === "/" && nodeName === "") return "/";
+	return (0, ufo.joinURL)(parentPath, nodeName);
+}
+/**
+* Flatten a tree into an array of nodes with their paths.
+* Traverses in BFS order.
+*/
+function flattenTree(root) {
+	const result = [];
+	const queue = [{
+		node: root,
+		path: "/",
+		depth: 0
+	}];
+	while (queue.length > 0) {
+		const { node, path, depth } = queue.shift();
+		result.push({
+			path,
+			node,
+			depth
+		});
+		if (node.children) for (const child of node.children) {
+			const childPath = computePath(path, child.name);
+			queue.push({
+				node: child,
+				path: childPath,
+				depth: depth + 1
+			});
+		}
+	}
+	return result;
+}
+/**
+* Find a node in the tree by path.
+*/
+function findNode(root, targetPath) {
+	if (targetPath === "/") return root;
+	const segments = targetPath.split("/").filter(Boolean);
+	let current = root;
+	for (const segment of segments) {
+		if (!current?.children) return void 0;
+		current = current.children.find((c) => c.name === segment);
+		if (!current) return void 0;
+	}
+	return current;
+}
+/**
+* Find the first file node in the tree (excluding root).
+*/
+function findFirstFile(root) {
+	return flattenTree(root).find((n) => n.path !== "/" && isFile(n.node) && !isDirectory(n.node));
+}
+/**
+* Find the first directory node in the tree (excluding root).
+*/
+function findFirstDirectory(root) {
+	return flattenTree(root).find((n) => n.path !== "/" && isDirectory(n.node));
+}
+/**
+* Find a nested directory (depth >= 2) in the tree.
+*/
+function findNestedDirectory(root) {
+	return flattenTree(root).find((n) => isDirectory(n.node) && n.depth >= 2);
+}
+/**
+* Get all file nodes from the tree.
+*/
+function getAllFiles(root) {
+	return flattenTree(root).filter((n) => isFile(n.node) && !isDirectory(n.node));
+}
+/**
+* Get all directory nodes from the tree.
+*/
+function getAllDirectories(root) {
+	return flattenTree(root).filter((n) => isDirectory(n.node));
+}
+
+//#endregion
+//#region src/suites/deep-list.ts
+/**
+* Run deep list traversal test suite.
+* Tests BFS depth expansion and pattern matching:
+* - maxDepth > 1 traversal
+* - Pattern filtering with glob
+* - Total count semantics
+*
+* IMPORTANT: list() only returns children, never includes the requested path itself.
+* - maxDepth=0: returns [] (no children at depth 0)
+* - maxDepth=1 or undefined: returns direct children only
+* - maxDepth=N (N>1): returns children + all descendants up to N-1 levels deep
+*/
+function runDeepListTests(getProvider, structure, config) {
+	const root = structure.root;
+	const allNodes = flattenTree(root);
+	const nestedDir = findNestedDirectory(root);
+	allNodes.length;
+	allNodes.filter((n) => isDirectory(n.node));
+	const maxDepth = Math.max(...allNodes.map((n) => n.depth));
+	const testOpts = config.timeout ? { timeout: config.timeout } : void 0;
+	(0, bun_test.describe)("deep-list", () => {
+		(0, bun_test.describe)("depth traversal", () => {
+			(0, bun_test.test)("maxDepth=0: should return empty array", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 0 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.length).toBe(0);
+			}, testOpts);
+			(0, bun_test.test)("maxDepth=1: should return only direct children (not self)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				validateListResult(result);
+				const rootChildCount = root.children?.length ?? 0;
+				(0, bun_test.expect)(result.data.length).toBe(rootChildCount);
+				(0, bun_test.expect)(result.data.some((e) => e.path === "/")).toBe(false);
+				for (const entry of result.data) {
+					const depth = entry.path.split("/").filter(Boolean).length;
+					(0, bun_test.expect)(depth).toBe(1);
+				}
+			}, testOpts);
+			if (maxDepth >= 2) {
+				(0, bun_test.test)("maxDepth=2: should include children and grandchildren (not self)", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const depth1Result = await provider.list("/", { maxDepth: 1 });
+					const depth2Result = await provider.list("/", { maxDepth: 2 });
+					validateListResult(depth2Result);
+					(0, bun_test.expect)(depth2Result.data.length).toBeGreaterThanOrEqual(depth1Result.data.length);
+					if (nestedDir) (0, bun_test.expect)(depth2Result.data.length).toBeGreaterThan(depth1Result.data.length);
+					(0, bun_test.expect)(depth2Result.data.some((e) => e.path === "/")).toBe(false);
+					for (const entry of depth2Result.data) {
+						const depth = entry.path.split("/").filter(Boolean).length;
+						(0, bun_test.expect)(depth).toBeGreaterThanOrEqual(1);
+						(0, bun_test.expect)(depth).toBeLessThanOrEqual(2);
+					}
+				}, testOpts);
+				(0, bun_test.test)("maxDepth=3: should traverse three levels (not including self)", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const depth2Result = await provider.list("/", { maxDepth: 2 });
+					const depth3Result = await provider.list("/", { maxDepth: 3 });
+					validateListResult(depth3Result);
+					(0, bun_test.expect)(depth3Result.data.length).toBeGreaterThanOrEqual(depth2Result.data.length);
+					(0, bun_test.expect)(depth3Result.data.some((e) => e.path === "/")).toBe(false);
+				}, testOpts);
+			}
+			(0, bun_test.test)("large maxDepth: should handle gracefully (not include self)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 100 });
+				validateListResult(result);
+				const rootChildCount = root.children?.length ?? 0;
+				if (rootChildCount > 0) (0, bun_test.expect)(result.data.length).toBeGreaterThanOrEqual(rootChildCount);
+				else (0, bun_test.expect)(result.data.length).toBe(0);
+				(0, bun_test.expect)(result.data.some((e) => e.path === "/")).toBe(false);
+			}, testOpts);
+			if (nestedDir) (0, bun_test.test)("depth from subdirectory: should traverse relative to path", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const parentPath = nestedDir.path.split("/").slice(0, -1).join("/") || "/";
+				const result = await provider.list(parentPath, { maxDepth: 2 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.some((e) => e.path === nestedDir.path)).toBe(true);
+			}, testOpts);
+		});
+		(0, bun_test.describe)("pattern filtering", () => {
+			(0, bun_test.test)("pattern *: should match all at current level", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const rootChildCount = root.children?.length ?? 0;
+				try {
+					const result = await provider.list("/", {
+						pattern: "*",
+						maxDepth: 1
+					});
+					validateListResult(result);
+					if (rootChildCount > 0) (0, bun_test.expect)(result.data.length).toBeGreaterThanOrEqual(1);
+					(0, bun_test.expect)(result.data.some((e) => e.path === "/")).toBe(false);
+				} catch {}
+			}, testOpts);
+			(0, bun_test.test)("pattern *.md: should filter by extension", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				allNodes.filter((n) => n.path.endsWith(".md"));
+				try {
+					const result = await provider.list("/", {
+						pattern: "*.md",
+						maxDepth: 10
+					});
+					validateListResult(result);
+					for (const entry of result.data) {
+						(0, bun_test.expect)(entry.path.endsWith(".md") || entry.meta?.childrenCount !== void 0).toBe(true);
+						(0, bun_test.expect)(entry.path).not.toBe("/");
+					}
+				} catch {}
+			}, testOpts);
+			(0, bun_test.test)("pattern with no matches: should return empty or just directories", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				try {
+					validateListResult(await provider.list("/", {
+						pattern: "*.nonexistentextension12345",
+						maxDepth: 10
+					}));
+				} catch {}
+			}, testOpts);
+		});
+		(0, bun_test.describe)("limit and total", () => {
+			(0, bun_test.test)("limit with deep traversal: should respect limit", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", {
+					maxDepth: 10,
+					limit: 3
+				});
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.length).toBeLessThanOrEqual(3);
+			}, testOpts);
+			(0, bun_test.test)("total: should indicate complete count if available", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				validateListResult(result);
+				if (result.total !== void 0) (0, bun_test.expect)(result.total).toBeGreaterThanOrEqual(result.data.length);
+			}, testOpts);
+			(0, bun_test.test)("small limit: should still work", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { limit: 1 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.length).toBeLessThanOrEqual(1);
+			}, testOpts);
+		});
+		(0, bun_test.describe)("BFS order", () => {
+			(0, bun_test.test)("entries should be in breadth-first order (no root included)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 10 });
+				validateListResult(result);
+				for (const entry of result.data) {
+					const depth = entry.path.split("/").filter(Boolean).length;
+					(0, bun_test.expect)(depth).toBeGreaterThanOrEqual(1);
+					(0, bun_test.expect)(entry.path).not.toBe("/");
+				}
+			}, testOpts);
+		});
+		(0, bun_test.describe)("default maxDepth behavior", () => {
+			(0, bun_test.test)("maxDepth=undefined defaults to 1 (direct children only)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const undefinedResult = await provider.list("/");
+				const depth1Result = await provider.list("/", { maxDepth: 1 });
+				validateListResult(undefinedResult);
+				(0, bun_test.expect)(undefinedResult.data.length).toBe(depth1Result.data.length);
+				(0, bun_test.expect)(undefinedResult.data.some((e) => e.path === "/")).toBe(false);
+			}, testOpts);
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/delete-cases.ts
+/**
+* Run delete case tests.
+* Tests delete operations based on fixture-defined cases.
+* These tests run LAST because they modify the data structure.
+*/
+function runDeleteCaseTests(getProvider, cases, _config) {
+	(0, bun_test.describe)("delete-cases", () => {
+		for (const testCase of cases) (0, bun_test.test)(`delete ${testCase.path}: ${testCase.name}`, async () => {
+			const provider = getProvider();
+			if (!provider.delete) return;
+			if (testCase.shouldThrow) {
+				let threw = false;
+				let errorMessage = "";
+				try {
+					await provider.delete(testCase.path, {});
+				} catch (error) {
+					threw = true;
+					errorMessage = error instanceof Error ? error.message : String(error);
+				}
+				(0, bun_test.expect)(threw).toBe(true);
+				if (typeof testCase.shouldThrow === "string") (0, bun_test.expect)(errorMessage).toContain(testCase.shouldThrow);
+				else if (testCase.shouldThrow instanceof RegExp) (0, bun_test.expect)(errorMessage).toMatch(testCase.shouldThrow);
+			} else {
+				(0, bun_test.expect)(await provider.delete(testCase.path, {})).toBeDefined();
+				if (testCase.verifyDeleted !== false && provider.list) {
+					let deleted = false;
+					try {
+						const listResult = await provider.list(testCase.path, {});
+						deleted = !listResult.data || listResult.data.length === 0;
+					} catch {
+						deleted = true;
+					}
+					(0, bun_test.expect)(deleted).toBe(true);
+				}
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/entry-fields.ts
+/**
+* Run entry fields validation test suite.
+* Tests that entries have required fields with correct types.
+*/
+function runEntryFieldsTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const fileNode = findFirstFile(root);
+	const dirNode = findFirstDirectory(root);
+	(0, bun_test.describe)("entry-fields", () => {
+		(0, bun_test.describe)("required fields", () => {
+			(0, bun_test.test)("read: entry should have id field", async () => {
+				const provider = getProvider();
+				if (!provider.read || !fileNode) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.id).toBeDefined();
+				(0, bun_test.expect)(typeof result.data?.id).toBe("string");
+			});
+			(0, bun_test.test)("read: entry should have path field", async () => {
+				const provider = getProvider();
+				if (!provider.read || !fileNode) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBeDefined();
+				(0, bun_test.expect)(typeof result.data?.path).toBe("string");
+				(0, bun_test.expect)(result.data?.path.startsWith("/")).toBe(true);
+			});
+			(0, bun_test.test)("list: entries should have id and path", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				(0, bun_test.expect)(result.data).toBeDefined();
+				for (const entry of result.data) {
+					(0, bun_test.expect)(entry.id).toBeDefined();
+					(0, bun_test.expect)(typeof entry.id).toBe("string");
+					(0, bun_test.expect)(entry.path).toBeDefined();
+					(0, bun_test.expect)(typeof entry.path).toBe("string");
+				}
+			});
+		});
+		(0, bun_test.describe)("metadata fields", () => {
+			if (dirNode) (0, bun_test.test)("directory: should have childrenCount in metadata", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(dirNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				if (result.data?.meta?.childrenCount !== void 0) {
+					(0, bun_test.expect)(typeof result.data.meta.childrenCount).toBe("number");
+					(0, bun_test.expect)(result.data.meta.childrenCount).toBeGreaterThanOrEqual(0);
+				}
+			});
+			(0, bun_test.test)("meta read: should return metadata object", async () => {
+				const provider = getProvider();
+				if (!provider.read || !fileNode) return;
+				const metaPath = (0, ufo.joinURL)(fileNode.path, ".meta");
+				const result = await provider.read(metaPath);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.meta).toBeDefined();
+				(0, bun_test.expect)(typeof result.data?.meta).toBe("object");
+			});
+		});
+		(0, bun_test.describe)("optional fields", () => {
+			if (fileNode) (0, bun_test.test)("file: content field should be present", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)("content" in (result.data || {})).toBe(true);
+			});
+			(0, bun_test.test)("entry: dates should be Date objects if present", async () => {
+				const provider = getProvider();
+				if (!provider.read || !fileNode) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				if (result.data?.createdAt !== void 0) (0, bun_test.expect)(result.data.createdAt).toBeInstanceOf(Date);
+				if (result.data?.updatedAt !== void 0) (0, bun_test.expect)(result.data.updatedAt).toBeInstanceOf(Date);
+			});
+		});
+		(0, bun_test.describe)("stat fields", () => {
+			(0, bun_test.test)("stat: should return path field", async () => {
+				const provider = getProvider();
+				if (!provider.stat || !fileNode) return;
+				const result = await provider.stat(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(fileNode.path);
+			});
+			if (dirNode) (0, bun_test.test)("stat directory: childrenCount should be number if present", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat(dirNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				if (result.data?.meta?.childrenCount !== void 0) (0, bun_test.expect)(typeof result.data.meta.childrenCount).toBe("number");
+			});
+			if (fileNode) (0, bun_test.test)("stat file: size should be number if present", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				if (result.data?.meta?.size !== void 0) {
+					(0, bun_test.expect)(typeof result.data.meta.size).toBe("number");
+					(0, bun_test.expect)(result.data.meta.size).toBeGreaterThanOrEqual(0);
+				}
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/error-types.ts
+/**
+* Run error types test suite.
+* Tests that errors are thrown with correct types and properties.
+*/
+function runErrorTypesTests(getProvider, _config) {
+	(0, bun_test.describe)("error-types", () => {
+		(0, bun_test.describe)("AFSNotFoundError", () => {
+			(0, bun_test.test)("list not-found: should throw AFSNotFoundError with path", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const nonExistentPath = "/non-existent-path-for-error-test-12345";
+				try {
+					await provider.list(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+					(0, bun_test.expect)(error.path).toBe(nonExistentPath);
+					(0, bun_test.expect)(error.code).toBe("AFS_NOT_FOUND");
+					(0, bun_test.expect)(error.name).toBe("AFSNotFoundError");
+				}
+			});
+			(0, bun_test.test)("read not-found: should throw AFSNotFoundError with path", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const nonExistentPath = "/non-existent-file-for-error-test-12345.txt";
+				try {
+					await provider.read(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+					(0, bun_test.expect)(error.path).toBe(nonExistentPath);
+					(0, bun_test.expect)(error.code).toBe("AFS_NOT_FOUND");
+				}
+			});
+			(0, bun_test.test)("stat not-found: should throw AFSNotFoundError with path", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const nonExistentPath = "/non-existent-stat-path-12345";
+				try {
+					await provider.stat(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+					(0, bun_test.expect)(error.path).toBe(nonExistentPath);
+					(0, bun_test.expect)(error.code).toBe("AFS_NOT_FOUND");
+				}
+			});
+			(0, bun_test.test)("meta not-found: should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const nonExistentPath = "/non-existent-meta-path-12345/.meta";
+				try {
+					await provider.read(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+					(0, bun_test.expect)(error.code).toBe("AFS_NOT_FOUND");
+				}
+			});
+		});
+		(0, bun_test.describe)("error message", () => {
+			(0, bun_test.test)("not-found error should have descriptive message", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const nonExistentPath = "/test-error-message-12345.txt";
+				try {
+					await provider.read(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(Error);
+					(0, bun_test.expect)(error.message).toBeDefined();
+					(0, bun_test.expect)(error.message.length).toBeGreaterThan(0);
+				}
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/execute.ts
+/**
+* Check if expected output is a validator function.
+*/
+function isValidator$1(expected) {
+	return typeof expected === "function";
+}
+/**
+* Check if expected output is a contains matcher.
+*/
+function isContainsMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "contains" in expected;
+}
+/**
+* Deep check if target contains all keys/values from subset.
+*/
+function deepContains(target, subset) {
+	if (subset === null || subset === void 0) return target === subset;
+	if (typeof subset !== "object") return target === subset;
+	if (Array.isArray(subset)) {
+		if (!Array.isArray(target)) return false;
+		return subset.every((item, index) => deepContains(target[index], item));
+	}
+	if (typeof target !== "object" || target === null) return false;
+	const targetObj = target;
+	const subsetObj = subset;
+	for (const key of Object.keys(subsetObj)) {
+		if (!(key in targetObj)) return false;
+		if (!deepContains(targetObj[key], subsetObj[key])) return false;
+	}
+	return true;
+}
+/**
+* Run execute test suite.
+* Tests input/output behavior of executable nodes.
+*/
+function runExecuteTests(getProvider, cases, _config) {
+	(0, bun_test.describe)("execute", () => {
+		for (const testCase of cases) (0, bun_test.test)(`exec ${testCase.path}: ${testCase.name}`, async () => {
+			const provider = getProvider();
+			if (!provider.exec) return;
+			if (testCase.shouldThrow) {
+				let threw = false;
+				let errorMessage = "";
+				try {
+					await provider.exec(testCase.path, testCase.args, {});
+				} catch (error) {
+					threw = true;
+					errorMessage = error instanceof Error ? error.message : String(error);
+				}
+				(0, bun_test.expect)(threw).toBe(true);
+				if (typeof testCase.shouldThrow === "string") (0, bun_test.expect)(errorMessage).toContain(testCase.shouldThrow);
+				else if (testCase.shouldThrow instanceof RegExp) (0, bun_test.expect)(errorMessage).toMatch(testCase.shouldThrow);
+			} else {
+				const result = await provider.exec(testCase.path, testCase.args, {});
+				(0, bun_test.expect)(result).toBeDefined();
+				(0, bun_test.expect)(result.data).toBeDefined();
+				if (testCase.expected !== void 0) if (isValidator$1(testCase.expected)) testCase.expected(result.data ?? {}, bun_test.expect);
+				else if (isContainsMatcher(testCase.expected)) (0, bun_test.expect)(deepContains(result.data ?? {}, testCase.expected.contains)).toBe(true);
+				else (0, bun_test.expect)(result.data).toEqual(testCase.expected);
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/explain.ts
+/**
+* Run explain operation test suite.
+* Tests the explain() method for getting human-readable descriptions.
+*/
+function runExplainTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const fileNode = findFirstFile(root);
+	(0, bun_test.describe)("explain", () => {
+		(0, bun_test.test)("explain: method should exist or be undefined", () => {
+			const provider = getProvider();
+			(0, bun_test.expect)(provider.explain === void 0 || typeof provider.explain === "function").toBe(true);
+		});
+		(0, bun_test.test)("explain root: should return explanation if supported", async () => {
+			const provider = getProvider();
+			if (!provider.explain) return;
+			try {
+				const result = await provider.explain("/");
+				(0, bun_test.expect)(result).toBeDefined();
+				if (result.content !== void 0) (0, bun_test.expect)(typeof result.content).toBe("string");
+				if (result.format !== void 0) {
+					(0, bun_test.expect)(typeof result.format).toBe("string");
+					(0, bun_test.expect)(["markdown", "text"]).toContain(result.format);
+				}
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(Error);
+				(0, bun_test.expect)(error.message).toContain("explain");
+			}
+		});
+		if (fileNode) (0, bun_test.test)("explain file: should return explanation for file path", async () => {
+			const provider = getProvider();
+			if (!provider.explain) return;
+			try {
+				const result = await provider.explain(fileNode.path);
+				(0, bun_test.expect)(result).toBeDefined();
+				(0, bun_test.expect)(result.format).toBeDefined();
+				(0, bun_test.expect)(result.content).toBeDefined();
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(Error);
+			}
+		});
+		(0, bun_test.test)("explain: no handler should throw descriptive error", async () => {
+			const provider = getProvider();
+			if (!provider.explain) return;
+			const testPath = "/test-explain-no-handler-12345";
+			try {
+				await provider.explain(testPath);
+			} catch (error) {
+				(0, bun_test.expect)(error).toBeInstanceOf(Error);
+				const message = error.message;
+				(0, bun_test.expect)(message.includes("explain") || message.includes("handler") || message.includes(testPath)).toBe(true);
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/explain-existence.ts
+/**
+* Run explain existence validation suite.
+* Verifies that the provider implements an explain handler
+* and that it returns non-empty content for the root path.
+*/
+function runExplainExistenceTests(getProvider, _structure, _config) {
+	(0, bun_test.describe)("explain-existence", () => {
+		(0, bun_test.test)("provider should implement explain handler", () => {
+			const provider = getProvider();
+			(0, bun_test.expect)(provider.explain).toBeDefined();
+			(0, bun_test.expect)(typeof provider.explain).toBe("function");
+		});
+		(0, bun_test.test)("explain root should return non-empty result", async () => {
+			const provider = getProvider();
+			if (!provider.explain) return;
+			const result = await provider.explain("/");
+			(0, bun_test.expect)(result).toBeDefined();
+			(0, bun_test.expect)(result.content).toBeDefined();
+			(0, bun_test.expect)(typeof result.content).toBe("string");
+			(0, bun_test.expect)(result.content.length).toBeGreaterThan(0);
+		});
+		(0, bun_test.test)("explain result should have format field", async () => {
+			const provider = getProvider();
+			if (!provider.explain) return;
+			const result = await provider.explain("/");
+			(0, bun_test.expect)(result.format).toBeDefined();
+			(0, bun_test.expect)(typeof result.format).toBe("string");
+			(0, bun_test.expect)(["markdown", "text"]).toContain(result.format);
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/list-options.ts
+/**
+* Run advanced list options test suite.
+* Tests list operations with various options.
+*/
+function runListOptionsTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const nestedDir = findNestedDirectory(root);
+	(0, bun_test.describe)("list-options", () => {
+		(0, bun_test.describe)("maxDepth", () => {
+			(0, bun_test.test)("maxDepth=2: should traverse two levels deep", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 2 });
+				validateListResult(result);
+				const depth1Result = await provider.list("/", { maxDepth: 1 });
+				if (nestedDir) (0, bun_test.expect)(result.data.length).toBeGreaterThanOrEqual(depth1Result.data.length);
+			});
+			(0, bun_test.test)("maxDepth=0: should return empty array", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 0 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.length).toBe(0);
+			});
+			if (nestedDir) (0, bun_test.test)("maxDepth on subdirectory: should respect depth from that point", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list(nestedDir.path, { maxDepth: 1 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.some((e) => e.path === nestedDir.path)).toBe(false);
+			});
+		});
+		(0, bun_test.describe)("limit", () => {
+			(0, bun_test.test)("limit=1: should return at most 1 entry", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { limit: 1 });
+				validateListResult(result);
+				(0, bun_test.expect)(result.data.length).toBeLessThanOrEqual(1);
+			});
+			(0, bun_test.test)("limit larger than total: should return all entries", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				validateListResult(await provider.list("/", { limit: 1e4 }));
+			});
+		});
+		(0, bun_test.describe)("offset", () => {
+			(0, bun_test.test)("offset=0: should return from beginning", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				validateListResult(await provider.list("/", { offset: 0 }));
+			});
+			(0, bun_test.test)("offset with limit: should be accepted without error", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				validateListResult(await provider.list("/", {
+					limit: 2,
+					offset: 1
+				}));
+			});
+		});
+		(0, bun_test.describe)("pattern", () => {
+			(0, bun_test.test)("pattern matching: should filter by glob pattern", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				try {
+					validateListResult(await provider.list("/", {
+						pattern: "*",
+						maxDepth: 1
+					}));
+				} catch {}
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/meta.ts
+/**
+* Run MetaOperations test suite.
+* Tests the .meta path suffix for reading and writing metadata.
+*/
+function runMetaTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const allNodes = flattenTree(root);
+	const rootHasMeta = root.meta !== void 0;
+	const fileWithMeta = allNodes.find((n) => n.path !== "/" && !isDirectory(n.node) && n.node.meta !== void 0);
+	const subdirFileWithMeta = allNodes.find((n) => n.depth >= 2 && !isDirectory(n.node) && n.node.meta !== void 0);
+	const dirWithMeta = allNodes.find((n) => n.path !== "/" && isDirectory(n.node) && n.node.meta !== void 0);
+	const dirNode = findFirstDirectory(root);
+	const fileNode = findFirstFile(root);
+	const subdirFileNode = allNodes.find((n) => n.depth >= 2 && n.node.content !== void 0 && !isDirectory(n.node));
+	(0, bun_test.describe)("meta-read-existing", () => {
+		if (rootHasMeta) (0, bun_test.test)("meta-read-root-existing: should read pre-existing root metadata", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read("/.meta");
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.meta).toBeDefined();
+			for (const [key, value] of Object.entries(root.meta)) (0, bun_test.expect)(result.data?.meta?.[key]).toEqual(value);
+		});
+		if (fileWithMeta) (0, bun_test.test)("meta-read-file-existing: should read pre-existing file metadata", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read((0, ufo.joinURL)(fileWithMeta.path, ".meta"));
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.meta).toBeDefined();
+			for (const [key, value] of Object.entries(fileWithMeta.node.meta)) (0, bun_test.expect)(result.data?.meta?.[key]).toEqual(value);
+		});
+		if (dirWithMeta) (0, bun_test.test)("meta-read-directory-existing: should read pre-existing directory metadata", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read((0, ufo.joinURL)(dirWithMeta.path, ".meta"));
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.meta).toBeDefined();
+			for (const [key, value] of Object.entries(dirWithMeta.node.meta)) (0, bun_test.expect)(result.data?.meta?.[key]).toEqual(value);
+		});
+		if (subdirFileWithMeta) (0, bun_test.test)("meta-read-subdir-file-existing: should read pre-existing subdir file metadata", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read((0, ufo.joinURL)(subdirFileWithMeta.path, ".meta"));
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.meta).toBeDefined();
+			for (const [key, value] of Object.entries(subdirFileWithMeta.node.meta)) (0, bun_test.expect)(result.data?.meta?.[key]).toEqual(value);
+		});
+	});
+	(0, bun_test.describe)("meta-write-read", () => {
+		async function supportsMetaWrite(provider, nodePath) {
+			if (!provider.write || !provider.read) return false;
+			try {
+				await provider.write(nodePath, { meta: { __afs_test_meta_support: true } });
+				const metaPath = (0, ufo.joinURL)(nodePath, ".meta");
+				return (await provider.read(metaPath)).data?.meta?.__afs_test_meta_support === true;
+			} catch (e) {
+				if (e instanceof Error && (e.message.includes("No write handler") || e.message.includes("No valid columns"))) return false;
+				return false;
+			}
+		}
+		if (fileNode) (0, bun_test.test)("meta-write-read-file-root: should write and read metadata for existing file", async () => {
+			const provider = getProvider();
+			if (!provider.write || !provider.read) return;
+			const testPath = fileNode.path;
+			const metaPath = (0, ufo.joinURL)(testPath, ".meta");
+			if (!await supportsMetaWrite(provider, testPath)) return;
+			const writeResult = await provider.write(testPath, { meta: {
+				customField: "rootValue",
+				count: 100
+			} });
+			(0, bun_test.expect)(writeResult).toBeDefined();
+			(0, bun_test.expect)(writeResult.data).toBeDefined();
+			const readResult = await provider.read(metaPath);
+			(0, bun_test.expect)(readResult.data).toBeDefined();
+			(0, bun_test.expect)(readResult.data?.meta).toBeDefined();
+			(0, bun_test.expect)(readResult.data?.meta?.customField).toBe("rootValue");
+			(0, bun_test.expect)(readResult.data?.meta?.count).toBe(100);
+		});
+		if (subdirFileNode) (0, bun_test.test)("meta-write-read-file-subdir: should write and read metadata for file in subdirectory", async () => {
+			const provider = getProvider();
+			if (!provider.write || !provider.read) return;
+			const testPath = subdirFileNode.path;
+			const metaPath = (0, ufo.joinURL)(testPath, ".meta");
+			if (!await supportsMetaWrite(provider, testPath)) return;
+			(0, bun_test.expect)(await provider.write(testPath, { meta: {
+				location: "subdir",
+				priority: 5
+			} })).toBeDefined();
+			const readResult = await provider.read(metaPath);
+			(0, bun_test.expect)(readResult.data).toBeDefined();
+			(0, bun_test.expect)(readResult.data?.meta?.location).toBe("subdir");
+			(0, bun_test.expect)(readResult.data?.meta?.priority).toBe(5);
+		});
+		if (dirNode) (0, bun_test.test)("meta-write-read-directory: should write and read metadata for directory", async () => {
+			const provider = getProvider();
+			if (!provider.write || !provider.read) return;
+			const testPath = dirNode.path;
+			const metaPath = (0, ufo.joinURL)(testPath, ".meta");
+			if (!await supportsMetaWrite(provider, testPath)) return;
+			(0, bun_test.expect)(await provider.write(testPath, { meta: {
+				dirType: "documentation",
+				indexed: true
+			} })).toBeDefined();
+			const readResult = await provider.read(metaPath);
+			(0, bun_test.expect)(readResult.data).toBeDefined();
+			(0, bun_test.expect)(readResult.data?.meta?.dirType).toBe("documentation");
+			(0, bun_test.expect)(readResult.data?.meta?.indexed).toBe(true);
+		});
+		(0, bun_test.test)("meta-write-read-root: should write and read metadata for root directory", async () => {
+			const provider = getProvider();
+			if (!provider.write || !provider.read) return;
+			const rootPath = "/";
+			const metaPath = "/.meta";
+			if (!await supportsMetaWrite(provider, rootPath)) return;
+			(0, bun_test.expect)(await provider.write(rootPath, { meta: {
+				projectName: "test-project",
+				version: "1.0.0"
+			} })).toBeDefined();
+			const readResult = await provider.read(metaPath);
+			(0, bun_test.expect)(readResult.data).toBeDefined();
+			(0, bun_test.expect)(readResult.data?.meta?.projectName).toBe("test-project");
+			(0, bun_test.expect)(readResult.data?.meta?.version).toBe("1.0.0");
+		});
+		if (fileNode) (0, bun_test.test)("meta-merge: should merge metadata on subsequent writes", async () => {
+			const provider = getProvider();
+			if (!provider.write || !provider.read) return;
+			const testPath = fileNode.path;
+			const metaPath = (0, ufo.joinURL)(testPath, ".meta");
+			if (!await supportsMetaWrite(provider, testPath)) return;
+			await provider.write(testPath, { meta: {
+				field1: "value1",
+				field2: "value2"
+			} });
+			await provider.write(testPath, { meta: {
+				field2: "updated",
+				field3: "value3"
+			} });
+			const readResult = await provider.read(metaPath);
+			(0, bun_test.expect)(readResult.data?.meta?.field1).toBe("value1");
+			(0, bun_test.expect)(readResult.data?.meta?.field2).toBe("updated");
+			(0, bun_test.expect)(readResult.data?.meta?.field3).toBe("value3");
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/metadata-richness.ts
+/**
+* Run metadata richness validation suite.
+* Checks that list entries have required metadata fields:
+* - meta.kind: must be a non-empty string
+* - meta.childrenCount: must be defined for directory nodes
+* - meta.description: recommended but not enforced
+*/
+function runMetadataRichnessTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const allNodes = flattenTree(root).filter((n) => n.path !== "/");
+	(0, bun_test.describe)("metadata-richness", () => {
+		(0, bun_test.describe)("kind field", () => {
+			(0, bun_test.test)("list entries should have meta.kind as non-empty string", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				(0, bun_test.expect)(result.data).toBeDefined();
+				for (const entry of result.data) {
+					(0, bun_test.expect)(entry.meta?.kind).toBeDefined();
+					(0, bun_test.expect)(typeof entry.meta?.kind).toBe("string");
+					(0, bun_test.expect)((entry.meta?.kind).length).toBeGreaterThan(0);
+				}
+			});
+			(0, bun_test.test)("kind is any non-empty string (no format restriction)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				if (result.data.length === 0) return;
+				const entry = result.data[0];
+				(0, bun_test.expect)(typeof entry.meta?.kind).toBe("string");
+				(0, bun_test.expect)((entry.meta?.kind).length).toBeGreaterThan(0);
+			});
+		});
+		(0, bun_test.describe)("childrenCount field", () => {
+			for (const node of allNodes.filter((n) => isDirectory(n.node))) (0, bun_test.test)(`directory "${node.path}" should have childrenCount defined`, async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const parentPath = node.path.split("/").slice(0, -1).join("/") || "/";
+				const entry = (await provider.list(parentPath, { maxDepth: 1 })).data.find((e) => e.path === node.path || e.id === node.node.name);
+				if (!entry) return;
+				(0, bun_test.expect)(entry.meta?.childrenCount).toBeDefined();
+				(0, bun_test.expect)(typeof entry.meta?.childrenCount).toBe("number");
+			});
+			(0, bun_test.test)("childrenCount = -1 is valid (unknown children count)", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				for (const entry of result.data) if (entry.meta?.childrenCount !== void 0) {
+					(0, bun_test.expect)(typeof entry.meta.childrenCount).toBe("number");
+					(0, bun_test.expect)(entry.meta.childrenCount >= -1).toBe(true);
+				}
+			});
+			(0, bun_test.test)("childrenCount = 0 is valid for leaf nodes and empty directories", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				for (const entry of result.data) if (entry.meta?.childrenCount === 0) (0, bun_test.expect)(entry.meta.childrenCount).toBe(0);
+			});
+		});
+		(0, bun_test.describe)("description field", () => {
+			(0, bun_test.test)("description is recommended but not required", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				for (const entry of result.data) if (entry.meta?.description !== void 0) (0, bun_test.expect)(typeof entry.meta.description).toBe("string");
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/no-handler.ts
+/**
+* Run not-found error test suite.
+* Tests that operations on non-existent paths throw AFSNotFoundError.
+*
+* Expected behavior:
+* - read/list/stat on non-existent path: throw AFSNotFoundError
+* - search on non-existent path: returns empty results (not error)
+* - write/delete/rename on non-existent path: throw AFSNotFoundError
+* - Unsupported operations: method is undefined
+*/
+function runNoHandlerTests(getProvider, _config) {
+	const nonExistentPath = "/____path-that-does-not-exist-12345____";
+	(0, bun_test.describe)("not-found-errors", () => {
+		(0, bun_test.describe)("read operations", () => {
+			(0, bun_test.test)("read: non-existent path should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				try {
+					await provider.read(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+				}
+			});
+			(0, bun_test.test)("list: non-existent path should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				try {
+					await provider.list(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+				}
+			});
+			(0, bun_test.test)("stat: non-existent path should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				try {
+					await provider.stat(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+				}
+			});
+		});
+		(0, bun_test.describe)("search behavior", () => {
+			(0, bun_test.test)("search: non-existent path should return empty results or throw error", async () => {
+				const provider = getProvider();
+				if (!provider.search) return;
+				try {
+					const result = await provider.search(nonExistentPath, "query");
+					(0, bun_test.expect)(result).toBeDefined();
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+					(0, bun_test.expect)(result.data.length).toBe(0);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(Error);
+				}
+			});
+		});
+		(0, bun_test.describe)("write operations", () => {
+			(0, bun_test.test)("delete: non-existent path should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.delete) return;
+				if (provider.accessMode === "readonly") return;
+				try {
+					await provider.delete(nonExistentPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+				}
+			});
+			(0, bun_test.test)("rename: non-existent source should throw AFSNotFoundError", async () => {
+				const provider = getProvider();
+				if (!provider.rename) return;
+				if (provider.accessMode === "readonly") return;
+				const newPath = "/____new-path____";
+				try {
+					await provider.rename(nonExistentPath, newPath);
+					(0, bun_test.expect)(true).toBe(false);
+				} catch (error) {
+					(0, bun_test.expect)(error).toBeInstanceOf(_aigne_afs.AFSNotFoundError);
+				}
+			});
+		});
+		(0, bun_test.describe)("method availability", () => {
+			(0, bun_test.test)("unsupported operations should have undefined methods", () => {
+				const provider = getProvider();
+				for (const op of [
+					"list",
+					"read",
+					"write",
+					"delete",
+					"exec",
+					"search",
+					"stat",
+					"explain",
+					"rename"
+				]) {
+					const method = provider[op];
+					(0, bun_test.expect)(method === void 0 || typeof method === "function").toBe(true);
+				}
+			});
+			(0, bun_test.test)("accessMode should be defined", () => {
+				const provider = getProvider();
+				(0, bun_test.expect)(provider.accessMode).toBeDefined();
+				(0, bun_test.expect)(["readonly", "readwrite"]).toContain(provider.accessMode);
+			});
+			(0, bun_test.test)("name should be defined", () => {
+				const provider = getProvider();
+				(0, bun_test.expect)(provider.name).toBeDefined();
+				(0, bun_test.expect)(typeof provider.name).toBe("string");
+				(0, bun_test.expect)(provider.name.length).toBeGreaterThan(0);
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/path-normalization.ts
+/**
+* Run path normalization test suite.
+* Tests that various path formats are handled correctly.
+*/
+function runPathNormalizationTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const fileNode = findFirstFile(root);
+	(0, bun_test.describe)("path-normalization", () => {
+		(0, bun_test.describe)("list", () => {
+			(0, bun_test.test)("root with trailing slash: list('/') should work", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+			});
+			(0, bun_test.test)("empty string path: should normalize to root", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				try {
+					(0, bun_test.expect)((await provider.list("")).data).toBeDefined();
+				} catch {}
+			});
+			if (fileNode) (0, bun_test.test)("path with trailing slash: should normalize", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const parentPath = fileNode.path.split("/").slice(0, -1).join("/") || "/";
+				try {
+					(0, bun_test.expect)((await provider.list((0, ufo.joinURL)(parentPath, "/"))).data).toBeDefined();
+				} catch {}
+			});
+		});
+		(0, bun_test.describe)("read", () => {
+			if (fileNode) {
+				(0, bun_test.test)("read with exact path: should return entry", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const result = await provider.read(fileNode.path);
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(result.data?.path).toBe(fileNode.path);
+				});
+				(0, bun_test.test)("read path without leading slash: should normalize", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const pathWithoutSlash = fileNode.path.slice(1);
+					try {
+						const result = await provider.read(pathWithoutSlash);
+						(0, bun_test.expect)(result.data).toBeDefined();
+						(0, bun_test.expect)(result.data?.path?.startsWith("/")).toBe(true);
+					} catch {}
+				});
+			}
+		});
+		(0, bun_test.describe)("stat", () => {
+			(0, bun_test.test)("stat root path: should work", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat("/");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe("/");
+			});
+			if (fileNode) (0, bun_test.test)("stat file path: should return path in result", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBeDefined();
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/read.ts
+/**
+* Run ReadOperations test suite.
+*/
+function runReadTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const fileNode = findFirstFile(root);
+	const dirNode = findFirstDirectory(root);
+	const allNodes = flattenTree(root);
+	const emptyDirNode = allNodes.find((n) => n.node.children !== void 0 && n.node.children.length === 0);
+	const subdirFileNode = allNodes.find((n) => n.depth >= 2 && n.node.content !== void 0 && !isDirectory(n.node));
+	(0, bun_test.describe)("list", () => {
+		(0, bun_test.test)("list-root: should list children at root (not including root itself)", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list("/");
+			validateListResult(result);
+			if ((root.children?.length ?? 0) > 0) (0, bun_test.expect)(result.data.length).toBeGreaterThan(0);
+			(0, bun_test.expect)(result.data.some((e) => e.path === "/")).toBe(false);
+		});
+		if (dirNode) (0, bun_test.test)("list-subdir: should list children in subdirectory (not including self)", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list(dirNode.path);
+			validateListResult(result);
+			(0, bun_test.expect)(result.data.some((e) => e.path === dirNode.path)).toBe(false);
+		});
+		if (emptyDirNode) (0, bun_test.test)("list-empty-dir: should return empty array for empty directory", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list(emptyDirNode.path);
+			validateListResult(result);
+			(0, bun_test.expect)(result.data.length).toBe(0);
+		});
+		(0, bun_test.test)("list-not-found: should throw for non-existent path", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			await (0, bun_test.expect)(provider.list("/non-existent-path-12345")).rejects.toThrow();
+		});
+		(0, bun_test.test)("list-depth-0: should return empty array for maxDepth=0", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list("/", { maxDepth: 0 });
+			validateListResult(result);
+			(0, bun_test.expect)(result.data.length).toBe(0);
+		});
+		(0, bun_test.test)("list-depth-1: should return direct children for maxDepth=1", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list("/", { maxDepth: 1 });
+			validateListResult(result);
+			(0, bun_test.expect)(result.data.some((e) => e.path === "/")).toBe(false);
+			for (const entry of result.data) {
+				const depth = entry.path.split("/").filter(Boolean).length;
+				(0, bun_test.expect)(depth).toBe(1);
+			}
+		});
+		(0, bun_test.test)("list-with-limit: should respect limit parameter", async () => {
+			const provider = getProvider();
+			if (!provider.list) return;
+			const result = await provider.list("/", { limit: 2 });
+			validateListResult(result);
+			(0, bun_test.expect)(result.data.length).toBeLessThanOrEqual(2);
+		});
+	});
+	(0, bun_test.describe)("list-read consistency", () => {
+		(0, bun_test.test)("all listed entries must be readable", async () => {
+			const provider = getProvider();
+			if (!provider.list || !provider.read) return;
+			async function checkPath(path, maxRecursionDepth = 3) {
+				if (maxRecursionDepth <= 0) return;
+				const listResult = await provider.list(path, { maxDepth: 1 });
+				validateListResult(listResult);
+				for (const entry of listResult.data) {
+					const readResult = await provider.read(entry.path);
+					(0, bun_test.expect)(readResult.data).toBeDefined();
+					(0, bun_test.expect)(readResult.data?.path).toBe(entry.path);
+					const childrenCount = readResult.data?.meta?.childrenCount;
+					if (childrenCount !== void 0 && childrenCount !== 0) await checkPath(entry.path, maxRecursionDepth - 1);
+				}
+			}
+			await checkPath("/");
+		});
+		(0, bun_test.test)("nested directories: all descendants should be readable", async () => {
+			const provider = getProvider();
+			if (!provider.list || !provider.read) return;
+			const result = await provider.list("/", { maxDepth: 3 });
+			validateListResult(result);
+			for (const entry of result.data) {
+				const readResult = await provider.read(entry.path);
+				(0, bun_test.expect)(readResult.data).toBeDefined();
+				(0, bun_test.expect)(readResult.data?.path).toBe(entry.path);
+			}
+		});
+	});
+	(0, bun_test.describe)("read", () => {
+		if (fileNode) (0, bun_test.test)("read-file-root: should read file content", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read(fileNode.path);
+			validateReadResult(result);
+			(0, bun_test.expect)(result.data).toBeDefined();
+			validateEntry(result.data);
+		});
+		if (subdirFileNode) (0, bun_test.test)("read-file-subdir: should read file in subdirectory", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read(subdirFileNode.path);
+			validateReadResult(result);
+			(0, bun_test.expect)(result.data).toBeDefined();
+			validateEntry(result.data);
+		});
+		if (dirNode) (0, bun_test.test)("read-directory: should read directory entry", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			const result = await provider.read(dirNode.path);
+			validateReadResult(result);
+			(0, bun_test.expect)(result.data).toBeDefined();
+		});
+		(0, bun_test.test)("read-not-found: should throw for non-existent path", async () => {
+			const provider = getProvider();
+			if (!provider.read) return;
+			await (0, bun_test.expect)(provider.read("/non-existent-file-12345.txt")).rejects.toThrow();
+		});
+	});
+	(0, bun_test.describe)("stat", () => {
+		if (fileNode) (0, bun_test.test)("stat-file: should get file stats", async () => {
+			const provider = getProvider();
+			if (!provider.stat) return;
+			const result = await provider.stat(fileNode.path);
+			validateStatResult(result);
+			(0, bun_test.expect)(result.data).toBeDefined();
+			(0, bun_test.expect)(result.data?.path).toBeDefined();
+		});
+		if (dirNode) (0, bun_test.test)("stat-directory: should get directory stats", async () => {
+			const provider = getProvider();
+			if (!provider.stat) return;
+			const result = await provider.stat(dirNode.path);
+			validateStatResult(result);
+			(0, bun_test.expect)(result.data).toBeDefined();
+		});
+		(0, bun_test.test)("stat-not-found: should throw for non-existent path", async () => {
+			const provider = getProvider();
+			if (!provider.stat) return;
+			await (0, bun_test.expect)(provider.stat("/non-existent-path-12345")).rejects.toThrow();
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/route-params.ts
+/**
+* Run route params test suite.
+* Tests that path parameters are correctly extracted and entries have proper structure.
+* This validates that the router correctly parses dynamic segments like :id, :path*, etc.
+*/
+function runRouteParamsTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const allNodes = flattenTree(root);
+	const fileNode = findFirstFile(root);
+	const dirNode = findFirstDirectory(root);
+	const deepNode = allNodes.find((n) => n.depth >= 2);
+	(0, bun_test.describe)("route-params", () => {
+		(0, bun_test.describe)("path extraction", () => {
+			(0, bun_test.test)("root path: should have path '/'", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read("/");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe("/");
+			});
+			if (fileNode) (0, bun_test.test)("file path: should match request path exactly", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(fileNode.path);
+			});
+			if (dirNode) (0, bun_test.test)("directory path: should match request path exactly", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(dirNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(dirNode.path);
+			});
+			if (deepNode) (0, bun_test.test)("deep path: should preserve full path structure", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(deepNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(deepNode.path);
+				const segments = deepNode.path.split("/").filter(Boolean);
+				(0, bun_test.expect)(result.data?.path?.split("/").filter(Boolean) ?? []).toEqual(segments);
+			});
+		});
+		(0, bun_test.describe)("id generation", () => {
+			(0, bun_test.test)("entry id: should be defined and non-empty", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read("/");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.id).toBeDefined();
+				(0, bun_test.expect)(typeof result.data?.id).toBe("string");
+				(0, bun_test.expect)(result.data?.id?.length).toBeGreaterThan(0);
+			});
+			if (fileNode) (0, bun_test.test)("file id: should be string", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(typeof result.data?.id).toBe("string");
+			});
+			(0, bun_test.test)("list entries: all should have valid ids", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 2 });
+				(0, bun_test.expect)(result.data).toBeDefined();
+				for (const entry of result.data) {
+					(0, bun_test.expect)(entry.id).toBeDefined();
+					(0, bun_test.expect)(typeof entry.id).toBe("string");
+					(0, bun_test.expect)(entry.id.length).toBeGreaterThan(0);
+				}
+			});
+		});
+		(0, bun_test.describe)("path consistency", () => {
+			(0, bun_test.test)("list entries: paths should be consistent with parent", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list("/", { maxDepth: 1 });
+				(0, bun_test.expect)(result.data).toBeDefined();
+				for (const entry of result.data) {
+					(0, bun_test.expect)(entry.path.startsWith("/")).toBe(true);
+					if (entry.path !== "/") (0, bun_test.expect)(entry.path.endsWith("/")).toBe(false);
+					if (entry.path !== "/") {
+						const parentPath = entry.path.split("/").slice(0, -1).join("/") || "/";
+						(0, bun_test.expect)(parentPath === "/" || result.data.some((e) => e.path === parentPath)).toBe(true);
+					}
+				}
+			});
+			if (dirNode) (0, bun_test.test)("subdirectory list: child paths should be prefixed correctly", async () => {
+				const provider = getProvider();
+				if (!provider.list) return;
+				const result = await provider.list(dirNode.path, { maxDepth: 1 });
+				(0, bun_test.expect)(result.data).toBeDefined();
+				for (const entry of result.data) {
+					const dirPathWithSlash = (0, ufo.joinURL)(dirNode.path, "/");
+					(0, bun_test.expect)(entry.path === dirNode.path || entry.path.startsWith(dirPathWithSlash)).toBe(true);
+				}
+			});
+		});
+		(0, bun_test.describe)("meta path handling", () => {
+			(0, bun_test.test)(".meta path: should have correct path in response", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const result = await provider.read("/.meta");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe("/.meta");
+			});
+			if (fileNode) (0, bun_test.test)("file .meta path: should preserve full meta path", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const metaPath = (0, ufo.joinURL)(fileNode.path, ".meta");
+				const result = await provider.read(metaPath);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(metaPath);
+			});
+			if (dirNode) (0, bun_test.test)("directory .meta path: should preserve full meta path", async () => {
+				const provider = getProvider();
+				if (!provider.read) return;
+				const metaPath = (0, ufo.joinURL)(dirNode.path, ".meta");
+				const result = await provider.read(metaPath);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(metaPath);
+			});
+		});
+		(0, bun_test.describe)("stat path handling", () => {
+			(0, bun_test.test)("stat: path should match request", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat("/");
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe("/");
+			});
+			if (fileNode) (0, bun_test.test)("stat file: path should match request", async () => {
+				const provider = getProvider();
+				if (!provider.stat) return;
+				const result = await provider.stat(fileNode.path);
+				(0, bun_test.expect)(result.data).toBeDefined();
+				(0, bun_test.expect)(result.data?.path).toBe(fileNode.path);
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/search.ts
+/**
+* Run SearchOperations test suite.
+*/
+function runSearchTests(getProvider, structure, _config) {
+	const root = structure.root;
+	const fileWithContent = flattenTree(root).find((n) => n.node.content !== void 0 && typeof n.node.content === "string" && !isDirectory(n.node));
+	const dirNode = findFirstDirectory(root);
+	(0, bun_test.describe)("search", () => {
+		(0, bun_test.test)("search-basic-root: should search with simple query at root", async () => {
+			const provider = getProvider();
+			if (!provider.search) return;
+			const content = fileWithContent?.node.content;
+			const query = typeof content === "string" ? content.slice(0, 10) : "test";
+			validateSearchResult(await provider.search("/", query));
+		});
+		if (dirNode) (0, bun_test.test)("search-basic-subdir: should search within subdirectory", async () => {
+			const provider = getProvider();
+			if (!provider.search) return;
+			validateSearchResult(await provider.search(dirNode.path, "test"));
+		});
+		(0, bun_test.test)("search-no-results: should return empty when no match", async () => {
+			const provider = getProvider();
+			if (!provider.search) return;
+			const result = await provider.search("/", "nonexistentquerystring12345xyz");
+			validateSearchResult(result);
+			(0, bun_test.expect)(result.data.length).toBe(0);
+		});
+		(0, bun_test.test)("search-with-limit: should respect limit parameter", async () => {
+			const provider = getProvider();
+			if (!provider.search) return;
+			const result = await provider.search("/", "e", { limit: 1 });
+			validateSearchResult(result);
+			(0, bun_test.expect)(result.data.length).toBeLessThanOrEqual(1);
+		});
+	});
+}
+
+//#endregion
+//#region src/suites/structure.ts
+/**
+* Run structure validation tests.
+* Strictly validates that every node in the defined tree structure:
+* 1. Can be read via read()
+* 2. Can be listed via list()
+* 3. Has accessible metadata via read(.meta)
+* 4. Has expected content/children/metadata values if specified
+*/
+function runStructureTests(getProvider, root, _config) {
+	(0, bun_test.describe)("structure-validation", () => {
+		const nodesToTest = [];
+		function collectNodes(node, parentPath) {
+			const currentPath = parentPath === "/" && node.name === "" ? "/" : (0, ufo.joinURL)(parentPath, node.name);
+			nodesToTest.push({
+				path: currentPath,
+				node
+			});
+			if (node.children) for (const child of node.children) collectNodes(child, currentPath);
+		}
+		collectNodes(root, "/");
+		for (const { path, node } of nodesToTest) {
+			const isDir = isDirectory(node);
+			const isFileNode = isFile(node);
+			(0, bun_test.describe)(`${path} (${isDir ? "directory" : isFileNode ? "file" : "node"})`, () => {
+				(0, bun_test.test)("read: should be readable", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const result = await provider.read(path);
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(result.data?.path).toBeDefined();
+				});
+				(0, bun_test.test)("list: should be listable with maxDepth=1", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const result = await provider.list(path, { maxDepth: 1 });
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+					(0, bun_test.expect)(result.data.some((e) => e.path === path)).toBe(false);
+				});
+				(0, bun_test.test)("list: maxDepth=0 should return empty array", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const result = await provider.list(path, { maxDepth: 0 });
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+					(0, bun_test.expect)(result.data.length).toBe(0);
+				});
+				(0, bun_test.test)("meta: should have accessible metadata", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const metaPath = (0, ufo.joinURL)(path, ".meta");
+					const result = await provider.read(metaPath);
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(result.data?.path).toBe(metaPath);
+					(0, bun_test.expect)(result.data?.meta).toBeDefined();
+				});
+				if (isFileNode && node.content !== void 0 && node.content !== "") (0, bun_test.test)("content: should have expected content", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const result = await provider.read(path);
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(result.data?.content).toContain(node.content);
+				});
+				if (isDir && node.children && node.children.length > 0) (0, bun_test.test)("children: should list expected children", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const result = await provider.list(path, { maxDepth: 1 });
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+					const listedPaths = result.data.map((e) => e.path);
+					const expectedChildPaths = node.children.map((child) => (0, ufo.joinURL)(path, child.name));
+					for (const expectedPath of expectedChildPaths) (0, bun_test.expect)(listedPaths).toContain(expectedPath);
+				});
+				(0, bun_test.test)("childrenCount: should match actual children count", async () => {
+					const provider = getProvider();
+					if (!provider.read || !provider.list) return;
+					const childrenCount = (await provider.read(path)).data?.meta?.childrenCount;
+					const actualChildCount = (await provider.list(path, { maxDepth: 1 })).data.length;
+					if (childrenCount === void 0 || childrenCount === 0) (0, bun_test.expect)(actualChildCount).toBe(0);
+					else if (childrenCount === -1) (0, bun_test.expect)(actualChildCount).toBeGreaterThanOrEqual(1);
+					else if (childrenCount > 0) (0, bun_test.expect)(actualChildCount).toBe(childrenCount);
+				});
+				if (node.meta && Object.keys(node.meta).length > 0) (0, bun_test.test)("meta: should have expected metadata values", async () => {
+					const provider = getProvider();
+					if (!provider.read) return;
+					const metaPath = (0, ufo.joinURL)(path, ".meta");
+					const result = await provider.read(metaPath);
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(result.data?.meta).toBeDefined();
+					for (const [key, value] of Object.entries(node.meta)) (0, bun_test.expect)(result.data?.meta?.[key]).toEqual(value);
+				});
+				if (node.actions && node.actions.length > 0) (0, bun_test.test)("actions: should have expected actions", async () => {
+					const provider = getProvider();
+					if (!provider.list) return;
+					const actionsPath = (0, ufo.joinURL)(path, ".actions");
+					const result = await provider.list(actionsPath, { maxDepth: 1 });
+					(0, bun_test.expect)(result.data).toBeDefined();
+					(0, bun_test.expect)(Array.isArray(result.data)).toBe(true);
+					const listedActionNames = result.data.filter((e) => e.path !== actionsPath).map((e) => {
+						const parts = e.path.split("/");
+						return parts[parts.length - 1];
+					});
+					for (const expectedAction of node.actions) {
+						(0, bun_test.expect)(listedActionNames).toContain(expectedAction.name);
+						if (expectedAction.description) {
+							const actionEntry = result.data.find((e) => e.path.endsWith(`/.actions/${expectedAction.name}`));
+							(0, bun_test.expect)(actionEntry?.meta?.description ?? actionEntry?.summary).toContain(expectedAction.description);
+						}
+					}
+				});
+			});
+		}
+	});
+}
+
+//#endregion
+//#region src/suites/write-cases.ts
+/**
+* Check if expected output is a validator function.
+*/
+function isValidator(expected) {
+	return typeof expected === "function";
+}
+/**
+* Check if expected output is a content matcher.
+*/
+function isContentMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "content" in expected;
+}
+/**
+* Check if expected output is a contentContains matcher.
+*/
+function isContentContainsMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "contentContains" in expected;
+}
+/**
+* Check if expected output is a meta matcher.
+*/
+function isMetaMatcher(expected) {
+	return typeof expected === "object" && expected !== null && "meta" in expected;
+}
+/**
+* Run write case tests.
+* Tests write operations based on fixture-defined cases.
+* These tests run LAST because they may modify the data structure.
+*/
+function runWriteCaseTests(getProvider, cases, _config) {
+	(0, bun_test.describe)("write-cases", () => {
+		for (const testCase of cases) (0, bun_test.test)(`write ${testCase.path}: ${testCase.name}`, async () => {
+			const provider = getProvider();
+			if (!provider.write) return;
+			if (testCase.shouldThrow) {
+				let threw = false;
+				let errorMessage = "";
+				try {
+					await provider.write(testCase.path, testCase.payload, {});
+				} catch (error) {
+					threw = true;
+					errorMessage = error instanceof Error ? error.message : String(error);
+				}
+				(0, bun_test.expect)(threw).toBe(true);
+				if (typeof testCase.shouldThrow === "string") (0, bun_test.expect)(errorMessage).toContain(testCase.shouldThrow);
+				else if (testCase.shouldThrow instanceof RegExp) (0, bun_test.expect)(errorMessage).toMatch(testCase.shouldThrow);
+			} else {
+				const result = await provider.write(testCase.path, testCase.payload, {});
+				(0, bun_test.expect)(result).toBeDefined();
+				if (testCase.expected !== void 0) {
+					if (isValidator(testCase.expected)) testCase.expected(result, bun_test.expect);
+					else if (isContentMatcher(testCase.expected)) (0, bun_test.expect)(result.data?.content).toEqual(testCase.expected.content);
+					else if (isContentContainsMatcher(testCase.expected)) {
+						const content = result.data?.content;
+						(0, bun_test.expect)(typeof content === "string").toBe(true);
+						(0, bun_test.expect)(content).toContain(testCase.expected.contentContains);
+					} else if (isMetaMatcher(testCase.expected)) (0, bun_test.expect)(result.data?.meta).toMatchObject(testCase.expected.meta);
+				}
+				if (testCase.expected && provider.read) (0, bun_test.expect)(await provider.read(testCase.path, {})).toBeDefined();
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/runner.ts
+/**
+* Run provider conformance tests.
+*
+* @example
+* ```typescript
+* import { runProviderTests } from "@aigne/afs/testing";
+*
+* describe("MyProvider Conformance", () => {
+*   runProviderTests({
+*     name: "MyProvider",
+*     createProvider: () => new MyProvider({ ... }),
+*     structure: {
+*       root: {
+*         name: "",
+*         children: [
+*           { name: "file.txt", content: "Hello" },
+*           {
+*             name: "docs",
+*             children: [
+*               { name: "readme.md", content: "# Readme" },
+*             ],
+*           },
+*         ],
+*       },
+*     },
+*   });
+* });
+* ```
+*/
+function runProviderTests(fixture) {
+	let provider;
+	const config = fixture.config ?? {};
+	const structure = fixture.structure;
+	(0, bun_test.describe)(fixture.name, () => {
+		if (fixture.beforeAll) (0, bun_test.beforeAll)(fixture.beforeAll);
+		(0, bun_test.beforeAll)(async () => {
+			provider = await fixture.createProvider();
+		});
+		if (fixture.afterAll) (0, bun_test.afterAll)(fixture.afterAll);
+		if (fixture.beforeEach) (0, bun_test.beforeEach)(fixture.beforeEach);
+		if (fixture.afterEach) (0, bun_test.afterEach)(fixture.afterEach);
+		(0, bun_test.describe)("StructureValidation", () => {
+			runStructureTests(() => provider, structure.root, config);
+		});
+		(0, bun_test.describe)("ReadOperations", () => {
+			runReadTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("SearchOperations", () => {
+			runSearchTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("MetaOperations", () => {
+			runMetaTests(() => provider, structure, config);
+		});
+		if (fixture.executeCases && fixture.executeCases.length > 0) (0, bun_test.describe)("ExecuteOperations", () => {
+			runExecuteTests(() => provider, fixture.executeCases, config);
+		});
+		(0, bun_test.describe)("ExplainOperations", () => {
+			runExplainTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("AccessModeValidation", () => {
+			runAccessModeTests(() => provider, config);
+		});
+		(0, bun_test.describe)("ErrorTypesValidation", () => {
+			runErrorTypesTests(() => provider, config);
+		});
+		(0, bun_test.describe)("EntryFieldsValidation", () => {
+			runEntryFieldsTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("ListOptionsValidation", () => {
+			runListOptionsTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("PathNormalizationValidation", () => {
+			runPathNormalizationTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("DeepListValidation", () => {
+			runDeepListTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("NoHandlerValidation", () => {
+			runNoHandlerTests(() => provider, config);
+		});
+		(0, bun_test.describe)("RouteParamsValidation", () => {
+			runRouteParamsTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("MetadataRichnessValidation", () => {
+			runMetadataRichnessTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("ExplainExistenceValidation", () => {
+			runExplainExistenceTests(() => provider, structure, config);
+		});
+		(0, bun_test.describe)("CapabilitiesOperationsValidation", () => {
+			runCapabilitiesOperationsTests(() => provider, structure, config);
+		});
+		if (fixture.actionCases && fixture.actionCases.length > 0) (0, bun_test.describe)("ActionOperations", () => {
+			runActionTests(() => provider, fixture.actionCases, config);
+		});
+		if (fixture.writeCases && fixture.writeCases.length > 0) (0, bun_test.describe)("WriteCaseOperations", () => {
+			runWriteCaseTests(() => provider, fixture.writeCases, config);
+		});
+		if (fixture.deleteCases && fixture.deleteCases.length > 0) (0, bun_test.describe)("DeleteCaseOperations", () => {
+			runDeleteCaseTests(() => provider, fixture.deleteCases, config);
+		});
+	});
+}
+
+//#endregion
+exports.computePath = computePath;
+exports.findFirstDirectory = findFirstDirectory;
+exports.findFirstFile = findFirstFile;
+exports.findNestedDirectory = findNestedDirectory;
+exports.findNode = findNode;
+exports.flattenTree = flattenTree;
+exports.getAllDirectories = getAllDirectories;
+exports.getAllFiles = getAllFiles;
+exports.isDirectory = isDirectory;
+exports.isFile = isFile;
+exports.runProviderTests = runProviderTests;
+exports.validateEntry = validateEntry;
+exports.validateListResult = validateListResult;
+exports.validateReadResult = validateReadResult;
+exports.validateSearchResult = validateSearchResult;
+exports.validateStatResult = validateStatResult;