@aigne/afs 1.11.0-beta → 1.11.0-beta.10

package/dist/index.mjs

@@ -1,343 +1,17 @@
-import { v7 } from "@aigne/uuid";
-import { Emitter } from "strict-event-emitter";
-import { joinURL } from "ufo";
-import { z } from "zod";
+import { AFSError, AFSMountError, AFSNotFoundError, AFSReadonlyError, AFSValidationError } from "./error.mjs";
+import { AFSPathError, isCanonicalPath, normalizePath, parseCanonicalPath, toCanonicalPath, validateModuleName, validatePath } from "./path.mjs";
+import { AFS } from "./afs.mjs";
+import { isWorldMappingCapable } from "./capabilities/world-mapping.mjs";
+import { combineValidationResults, validateNodes } from "./meta/validation.mjs";
+import { WELL_KNOWN_KINDS, WELL_KNOWN_KINDS_MAP, afsDocument, afsExecutable, afsImage, afsLink, afsNode, commonMetaSchema, getWellKnownKind, isWellKnownKind } from "./meta/well-known-kinds.mjs";
+import { KindError, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, resolveKindSchema } from "./meta/kind.mjs";
+import { KINDS_SEGMENT, META_SEGMENT, getNodePathFromMetaPath, isKindsPath, isMetaPath, parseMetaPath } from "./meta/path.mjs";
+import "./meta/index.mjs";
+import { Actions, Delete, Exec, Explain, List, Meta, Read, Rename, Search, Stat, Write, clearRoutes, getRoutes } from "./provider/decorators.mjs";
+import { ProviderRouter } from "./provider/router.mjs";
+import { AFSBaseProvider } from "./provider/base.mjs";
+import "./provider/index.mjs";
+import { ProviderRegistry } from "./registry.mjs";
+import { accessModeSchema, actionSummarySchema, afsEntrySchema } from "./type.mjs";
 
