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

package/dist/provider/base.cjs

@@ -0,0 +1,425 @@
+const require_error = require('../error.cjs');
+const require_decorators = require('./decorators.cjs');
+const require_router = require('./router.cjs');
+let minimatch = require("minimatch");
+
+//#region src/provider/base.ts
+/**
+* Abstract base class for AFS providers using virtual routing
+*
+* All providers extend this class and use decorators to define routes:
+* - @List(pattern) - Handle list operations
+* - @Read(pattern) - Handle read operations
+* - @Write(pattern) - Handle write operations
+* - @Delete(pattern) - Handle delete operations
+* - @Exec(pattern) - Handle exec operations
+* - @Search(pattern) - Handle search operations
+* - @Meta(pattern) - Handle .meta path reads
+* - @Actions(pattern) - Handle .actions path listing
+*
+* @example
+* ```typescript
+* class MyProvider extends AFSBaseProvider {
+*   readonly name = "my-provider";
+*
+*   @List("/")
+*   async listRoot(ctx: RouteContext) {
+*     return { data: [...] };
+*   }
+*
+*   @Read("/:id")
+*   async getItem(ctx: RouteContext<{ id: string }>) {
+*     return { id: ctx.params.id, path: ctx.path, content: ... };
+*   }
+* }
+* ```
+*/
+var AFSBaseProvider = class {
+	/** Optional description */
+	description;
+	/** Access mode: "readonly" or "readwrite" */
+	accessMode = "readonly";
+	/** Internal router for path matching */
+	router;
+	constructor() {
+		this.router = new require_router.ProviderRouter();
+		this.collectDecoratorRoutes();
+		this.removeUnimplementedMethods();
+	}
+	/**
+	* Collect routes from decorators and register them
+	*/
+	collectDecoratorRoutes() {
+		const routes = require_decorators.getRoutes(this.constructor);
+		for (const route of routes) {
+			const handler = this[route.methodName];
+			if (typeof handler !== "function") {
+				console.warn(`[AFSBaseProvider] Method ${route.methodName} not found on ${this.constructor.name}`);
+				continue;
+			}
+			const boundHandler = handler.bind(this);
+			this.router.registerRoute(route.pattern, route.operation, boundHandler, route.description, route.listOptions);
+		}
+	}
+	/**
+	* Remove methods for operations that have no routes registered.
+	* This allows core to check if a provider supports a capability via typeof check.
+	*
+	* We set the method to undefined on the instance to shadow the prototype method,
+	* since `delete` only removes instance properties, not inherited ones.
+	*/
+	removeUnimplementedMethods() {
+		for (const [operation, methodName] of Object.entries({
+			list: "list",
+			read: "read",
+			write: "write",
+			delete: "delete",
+			exec: "exec",
+			search: "search",
+			stat: "stat",
+			explain: "explain",
+			rename: "rename"
+		})) if (this.router.getRoutesForOperation(operation).length === 0) this[methodName] = void 0;
+	}
+	/**
+	* Build an OperationsDeclaration based on which methods are implemented.
+	* Uses the fact that removeUnimplementedMethods() sets unsupported methods to undefined.
+	* Write/delete/exec/rename are also gated by accessMode.
+	*/
+	getOperationsDeclaration() {
+		const isReadwrite = this.accessMode === "readwrite";
+		return {
+			read: typeof this.read === "function",
+			list: typeof this.list === "function",
+			write: typeof this.write === "function" && isReadwrite,
+			delete: typeof this.delete === "function" && isReadwrite,
+			search: typeof this.search === "function",
+			exec: typeof this.exec === "function",
+			stat: typeof this.stat === "function",
+			explain: typeof this.explain === "function"
+		};
+	}
+	/**
+	* List entries at a path
+	*/
+	async list(path, options) {
+		const maxDepth = options?.maxDepth ?? 1;
+		if (maxDepth === 0) return { data: [] };
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "list");
+		if (!match) throw new require_error.AFSNotFoundError(normalizedPath);
+		const limit = options?.limit;
+		if ((match.route.listOptions?.handleDepth ?? false) || maxDepth <= 1) {
+			const ctx = {
+				path: normalizedPath,
+				params: match.params,
+				options
+			};
+			const handler = match.route.handler;
+			const handlerResult = await handler(ctx);
+			const result = {
+				data: handlerResult.data,
+				total: handlerResult.total
+			};
+			if (limit !== void 0 && result.data.length > limit) return {
+				data: result.data.slice(0, limit),
+				total: result.total ?? result.data.length
+			};
+			return result;
+		}
+		return this.listWithDepthExpansion(normalizedPath, options, maxDepth);
+	}
+	/**
+	* Expand list results to specified depth using BFS traversal.
+	* Used when handler has handleDepth: false.
+	*
+	* The handler is expected to return single-level results (direct children only).
+	* This method recursively calls the handler to expand directories up to maxDepth.
+	* Pattern filtering is applied after BFS completes to ensure directories are
+	* traversed even if they don't match the pattern.
+	*/
+	async listWithDepthExpansion(basePath, options, maxDepth) {
+		const limit = options?.limit ?? 1e3;
+		const pattern = options?.pattern;
+		const allEntries = [];
+		const visited = /* @__PURE__ */ new Set();
+		const queue = [{
+			path: basePath,
+			depth: 0
+		}];
+		const unfilteredEntries = [];
+		while (queue.length > 0) {
+			const { path, depth } = queue.shift();
+			if (visited.has(path)) continue;
+			visited.add(path);
+			const singleLevelOptions = {
+				...options,
+				maxDepth: 1,
+				pattern: void 0
+			};
+			const match = this.router.match(path, "list");
+			if (!match) continue;
+			const ctx = {
+				path,
+				params: match.params,
+				options: singleLevelOptions
+			};
+			const handler = match.route.handler;
+			let result;
+			try {
+				result = await handler(ctx);
+			} catch (error) {
+				const code = error.code;
+				if (code === "ENOENT" || code === "ENOTDIR" || error instanceof Error && error.message.includes("not found")) continue;
+				throw error;
+			}
+			const noExpandSet = new Set(result.noExpand ?? []);
+			for (const entry of result.data) {
+				if (entry.path === path && depth > 0) continue;
+				unfilteredEntries.push(entry);
+				const childrenCount = entry.meta?.childrenCount;
+				const isDirectory = childrenCount !== void 0 && childrenCount !== 0;
+				const shouldExpand = !noExpandSet.has(entry.path);
+				if (depth < maxDepth - 1 && isDirectory && shouldExpand && entry.path !== path) queue.push({
+					path: entry.path,
+					depth: depth + 1
+				});
+			}
+		}
+		if (pattern) for (const entry of unfilteredEntries) {
+			if (allEntries.length >= limit) break;
+			if (this.matchesPattern(entry.path, pattern)) allEntries.push(entry);
+		}
+		else for (const entry of unfilteredEntries) {
+			if (allEntries.length >= limit) break;
+			allEntries.push(entry);
+		}
+		return {
+			data: allEntries,
+			total: allEntries.length >= limit ? void 0 : allEntries.length
+		};
+	}
+	/**
+	* Check if a path matches a glob pattern
+	*/
+	matchesPattern(path, pattern) {
+		return (0, minimatch.minimatch)(path, pattern, { matchBase: true });
+	}
+	/**
+	* Read an entry at a path
+	*/
+	async read(path, options) {
+		const normalizedPath = this.normalizePath(path);
+		const actionsMatch = normalizedPath.match(/^(.*)\/\.actions\/([^/]+)$/);
+		if (actionsMatch) {
+			const actionsListPath = `${actionsMatch[1] || ""}/.actions`;
+			const actionName = actionsMatch[2];
+			const listMatch = this.router.match(actionsListPath, "list");
+			if (listMatch) {
+				const ctx = {
+					path: actionsListPath,
+					params: listMatch.params,
+					options: {}
+				};
+				const handler = listMatch.route.handler;
+				const actionEntry = (await handler(ctx)).data.find((entry) => entry.summary === actionName || entry.id === actionName || entry.id.endsWith(`:${actionName}`) || entry.meta?.name === actionName);
+				if (actionEntry) return { data: actionEntry };
+			}
+		}
+		const match = this.router.match(normalizedPath, "read");
+		if (match) {
+			const ctx = {
+				path: normalizedPath,
+				params: match.params,
+				options
+			};
+			const handler = match.route.handler;
+			return { data: await handler(ctx) };
+		}
+		throw new require_error.AFSNotFoundError(normalizedPath);
+	}
+	/**
+	* Write an entry at a path
+	*/
+	async write(path, content, options) {
+		if (this.accessMode === "readonly") throw new require_error.AFSReadonlyError("Cannot write on a readonly provider");
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "write");
+		if (!match) throw new Error(`No write handler for path: ${path}`);
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx, content);
+	}
+	/**
+	* Delete an entry at a path
+	*/
+	async delete(path, options) {
+		if (this.accessMode === "readonly") throw new require_error.AFSReadonlyError("Cannot delete on a readonly provider");
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "delete");
+		if (!match) throw new Error(`No delete handler for path: ${path}`);
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx);
+	}
+	/**
+	* Search entries at a path
+	*/
+	async search(path, query, options) {
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "search");
+		if (!match) return { data: [] };
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx, query, options);
+	}
+	/**
+	* Execute an action at a path
+	*/
+	async exec(path, args, options) {
+		if (this.accessMode === "readonly") throw new require_error.AFSReadonlyError("Cannot exec on a readonly provider");
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "exec");
+		if (!match) throw new Error(`No exec handler for path: ${path}`);
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx, args);
+	}
+	/**
+	* Get stat information for a path
+	*
+	* Note: Fallback to read() is handled at AFS core level, not here.
+	*/
+	async stat(path, options) {
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "stat");
+		if (match) {
+			const ctx = {
+				path: normalizedPath,
+				params: match.params,
+				options
+			};
+			const handler = match.route.handler;
+			return handler(ctx);
+		}
+		throw new require_error.AFSNotFoundError(normalizedPath);
+	}
+	/**
+	* Get human-readable explanation for a path
+	*
+	* Note: Fallback to stat() is handled at AFS core level, not here.
+	*/
+	async explain(path, options) {
+		const normalizedPath = this.normalizePath(path);
+		const match = this.router.match(normalizedPath, "explain");
+		if (!match) throw new Error(`No explain handler for path: ${path}`);
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx);
+	}
+	/**
+	* Rename/move a path
+	*/
+	async rename(oldPath, newPath, options) {
+		if (this.accessMode === "readonly") throw new require_error.AFSReadonlyError("Cannot rename on a readonly provider");
+		const normalizedPath = this.normalizePath(oldPath);
+		const match = this.router.match(normalizedPath, "rename");
+		if (!match) throw new require_error.AFSNotFoundError(normalizedPath);
+		const ctx = {
+			path: normalizedPath,
+			params: match.params,
+			options
+		};
+		const handler = match.route.handler;
+		return handler(ctx, newPath);
+	}
+	/**
+	* Normalize a path to ensure consistent format
+	* - Always starts with /
+	* - No trailing slash (except for root)
+	*/
+	normalizePath(path) {
+		if (!path || path === "/") return "/";
+		let normalized = path.startsWith("/") ? path : `/${path}`;
+		if (normalized.length > 1 && normalized.endsWith("/")) normalized = normalized.slice(0, -1);
+		return normalized;
+	}
+	/**
+	* Join path segments
+	*/
+	joinPath(...segments) {
+		return `/${segments.map((s) => s.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/")}`;
+	}
+	/**
+	* Build an AFSEntry helper
+	*
+	* @param path - The entry path (will be normalized)
+	* @param options - Entry options
+	* @param options.id - Entry ID. Defaults to normalized path if not provided
+	* @param options.content - Entry content
+	* @param options.meta - Entry metadata
+	* @param options.createdAt - Creation time. Undefined if not available from data source
+	* @param options.updatedAt - Last update time. Undefined if not available from data source
+	*
+	* @example
+	* ```typescript
+	* // Simple entry with just path
+	* this.buildEntry("/items/1")
+	*
+	* // Entry with content and metadata
+	* this.buildEntry("/items/1", {
+	*   content: { name: "Item 1" },
+	*   meta: { size: 100 },
+	* })
+	*
+	* // Entry with all fields
+	* this.buildEntry("/items/1", {
+	*   id: "custom-id",
+	*   content: data,
+	*   meta: { size: stats.size },
+	*   createdAt: stats.birthtime,
+	*   updatedAt: stats.mtime,
+	* })
+	* ```
+	*/
+	buildEntry(path, options) {
+		const normalizedPath = this.normalizePath(path);
+		return {
+			id: options?.id ?? normalizedPath,
+			path: normalizedPath,
+			content: options?.content,
+			meta: options?.meta,
+			createdAt: options?.createdAt,
+			updatedAt: options?.updatedAt
+		};
+	}
+	/**
+	* Get the router (for testing/debugging)
+	*/
+	getRouter() {
+		return this.router;
+	}
+};
+
+//#endregion
+exports.AFSBaseProvider = AFSBaseProvider;

