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

package/dist/provider/types.d.mts

@@ -0,0 +1,113 @@
+import { AFSExplainResult } from "../meta/type.mjs";
+import { AFSDeleteOptions, AFSDeleteResult, AFSEntry, AFSExecOptions, AFSExecResult, AFSListOptions, AFSReadOptions, AFSRenameResult, AFSSearchOptions, AFSSearchResult, AFSStatResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "../type.mjs";
+
+//#region src/provider/types.d.ts
+/**
+ * Route operation types matching AFSModule methods
+ */
+type RouteOperation = "list" | "read" | "write" | "delete" | "exec" | "search" | "stat" | "explain" | "rename";
+/**
+ * Union type for all possible operation options
+ */
+type RouteOptions = AFSListOptions | AFSReadOptions | AFSWriteOptions | AFSDeleteOptions | AFSExecOptions | AFSSearchOptions;
+/**
+ * Context passed to route handlers
+ *
+ * Note: Wildcard params (e.g., :path*) may be undefined for paths that
+ * don't include that segment (e.g., root paths). Always check for undefined
+ * when using optional wildcard params.
+ */
+interface RouteContext<TParams = Record<string, string | undefined>> {
+  /** The full request path */
+  path: string;
+  /** Parameters extracted from the route pattern */
+  params: TParams;
+  /** Operation options (type depends on operation) */
+  options?: RouteOptions;
+}
+/**
+ * Result type for @List handlers
+ * - data: array of entries
+ * - total: optional, if present indicates complete dataset size
+ *          if absent, data.length IS the total (all data returned)
+ * - noExpand: optional, paths that should not be expanded during BFS depth traversal
+ *             (internal use only, not exposed in public API)
+ */
+interface ListHandlerResult {
+  data: AFSEntry[];
+  total?: number;
+  /** Paths that should not be expanded during BFS (internal, not exposed in public API) */
+  noExpand?: string[];
+}
+/**
+ * Handler function types for each operation
+ */
+type ListRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<ListHandlerResult>;
+type ReadRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSEntry | undefined>;
+type WriteRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, content: AFSWriteEntryPayload) => Promise<AFSWriteResult>;
+type DeleteRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSDeleteResult>;
+type ExecRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, args: Record<string, unknown>) => Promise<AFSExecResult>;
+type SearchRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, query: string, options?: AFSSearchOptions) => Promise<AFSSearchResult>;
+type StatRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSStatResult>;
+type ExplainRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>) => Promise<AFSExplainResult>;
+type RenameRouteHandler<TParams = Record<string, string | undefined>> = (ctx: RouteContext<TParams>, newPath: string) => Promise<AFSRenameResult>;
+/**
+ * Union type for all route handlers
+ */
+type RouteHandler = ListRouteHandler | ReadRouteHandler | WriteRouteHandler | DeleteRouteHandler | ExecRouteHandler | SearchRouteHandler | StatRouteHandler | ExplainRouteHandler | RenameRouteHandler;
+/**
+ * Route definition stored in the router
+ */
+interface RouteDefinition {
+  /** Route pattern (e.g., "/:table/:pk") */
+  pattern: string;
+  /** Operation type */
+  operation: RouteOperation;
+  /** Handler function */
+  handler: RouteHandler;
+  /** Optional description for documentation */
+  description?: string;
+  /** Options specific to list operations */
+  listOptions?: ListDecoratorOptions;
+}
+/**
+ * Options for @List decorator
+ */
+interface ListDecoratorOptions {
+  /**
+   * Whether the handler handles maxDepth recursion itself.
+   * - false (default): Base provider will auto-expand depth via BFS
+   * - true: Handler is responsible for depth traversal
+   *
+   * Most providers can use the default (false) and just return single-level results.
+   * Set to true for providers that need custom depth handling (like S3 with delimiter optimization).
+   */
+  handleDepth?: boolean;
+}
+/**
+ * Metadata stored by decorators for later collection
+ */
+interface RouteMetadata {
+  /** Route pattern */
+  pattern: string;
+  /** Operation type */
+  operation: RouteOperation;
+  /** Method name on the class */
+  methodName: string;
+  /** Optional description */
+  description?: string;
+  /** Options specific to list operations */
+  listOptions?: ListDecoratorOptions;
+}
+/**
+ * Match result from router
+ */
+interface RouteMatch {
+  /** The matched route definition */
+  route: RouteDefinition;
+  /** Extracted parameters (wildcards may be undefined or empty string) */
+  params: Record<string, string | undefined>;
+}
+//#endregion
+export { DeleteRouteHandler, ExecRouteHandler, ExplainRouteHandler, ListDecoratorOptions, ListHandlerResult, ListRouteHandler, ReadRouteHandler, RenameRouteHandler, RouteContext, RouteDefinition, RouteHandler, RouteMatch, RouteMetadata, RouteOperation, SearchRouteHandler, StatRouteHandler, WriteRouteHandler };
+//# sourceMappingURL=types.d.mts.map