-//#region src/error.ts
-/**
-* Base error class for all AFS errors.
-*/
-var AFSError = class extends Error {
-	code;
-	constructor(message, code) {
-		super(message);
-		this.name = "AFSError";
-		this.code = code;
-	}
-};
-/**
-* Error thrown when attempting write operations on a readonly AFS or module.
-*/
-var AFSReadonlyError = class extends AFSError {
-	constructor(message) {
-		super(message, "AFS_READONLY");
-		this.name = "AFSReadonlyError";
-	}
-};
-
-//#endregion
-//#region src/type.ts
-/**
-* Zod schema for access mode validation.
-* Can be reused across modules that support access mode configuration.
-*/
-const accessModeSchema = z.enum(["readonly", "readwrite"]).describe("Access mode for this module").optional();
-const afsEntrySchema = z.object({
-	id: z.string(),
-	createdAt: z.date().optional(),
-	updatedAt: z.date().optional(),
-	path: z.string(),
-	userId: z.string().nullable().optional(),
-	sessionId: z.string().nullable().optional(),
-	summary: z.string().nullable().optional(),
-	description: z.string().nullable().optional(),
-	metadata: z.record(z.any()).nullable().optional(),
-	linkTo: z.string().nullable().optional(),
-	content: z.any().optional()
-});
-
-//#endregion
-//#region src/afs.ts
-const DEFAULT_MAX_DEPTH = 1;
-const MODULES_ROOT_DIR = "/modules";
-var AFS = class extends Emitter {
-	name = "AFSRoot";
-	constructor(options = {}) {
-		super();
-		this.options = options;
-		for (const module of options?.modules ?? []) this.mount(module);
-	}
-	modules = /* @__PURE__ */ new Map();
-	/**
-	* Check if write operations are allowed for the given module.
-	* Throws AFSReadonlyError if not allowed.
-	*/
-	checkWritePermission(module, operation, path) {
-		if (module.accessMode !== "readwrite") throw new AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
-	}
-	mount(module) {
-		if (module.name.includes("/")) throw new Error(`Invalid module name: ${module.name}. Module name must not contain '/'`);
-		const path = joinURL(MODULES_ROOT_DIR, module.name);
-		if (this.modules.has(path)) throw new Error(`Module already mounted at path: ${path}`);
-		this.modules.set(path, module);
-		module.onMount?.(this);
-		return this;
-	}
-	async listModules() {
-		return Array.from(this.modules.entries()).map(([path, module]) => ({
-			path,
-			name: module.name,
-			description: module.description,
-			module
-		}));
-	}
-	async list(path, options = {}) {
-		let preset;
-		if (options.preset) {
-			preset = this.options?.context?.list?.presets?.[options.preset];
-			if (!preset) throw new Error(`Preset not found: ${options.preset}`);
-		}
-		return await this.processWithPreset(path, void 0, preset, {
-			...options,
-			defaultSelect: () => this._list(path, options)
-		});
-	}
-	async _list(path, options = {}) {
-		const results = [];
-		if (path === "/" && this.modules.size > 0) {
-			const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
-			results.push({
-				id: "modules",
-				path: MODULES_ROOT_DIR,
-				summary: "All mounted modules"
-			});
-			if (maxDepth === 1) return { data: results };
-			const childrenResult = await this._list(MODULES_ROOT_DIR, {
-				...options,
-				maxDepth: maxDepth - 1
-			});
-			results.push(...childrenResult.data);
-			return { data: results };
-		}
-		const matches = this.findModules(path, options);
-		for (const matched of matches) {
-			if (matched.maxDepth === 0) {
-				const moduleEntry = {
-					id: matched.module.name,
-					path: matched.modulePath,
-					summary: matched.module.description
-				};
-				results.push(moduleEntry);
-				continue;
-			}
-			if (!matched.module.list) continue;
-			try {
-				const { data } = await matched.module.list(matched.subpath, {
-					...options,
-					maxDepth: matched.maxDepth
-				});
-				const children = data.map((entry) => ({
-					...entry,
-					path: joinURL(matched.modulePath, entry.path)
-				}));
-				results.push(...children);
-			} catch (error) {
-				throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
-			}
-		}
-		return { data: results };
-	}
-	async read(path, _options) {
-		const modules = this.findModules(path, { exactMatch: true });
-		for (const { module, modulePath, subpath } of modules) {
-			const res = await module.read?.(subpath);
-			if (res?.data) return {
-				...res,
-				data: {
-					...res.data,
-					path: joinURL(modulePath, res.data.path)
-				}
-			};
-		}
-		return {
-			data: void 0,
-			message: "File not found"
-		};
-	}
-	async write(path, content, options) {
-		const module = this.findModules(path, { exactMatch: true })[0];
-		if (!module?.module.write) throw new Error(`No module found for path: ${path}`);
-		this.checkWritePermission(module.module, "write", path);
-		const res = await module.module.write(module.subpath, content, options);
-		return {
-			...res,
-			data: {
-				...res.data,
-				path: joinURL(module.modulePath, res.data.path)
-			}
-		};
-	}
-	async delete(path, options) {
-		const module = this.findModules(path, { exactMatch: true })[0];
-		if (!module?.module.delete) throw new Error(`No module found for path: ${path}`);
-		this.checkWritePermission(module.module, "delete", path);
-		return await module.module.delete(module.subpath, options);
-	}
-	async rename(oldPath, newPath, options) {
-		const oldModule = this.findModules(oldPath, { exactMatch: true })[0];
-		const newModule = this.findModules(newPath, { exactMatch: true })[0];
-		if (!oldModule || !newModule || oldModule.modulePath !== newModule.modulePath) throw new Error(`Cannot rename across different modules. Both paths must be in the same module.`);
-		if (!oldModule.module.rename) throw new Error(`Module does not support rename operation: ${oldModule.modulePath}`);
-		this.checkWritePermission(oldModule.module, "rename", oldPath);
-		return await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
-	}
-	async search(path, query, options = {}) {
-		let preset;
-		if (options.preset) {
-			preset = this.options?.context?.search?.presets?.[options.preset];
-			if (!preset) throw new Error(`Preset not found: ${options.preset}`);
-		}
-		return await this.processWithPreset(path, query, preset, {
-			...options,
-			defaultSelect: () => this._search(path, query, options)
-		});
-	}
-	async processWithPreset(path, query, preset, options) {
-		const select = options.select || preset?.select;
-		const per = options.per || preset?.per;
-		const dedupe = options.dedupe || preset?.dedupe;
-		const format = options.format || preset?.format;
-		const entries = select ? (await this._select(path, query, select, options)).data : (await options.defaultSelect()).data;
-		const mapped = per ? await Promise.all(entries.map((data) => per.invoke({ data }, options).then((res) => res.data))) : entries;
-		const deduped = dedupe ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data) : mapped;
-		let formatted = deduped;
-		if (format === "simple-list" || format === "tree") {
-			const valid = z.array(afsEntrySchema).safeParse(deduped);
-			if (!valid.data) throw new Error("Tree format requires entries to be AFSEntry objects");
-			if (format === "tree") formatted = this.buildTreeView(valid.data);
-			else if (format === "simple-list") formatted = this.buildSimpleListView(valid.data);
-		} else if (typeof format === "object" && typeof format.invoke === "function") formatted = await format.invoke({ data: deduped }, options).then((res) => res.data);
-		return { data: formatted };
-	}
-	async _select(path, query, select, options) {
-		const { data } = await select.invoke({
-			path,
-			query
-		}, options);
-		return { data: (await Promise.all(data.map((p) => this.read(p).then((res) => res.data)))).filter((i) => !!i) };
-	}
-	async _search(path, query, options) {
-		const results = [];
-		const messages = [];
-		for (const { module, modulePath, subpath } of this.findModules(path)) {
-			if (!module.search) continue;
-			try {
-				const { data, message } = await module.search(subpath, query, options);
-				results.push(...data.map((entry) => ({
-					...entry,
-					path: joinURL(modulePath, entry.path)
-				})));
-				if (message) messages.push(message);
-			} catch (error) {
-				throw new Error(`Error searching in module at ${modulePath}: ${error.message}`);
-			}
-		}
-		return {
-			data: results,
-			message: messages.join("; ")
-		};
-	}
-	findModules(path, options) {
-		const maxDepth = Math.max(options?.maxDepth ?? DEFAULT_MAX_DEPTH, 1);
-		const matched = [];
-		for (const [modulePath, module] of this.modules) {
-			const pathSegments = path.split("/").filter(Boolean);
-			const modulePathSegments = modulePath.split("/").filter(Boolean);
-			let newMaxDepth;
-			let subpath;
-			let remainedModulePath;
-			if (!options?.exactMatch && modulePath.startsWith(path)) {
-				newMaxDepth = Math.max(0, maxDepth - (modulePathSegments.length - pathSegments.length));
-				subpath = "/";
-				remainedModulePath = joinURL("/", ...modulePathSegments.slice(pathSegments.length).slice(0, maxDepth));
-			} else if (path.startsWith(modulePath)) {
-				newMaxDepth = maxDepth;
-				subpath = joinURL("/", ...pathSegments.slice(modulePathSegments.length));
-				remainedModulePath = "/";
-			} else continue;
-			if (newMaxDepth < 0) continue;
-			matched.push({
-				module,
-				modulePath,
-				maxDepth: newMaxDepth,
-				subpath,
-				remainedModulePath
-			});
-		}
-		return matched;
-	}
-	async exec(path, args, options) {
-		const module = this.findModules(path)[0];
-		if (!module?.module.exec) throw new Error(`No module found for path: ${path}`);
-		return await module.module.exec(module.subpath, args, options);
-	}
-	buildSimpleListView(entries) {
-		return entries.map((entry) => `${entry.path}${this.buildMetadataSuffix(entry)}`);
-	}
-	buildTreeView(entries) {
-		const tree = {};
-		const entryMap = /* @__PURE__ */ new Map();
-		for (const entry of entries) {
-			entryMap.set(entry.path, entry);
-			const parts = entry.path.split("/").filter(Boolean);
-			let current = tree;
-			for (const part of parts) {
-				if (!current[part]) current[part] = {};
-				current = current[part];
-			}
-		}
-		const renderTree = (node, prefix = "", currentPath = "") => {
-			let result = "";
-			const keys = Object.keys(node);
-			keys.forEach((key, index) => {
-				const isLast = index === keys.length - 1;
-				const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
-				const entry = entryMap.get(fullPath);
-				result += `${prefix}${isLast ? "└── " : "├── "}${key}${entry ? this.buildMetadataSuffix(entry) : ""}`;
-				result += `\n`;
-				result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
-			});
-			return result;
-		};
-		return renderTree(tree);
-	}
-	buildMetadataSuffix(entry) {
-		const metadataParts = [];
-		const childrenCount = entry?.metadata?.childrenCount;
-		if (typeof childrenCount === "number") metadataParts.push(`${childrenCount} items`);
-		if (entry?.metadata?.childrenTruncated) metadataParts.push("truncated");
-		if (entry?.metadata?.gitignored) metadataParts.push("gitignored");
-		if (entry?.metadata?.execute) metadataParts.push("executable");
-		return metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
-	}
-	physicalPath;
-	async initializePhysicalPath() {
-		this.physicalPath ??= (async () => {
-			const path = await import("node:path");
-			const os = await import("node:os");
-			const fs = await import("node:fs/promises");
-			const rootDir = path.join(os.tmpdir(), v7());
-			await fs.mkdir(rootDir, { recursive: true });
-			for (const [modulePath, module] of this.modules) {
-				const physicalModulePath = path.join(rootDir, modulePath);
-				await fs.mkdir(path.dirname(physicalModulePath), { recursive: true });
-				await module.symlinkToPhysical?.(physicalModulePath);
-			}
-			return rootDir;
-		})();
-		return this.physicalPath;
-	}
-	async cleanupPhysicalPath() {
-		if (this.physicalPath) {
-			await (await import("node:fs/promises")).rm(await this.physicalPath, {
-				recursive: true,
-				force: true
-			});
-			this.physicalPath = void 0;
-		}
-	}
-};
-
-//#endregion
-export { AFS, AFSError, AFSReadonlyError, accessModeSchema, afsEntrySchema };
-//# sourceMappingURL=index.mjs.map
+export { AFS, AFSBaseProvider, AFSError, AFSMountError, AFSNotFoundError, AFSPathError, AFSReadonlyError, AFSValidationError, Actions, Delete, Exec, Explain, KINDS_SEGMENT, KindError, List, META_SEGMENT, Meta, ProviderRegistry, ProviderRouter, Read, Rename, Search, Stat, WELL_KNOWN_KINDS, WELL_KNOWN_KINDS_MAP, Write, accessModeSchema, actionSummarySchema, afsDocument, afsEntrySchema, afsExecutable, afsImage, afsLink, afsNode, clearRoutes, combineValidationResults, commonMetaSchema, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, getNodePathFromMetaPath, getRoutes, getWellKnownKind, isCanonicalPath, isKindsPath, isMetaPath, isWellKnownKind, isWorldMappingCapable, normalizePath, parseCanonicalPath, parseMetaPath, resolveKindSchema, toCanonicalPath, validateModuleName, validateNodes, validatePath };

