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

package/dist/afs.mjs

@@ -0,0 +1,1331 @@
+import { AFSMountError, AFSNotFoundError, AFSReadonlyError, AFSValidationError } from "./error.mjs";
+import { isCanonicalPath, parseCanonicalPath, validateModuleName, validatePath } from "./path.mjs";
+import { v7 } from "@aigne/uuid";
+import { joinURL } from "ufo";
+
+//#region src/afs.ts
+const DEFAULT_MAX_DEPTH = 1;
+const MODULES_ROOT_DIR = "/modules";
+/**
+* Default timeout for mount check operations (10 seconds)
+*/
+const DEFAULT_MOUNT_TIMEOUT = 1e4;
+/**
+* Execute a promise with a timeout.
+* Throws an error if the promise does not resolve within the timeout.
+*/
+async function withTimeout(promise, ms) {
+	let timeoutId;
+	const timeoutPromise = new Promise((_, reject) => {
+		timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Timeout after ${ms}ms`)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeoutPromise]);
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+/**
+* Get the timeout value for a provider.
+* Returns provider.timeout if set, otherwise DEFAULT_MOUNT_TIMEOUT.
+*/
+function getTimeout(provider) {
+	return provider.timeout ?? DEFAULT_MOUNT_TIMEOUT;
+}
+/**
+* Get error message from an error, handling timeout specially.
+*/
+function getMountErrorMessage(err, timeout) {
+	if (err instanceof Error) {
+		if (err.message.includes("Timeout")) return `Timeout after ${timeout}ms`;
+		return err.message;
+	}
+	return String(err);
+}
+/**
+* Characters forbidden in namespace names (security-sensitive)
+*/
+const NAMESPACE_FORBIDDEN_CHARS = [
+	"/",
+	"\\",
+	":",
+	";",
+	"|",
+	"&",
+	"`",
+	"$",
+	"(",
+	")",
+	">",
+	"<",
+	"\n",
+	"\r",
+	"	",
+	"\0"
+];
+/**
+* Validate a namespace name for mount operations
+* @throws Error if namespace is invalid
+*/
+function validateNamespaceName(namespace) {
+	if (namespace.trim() === "") throw new Error("Namespace cannot be empty or whitespace-only");
+	for (const char of NAMESPACE_FORBIDDEN_CHARS) if (namespace.includes(char)) throw new Error(`Namespace contains forbidden character: '${char}'`);
+}
+var AFS = class {
+	name = "AFSRoot";
+	/**
+	* Injectable method for loading and mounting a provider from a URI.
+	* Injected by CLI layer (afs-loader.ts) with full pipeline:
+	*   1. ProviderRegistry.createProvider({ uri, path, ...options }) → provider instance
+	*   2. afs.mount(provider, path)
+	*
+	* Used by root-level /.actions/mount action and registry mount action.
+	*/
+	loadProvider;
+	/**
+	* Injectable callback for removing a provider's config on unmount.
+	* Injected by CLI layer (afs-loader.ts) for persistence sync.
+	*/
+	unloadProvider;
+	/**
+	* Injectable callback for updating a provider's options in the config file.
+	* Injected by CLI layer (afs-loader.ts) for persistence sync.
+	* Used by providers to persist runtime config changes (e.g., default model selection).
+	*/
+	updateProviderConfig;
+	constructor(options = {}) {
+		this.options = options;
+		for (const module of options?.modules ?? []) this.mount(module, joinURL(MODULES_ROOT_DIR, module.name));
+	}
+	/**
+	* Internal storage: Map<compositeKey, MountEntry>
+	* compositeKey = `${namespace ?? ""}:${path}`
+	*/
+	mounts = /* @__PURE__ */ new Map();
+	/**
+	* Legacy compatibility: Map<path, AFSModule> for modules mounted via old API
+	* This is used internally by findModules for backward compatibility
+	*/
+	get modules() {
+		const map = /* @__PURE__ */ new Map();
+		for (const entry of this.mounts.values()) if (entry.namespace === null) map.set(entry.path, entry.module);
+		return map;
+	}
+	/**
+	* Create composite key for mount storage
+	*/
+	makeKey(namespace, path) {
+		return `${namespace ?? ""}:${path}`;
+	}
+	/**
+	* Check if write operations are allowed for the given module.
+	* Throws AFSReadonlyError if not allowed.
+	*/
+	/** Fire-and-forget change notification */
+	notifyChange(record) {
+		try {
+			this.options.onChange?.(record);
+		} catch {}
+	}
+	checkWritePermission(module, operation, path) {
+		if (module.accessMode !== "readwrite") throw new AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
+	}
+	/**
+	* Check provider availability on mount.
+	* Validates that the provider can successfully respond to stat/read
+	* and list (if childrenCount indicates children exist).
+	*
+	* @throws AFSMountError if validation fails
+	*/
+	async checkProviderOnMount(provider) {
+		const timeout = getTimeout(provider);
+		const name = provider.name;
+		let rootData;
+		if (provider.stat) try {
+			rootData = (await withTimeout(provider.stat("/"), timeout)).data;
+		} catch (err) {
+			throw new AFSMountError(name, "stat", getMountErrorMessage(err, timeout));
+		}
+		else if (provider.read) try {
+			const result = await withTimeout(provider.read("/"), timeout);
+			if (result.data) rootData = {
+				path: result.data.path,
+				meta: result.data.meta ?? void 0
+			};
+		} catch (err) {
+			throw new AFSMountError(name, "read", getMountErrorMessage(err, timeout));
+		}
+		else throw new AFSMountError(name, "read", "Provider has no stat or read method");
+		if (!rootData) throw new AFSMountError(name, provider.stat ? "stat" : "read", "Root path returned undefined data");
+		const childrenCount = rootData.meta?.childrenCount;
+		if (childrenCount === -1 || typeof childrenCount === "number" && childrenCount > 0) {
+			if (!provider.list) throw new AFSMountError(name, "list", "Provider has childrenCount but no list method");
+			try {
+				const listResult = await withTimeout(provider.list("/"), timeout);
+				if (!listResult.data || listResult.data.length === 0) throw new AFSMountError(name, "list", "childrenCount indicates children but list returned empty");
+			} catch (err) {
+				if (err instanceof AFSMountError) throw err;
+				throw new AFSMountError(name, "list", getMountErrorMessage(err, timeout));
+			}
+		}
+	}
+	/**
+	* Mount a module at a path in a namespace
+	*
+	* @param module - The module to mount
+	* @param path - The path to mount at (optional, defaults to /modules/{module.name} for backward compatibility)
+	* @param options - Mount options (namespace, replace)
+	*/
+	async mount(module, path, options) {
+		validateModuleName(module.name);
+		const normalizedPath = validatePath(path ?? joinURL(MODULES_ROOT_DIR, module.name));
+		const namespace = options?.namespace === void 0 ? null : options.namespace;
+		if (namespace !== null) {
+			if (namespace === "") throw new Error("Namespace cannot be empty or whitespace-only");
+			validateNamespaceName(namespace);
+		}
+		const key = this.makeKey(namespace, normalizedPath);
+		if (this.mounts.has(key)) if (options?.replace) this.mounts.delete(key);
+		else throw new Error(`Mount conflict: path '${normalizedPath}' already mounted in namespace '${namespace ?? "default"}'`);
+		for (const entry of this.mounts.values()) {
+			if (entry.namespace !== namespace) continue;
+			const existingPath = entry.path;
+			if (normalizedPath === "/" || existingPath === "/") throw new Error(`Mount conflict: path '${normalizedPath}' conflicts with existing mount '${existingPath}' in namespace '${namespace ?? "default"}'`);
+			if (existingPath.startsWith(normalizedPath) && (existingPath === normalizedPath || existingPath.length === normalizedPath.length || existingPath[normalizedPath.length] === "/")) throw new Error(`Mount conflict: path '${normalizedPath}' conflicts with existing mount '${existingPath}' in namespace '${namespace ?? "default"}'`);
+			if (normalizedPath.startsWith(existingPath) && (normalizedPath === existingPath || normalizedPath.length === existingPath.length || normalizedPath[existingPath.length] === "/")) throw new Error(`Mount conflict: path '${normalizedPath}' conflicts with existing mount '${existingPath}' in namespace '${namespace ?? "default"}'`);
+		}
+		await this.checkProviderOnMount(module);
+		this.mounts.set(key, {
+			namespace,
+			path: normalizedPath,
+			module
+		});
+		module.onMount?.(this, normalizedPath);
+		this.notifyChange({
+			kind: "mount",
+			path: normalizedPath,
+			moduleName: module.name,
+			namespace,
+			timestamp: Date.now()
+		});
+		return this;
+	}
+	/**
+	* Get all mounts, optionally filtered by namespace
+	*
+	* @param namespace - Filter by namespace (undefined = all, null = default only)
+	*/
+	getMounts(namespace) {
+		const result = [];
+		for (const entry of this.mounts.values()) if (namespace === void 0 || entry.namespace === namespace) result.push({
+			namespace: entry.namespace,
+			path: entry.path,
+			module: entry.module
+		});
+		return result;
+	}
+	/**
+	* Get all unique namespaces that have mounts
+	*/
+	getNamespaces() {
+		const namespaces = /* @__PURE__ */ new Set();
+		for (const entry of this.mounts.values()) namespaces.add(entry.namespace);
+		return Array.from(namespaces);
+	}
+	/**
+	* Unmount a module at a path in a namespace
+	*
+	* @param path - The path to unmount
+	* @param namespace - The namespace (undefined/null for default namespace)
+	* @returns true if unmounted, false if not found
+	*/
+	unmount(path, namespace) {
+		const normalizedPath = validatePath(path);
+		const ns = namespace === void 0 ? null : namespace;
+		const key = this.makeKey(ns, normalizedPath);
+		const entry = this.mounts.get(key);
+		if (entry) {
+			this.mounts.delete(key);
+			this.notifyChange({
+				kind: "unmount",
+				path: normalizedPath,
+				moduleName: entry.module.name,
+				namespace: entry.namespace,
+				timestamp: Date.now()
+			});
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Check if a path is mounted in a namespace
+	*
+	* @param path - The path to check
+	* @param namespace - The namespace (undefined/null for default namespace)
+	*/
+	isMounted(path, namespace) {
+		const normalizedPath = validatePath(path);
+		const ns = namespace === void 0 ? null : namespace;
+		const key = this.makeKey(ns, normalizedPath);
+		return this.mounts.has(key);
+	}
+	async listModules() {
+		return Array.from(this.mounts.values()).map((entry) => ({
+			path: entry.path,
+			namespace: entry.namespace,
+			name: entry.module.name,
+			description: entry.module.description,
+			module: entry.module
+		}));
+	}
+	/**
+	* Parse a path and extract namespace if it's a canonical path
+	* Returns the namespace and the path within the namespace
+	*/
+	parsePathWithNamespace(inputPath) {
+		if (isCanonicalPath(inputPath)) {
+			const parsed = parseCanonicalPath(inputPath);
+			return {
+				namespace: parsed.namespace,
+				path: parsed.path
+			};
+		}
+		return {
+			namespace: null,
+			path: validatePath(inputPath)
+		};
+	}
+	/**
+	* Find modules that can handle a path in a specific namespace
+	*/
+	findModulesInNamespace(path, namespace, options) {
+		const maxDepth = Math.max(options?.maxDepth ?? DEFAULT_MAX_DEPTH, 1);
+		const matched = [];
+		for (const entry of this.mounts.values()) {
+			if (entry.namespace !== namespace) continue;
+			const modulePath = entry.path;
+			const module = entry.module;
+			const pathSegments = path.split("/").filter(Boolean);
+			const modulePathSegments = modulePath.split("/").filter(Boolean);
+			let newMaxDepth;
+			let subpath;
+			let remainedModulePath;
+			const moduleUnderPath = !options?.exactMatch && modulePath.startsWith(path) && (modulePath === path || path === "/" || modulePath[path.length] === "/");
+			const pathUnderModule = path.startsWith(modulePath) && (path === modulePath || modulePath === "/" || path[modulePath.length] === "/");
+			if (moduleUnderPath) {
+				newMaxDepth = Math.max(0, maxDepth - (modulePathSegments.length - pathSegments.length));
+				subpath = "/";
+				remainedModulePath = joinURL("/", ...modulePathSegments.slice(pathSegments.length).slice(0, maxDepth));
+			} else if (pathUnderModule) {
+				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 list(path, options = {}) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (normalizedPath === "/.actions" && namespace === null) return this.listRootActions();
+		return await this._list(normalizedPath, namespace, options);
+	}
+	async _list(path, namespace, options = {}) {
+		if (options?.maxDepth === 0) return { data: [] };
+		const results = [];
+		const hasModulesMounts = namespace === null && [...this.mounts.values()].some((m) => m.namespace === null && m.path.startsWith(`${MODULES_ROOT_DIR}/`));
+		if (path === "/" && hasModulesMounts) {
+			const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+			let moduleCount = 0;
+			for (const entry of this.mounts.values()) if (entry.namespace === namespace) moduleCount++;
+			results.push({
+				id: "modules",
+				path: MODULES_ROOT_DIR,
+				summary: "All mounted modules",
+				meta: {
+					childrenCount: moduleCount,
+					description: "All mounted modules"
+				}
+			});
+			if (maxDepth === 1) return { data: results };
+			const childrenResult = await this._list(MODULES_ROOT_DIR, namespace, {
+				...options,
+				maxDepth: maxDepth - 1
+			});
+			results.push(...childrenResult.data);
+			return { data: results };
+		}
+		const matches = this.findModulesInNamespace(path, namespace, options);
+		if (matches.length === 0) return { data: results };
+		const virtualDirs = /* @__PURE__ */ new Map();
+		for (const matched of matches) {
+			if (matched.maxDepth === 0) {
+				const truncatedPath = joinURL(path, matched.remainedModulePath);
+				if (truncatedPath === matched.modulePath) {
+					const moduleEntry = {
+						id: matched.module.name,
+						path: matched.modulePath,
+						summary: matched.module.description,
+						meta: {
+							childrenCount: -1,
+							description: matched.module.description
+						}
+					};
+					results.push(moduleEntry);
+				} else virtualDirs.set(truncatedPath, (virtualDirs.get(truncatedPath) ?? 0) + 1);
+				continue;
+			}
+			if (!matched.module.list) {
+				if (matched.module.read) try {
+					const childrenCount = (await matched.module.read(matched.subpath)).data?.meta?.childrenCount;
+					if (childrenCount === void 0 || childrenCount === 0) continue;
+					throw new Error(`Provider '${matched.module.name}' has childrenCount=${childrenCount} but does not implement list(). Providers with children must implement the list() method.`);
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("does not implement list")) throw error;
+					continue;
+				}
+				continue;
+			}
+			try {
+				const result = await matched.module.list(matched.subpath, {
+					...options,
+					maxDepth: matched.maxDepth
+				});
+				const children = result.data.map((entry) => ({
+					...entry,
+					path: joinURL(matched.modulePath, entry.path)
+				}));
+				results.push(...children);
+				if (result.message && children.length === 0) return {
+					data: results,
+					message: result.message
+				};
+			} catch (error) {
+				throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
+			}
+		}
+		for (const [dirPath] of virtualDirs) {
+			const dirName = dirPath.split("/").filter(Boolean).pop() || "";
+			results.push({
+				id: dirName,
+				path: dirPath,
+				meta: { childrenCount: -1 }
+			});
+		}
+		return { data: results };
+	}
+	/**
+	* Check if a path should skip auto-enrichment.
+	* Paths ending with /.meta or /.actions should not be enriched
+	* to avoid recursive fetches, but their children (e.g., /.meta/kinds)
+	* can still be enriched.
+	*/
+	shouldSkipEnrich(path) {
+		return path.endsWith("/.meta") || path.endsWith("/.actions");
+	}
+	/**
+	* Fetch actions for a path by listing path/.actions.
+	* Returns ActionSummary[] on success, [] on failure.
+	*/
+	async fetchActions(module, subpath) {
+		try {
+			const actionsPath = joinURL(subpath, ".actions");
+			const result = await module.list?.(actionsPath);
+			if (!result?.data) return [];
+			return result.data.filter((entry) => entry.meta?.kind === "afs:executable").map((entry) => ({
+				name: entry.id,
+				description: entry.meta?.description,
+				inputSchema: entry.meta?.inputSchema
+			}));
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Fetch meta for a path by reading path/.meta.
+	* Returns the meta content on success, null on failure.
+	*/
+	async fetchMeta(module, subpath) {
+		try {
+			const metaPath = joinURL(subpath, ".meta");
+			const result = await module.read?.(metaPath);
+			if (!result?.data?.content) return null;
+			const content = result.data.content;
+			if (typeof content === "object" && content !== null && !Array.isArray(content)) return content;
+			return null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Type for data that can be enriched (has path, optional actions, optional meta)
+	*/
+	async enrichData(data, module, subpath) {
+		if (this.shouldSkipEnrich(subpath)) return data;
+		const result = { ...data };
+		const enrichPromises = [];
+		if (result.actions === void 0) enrichPromises.push(this.fetchActions(module, subpath).then((actions) => {
+			result.actions = actions;
+		}));
+		if (result.meta?.kind === void 0) enrichPromises.push(this.fetchMeta(module, subpath).then((meta) => {
+			if (meta) result.meta = {
+				...result.meta,
+				...meta
+			};
+		}));
+		await Promise.all(enrichPromises);
+		return result;
+	}
+	async read(path, _options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (namespace === null) {
+			if (normalizedPath.startsWith("/.actions/")) return this.readRootAction(normalizedPath);
+			if (normalizedPath === "/.actions") return this.readRootActions();
+			if (normalizedPath === "/.meta") return this.readRootMeta();
+		}
+		if (normalizedPath === "/.meta/.capabilities") return { data: {
+			id: ".capabilities",
+			path: "/.meta/.capabilities",
+			content: await this.aggregateCapabilities(namespace),
+			meta: { kind: "afs:capabilities" }
+		} };
+		const modules = this.findModulesInNamespace(normalizedPath, namespace, { exactMatch: true });
+		for (const { module, modulePath, subpath } of modules) {
+			const res = await module.read?.(subpath);
+			if (res?.data) {
+				const enrichedData = await this.enrichData(res.data, module, subpath);
+				return {
+					...res,
+					data: {
+						...enrichedData,
+						path: joinURL(modulePath, res.data.path)
+					}
+				};
+			}
+		}
+		const virtualDir = this.resolveVirtualDirectory(normalizedPath, namespace);
+		if (virtualDir) return virtualDir;
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* Check if a path is a virtual intermediate directory.
+	* Returns a read result if the path is a parent of one or more mount paths.
+	*/
+	resolveVirtualDirectory(path, namespace) {
+		const pathSegments = path.split("/").filter(Boolean);
+		const childNames = /* @__PURE__ */ new Set();
+		for (const entry of this.mounts.values()) {
+			if (entry.namespace !== namespace) continue;
+			const moduleSegments = entry.path.split("/").filter(Boolean);
+			if (moduleSegments.length <= pathSegments.length) continue;
+			let match = true;
+			for (let i = 0; i < pathSegments.length; i++) if (moduleSegments[i] !== pathSegments[i]) {
+				match = false;
+				break;
+			}
+			if (match) childNames.add(moduleSegments[pathSegments.length]);
+		}
+		if (childNames.size === 0) return null;
+		return { data: {
+			id: pathSegments[pathSegments.length - 1] || "/",
+			path,
+			meta: { childrenCount: childNames.size }
+		} };
+	}
+	/**
+	* Aggregate capabilities from all mounted providers.
+	*
+	* For each provider:
+	* - Read /.meta/.capabilities
+	* - Merge tools with provider prefix and mount path prefix
+	* - Merge actions with mount path prefix on discovery.pathTemplate
+	* - Silently skip providers that fail or don't implement capabilities
+	*/
+	async aggregateCapabilities(namespace) {
+		const allTools = [];
+		const allActions = [];
+		const skipped = [];
+		const allOperations = [];
+		const mounts = this.getMounts(namespace);
+		for (const mount of mounts) {
+			const { path: mountPath, module: provider } = mount;
+			try {
+				const content = (await provider.read?.("/.meta/.capabilities"))?.data?.content;
+				if (!content) continue;
+				const manifest = content;
+				for (const tool of manifest.tools ?? []) allTools.push({
+					...tool,
+					name: `${manifest.provider}.${tool.name}`,
+					path: joinURL(mountPath, tool.path)
+				});
+				for (const actionCatalog of manifest.actions ?? []) allActions.push({
+					...actionCatalog,
+					discovery: {
+						...actionCatalog.discovery,
+						pathTemplate: joinURL(mountPath, actionCatalog.discovery.pathTemplate)
+					}
+				});
+				if (manifest.operations) allOperations.push(manifest.operations);
+			} catch {
+				skipped.push(mountPath);
+			}
+		}
+		const result = {
+			schemaVersion: 1,
+			provider: "afs",
+			description: "AFS aggregated capabilities",
+			tools: allTools,
+			actions: allActions
+		};
+		if (allOperations.length > 0) result.operations = {
+			read: allOperations.some((o) => o.read),
+			list: allOperations.some((o) => o.list),
+			write: allOperations.some((o) => o.write),
+			delete: allOperations.some((o) => o.delete),
+			search: allOperations.some((o) => o.search),
+			exec: allOperations.some((o) => o.exec),
+			stat: allOperations.some((o) => o.stat),
+			explain: allOperations.some((o) => o.explain)
+		};
+		if (skipped.length > 0) {
+			result.partial = true;
+			result.skipped = skipped;
+		}
+		return result;
+	}
+	async write(path, content, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		const module = this.findModulesInNamespace(normalizedPath, namespace, { exactMatch: true })[0];
+		if (!module?.module.write) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
+		this.checkWritePermission(module.module, "write", path);
+		const res = await module.module.write(module.subpath, content, options);
+		const result = {
+			...res,
+			data: {
+				...res.data,
+				path: joinURL(module.modulePath, res.data.path)
+			}
+		};
+		this.notifyChange({
+			kind: "write",
+			path: result.data.path,
+			moduleName: module.module.name,
+			timestamp: Date.now()
+		});
+		return result;
+	}
+	async delete(path, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		const module = this.findModulesInNamespace(normalizedPath, namespace, { exactMatch: true })[0];
+		if (!module?.module.delete) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
+		this.checkWritePermission(module.module, "delete", path);
+		const result = await module.module.delete(module.subpath, options);
+		this.notifyChange({
+			kind: "delete",
+			path: joinURL(module.modulePath, module.subpath),
+			moduleName: module.module.name,
+			timestamp: Date.now()
+		});
+		return result;
+	}
+	async rename(oldPath, newPath, options) {
+		const { namespace: oldNamespace, path: normalizedOldPath } = this.parsePathWithNamespace(oldPath);
+		const { namespace: newNamespace, path: normalizedNewPath } = this.parsePathWithNamespace(newPath);
+		if (oldNamespace !== newNamespace) throw new Error(`Cannot rename across different namespaces.`);
+		const oldModule = this.findModulesInNamespace(normalizedOldPath, oldNamespace, { exactMatch: true })[0];
+		const newModule = this.findModulesInNamespace(normalizedNewPath, newNamespace, { 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);
+		const result = await oldModule.module.rename(oldModule.subpath, newModule.subpath, options);
+		this.notifyChange({
+			kind: "rename",
+			path: joinURL(oldModule.modulePath, oldModule.subpath),
+			moduleName: oldModule.module.name,
+			namespace: oldNamespace,
+			meta: { newPath: joinURL(newModule.modulePath, newModule.subpath) },
+			timestamp: Date.now()
+		});
+		return result;
+	}
+	async search(path, query, options = {}) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		return await this._search(normalizedPath, namespace, query, options);
+	}
+	async _search(path, namespace, query, options) {
+		const results = [];
+		const messages = [];
+		for (const { module, modulePath, subpath } of this.findModulesInNamespace(path, namespace)) {
+			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("; ")
+		};
+	}
+	async exec(path, args, options = {}) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (normalizedPath.startsWith("/.actions/")) return await this.execRootAction(normalizedPath, args);
+		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
+		if (!module?.module.exec) throw new Error(`No module found for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
+		this.checkWritePermission(module.module, "exec", path);
+		await this.validateExecInput(module.module, module.subpath, args);
+		const enhancedOptions = {
+			...options,
+			context: {
+				...options?.context,
+				afs: this
+			}
+		};
+		return await module.module.exec(module.subpath, args, enhancedOptions);
+	}
+	/**
+	* Read a root-level action entry (/.actions/mount, /.actions/unmount).
+	* Returns the action entry with metadata including inputSchema.
+	*/
+	async readRootAction(path) {
+		const actionName = path.slice(10);
+		const { data: actions } = await this.listRootActions();
+		const entry = actions.find((a) => a.id === actionName);
+		if (!entry) throw new AFSNotFoundError(path, `Root action not found: ${actionName}`);
+		const action = entry.actions?.[0];
+		return { data: {
+			...entry,
+			content: {
+				description: action?.description,
+				inputSchema: action?.inputSchema
+			},
+			meta: {
+				...entry.meta,
+				description: action?.description,
+				inputSchema: action?.inputSchema
+			}
+		} };
+	}
+	/**
+	* Read root metadata (/.meta).
+	* Returns mounted providers list, root actions, and childrenCount.
+	*/
+	async readRootMeta() {
+		const mounts = this.getMounts(null);
+		const { data: actions } = await this.listRootActions();
+		const mountedProviders = mounts.map((m) => {
+			const mod = m.module;
+			const operations = [];
+			if (mod.read) operations.push("read");
+			if (mod.list) operations.push("list");
+			if (mod.stat) operations.push("stat");
+			if (mod.write) operations.push("write");
+			if (mod.delete) operations.push("delete");
+			if (mod.search) operations.push("search");
+			if (mod.exec) operations.push("exec");
+			if (mod.explain) operations.push("explain");
+			if (mod.rename) operations.push("rename");
+			return {
+				name: mod.name,
+				path: m.path,
+				description: mod.description,
+				operations
+			};
+		});
+		const rootActions = actions.map((a) => ({
+			name: a.id,
+			description: a.actions?.[0]?.description || a.summary || ""
+		}));
+		return { data: {
+			id: ".meta",
+			path: "/.meta",
+			content: {
+				description: "AFS root metadata",
+				childrenCount: mounts.length,
+				mountedProviders,
+				rootActions
+			},
+			meta: { kind: "afs:meta" }
+		} };
+	}
+	/**
+	* Read root actions directory (/.actions).
+	* Returns content with actions list.
+	*/
+	async readRootActions() {
+		const { data: actions } = await this.listRootActions();
+		return { data: {
+			id: ".actions",
+			path: "/.actions",
+			content: { actions: actions.map((a) => ({
+				name: a.id,
+				path: a.path,
+				description: a.actions?.[0]?.description || a.summary || ""
+			})) },
+			meta: {
+				kind: "afs:directory",
+				childrenCount: actions.length
+			}
+		} };
+	}
+	/**
+	* Stat a root action path (/.actions or /.actions/{name}).
+	*/
+	async statRootAction(path) {
+		if (path === "/.actions") {
+			const { data: actions } = await this.listRootActions();
+			return { data: {
+				id: ".actions",
+				path: "/.actions",
+				meta: {
+					kind: "afs:directory",
+					childrenCount: actions.length
+				}
+			} };
+		}
+		const readResult = await this.readRootAction(path);
+		if (readResult.data) {
+			const { content: _content, ...statData } = readResult.data;
+			return { data: statData };
+		}
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* Stat a root meta path (/.meta or /.meta/{subpath}).
+	*/
+	async statRootMeta(path) {
+		if (path === "/.meta") return { data: {
+			id: ".meta",
+			path: "/.meta",
+			meta: {
+				kind: "afs:meta",
+				childrenCount: 1
+			}
+		} };
+		if (path === "/.meta/.capabilities") return { data: {
+			id: ".capabilities",
+			path: "/.meta/.capabilities",
+			meta: { kind: "afs:capabilities" }
+		} };
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* List root-level actions (/.actions).
+	*/
+	async listRootActions() {
+		const actions = [];
+		if (this.loadProvider) actions.push({
+			id: "mount",
+			path: "/.actions/mount",
+			summary: "Mount a new provider",
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"]
+			},
+			actions: [{
+				name: "mount",
+				description: "Mount a provider from URI",
+				inputSchema: {
+					type: "object",
+					properties: {
+						uri: {
+							type: "string",
+							description: "Provider URI"
+						},
+						path: {
+							type: "string",
+							description: "Mount path"
+						},
+						accessMode: {
+							type: "string",
+							enum: ["readonly", "readwrite"],
+							description: "Access mode (default: readonly)"
+						},
+						auth: {
+							type: "string",
+							description: "Authentication token"
+						},
+						description: {
+							type: "string",
+							description: "Human-readable description"
+						},
+						scope: {
+							type: "string",
+							enum: [
+								"cwd",
+								"project",
+								"user"
+							],
+							description: "Where to persist the mount config. 'cwd' (default) = current directory, 'project' = project root (.git), 'user' = user home"
+						},
+						sensitiveArgs: {
+							type: "array",
+							items: { type: "string" },
+							description: "Field names that should be treated as sensitive credentials (stored in credentials.toml instead of config.toml)"
+						}
+					},
+					required: ["uri", "path"]
+				}
+			}]
+		});
+		actions.push({
+			id: "unmount",
+			path: "/.actions/unmount",
+			summary: "Unmount a provider",
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"]
+			},
+			actions: [{
+				name: "unmount",
+				description: "Unmount a provider at a given path",
+				inputSchema: {
+					type: "object",
+					properties: {
+						path: {
+							type: "string",
+							description: "Path to unmount"
+						},
+						scope: {
+							type: "string",
+							enum: [
+								"cwd",
+								"project",
+								"user"
+							],
+							description: "Config scope to remove mount from. If omitted, searches all scopes."
+						}
+					},
+					required: ["path"]
+				}
+			}]
+		});
+		return { data: actions };
+	}
+	/**
+	* Handle root-level action execution (/.actions/*).
+	* Supports:
+	* - /.actions/mount: Load and mount a provider via loadProvider
+	* - /.actions/unmount: Unmount a provider at a given path
+	*/
+	async execRootAction(path, args) {
+		const actionName = path.slice(10);
+		if (actionName === "mount") return await this.execRootMountAction(args);
+		if (actionName === "unmount") return await this.execRootUnmountAction(args);
+		throw new AFSNotFoundError(path, `Root action not found: ${actionName}`);
+	}
+	/**
+	* Execute root-level mount action.
+	* Validates input and delegates to loadProvider.
+	*/
+	async execRootMountAction(args) {
+		if (typeof args.uri !== "string" || args.uri === "") throw new AFSValidationError("Input validation failed: uri: must be a non-empty string");
+		if (typeof args.path !== "string" || args.path === "") throw new AFSValidationError("Input validation failed: path: must be a non-empty string");
+		if (!this.loadProvider) throw new Error("loadProvider not configured");
+		const { uri, path, sensitiveArgs, ...options } = args;
+		if (Array.isArray(sensitiveArgs) && sensitiveArgs.length > 0) options._sensitiveArgs = sensitiveArgs;
+		await this.loadProvider(uri, path, Object.keys(options).length > 0 ? options : void 0);
+		return {
+			success: true,
+			data: {
+				uri,
+				path
+			}
+		};
+	}
+	/**
+	* Execute root-level unmount action.
+	* Validates input and delegates to unmount().
+	*/
+	async execRootUnmountAction(args) {
+		if (typeof args.path !== "string" || args.path === "") throw new AFSValidationError("Input validation failed: path: must be a non-empty string");
+		if (!this.unmount(args.path)) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `No provider mounted at ${args.path}`
+			}
+		};
+		if (this.unloadProvider) try {
+			const { path: _path, ...options } = args;
+			await this.unloadProvider(args.path, Object.keys(options).length > 0 ? options : void 0);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.warn(`[unmount] config persistence failed: ${msg}`);
+		}
+		return {
+			success: true,
+			data: { path: args.path }
+		};
+	}
+	/**
+	* Validate exec input args against inputSchema.
+	* Throws AFSValidationError if validation fails.
+	* Uses zod-from-json-schema for full JSON Schema validation.
+	*/
+	async validateExecInput(module, subpath, args) {
+		let inputSchema;
+		if (module.read) try {
+			inputSchema = (await module.read(subpath)).data?.meta?.inputSchema;
+		} catch {
+			return;
+		}
+		if (!inputSchema) return;
+		try {
+			const { convertJsonSchemaToZod } = await import("zod-from-json-schema");
+			const testResult = convertJsonSchemaToZod(inputSchema).safeParse(args);
+			if (!testResult.success) {
+				if (testResult.error.issues.some((issue) => issue.message === "Invalid input: expected never, received object" || issue.message.startsWith("Invalid input: expected never"))) return;
+				throw new AFSValidationError(`Input validation failed: ${testResult.error.issues.map((issue) => {
+					const path = issue.path.join(".");
+					return path ? `${path}: ${issue.message}` : issue.message;
+				}).join("; ")}`);
+			}
+		} catch (error) {
+			if (error instanceof AFSValidationError) throw error;
+		}
+	}
+	/**
+	* Get stat information for a path
+	*
+	* Resolution order:
+	* 1. Provider's stat() method (if implemented)
+	* 2. Fallback to read() - extracts stat data from AFSEntry
+	*
+	* This allows providers to implement only read() while stat() still works.
+	*/
+	async stat(path, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (namespace === null) {
+			if (normalizedPath === "/.actions" || normalizedPath.startsWith("/.actions/")) return this.statRootAction(normalizedPath);
+			if (normalizedPath === "/.meta" || normalizedPath.startsWith("/.meta/")) return this.statRootMeta(normalizedPath);
+		}
+		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
+		if (!module) {
+			const virtualDir = this.resolveVirtualDirectory(normalizedPath, namespace);
+			if (virtualDir?.data) return { data: virtualDir.data };
+			try {
+				const readResult = await this.read(path);
+				if (readResult.data) {
+					const { content: _content, ...statData } = readResult.data;
+					return { data: statData };
+				}
+			} catch {}
+			throw new AFSNotFoundError(path);
+		}
+		if (module.remainedModulePath !== "/") {
+			const virtualDir = this.resolveVirtualDirectory(normalizedPath, namespace);
+			if (virtualDir?.data) return { data: virtualDir.data };
+		}
+		if (module.module.stat) try {
+			const result = await module.module.stat(module.subpath, options);
+			if (result.data) {
+				const enrichedData = await this.enrichData(result.data, module.module, module.subpath);
+				return {
+					...result,
+					data: enrichedData
+				};
+			}
+			throw new AFSNotFoundError(path);
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+		}
+		if (module.module.read) {
+			const readResult = await module.module.read(module.subpath, options);
+			if (readResult.data) {
+				const { content: _content, ...statData } = readResult.data;
+				return { data: await this.enrichData(statData, module.module, module.subpath) };
+			}
+		}
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* Get human-readable explanation for a path
+	*
+	* Resolution order:
+	* 1. Provider's explain() method (if implemented)
+	* 2. Fallback to stat() - builds explanation from metadata
+	*
+	* This allows providers to skip implementing explain() while it still works.
+	*/
+	async explain(path, options) {
+		const { namespace, path: normalizedPath } = this.parsePathWithNamespace(path);
+		if (namespace === null) {
+			if (normalizedPath === "/") return this.explainRoot();
+			if (normalizedPath === "/.actions" || normalizedPath.startsWith("/.actions/")) return this.explainRootAction(normalizedPath);
+			if (normalizedPath === "/.meta" || normalizedPath.startsWith("/.meta/")) return this.explainRootMeta(normalizedPath);
+		}
+		const module = this.findModulesInNamespace(normalizedPath, namespace)[0];
+		if (!module) {
+			const virtualDir = this.resolveVirtualDirectory(normalizedPath, namespace);
+			if (virtualDir?.data) return this.buildVirtualDirExplain(normalizedPath, virtualDir.data);
+			try {
+				const statResult$1 = await this.stat(path);
+				if (statResult$1.data) return this.buildExplainFromStat(normalizedPath, statResult$1.data);
+			} catch {}
+			throw new AFSNotFoundError(path);
+		}
+		if (module.remainedModulePath !== "/") {
+			const virtualDir = this.resolveVirtualDirectory(normalizedPath, namespace);
+			if (virtualDir?.data) return this.buildVirtualDirExplain(normalizedPath, virtualDir.data);
+		}
+		if (module.module.explain) try {
+			return await module.module.explain(module.subpath, options);
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+		}
+		const statResult = await this.stat(path, options);
+		if (statResult.data) return this.buildExplainFromStat(normalizedPath, statResult.data);
+		throw new Error(`No explain or stat handler for path: ${normalizedPath} in namespace '${namespace ?? "default"}'`);
+	}
+	/**
+	* Format bytes to human-readable string
+	*/
+	buildVirtualDirExplain(path, data) {
+		const childrenCount = data.meta?.childrenCount;
+		const lines = [];
+		lines.push(`# ${path}`);
+		lines.push("");
+		lines.push("- **Type**: Virtual directory");
+		if (childrenCount !== void 0) lines.push(`- **Children**: ${childrenCount} items`);
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	/**
+	* Explain root path ('/').
+	* Generates a complete navigation guide with 4 required sections.
+	*/
+	async explainRoot() {
+		const lines = [];
+		lines.push("# AFS Root");
+		lines.push("");
+		lines.push("## Mounted Providers");
+		lines.push("");
+		const mounts = this.getMounts(null);
+		if (mounts.length === 0) {
+			lines.push("No providers currently mounted. Use the `mount` action to add providers.");
+			lines.push("");
+		} else {
+			for (const m of mounts) if (m.module.description) {
+				const descLines = m.module.description.split("\n");
+				lines.push(`- **${m.module.name}** (\`${m.path}\`) — ${descLines[0]}`);
+				for (let i = 1; i < descLines.length; i++) lines.push(`  ${descLines[i]}`);
+			} else lines.push(`- **${m.module.name}** (\`${m.path}\`)`);
+			lines.push("");
+		}
+		lines.push("## Standard Operations");
+		lines.push("");
+		lines.push("- **read** — Read file or node content");
+		lines.push("- **list** — List children of a directory or container");
+		lines.push("- **stat** — Get metadata without content");
+		lines.push("- **explain** — Get human-readable documentation for a path");
+		lines.push("- **search** — Search within a mounted provider");
+		lines.push("- **write** — Create or update content");
+		lines.push("- **delete** — Remove a file or node");
+		lines.push("- **exec** — Execute an action at a path");
+		lines.push("");
+		lines.push("## Root Actions");
+		lines.push("");
+		const { data: actions } = await this.listRootActions();
+		for (const action of actions) {
+			const desc = action.actions?.[0]?.description || action.summary || "";
+			lines.push(`- **${action.id}** — ${desc}`);
+		}
+		lines.push("");
+		lines.push("Use `explain('/.actions/<name>')` for detailed usage.");
+		lines.push("");
+		lines.push("## Built-in Systems");
+		lines.push("");
+		lines.push("- **`.meta`** — Metadata for any node. Access via `read('/.meta')` at root, or append `/.meta` to any path.");
+		lines.push("- **`.actions`** — Executable actions. Access via `read('/.actions')` to list, `exec('/.actions/<name>', args)` to run.");
+		lines.push("");
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	/**
+	* Explain a root action path (/.actions or /.actions/{name}).
+	*/
+	async explainRootAction(path) {
+		if (path === "/.actions") {
+			const lines$1 = [];
+			lines$1.push("# Root Actions");
+			lines$1.push("");
+			lines$1.push("Available actions at the AFS root level:");
+			lines$1.push("");
+			const { data: actions$1 } = await this.listRootActions();
+			for (const action$1 of actions$1) {
+				const desc = action$1.actions?.[0]?.description || action$1.summary || "";
+				lines$1.push(`- **${action$1.id}** — ${desc}`);
+			}
+			lines$1.push("");
+			lines$1.push("Use `explain('/.actions/<name>')` for detailed parameters and usage.");
+			return {
+				format: "markdown",
+				content: lines$1.join("\n")
+			};
+		}
+		const actionName = path.slice(10);
+		const { data: actions } = await this.listRootActions();
+		const entry = actions.find((a) => a.id === actionName);
+		if (!entry) throw new AFSNotFoundError(path, `Root action not found: ${actionName}`);
+		const action = entry.actions?.[0];
+		const lines = [];
+		lines.push(`# ${actionName}`);
+		lines.push("");
+		if (action?.description) {
+			lines.push(action.description);
+			lines.push("");
+		}
+		const schema = action?.inputSchema;
+		const properties = schema?.properties;
+		const required = schema?.required || [];
+		if (properties && Object.keys(properties).length > 0) {
+			lines.push("## Parameters");
+			lines.push("");
+			lines.push("| Name | Type | Required | Description |");
+			lines.push("|------|------|----------|-------------|");
+			for (const [name, prop] of Object.entries(properties)) {
+				const type = prop.type || "any";
+				const isRequired = required.includes(name) ? "yes" : "no";
+				const desc = prop.description || "";
+				lines.push(`| ${name} | ${type} | ${isRequired} | ${desc} |`);
+			}
+			lines.push("");
+		}
+		lines.push("## Example");
+		lines.push("");
+		const exampleArgs = {};
+		for (const name of required) exampleArgs[name] = `<${name}>`;
+		lines.push(`\`\`\`\nexec('/.actions/${actionName}', ${JSON.stringify(exampleArgs, null, 2)})\n\`\`\``);
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	/**
+	* Explain a root meta path (/.meta or /.meta/{subpath}).
+	*/
+	async explainRootMeta(path) {
+		if (path === "/.meta") {
+			const lines = [];
+			lines.push("# Root Metadata");
+			lines.push("");
+			lines.push("The `.meta` system provides metadata about any AFS node.");
+			lines.push("");
+			lines.push("## Available Sub-paths");
+			lines.push("");
+			lines.push("- **`.capabilities`** — Aggregated capabilities from all mounted providers");
+			lines.push("");
+			lines.push("Use `read('/.meta')` to get structured root metadata including mounted providers and available actions.");
+			return {
+				format: "markdown",
+				content: lines.join("\n")
+			};
+		}
+		if (path === "/.meta/.capabilities") {
+			const lines = [];
+			lines.push("# Capabilities");
+			lines.push("");
+			lines.push("Aggregated capabilities manifest from all mounted providers.");
+			lines.push("Describes the combined operations, tools, and action catalogs available across the system.");
+			lines.push("");
+			lines.push("Use `read('/.meta/.capabilities')` to get the full structured capabilities data.");
+			return {
+				format: "markdown",
+				content: lines.join("\n")
+			};
+		}
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* Build explain markdown from stat data.
+	* Used by both the module-found fallback and the no-module safety net.
+	*/
+	buildExplainFromStat(path, data) {
+		const lines = [];
+		lines.push(`# ${path}`);
+		lines.push("");
+		const meta = data.meta || {};
+		if (meta.size !== void 0) lines.push(`- **Size**: ${this.formatBytes(meta.size)}`);
+		if (meta.childrenCount !== void 0) lines.push(`- **Children**: ${meta.childrenCount} items`);
+		if (data.updatedAt) lines.push(`- **Modified**: ${data.updatedAt.toISOString()}`);
+		if (meta.description) {
+			lines.push("");
+			lines.push("## Description");
+			lines.push(String(meta.description));
+		}
+		if (meta.provider) lines.push(`- **Provider**: ${meta.provider}`);
+		if (meta.kind) lines.push(`- **Kind**: ${meta.kind}`);
+		if (meta.kinds && Array.isArray(meta.kinds)) lines.push(`- **Kinds**: ${meta.kinds.join(", ")}`);
+		if (data.actions && data.actions.length > 0) {
+			lines.push("");
+			lines.push("## Actions");
+			for (const action of data.actions) lines.push(`- **${action.name}**${action.description ? `: ${action.description}` : ""}`);
+		}
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	formatBytes(bytes) {
+		if (bytes === 0) return "0 B";
+		const k = 1024;
+		const sizes = [
+			"B",
+			"KB",
+			"MB",
+			"GB",
+			"TB"
+		];
+		const i = Math.floor(Math.log(bytes) / Math.log(k));
+		return `${Number.parseFloat((bytes / k ** i).toFixed(2))} ${sizes[i]}`;
+	}
+	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 entry of this.mounts.values()) {
+				const namespacePart = entry.namespace ?? "_default";
+				const physicalModulePath = path.join(rootDir, namespacePart, entry.path);
+				await fs.mkdir(path.dirname(physicalModulePath), { recursive: true });
+				await entry.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 };
+//# sourceMappingURL=afs.mjs.map