package/dist/provider/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/provider/types.ts"],"mappings":";;;;;;;KAqBY,cAAA;;;;KAcA,YAAA,GACR,cAAA,GACA,cAAA,GACA,eAAA,GACA,gBAAA,GACA,cAAA,GACA,gBAAA;AANJ;;;;;;;AAAA,UAeiB,YAAA,WAAuB,MAAA;EATpC;EAWF,IAAA;EAXkB;EAclB,MAAA,EAAQ,OAAA;EAlBN;EAqBF,OAAA,GAAU,YAAA;AAAA;;;;;AARZ;;;;UAmBiB,iBAAA;EACf,IAAA,EAAM,QAAA;EACN,KAAA;EAbsB;EAetB,QAAA;AAAA;;;;KAMU,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,iBAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,QAAA;AAAA,KAED,iBAAA,WAA4B,MAAA,iCACtC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,OAAA,EAAS,oBAAA,KACN,OAAA,CAAQ,cAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,eAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,IAAA,EAAM,MAAA,sBACH,OAAA,CAAQ,aAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,KAAA,UACA,OAAA,GAAU,gBAAA,KACP,OAAA,CAAQ,eAAA;AAAA,KAED,gBAAA,WAA2B,MAAA,iCACrC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,aAAA;AAAA,KAED,mBAAA,WAA8B,MAAA,iCACxC,GAAA,EAAK,YAAA,CAAa,OAAA,MACf,OAAA,CAAQ,gBAAA;AAAA,KAED,kBAAA,WAA6B,MAAA,iCACvC,GAAA,EAAK,YAAA,CAAa,OAAA,GAClB,OAAA,aACG,OAAA,CAAQ,eAAA;;;;KAKD,YAAA,GACR,gBAAA,GACA,gBAAA,GACA,iBAAA,GACA,kBAAA,GACA,gBAAA,GACA,kBAAA,GACA,gBAAA,GACA,mBAAA,GACA,kBAAA;;AArDJ;;UA0DiB,eAAA;EA1DsB;EA4DrC,OAAA;EA3DK;EA8DL,SAAA,EAAW,cAAA;EA7DR;EAgEH,OAAA,EAAS,YAAA;EAhEC;EAmEV,WAAA;EArEqC;EAwErC,WAAA,GAAc,oBAAA;AAAA;;;;UAMC,oBAAA;EA5Ea;AAE9B;;;;;;;EAmFE,WAAA;AAAA;;;;UAMe,aAAA;EAxFG;EA0FlB,OAAA;EAzFG;EA4FH,SAAA,EAAW,cAAA;EA5FQ;EA+FnB,UAAA;EA7FU;EAgGV,WAAA;EAhG2B;EAmG3B,WAAA,GAAc,oBAAA;AAAA;;;;UAMC,UAAA;EAtGL;EAwGV,KAAA,EAAO,eAAA;EA3GqB;EA8G5B,MAAA,EAAQ,MAAA;AAAA"}

package/dist/registry.cjs