package/dist/loader/index.cjs

@@ -0,0 +1,110 @@
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+
+//#region src/loader/index.ts
+/**
+* AFS Provider Dynamic Loader
+*
+* Provides utilities for dynamically loading AFS providers at runtime.
+*
+* @example
+* ```typescript
+* import { loadProvider, getProviderSchema } from "@aigne/afs/loader";
+*
+* // Load a provider with configuration
+* const fs = await loadProvider("@aigne/afs-fs", {
+*   config: { localPath: "./data" },
+*   basePath: "/path/to/config/dir"
+* });
+*
+* // Get provider schema for validation
+* const schema = await getProviderSchema("@aigne/afs-fs");
+* ```
+*/
+/**
+* Resolve a package specifier to an importable path.
+* If the specifier is a directory path (e.g. from npm install),
+* read its package.json to find the ESM entry point.
+* We must use the ESM (.mjs) entry, not CJS (.cjs), because
+* importing CJS from ESM wraps module.exports in an extra default layer
+* which breaks the expected export shape.
+*/
+function resolveImportPath(specifier) {
+	if (!specifier.startsWith("/")) return specifier;
+	const pkgJsonPath = (0, node_path.join)(specifier, "package.json");
+	if (!(0, node_fs.existsSync)(pkgJsonPath)) return specifier;
+	try {
+		const pkg = JSON.parse((0, node_fs.readFileSync)(pkgJsonPath, "utf-8"));
+		const esmEntry = typeof pkg.exports === "object" && pkg.exports["."]?.import || pkg.module;
+		if (esmEntry) return (0, node_path.join)(specifier, esmEntry);
+		if (pkg.main) return (0, node_path.join)(specifier, pkg.main);
+	} catch {}
+	return specifier;
+}
+/**
+* Dynamically load an AFS Provider from a package.
+*
+* @param packageName - Package name or subpath (e.g., "@aigne/afs-fs" or "@aigne/afs-cloud/s3")
+* @param options - Load options (optional)
+* @returns Provider instance
+*
+* @throws Error if package doesn't exist or doesn't export a valid AFS Provider
+*
+* @example
+* ```typescript
+* const fs = await loadProvider("@aigne/afs-fs", {
+*   config: { localPath: "./data" },
+*   basePath: "/path/to/config/dir"
+* });
+* ```
+*/
+async function loadProvider(packageName, options) {
+	const importPath = resolveImportPath(packageName);
+	let module;
+	try {
+		module = await import(importPath);
+	} catch (error) {
+		throw new Error(`Failed to import package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ProviderClass = module.default;
+	if (!ProviderClass || typeof ProviderClass.load !== "function") throw new Error(`Package "${packageName}" does not export a valid AFS Provider. Expected default export with static load() method.`);
+	return ProviderClass.load(options ?? {});
+}
+/**
+* Get the configuration schema for an AFS Provider without creating an instance.
+*
+* Useful for:
+* - Configuration validation
+* - Documentation generation
+* - IDE integration
+*
+* @param packageName - Package name or subpath
+* @returns Zod schema for the provider's configuration
+*
+* @throws Error if package doesn't export schema() method
+*
+* @example
+* ```typescript
+* const schema = await getProviderSchema("@aigne/afs-fs");
+* const result = schema.safeParse(config);
+* if (!result.success) {
+*   console.error(result.error);
+* }
+* ```
+*/
+async function getProviderSchema(packageName) {
+	const importPath = resolveImportPath(packageName);
+	let module;
+	try {
+		module = await import(importPath);
+	} catch (error) {
+		throw new Error(`Failed to import package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ProviderClass = module.default;
+	if (!ProviderClass || typeof ProviderClass.schema !== "function") throw new Error(`Package "${packageName}" does not export schema() method.`);
+	return ProviderClass.schema();
+}
+
+//#endregion
+exports.getProviderSchema = getProviderSchema;
+exports.loadProvider = loadProvider;

package/dist/loader/index.d.cts

@@ -0,0 +1,48 @@
+import { AFSModule, AFSModuleLoadParams } from "../type.cjs";
+import { ZodType } from "zod";
+
+//#region src/loader/index.d.ts
+/**
+ * Dynamically load an AFS Provider from a package.
+ *
+ * @param packageName - Package name or subpath (e.g., "@aigne/afs-fs" or "@aigne/afs-cloud/s3")
+ * @param options - Load options (optional)
+ * @returns Provider instance
+ *
+ * @throws Error if package doesn't exist or doesn't export a valid AFS Provider
+ *
+ * @example
+ * ```typescript
+ * const fs = await loadProvider("@aigne/afs-fs", {
+ *   config: { localPath: "./data" },
+ *   basePath: "/path/to/config/dir"
+ * });
+ * ```
+ */
+declare function loadProvider<T extends AFSModule = AFSModule>(packageName: string, options?: AFSModuleLoadParams): Promise<T>;
+/**
+ * Get the configuration schema for an AFS Provider without creating an instance.
+ *
+ * Useful for:
+ * - Configuration validation
+ * - Documentation generation
+ * - IDE integration
+ *
+ * @param packageName - Package name or subpath
+ * @returns Zod schema for the provider's configuration
+ *
+ * @throws Error if package doesn't export schema() method
+ *
+ * @example
+ * ```typescript
+ * const schema = await getProviderSchema("@aigne/afs-fs");
+ * const result = schema.safeParse(config);
+ * if (!result.success) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function getProviderSchema(packageName: string): Promise<ZodType<unknown>>;
+//#endregion
+export { type AFSModuleLoadParams, getProviderSchema, loadProvider };
+//# sourceMappingURL=index.d.cts.map

package/dist/loader/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/loader/index.ts"],"mappings":";;;;;;AA6HA;;;;;;;;;;;;;;;iBArDsB,YAAA,WAAuB,SAAA,GAAY,SAAA,CAAA,CACvD,WAAA,UACA,OAAA,GAAU,mBAAA,GACT,OAAA,CAAQ,CAAA;;;;;;;;;;;;;;;;;;;;;;;iBAkDW,iBAAA,CAAkB,WAAA,WAAsB,OAAA,CAAQ,OAAA"}

package/dist/loader/index.d.mts

@@ -0,0 +1,48 @@
+import { AFSModule, AFSModuleLoadParams } from "../type.mjs";
+import { ZodType } from "zod";
+
+//#region src/loader/index.d.ts
+/**
+ * Dynamically load an AFS Provider from a package.
+ *
+ * @param packageName - Package name or subpath (e.g., "@aigne/afs-fs" or "@aigne/afs-cloud/s3")
+ * @param options - Load options (optional)
+ * @returns Provider instance
+ *
+ * @throws Error if package doesn't exist or doesn't export a valid AFS Provider
+ *
+ * @example
+ * ```typescript
+ * const fs = await loadProvider("@aigne/afs-fs", {
+ *   config: { localPath: "./data" },
+ *   basePath: "/path/to/config/dir"
+ * });
+ * ```
+ */
+declare function loadProvider<T extends AFSModule = AFSModule>(packageName: string, options?: AFSModuleLoadParams): Promise<T>;
+/**
+ * Get the configuration schema for an AFS Provider without creating an instance.
+ *
+ * Useful for:
+ * - Configuration validation
+ * - Documentation generation
+ * - IDE integration
+ *
+ * @param packageName - Package name or subpath
+ * @returns Zod schema for the provider's configuration
+ *
+ * @throws Error if package doesn't export schema() method
+ *
+ * @example
+ * ```typescript
+ * const schema = await getProviderSchema("@aigne/afs-fs");
+ * const result = schema.safeParse(config);
+ * if (!result.success) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function getProviderSchema(packageName: string): Promise<ZodType<unknown>>;
+//#endregion
+export { type AFSModuleLoadParams, getProviderSchema, loadProvider };
+//# sourceMappingURL=index.d.mts.map

package/dist/loader/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/loader/index.ts"],"mappings":";;;;;;AA6HA;;;;;;;;;;;;;;;iBArDsB,YAAA,WAAuB,SAAA,GAAY,SAAA,CAAA,CACvD,WAAA,UACA,OAAA,GAAU,mBAAA,GACT,OAAA,CAAQ,CAAA;;;;;;;;;;;;;;;;;;;;;;;iBAkDW,iBAAA,CAAkB,WAAA,WAAsB,OAAA,CAAQ,OAAA"}

package/dist/loader/index.mjs

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/loader/index.ts
+/**
+* AFS Provider Dynamic Loader
+*
+* Provides utilities for dynamically loading AFS providers at runtime.
+*
+* @example
+* ```typescript
+* import { loadProvider, getProviderSchema } from "@aigne/afs/loader";
+*
+* // Load a provider with configuration
+* const fs = await loadProvider("@aigne/afs-fs", {
+*   config: { localPath: "./data" },
+*   basePath: "/path/to/config/dir"
+* });
+*
+* // Get provider schema for validation
+* const schema = await getProviderSchema("@aigne/afs-fs");
+* ```
+*/
+/**
+* Resolve a package specifier to an importable path.
+* If the specifier is a directory path (e.g. from npm install),
+* read its package.json to find the ESM entry point.
+* We must use the ESM (.mjs) entry, not CJS (.cjs), because
+* importing CJS from ESM wraps module.exports in an extra default layer
+* which breaks the expected export shape.
+*/
+function resolveImportPath(specifier) {
+	if (!specifier.startsWith("/")) return specifier;
+	const pkgJsonPath = join(specifier, "package.json");
+	if (!existsSync(pkgJsonPath)) return specifier;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+		const esmEntry = typeof pkg.exports === "object" && pkg.exports["."]?.import || pkg.module;
+		if (esmEntry) return join(specifier, esmEntry);
+		if (pkg.main) return join(specifier, pkg.main);
+	} catch {}
+	return specifier;
+}
+/**
+* Dynamically load an AFS Provider from a package.
+*
+* @param packageName - Package name or subpath (e.g., "@aigne/afs-fs" or "@aigne/afs-cloud/s3")
+* @param options - Load options (optional)
+* @returns Provider instance
+*
+* @throws Error if package doesn't exist or doesn't export a valid AFS Provider
+*
+* @example
+* ```typescript
+* const fs = await loadProvider("@aigne/afs-fs", {
+*   config: { localPath: "./data" },
+*   basePath: "/path/to/config/dir"
+* });
+* ```
+*/
+async function loadProvider(packageName, options) {
+	const importPath = resolveImportPath(packageName);
+	let module;
+	try {
+		module = await import(importPath);
+	} catch (error) {
+		throw new Error(`Failed to import package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ProviderClass = module.default;
+	if (!ProviderClass || typeof ProviderClass.load !== "function") throw new Error(`Package "${packageName}" does not export a valid AFS Provider. Expected default export with static load() method.`);
+	return ProviderClass.load(options ?? {});
+}
+/**
+* Get the configuration schema for an AFS Provider without creating an instance.
+*
+* Useful for:
+* - Configuration validation
+* - Documentation generation
+* - IDE integration
+*
+* @param packageName - Package name or subpath
+* @returns Zod schema for the provider's configuration
+*
+* @throws Error if package doesn't export schema() method
+*
+* @example
+* ```typescript
+* const schema = await getProviderSchema("@aigne/afs-fs");
+* const result = schema.safeParse(config);
+* if (!result.success) {
+*   console.error(result.error);
+* }
+* ```
+*/
+async function getProviderSchema(packageName) {
+	const importPath = resolveImportPath(packageName);
+	let module;
+	try {
+		module = await import(importPath);
+	} catch (error) {
+		throw new Error(`Failed to import package "${packageName}": ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ProviderClass = module.default;
+	if (!ProviderClass || typeof ProviderClass.schema !== "function") throw new Error(`Package "${packageName}" does not export schema() method.`);
+	return ProviderClass.schema();
+}
+
+//#endregion
+export { getProviderSchema, loadProvider };
+//# sourceMappingURL=index.mjs.map