@aigne/afs 1.4.0 → 1.11.0-beta

package/README.md

@@ -34,28 +34,30 @@ import { AFSHistory } from "@aigne/afs-history";
 const afs = new AFS();
 
 // Mount history module (optional)
-afs.mount(new AFSHistory({
-  storage: { url: "file:./memory.sqlite3" }
-}));
+afs.mount(
+  new AFSHistory({
+    storage: { url: "file:./memory.sqlite3" },
+  }),
+);
 
 // All modules are mounted under /modules
 // List modules
 const modules = await afs.listModules();
 
 // List entries in a module
-const { list } = await afs.list('/modules/history');
+const { list } = await afs.list("/modules/history");
 
 // Read an entry
-const { result } = await afs.read('/modules/history/some-id');
+const { result } = await afs.read("/modules/history/some-id");
 
 // Write an entry (if module supports write)
-await afs.write('/modules/history/notes', {
-  content: 'My notes',
-  summary: 'Personal notes'
+await afs.write("/modules/history/notes", {
+  content: "My notes",
+  summary: "Personal notes",
 });
 
 // Search for content
-const { list: results } = await afs.search('/modules/history', 'search query');
+const { list: results } = await afs.search("/modules/history", "search query");
 ```
 
 ## Core Concepts
@@ -66,16 +68,16 @@ All data in AFS is represented as `AFSEntry` objects:
 
 ```typescript
 interface AFSEntry {
-  id: string;                      // Unique identifier
-  path: string;                    // Full path in AFS
-  content?: any;                   // File/data content
-  summary?: string;                // Optional summary
-  metadata?: Record<string, any>;  // Custom metadata
-  createdAt?: Date;                // Creation timestamp
-  updatedAt?: Date;                // Last update timestamp
-  userId?: string;                 // Associated user
-  sessionId?: string;              // Associated session
-  linkTo?: string;                 // Link to another entry
+  id: string; // Unique identifier
+  path: string; // Full path in AFS
+  content?: any; // File/data content
+  summary?: string; // Optional summary
+  metadata?: Record<string, any>; // Custom metadata
+  createdAt?: Date; // Creation timestamp
+  updatedAt?: Date; // Last update timestamp
+  userId?: string; // Associated user
+  sessionId?: string; // Associated session
+  linkTo?: string; // Link to another entry
 }
 ```
 
@@ -85,15 +87,29 @@ Modules are pluggable components that implement storage backends. All modules ar
 
 ```typescript
 interface AFSModule {
-  name: string;                   // Module name (used as mount path)
-  description?: string;           // Description for AI agents
+  name: string; // Module name (used as mount path)
+  description?: string; // Description for AI agents
 
   // Operations (all optional)
-  list?(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }>;
+  list?(
+    path: string,
+    options?: AFSListOptions,
+  ): Promise<{ list: AFSEntry[]; message?: string }>;
   read?(path: string): Promise<{ result?: AFSEntry; message?: string }>;
-  write?(path: string, entry: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }>;
-  search?(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }>;
-  exec?(path: string, args: Record<string, any>, options: { context: any }): Promise<{ result: Record<string, any> }>;
+  write?(
+    path: string,
+    entry: AFSWriteEntryPayload,
+  ): Promise<{ result: AFSEntry; message?: string }>;
+  search?(
+    path: string,
+    query: string,
+    options?: AFSSearchOptions,
+  ): Promise<{ list: AFSEntry[]; message?: string }>;
+  exec?(
+    path: string,
+    args: Record<string, any>,
+    options: { context: any },
+  ): Promise<{ result: Record<string, any> }>;
 
   // Lifecycle
   onMount?(afs: AFSRoot): void;
@@ -114,11 +130,13 @@ new AFS(options?: AFSOptions)
 ```
 
 Options:
+
 - `modules`: Optional array of modules to mount on initialization
 
 #### Methods
 
 ##### mount(module: AFSModule)
+
 ##### mount(path: string, module: AFSModule)
 
 Mount a module. The module will be accessible under `/modules/{module.name}` or `/modules/{path}`:
@@ -145,12 +163,13 @@ const modules = await afs.listModules();
 List entries in a directory:
 
 ```typescript
-const { list, message } = await afs.list('/modules/history', {
-  maxDepth: 2
+const { list, message } = await afs.list("/modules/history", {
+  maxDepth: 2,
 });
 ```
 
 Options:
+
 - `maxDepth`: Maximum recursion depth (default: 1)
 
 ##### read(path: string)
@@ -158,7 +177,7 @@ Options:
 Read a specific entry:
 
 ```typescript
-const { result, message } = await afs.read('/modules/history/uuid-123');
+const { result, message } = await afs.read("/modules/history/uuid-123");
 ```
 
 ##### write(path: string, content: AFSWriteEntryPayload)
@@ -166,10 +185,10 @@ const { result, message } = await afs.read('/modules/history/uuid-123');
 Write or update an entry:
 
 ```typescript
-const { result, message } = await afs.write('/modules/my-module/file.txt', {
-  content: 'Hello, world!',
-  summary: 'Greeting file',
-  metadata: { type: 'greeting' }
+const { result, message } = await afs.write("/modules/my-module/file.txt", {
+  content: "Hello, world!",
+  summary: "Greeting file",
+  metadata: { type: "greeting" },
 });
 ```
 
@@ -178,7 +197,10 @@ const { result, message } = await afs.write('/modules/my-module/file.txt', {
 Search for content:
 
 ```typescript
-const { list, message } = await afs.search('/modules/history', 'authentication');
+const { list, message } = await afs.search(
+  "/modules/history",
+  "authentication",
+);
 ```
 
 ##### exec(path: string, args: Record<string, any>, options: { context: any })
@@ -186,7 +208,11 @@ const { list, message } = await afs.search('/modules/history', 'authentication')
 Execute a module-specific operation:
 
 ```typescript
-const { result } = await afs.exec('/modules/my-module/action', { param: 'value' }, { context });
+const { result } = await afs.exec(
+  "/modules/my-module/action",
+  { param: "value" },
+  { context },
+);
 ```
 
 ### Events
@@ -195,15 +221,16 @@ AFS uses an event system for module communication:
 
 ```typescript
 // Modules can listen to events
-afs.on('agentSucceed', ({ input, output }) => {
-  console.log('Agent succeeded:', input, output);
+afs.on("agentSucceed", ({ input, output }) => {
+  console.log("Agent succeeded:", input, output);
 });
 
 // Modules can emit custom events
-afs.emit('customEvent', { data: 'value' });
+afs.emit("customEvent", { data: "value" });
 ```
 
 Common events from `AFSRootEvents`:
+
 - `agentSucceed`: Emitted when an agent successfully completes
 - `agentFail`: Emitted when an agent fails
 
@@ -214,6 +241,7 @@ Common events from `AFSRootEvents`:
 The history module tracks conversation history. It is available as a separate package: `@aigne/afs-history`.
 
 **Features:**
+
 - Listens to `agentSucceed` events and records agent interactions
 - Stores input/output pairs with UUID paths
 - Supports list and read operations
@@ -221,6 +249,7 @@ The history module tracks conversation history. It is available as a separate pa
 - Persistent SQLite storage
 
 **Installation:**
+
 ```bash
 npm install @aigne/afs-history
 ```
@@ -232,15 +261,18 @@ import { AFS } from "@aigne/afs";
 import { AFSHistory } from "@aigne/afs-history";
 
 const afs = new AFS();
-afs.mount(new AFSHistory({
-  storage: { url: "file:./memory.sqlite3" }
-}));
+afs.mount(
+  new AFSHistory({
+    storage: { url: "file:./memory.sqlite3" },
+  }),
+);
 
 // History entries are accessible at /modules/history
-const { list } = await afs.list('/modules/history');
+const { list } = await afs.list("/modules/history");
 ```
 
 **Configuration:**
+
 - `storage`: Storage configuration (e.g., `{ url: "file:./memory.sqlite3" }`) or a SharedAFSStorage instance
 
 **Note:** History is NOT automatically mounted. You must explicitly mount it if needed.
@@ -258,7 +290,10 @@ export class CustomModule implements AFSModule {
   readonly name = "custom-module";
   readonly description = "My custom storage";
 
-  async list(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+  async list(
+    path: string,
+    options?: AFSListOptions,
+  ): Promise<{ list: AFSEntry[]; message?: string }> {
     // path is the subpath within your module
     // Implement your list logic
     return { list: [] };
@@ -269,13 +304,20 @@ export class CustomModule implements AFSModule {
     return { result: undefined };
   }
 
-  async write(path: string, content: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }> {
+  async write(
+    path: string,
+    content: AFSWriteEntryPayload,
+  ): Promise<{ result: AFSEntry; message?: string }> {
     // Implement your write logic
-    const entry: AFSEntry = { id: 'id', path, ...content };
+    const entry: AFSEntry = { id: "id", path, ...content };
     return { result: entry };
   }
 
-  async search(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+  async search(
+    path: string,
+    query: string,
+    options?: AFSSearchOptions,
+  ): Promise<{ list: AFSEntry[]; message?: string }> {
     // Implement your search logic
     return { list: [] };
   }
@@ -284,7 +326,7 @@ export class CustomModule implements AFSModule {
     console.log(`${this.name} mounted`);
 
     // Listen to events
-    afs.on('agentSucceed', (data) => {
+    afs.on("agentSucceed", (data) => {
       // Handle event
     });
   }
@@ -323,18 +365,20 @@ import { AFS } from "@aigne/afs";
 import { AFSHistory } from "@aigne/afs-history";
 
 const afs = new AFS();
-afs.mount(new AFSHistory({
-  storage: { url: "file:./memory.sqlite3" }
-}));
+afs.mount(
+  new AFSHistory({
+    storage: { url: "file:./memory.sqlite3" },
+  }),
+);
 
 const agent = AIAgent.from({
   name: "assistant",
-  afs: afs
+  afs: afs,
 });
 
 const context = aigne.newContext();
 const result = await context.invoke(agent, {
-  message: "What's in my history?"
+  message: "What's in my history?",
 });
 ```
 

package/dist/index.cjs

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