@@ -0,0 +1,358 @@
+const require_utils_uri = require('./utils/uri.cjs');
+const require_utils_uri_template = require('./utils/uri-template.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+
+//#region src/registry.ts
+/**
+* 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.
+*/
+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;
+}
+/** Mutex for npm install operations to prevent concurrent installs */
+const npmInstallLocks = /* @__PURE__ */ new Map();
+/**
+* Validate npm package name format.
+* Rejects path traversal and shell metacharacters.
+*/
+function isValidNpmPackageName(name) {
+	if (!name || name.length > 214) return false;
+	if (name.includes("..") || name.startsWith("/") || name.startsWith("\\")) return false;
+	for (const char of [
+		";",
+		"|",
+		"&",
+		"`",
+		"$",
+		"(",
+		")",
+		">",
+		"<",
+		"\n",
+		"\r",
+		"	",
+		"\0"
+	]) if (name.includes(char)) return false;
+	if (name.startsWith("@")) {
+		const parts = name.slice(1).split("/");
+		if (parts.length !== 2 || !parts[0] || !parts[1]) return false;
+	}
+	return true;
+}
+/**
+* Install an npm package if not already present.
+* Uses per-package mutex to prevent concurrent installs.
+*/
+async function npmInstall(packageName, packagesDir) {
+	const existing = npmInstallLocks.get(packageName);
+	if (existing) {
+		await existing;
+		return;
+	}
+	const { mkdir } = await import("node:fs/promises");
+	const installPromise = (async () => {
+		await mkdir(packagesDir, { recursive: true });
+		const { execSync } = await import("node:child_process");
+		try {
+			execSync(`npm install --prefix ${JSON.stringify(packagesDir)} ${JSON.stringify(packageName)}`, {
+				stdio: "pipe",
+				timeout: 12e4
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`Failed to install npm package "${packageName}": ${message}`);
+		}
+	})();
+	npmInstallLocks.set(packageName, installPromise);
+	try {
+		await installPromise;
+	} finally {
+		npmInstallLocks.delete(packageName);
+	}
+}
+/**
+* Get the npm packages install directory (~/.afs-config/packages/).
+*/
+function getNpmPackagesDir() {
+	const os = require("node:os");
+	const { resolve } = require("node:path");
+	return resolve(os.homedir(), ".afs-config", "packages");
+}
+/** How often to check for package updates (24 hours). */
+const UPDATE_CHECK_STALE_MS = 1440 * 60 * 1e3;
+/**
+* Trigger a background npm update if the package hasn't been checked recently.
+* Completely silent — never blocks, never throws, never produces output.
+*/
+function npmUpdateIfStale(packageName, packagesDir) {
+	const checkFile = (0, node_path.join)(packagesDir, ".update-check.json");
+	const now = Date.now();
+	let checks = {};
+	try {
+		checks = JSON.parse((0, node_fs.readFileSync)(checkFile, "utf-8"));
+	} catch {}
+	if (now - (checks[packageName] ?? 0) < UPDATE_CHECK_STALE_MS) return;
+	checks[packageName] = now;
+	try {
+		(0, node_fs.writeFileSync)(checkFile, JSON.stringify(checks, null, 2));
+	} catch {}
+	npmUpdateBackground(packageName, packagesDir).catch(() => {});
+}
+/**
+* Run `npm update` for a single package in the background.
+* Errors are silently swallowed (e.g. no network).
+*/
+async function npmUpdateBackground(packageName, packagesDir) {
+	const { execSync } = await import("node:child_process");
+	try {
+		execSync(`npm update --prefix ${JSON.stringify(packagesDir)} ${JSON.stringify(packageName)}`, {
+			stdio: "ignore",
+			timeout: 12e4
+		});
+	} catch {}
+}
+/**
+* Package name overrides for schemes that don't follow the @aigne/afs-{scheme} convention.
+* Class discovery uses the .manifest() static method — no class name mapping needed.
+*/
+const PACKAGE_OVERRIDES = { https: "@aigne/afs-http" };
+/**
+* Derive the base scheme for compound schemes.
+* e.g. "mcp+stdio" → "mcp", "mcp+http" → "mcp"
+*/
+function baseScheme(scheme) {
+	const plusIdx = scheme.indexOf("+");
+	return plusIdx >= 0 ? scheme.slice(0, plusIdx) : scheme;
+}
+/**
+* Registry of provider factories with unified manifest-driven loading.
+*
+* Loading flow:
+* 1. parseURI → get scheme
+* 2. Check registered factories (workspace, custom) → use directly
+* 3. Resolve package: mount.provider or @aigne/afs-{baseScheme}
+* 4. Import package → get ProviderClass
+* 5. Get manifest from ProviderClass.manifest()
+* 6. Match manifest by scheme (for multi-manifest providers)
+* 7. parseTemplate(uriTemplate, body) → extract path variables
+* 8. Merge params: body vars > query > mount.options
+* 9. Construct provider with merged options
+*/
+var ProviderRegistry = class {
+	factories = /* @__PURE__ */ new Map();
+	/** Register a scheme → factory mapping. Overwrites any existing registration. */
+	register(scheme, factory) {
+		this.factories.set(scheme.toLowerCase(), factory);
+	}
+	/** Check if a scheme has a registered factory. */
+	has(scheme) {
+		return this.factories.has(scheme.toLowerCase());
+	}
+	/**
+	* Get provider metadata (schema, auth, manifest) for a URI.
+	*
+	* Used by CLI credential resolution to get schema and auth method
+	* without constructing the provider.
+	*
+	* Returns null if the provider class can't be loaded (e.g., unknown scheme).
+	*/
+	async getProviderInfo(uri) {
+		try {
+			const parsed = require_utils_uri.parseURI(uri);
+			const base = baseScheme(parsed.scheme);
+			const packageName = PACKAGE_OVERRIDES[base] ?? `@aigne/afs-${base}`;
+			const ProviderClass = await this.importProviderClass(packageName, base);
+			const auth = ProviderClass.auth ? ProviderClass.auth.bind(ProviderClass) : void 0;
+			let manifest = null;
+			if (ProviderClass.manifest) {
+				const manifests = this.getManifests(ProviderClass, packageName);
+				manifest = this.matchManifest(manifests, parsed.scheme, packageName);
+			}
+			let schema = null;
+			if (manifest?.schema) try {
+				const { z } = await import("zod");
+				schema = z.toJSONSchema(manifest.schema);
+			} catch {}
+			if (!schema && ProviderClass.schema) try {
+				const zodSchema = ProviderClass.schema();
+				const { z } = await import("zod");
+				schema = z.toJSONSchema(zodSchema);
+			} catch {}
+			return {
+				schema,
+				auth,
+				manifest
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Create a provider from a mount config.
+	*
+	* Uses registered factory if available, otherwise auto-loads
+	* via manifest-driven resolution.
+	*/
+	async createProvider(mount) {
+		const parsed = require_utils_uri.parseURI(mount.uri);
+		const factory = this.factories.get(parsed.scheme);
+		if (factory) {
+			const provider$1 = await factory(mount, parsed);
+			provider$1.uri = mount.uri;
+			return provider$1;
+		}
+		const provider = await this.autoLoadProvider(mount, parsed);
+		provider.uri = mount.uri;
+		return provider;
+	}
+	/**
+	* Auto-load a provider using the manifest-driven unified flow.
+	*/
+	async autoLoadProvider(mount, parsed) {
+		const base = baseScheme(parsed.scheme);
+		const packageName = PACKAGE_OVERRIDES[base] ?? `@aigne/afs-${base}`;
+		const ProviderClass = await this.importProviderClass(packageName, base);
+		const manifests = this.getManifests(ProviderClass, packageName);
+		const manifest = this.matchManifest(manifests, parsed.scheme, packageName);
+		const templateVars = require_utils_uri_template.parseTemplate(manifest.uriTemplate, parsed.body);
+		const mergedOptions = this.mergeOptions(templateVars, parsed.query, mount);
+		return this.constructProvider(ProviderClass, mount, parsed, mergedOptions, manifest);
+	}
+	/**
+	* Import a provider class from a package name.
+	* Resolution order:
+	* 1. Direct import (works when package is a dependency of the importing module)
+	* 2. createRequire from process.cwd() (works in monorepo dev environments)
+	* 3. npm auto-install to ~/.afs-config/packages/
+	*/
+	async importProviderClass(packageName, scheme, explicitClassName) {
+		let mod;
+		try {
+			mod = await this.resolveAndImport(packageName);
+		} catch {
+			if (!isValidNpmPackageName(packageName)) throw new Error(`Unknown URI scheme "${scheme}": package "${packageName}" not found and name is invalid.`);
+			const packagesDir = getNpmPackagesDir();
+			const { resolve } = await import("node:path");
+			const nodeModulesPath = resolve(packagesDir, "node_modules", ...packageName.split("/"));
+			if (!(0, node_fs.existsSync)(nodeModulesPath)) await npmInstall(packageName, packagesDir);
+			else npmUpdateIfStale(packageName, packagesDir);
+			const importPath = resolveImportPath(nodeModulesPath);
+			try {
+				mod = await import(importPath);
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				throw new Error(`Failed to import provider package "${packageName}" for scheme "${scheme}": ${msg}`);
+			}
+		}
+		if (explicitClassName && mod[explicitClassName]) return mod[explicitClassName];
+		const conventionName = `AFS${scheme.charAt(0).toUpperCase()}${scheme.slice(1).toUpperCase()}`;
+		if (mod[conventionName]) return mod[conventionName];
+		for (const key of Object.keys(mod)) {
+			const val = mod[key];
+			if (typeof val === "function" && key !== "default" && val.manifest) return val;
+		}
+		if (mod.default && typeof mod.default === "function") return mod.default;
+		throw new Error(`Package "${packageName}" does not export a valid AFS Provider class for scheme "${scheme}".`);
+	}
+	/**
+	* Get manifest(s) from a provider class.
+	*/
+	getManifests(ProviderClass, packageName) {
+		if (!ProviderClass.manifest) throw new Error(`Provider class from "${packageName}" does not implement static manifest(). Please add a static manifest() method to the provider class.`);
+		const result = ProviderClass.manifest();
+		return Array.isArray(result) ? result : [result];
+	}
+	/**
+	* Find the matching manifest for a given scheme.
+	* For multi-manifest providers (e.g., MCP with mcp+stdio, mcp+http, mcp+sse),
+	* match by the full scheme from the URI template.
+	*/
+	matchManifest(manifests, scheme, packageName) {
+		if (manifests.length === 1) return manifests[0];
+		for (const m of manifests) try {
+			if (require_utils_uri_template.extractSchemeFromTemplate(m.uriTemplate) === scheme) return m;
+		} catch {}
+		if (manifests.length > 0) return manifests[0];
+		throw new Error(`No matching manifest found for scheme "${scheme}" in package "${packageName}".`);
+	}
+	/**
+	* Merge parameters from multiple sources.
+	* Priority: template vars (from URI body) > query params > mount.options
+	*/
+	mergeOptions(templateVars, query, mount) {
+		const result = {};
+		if (mount.options) Object.assign(result, mount.options);
+		for (const [key, value] of Object.entries(query)) if (value !== "") result[key] = value;
+		for (const [key, value] of Object.entries(templateVars)) if (value !== void 0) result[key] = value;
+		return result;
+	}
+	/**
+	* Construct a provider instance with merged options.
+	*/
+	async constructProvider(ProviderClass, mount, _parsed, mergedOptions, manifest) {
+		const constructorOptions = {
+			...mergedOptions,
+			name: mount.path.slice(1).replace(/\//g, "-") || manifest.name,
+			description: mount.description,
+			accessMode: mount.access_mode,
+			uri: mount.uri
+		};
+		if (mount.auth !== void 0) constructorOptions.auth = mount.auth;
+		if (mount.token !== void 0) constructorOptions.token = mount.token;
+		const provider = new ProviderClass(constructorOptions);
+		if (typeof provider.ready === "function") await provider.ready();
+		return provider;
+	}
+	/**
+	* Resolve and import a package, trying multiple resolution strategies.
+	*
+	* In a monorepo (pnpm workspace), `import("@aigne/afs-fs")` inside packages/core
+	* won't find packages/cli's dependencies. We locate the package directory via
+	* createRequire, then use resolveImportPath to find the correct ESM entry.
+	*/
+	async resolveAndImport(packageName) {
+		try {
+			return await import(resolveImportPath(packageName));
+		} catch {}
+		const packageDir = this.locatePackageDir(packageName);
+		if (packageDir) return await import(resolveImportPath(packageDir));
+		throw new Error(`Cannot resolve module "${packageName}"`);
+	}
+	/**
+	* Locate a package directory using createRequire from various contexts.
+	* Returns the package directory path, or undefined if not found.
+	*/
+	locatePackageDir(packageName) {
+		const { createRequire } = require("node:module");
+		const { dirname } = require("node:path");
+		const contexts = [(0, node_path.join)(process.cwd(), "__resolve__.js"), ...process.argv[1] ? [(0, node_path.join)(dirname(process.argv[1]), "__resolve__.js")] : []];
+		for (const context of contexts) try {
+			return dirname(createRequire(context).resolve((0, node_path.join)(packageName, "package.json")));
+		} catch {
+			try {
+				let dir = dirname(createRequire(context).resolve(packageName));
+				for (let i = 0; i < 5; i++) {
+					if ((0, node_fs.existsSync)((0, node_path.join)(dir, "package.json"))) return dir;
+					const parent = dirname(dir);
+					if (parent === dir) break;
+					dir = parent;
+				}
+			} catch {}
+		}
+	}
+};
+
+//#endregion
+exports.ProviderRegistry = ProviderRegistry;

package/dist/registry.d.cts

@@ -0,0 +1,96 @@
+import { AFSModule, MountConfig, ProviderManifest } from "./type.cjs";
+import { ParsedURI } from "./utils/uri.cjs";
+
+//#region src/registry.d.ts
+/**
+ * Factory function that creates a provider from a mount config and pre-parsed URI.
+ */
+type ProviderFactory = (mount: MountConfig, parsed: ParsedURI) => Promise<AFSModule>;
+/**
+ * Registry of provider factories with unified manifest-driven loading.
+ *
+ * Loading flow:
+ * 1. parseURI → get scheme
+ * 2. Check registered factories (workspace, custom) → use directly
+ * 3. Resolve package: mount.provider or @aigne/afs-{baseScheme}
+ * 4. Import package → get ProviderClass
+ * 5. Get manifest from ProviderClass.manifest()
+ * 6. Match manifest by scheme (for multi-manifest providers)
+ * 7. parseTemplate(uriTemplate, body) → extract path variables
+ * 8. Merge params: body vars > query > mount.options
+ * 9. Construct provider with merged options
+ */
+declare class ProviderRegistry {
+  private factories;
+  /** Register a scheme → factory mapping. Overwrites any existing registration. */
+  register(scheme: string, factory: ProviderFactory): void;
+  /** Check if a scheme has a registered factory. */
+  has(scheme: string): boolean;
+  /**
+   * Get provider metadata (schema, auth, manifest) for a URI.
+   *
+   * Used by CLI credential resolution to get schema and auth method
+   * without constructing the provider.
+   *
+   * Returns null if the provider class can't be loaded (e.g., unknown scheme).
+   */
+  getProviderInfo(uri: string): Promise<{
+    schema: any | null;
+    auth: ((context: any) => Promise<Record<string, unknown> | null>) | undefined;
+    manifest: ProviderManifest | null;
+  } | null>;
+  /**
+   * Create a provider from a mount config.
+   *
+   * Uses registered factory if available, otherwise auto-loads
+   * via manifest-driven resolution.
+   */
+  createProvider(mount: MountConfig): Promise<AFSModule>;
+  /**
+   * Auto-load a provider using the manifest-driven unified flow.
+   */
+  private autoLoadProvider;
+  /**
+   * Import a provider class from a package name.
+   * Resolution order:
+   * 1. Direct import (works when package is a dependency of the importing module)
+   * 2. createRequire from process.cwd() (works in monorepo dev environments)
+   * 3. npm auto-install to ~/.afs-config/packages/
+   */
+  private importProviderClass;
+  /**
+   * Get manifest(s) from a provider class.
+   */
+  private getManifests;
+  /**
+   * Find the matching manifest for a given scheme.
+   * For multi-manifest providers (e.g., MCP with mcp+stdio, mcp+http, mcp+sse),
+   * match by the full scheme from the URI template.
+   */
+  private matchManifest;
+  /**
+   * Merge parameters from multiple sources.
+   * Priority: template vars (from URI body) > query params > mount.options
+   */
+  private mergeOptions;
+  /**
+   * Construct a provider instance with merged options.
+   */
+  private constructProvider;
+  /**
+   * Resolve and import a package, trying multiple resolution strategies.
+   *
+   * In a monorepo (pnpm workspace), `import("@aigne/afs-fs")` inside packages/core
+   * won't find packages/cli's dependencies. We locate the package directory via
+   * createRequire, then use resolveImportPath to find the correct ESM entry.
+   */
+  private resolveAndImport;
+  /**
+   * Locate a package directory using createRequire from various contexts.
+   * Returns the package directory path, or undefined if not found.
+   */
+  private locatePackageDir;
+}
+//#endregion
+export { ProviderFactory, ProviderRegistry };
+//# sourceMappingURL=registry.d.cts.map

package/dist/registry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.cts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;;;AASA;KAAY,eAAA,IAAmB,KAAA,EAAO,WAAA,EAAa,MAAA,EAAQ,SAAA,KAAc,OAAA,CAAQ,SAAA;;;;;;;;;;;;;;;cA4KpE,gBAAA;EAAA,QACH,SAAA;EADmB;EAI3B,QAAA,CAAS,MAAA,UAAgB,OAAA,EAAS,eAAA;EAAA;EAKlC,GAAA,CAAI,MAAA;EAcuB;;;;;;;;EAFrB,eAAA,CAAgB,GAAA,WAAc,OAAA;IAClC,MAAA;IACA,IAAA,IAAQ,OAAA,UAAiB,OAAA,CAAQ,MAAA;IACjC,QAAA,EAAU,gBAAA;EAAA;EAfZ;;;;;;EAmEM,cAAA,CAAe,KAAA,EAAO,WAAA,GAAc,OAAA,CAAQ,SAAA;EArDxC;;;EAAA,QAyEI,gBAAA;EAxEF;;;;;;;EAAA,QAuGE,mBAAA;EAwEN;;;EAAA,QAAA,YAAA;EAuHM;;;;;EAAA,QAtGN,aAAA;;;;;UAiCA,YAAA;;;;UAgCM,iBAAA;;;;;;;;UAqCA,gBAAA;;;;;UAyBN,gBAAA;AAAA"}

package/dist/registry.d.mts

@@ -0,0 +1,96 @@
+import { AFSModule, MountConfig, ProviderManifest } from "./type.mjs";
+import { ParsedURI } from "./utils/uri.mjs";
+
+//#region src/registry.d.ts
+/**
+ * Factory function that creates a provider from a mount config and pre-parsed URI.
+ */
+type ProviderFactory = (mount: MountConfig, parsed: ParsedURI) => Promise<AFSModule>;
+/**
+ * Registry of provider factories with unified manifest-driven loading.
+ *
+ * Loading flow:
+ * 1. parseURI → get scheme
+ * 2. Check registered factories (workspace, custom) → use directly
+ * 3. Resolve package: mount.provider or @aigne/afs-{baseScheme}
+ * 4. Import package → get ProviderClass
+ * 5. Get manifest from ProviderClass.manifest()
+ * 6. Match manifest by scheme (for multi-manifest providers)
+ * 7. parseTemplate(uriTemplate, body) → extract path variables
+ * 8. Merge params: body vars > query > mount.options
+ * 9. Construct provider with merged options
+ */
+declare class ProviderRegistry {
+  private factories;
+  /** Register a scheme → factory mapping. Overwrites any existing registration. */
+  register(scheme: string, factory: ProviderFactory): void;
+  /** Check if a scheme has a registered factory. */
+  has(scheme: string): boolean;
+  /**
+   * Get provider metadata (schema, auth, manifest) for a URI.
+   *
+   * Used by CLI credential resolution to get schema and auth method
+   * without constructing the provider.
+   *
+   * Returns null if the provider class can't be loaded (e.g., unknown scheme).
+   */
+  getProviderInfo(uri: string): Promise<{
+    schema: any | null;
+    auth: ((context: any) => Promise<Record<string, unknown> | null>) | undefined;
+    manifest: ProviderManifest | null;
+  } | null>;
+  /**
+   * Create a provider from a mount config.
+   *
+   * Uses registered factory if available, otherwise auto-loads
+   * via manifest-driven resolution.
+   */
+  createProvider(mount: MountConfig): Promise<AFSModule>;
+  /**
+   * Auto-load a provider using the manifest-driven unified flow.
+   */
+  private autoLoadProvider;
+  /**
+   * Import a provider class from a package name.
+   * Resolution order:
+   * 1. Direct import (works when package is a dependency of the importing module)
+   * 2. createRequire from process.cwd() (works in monorepo dev environments)
+   * 3. npm auto-install to ~/.afs-config/packages/
+   */
+  private importProviderClass;
+  /**
+   * Get manifest(s) from a provider class.
+   */
+  private getManifests;
+  /**
+   * Find the matching manifest for a given scheme.
+   * For multi-manifest providers (e.g., MCP with mcp+stdio, mcp+http, mcp+sse),
+   * match by the full scheme from the URI template.
+   */
+  private matchManifest;
+  /**
+   * Merge parameters from multiple sources.
+   * Priority: template vars (from URI body) > query params > mount.options
+   */
+  private mergeOptions;
+  /**
+   * Construct a provider instance with merged options.
+   */
+  private constructProvider;
+  /**
+   * Resolve and import a package, trying multiple resolution strategies.
+   *
+   * In a monorepo (pnpm workspace), `import("@aigne/afs-fs")` inside packages/core
+   * won't find packages/cli's dependencies. We locate the package directory via
+   * createRequire, then use resolveImportPath to find the correct ESM entry.
+   */
+  private resolveAndImport;
+  /**
+   * Locate a package directory using createRequire from various contexts.
+   * Returns the package directory path, or undefined if not found.
+   */
+  private locatePackageDir;
+}
+//#endregion
+export { ProviderFactory, ProviderRegistry };
+//# sourceMappingURL=registry.d.mts.map

package/dist/registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.mts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;;;AASA;KAAY,eAAA,IAAmB,KAAA,EAAO,WAAA,EAAa,MAAA,EAAQ,SAAA,KAAc,OAAA,CAAQ,SAAA;;;;;;;;;;;;;;;cA4KpE,gBAAA;EAAA,QACH,SAAA;EADmB;EAI3B,QAAA,CAAS,MAAA,UAAgB,OAAA,EAAS,eAAA;EAAA;EAKlC,GAAA,CAAI,MAAA;EAcuB;;;;;;;;EAFrB,eAAA,CAAgB,GAAA,WAAc,OAAA;IAClC,MAAA;IACA,IAAA,IAAQ,OAAA,UAAiB,OAAA,CAAQ,MAAA;IACjC,QAAA,EAAU,gBAAA;EAAA;EAfZ;;;;;;EAmEM,cAAA,CAAe,KAAA,EAAO,WAAA,GAAc,OAAA,CAAQ,SAAA;EArDxC;;;EAAA,QAyEI,gBAAA;EAxEF;;;;;;;EAAA,QAuGE,mBAAA;EAwEN;;;EAAA,QAAA,YAAA;EAuHM;;;;;EAAA,QAtGN,aAAA;;;;;UAiCA,YAAA;;;;UAgCM,iBAAA;;;;;;;;UAqCA,gBAAA;;;;;UAyBN,gBAAA;AAAA"}