package/dist/provider/base.d.cts

@@ -0,0 +1,175 @@
+import { AFSExplainResult } from "../meta/type.cjs";
+import { AFSAccessMode, AFSDeleteOptions, AFSDeleteResult, AFSEntry, AFSEntryMetadata, AFSExecOptions, AFSExecResult, AFSExplainOptions, AFSListOptions, AFSListResult, AFSModule, AFSReadOptions, AFSReadResult, AFSRenameOptions, AFSRenameResult, AFSSearchOptions, AFSSearchResult, AFSStatOptions, AFSStatResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "../type.cjs";
+import { OperationsDeclaration } from "../capabilities/types.cjs";
+import { ProviderRouter } from "./router.cjs";
+
+//#region src/provider/base.d.ts
+/**
+ * Abstract base class for AFS providers using virtual routing
+ *
+ * All providers extend this class and use decorators to define routes:
+ * - @List(pattern) - Handle list operations
+ * - @Read(pattern) - Handle read operations
+ * - @Write(pattern) - Handle write operations
+ * - @Delete(pattern) - Handle delete operations
+ * - @Exec(pattern) - Handle exec operations
+ * - @Search(pattern) - Handle search operations
+ * - @Meta(pattern) - Handle .meta path reads
+ * - @Actions(pattern) - Handle .actions path listing
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends AFSBaseProvider {
+ *   readonly name = "my-provider";
+ *
+ *   @List("/")
+ *   async listRoot(ctx: RouteContext) {
+ *     return { data: [...] };
+ *   }
+ *
+ *   @Read("/:id")
+ *   async getItem(ctx: RouteContext<{ id: string }>) {
+ *     return { id: ctx.params.id, path: ctx.path, content: ... };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AFSBaseProvider implements AFSModule {
+  /** Provider name, must be unique when mounted */
+  abstract readonly name: string;
+  /** Optional description */
+  readonly description?: string;
+  /** Access mode: "readonly" or "readwrite" */
+  readonly accessMode: AFSAccessMode;
+  /** Internal router for path matching */
+  private router;
+  constructor();
+  /**
+   * Collect routes from decorators and register them
+   */
+  private collectDecoratorRoutes;
+  /**
+   * Remove methods for operations that have no routes registered.
+   * This allows core to check if a provider supports a capability via typeof check.
+   *
+   * We set the method to undefined on the instance to shadow the prototype method,
+   * since `delete` only removes instance properties, not inherited ones.
+   */
+  private removeUnimplementedMethods;
+  /**
+   * Build an OperationsDeclaration based on which methods are implemented.
+   * Uses the fact that removeUnimplementedMethods() sets unsupported methods to undefined.
+   * Write/delete/exec/rename are also gated by accessMode.
+   */
+  protected getOperationsDeclaration(): OperationsDeclaration;
+  /**
+   * List entries at a path
+   */
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  /**
+   * Expand list results to specified depth using BFS traversal.
+   * Used when handler has handleDepth: false.
+   *
+   * The handler is expected to return single-level results (direct children only).
+   * This method recursively calls the handler to expand directories up to maxDepth.
+   * Pattern filtering is applied after BFS completes to ensure directories are
+   * traversed even if they don't match the pattern.
+   */
+  private listWithDepthExpansion;
+  /**
+   * Check if a path matches a glob pattern
+   */
+  private matchesPattern;
+  /**
+   * Read an entry at a path
+   */
+  read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
+  /**
+   * Write an entry at a path
+   */
+  write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+  /**
+   * Delete an entry at a path
+   */
+  delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  /**
+   * Search entries at a path
+   */
+  search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+  /**
+   * Execute an action at a path
+   */
+  exec(path: string, args: Record<string, unknown>, options?: AFSExecOptions): Promise<AFSExecResult>;
+  /**
+   * Get stat information for a path
+   *
+   * Note: Fallback to read() is handled at AFS core level, not here.
+   */
+  stat(path: string, options?: AFSStatOptions): Promise<AFSStatResult>;
+  /**
+   * Get human-readable explanation for a path
+   *
+   * Note: Fallback to stat() is handled at AFS core level, not here.
+   */
+  explain(path: string, options?: AFSExplainOptions): Promise<AFSExplainResult>;
+  /**
+   * Rename/move a path
+   */
+  rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+  /**
+   * Normalize a path to ensure consistent format
+   * - Always starts with /
+   * - No trailing slash (except for root)
+   */
+  protected normalizePath(path: string): string;
+  /**
+   * Join path segments
+   */
+  protected joinPath(...segments: string[]): string;
+  /**
+   * Build an AFSEntry helper
+   *
+   * @param path - The entry path (will be normalized)
+   * @param options - Entry options
+   * @param options.id - Entry ID. Defaults to normalized path if not provided
+   * @param options.content - Entry content
+   * @param options.meta - Entry metadata
+   * @param options.createdAt - Creation time. Undefined if not available from data source
+   * @param options.updatedAt - Last update time. Undefined if not available from data source
+   *
+   * @example
+   * ```typescript
+   * // Simple entry with just path
+   * this.buildEntry("/items/1")
+   *
+   * // Entry with content and metadata
+   * this.buildEntry("/items/1", {
+   *   content: { name: "Item 1" },
+   *   meta: { size: 100 },
+   * })
+   *
+   * // Entry with all fields
+   * this.buildEntry("/items/1", {
+   *   id: "custom-id",
+   *   content: data,
+   *   meta: { size: stats.size },
+   *   createdAt: stats.birthtime,
+   *   updatedAt: stats.mtime,
+   * })
+   * ```
+   */
+  protected buildEntry(path: string, options?: {
+    id?: string;
+    content?: unknown;
+    meta?: Partial<AFSEntryMetadata>;
+    createdAt?: Date;
+    updatedAt?: Date;
+  }): AFSEntry;
+  /**
+   * Get the router (for testing/debugging)
+   */
+  protected getRouter(): ProviderRouter;
+}
+//#endregion
+export { AFSBaseProvider };
+//# sourceMappingURL=base.d.cts.map

package/dist/provider/base.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.cts","names":[],"sources":["../../src/provider/base.ts"],"mappings":";;;;;;;;;AA0EA;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAAsB,eAAA,YAA2B,SAAA;EAmdT;EAAA,kBAjdpB,IAAA;EAidwC;EAAA,SA9cjD,WAAA;EAueE;EAAA,SApeF,UAAA,EAAY,aAAA;EAkkBF;EAAA,QA/jBX,MAAA;;EAikBQ;;;EAAA,QAtjBR,sBAAA;EAtBgD;;;;;;;EAAA,QAqDhD,0BAAA;;;;;;YA4BE,wBAAA,CAAA,GAA4B,qBAAA;EAmB3B;;;EAAL,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAAA;;;;;;;;;EAAA,QAyD9C,sBAAA;EAsLZ;;;EAAA,QAlEM,cAAA;EAoEN;;;EA7DI,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAuF/C;;;EA7BP,KAAA,CACJ,IAAA,UACA,OAAA,EAAS,oBAAA,EACT,OAAA,GAAU,eAAA,GACT,OAAA,CAAQ,cAAA;EAyBqD;;;EAA1D,MAAA,CAAO,IAAA,UAAc,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EAyBZ;;;EAA9C,MAAA,CAAO,IAAA,UAAc,KAAA,UAAe,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,eAAA;EAqBzE;;;EAAA,IAAA,CACJ,IAAA,UACA,IAAA,EAAM,MAAA,mBACN,OAAA,GAAU,cAAA,GACT,OAAA,CAAQ,aAAA;EADC;;;;;EA4BN,IAAA,CAAK,IAAA,UAAc,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAAzB;;;;;EAuB7B,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAU,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;EAA5B;;;EAqBhC,MAAA,CACJ,OAAA,UACA,OAAA,UACA,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;EAJL;;;;;EAAA,UAiCI,aAAA,CAAc,IAAA;EA7Bb;;;EAAA,UAgDD,QAAA,CAAA,GAAY,QAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAA,UAyCZ,UAAA,CACR,IAAA,UACA,OAAA;IACE,EAAA;IACA,OAAA;IACA,IAAA,GAAO,OAAA,CAAQ,gBAAA;IACf,SAAA,GAAY,IAAA;IACZ,SAAA,GAAY,IAAA;EAAA,IAEb,QAAA;;;;YAeO,SAAA,CAAA,GAAa,cAAA;AAAA"}