@aigne/afs 1.4.0-beta.1 → 1.4.0-beta.10

package/lib/dts/type.d.ts

@@ -1,9 +1,26 @@
 import type { Emitter } from "strict-event-emitter";
-import { type ZodType } from "zod";
-export interface AFSListOptions {
+import { type ZodType, z } from "zod";
+/**
+ * Access mode for AFS modules and root.
+ * - "readonly": Only read operations are allowed (list, read, search)
+ * - "readwrite": All operations are allowed
+ */
+export type AFSAccessMode = "readonly" | "readwrite";
+/**
+ * Zod schema for access mode validation.
+ * Can be reused across modules that support access mode configuration.
+ */
+export declare const accessModeSchema: z.ZodOptional<z.ZodEnum<["readonly", "readwrite"]>>;
+export interface AFSOperationOptions {
+    context?: any;
+}
+export interface AFSListOptions extends AFSOperationOptions {
     filter?: {
+        agentId?: string;
         userId?: string;
         sessionId?: string;
+        before?: string;
+        after?: string;
     };
     maxDepth?: number;
     limit?: number;
@@ -15,46 +32,45 @@ export interface AFSListOptions {
      * @default false
      */
     disableGitignore?: boolean;
-    context?: any;
+    /**
+     * Glob pattern to filter entries by path.
+     * Examples: "*.ts", "**\/*.js", "src/**\/*.{ts,tsx}"
+     */
+    pattern?: string;
 }
 export interface AFSListResult {
     data: AFSEntry[];
     message?: string;
-    context?: any;
 }
-export interface AFSSearchOptions {
+export interface AFSSearchOptions extends AFSOperationOptions {
     limit?: number;
     caseSensitive?: boolean;
-    context?: any;
 }
 export interface AFSSearchResult {
     data: AFSEntry[];
     message?: string;
 }
-export interface AFSReadOptions {
-    context?: any;
+export interface AFSReadOptions extends AFSOperationOptions {
+    filter?: AFSListOptions["filter"];
 }
 export interface AFSReadResult {
     data?: AFSEntry;
     message?: string;
 }
-export interface AFSDeleteOptions {
+export interface AFSDeleteOptions extends AFSOperationOptions {
     recursive?: boolean;
-    context?: any;
 }
 export interface AFSDeleteResult {
     message?: string;
 }
-export interface AFSRenameOptions {
+export interface AFSRenameOptions extends AFSOperationOptions {
     overwrite?: boolean;
-    context?: any;
 }
 export interface AFSRenameResult {
     message?: string;
 }
-export interface AFSWriteOptions {
+export interface AFSWriteOptions extends AFSOperationOptions {
     append?: boolean;
-    context?: any;
 }
 export interface AFSWriteResult {
     data: AFSEntry;
@@ -63,8 +79,7 @@ export interface AFSWriteResult {
 }
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
-export interface AFSExecOptions {
-    context: any;
+export interface AFSExecOptions extends AFSOperationOptions {
 }
 export interface AFSExecResult {
     data: Record<string, any>;
@@ -72,7 +87,21 @@ export interface AFSExecResult {
 export interface AFSModule {
     readonly name: string;
     readonly description?: string;
+    /**
+     * Access mode for this module.
+     * - "readonly": Only read operations are allowed
+     * - "readwrite": All operations are allowed
+     * Default behavior is implementation-specific.
+     */
+    readonly accessMode?: AFSAccessMode;
+    /**
+     * Enable automatic agent skill scanning for this module.
+     * When set to true, the system will scan this module for agent skills.
+     * @default false
+     */
+    readonly agentSkills?: boolean;
     onMount?(root: AFSRoot): void;
+    symlinkToPhysical?(path: string): Promise<void>;
     list?(path: string, options?: AFSListOptions): Promise<AFSListResult>;
     read?(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
     write?(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
@@ -81,14 +110,53 @@ export interface AFSModule {
     search?(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
     exec?(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
 }
+/**
+ * Parameters for loading a module from configuration.
+ */
+export interface AFSModuleLoadParams {
+    /** Path to the configuration file */
+    filepath: string;
+    /** Parsed configuration object */
+    parsed?: object;
+}
+/**
+ * Interface for module classes that support schema validation and loading from configuration.
+ * This describes the static part of a module class.
+ *
+ * @example
+ * ```typescript
+ * class MyModule implements AFSModule {
+ *   static schema() { return mySchema; }
+ *   static async load(params: AFSModuleLoadParams) { ... }
+ *   // ...
+ * }
+ *
+ * // Type check
+ * const _check: AFSModuleClass<MyModule, MyModuleOptions> = MyModule;
+ * ```
+ */
+export interface AFSModuleClass<T extends AFSModule = AFSModule, O extends object = object> {
+    /** Returns the Zod schema for validating module configuration */
+    schema(): ZodType<O>;
+    /** Loads a module instance from configuration file path and parsed config */
+    load(params: AFSModuleLoadParams): Promise<T>;
+    /** Constructor */
+    new (options: O): T;
+}
 export type AFSRootEvents = {
-    agentSucceed: [{
-        input: object;
-        output: object;
-    }];
+    agentSucceed: [
+        {
+            agentId?: string;
+            userId?: string;
+            sessionId?: string;
+            input: object;
+            output: object;
+            messages?: object[];
+        }
+    ];
     historyCreated: [{
         entry: AFSEntry;
-    }];
+    }, options: AFSOperationOptions];
 };
 export interface AFSRootListOptions extends AFSListOptions, AFSContextPreset {
     preset?: string;
@@ -105,6 +173,8 @@ export interface AFSRootSearchResult extends Omit<AFSSearchResult, "data"> {
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
     list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
     search(path: string, query: string, options: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }
 export interface AFSEntryMetadata extends Record<string, any> {
     execute?: {
@@ -115,12 +185,14 @@ export interface AFSEntryMetadata extends Record<string, any> {
     };
     childrenCount?: number;
     childrenTruncated?: boolean;
+    gitignored?: boolean;
 }
 export interface AFSEntry<T = any> {
     id: string;
     createdAt?: Date;
     updatedAt?: Date;
     path: string;
+    agentId?: string | null;
     userId?: string | null;
     sessionId?: string | null;
     summary?: string | null;
@@ -151,7 +223,7 @@ export interface AFSContextPreset {
     }, {
         data: unknown;
     }>;
-    format?: "default" | "tree" | AFSContextPresetOptionAgent<{
+    format?: "default" | "simple-list" | "tree" | AFSContextPresetOptionAgent<{
         data: unknown;
     }, {
         data: unknown;

package/lib/esm/afs.d.ts

@@ -9,6 +9,11 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     name: string;
     constructor(options?: AFSOptions);
     private modules;
+    /**
+     * Check if write operations are allowed for the given module.
+     * Throws AFSReadonlyError if not allowed.
+     */
+    private checkWritePermission;
     mount(module: AFSModule): this;
     listModules(): Promise<{
         name: string;
@@ -28,5 +33,10 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
     private _search;
     private findModules;
     exec(path: string, args: Record<string, any>, options: AFSExecOptions): Promise<AFSExecResult>;
+    private buildSimpleListView;
     private buildTreeView;
+    private buildMetadataSuffix;
+    private physicalPath?;
+    initializePhysicalPath(): Promise<string>;
+    cleanupPhysicalPath(): Promise<void>;
 }

package/lib/esm/afs.js

@@ -1,6 +1,9 @@
+import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import { v7 } from "@aigne/uuid";
 import { Emitter } from "strict-event-emitter";
 import { joinURL } from "ufo";
 import { z } from "zod";
+import { AFSReadonlyError } from "./error.js";
 import { afsEntrySchema, } from "./type.js";
 const DEFAULT_MAX_DEPTH = 1;
 const MODULES_ROOT_DIR = "/modules";
@@ -15,12 +18,22 @@ export class AFS extends Emitter {
         }
     }
     modules = new Map();
+    /**
+     * Check if write operations are allowed for the given module.
+     * Throws AFSReadonlyError if not allowed.
+     */
+    checkWritePermission(module, operation, path) {
+        // Module-level readonly (undefined means readonly by default)
+        if (module.accessMode !== "readwrite") {
+            throw new AFSReadonlyError(`Module '${module.name}' is readonly, cannot perform ${operation} to ${path}`);
+        }
+    }
     mount(module) {
-        let path = joinURL("/", module.name);
-        if (!/^\/[^/]+$/.test(path)) {
-            throw new Error(`Invalid mount path: ${path}. Must start with '/' and contain no other '/'`);
+        // Validate module name (should not contain '/')
+        if (module.name.includes("/")) {
+            throw new Error(`Invalid module name: ${module.name}. Module name must not contain '/'`);
         }
-        path = joinURL(MODULES_ROOT_DIR, path);
+        const path = joinURL(MODULES_ROOT_DIR, module.name);
         if (this.modules.has(path)) {
             throw new Error(`Module already mounted at path: ${path}`);
         }
@@ -50,14 +63,36 @@ export class AFS extends Emitter {
     }
     async _list(path, options = {}) {
         const results = [];
+        // Special case: listing root "/" should return /modules directory
+        if (path === "/" && this.modules.size > 0) {
+            const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+            // Always include /modules directory first
+            results.push({
+                id: "modules",
+                path: MODULES_ROOT_DIR,
+                summary: "All mounted modules",
+            });
+            if (maxDepth === 1) {
+                // Only show /modules directory
+                return { data: results };
+            }
+            // For maxDepth > 1, also get children of /modules with reduced depth
+            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) {
-            const moduleEntry = {
-                id: matched.module.name,
-                path: matched.remainedModulePath,
-                summary: matched.module.description,
-            };
             if (matched.maxDepth === 0) {
+                // When maxDepth is 0, show the module entry
+                const moduleEntry = {
+                    id: matched.module.name,
+                    path: matched.modulePath,
+                    summary: matched.module.description,
+                };
                 results.push(moduleEntry);
                 continue;
             }
@@ -68,18 +103,16 @@ export class AFS extends Emitter {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (data.length) {
-                    results.push(...data.map((entry) => ({
-                        ...entry,
-                        path: joinURL(matched.modulePath, entry.path),
-                    })));
-                }
-                else {
-                    results.push(moduleEntry);
-                }
+                const children = data.map((entry) => ({
+                    ...entry,
+                    path: joinURL(matched.modulePath, entry.path),
+                }));
+                // Always include all nodes (including the current path itself)
+                // This ensures consistent behavior across all listing scenarios
+                results.push(...children);
             }
             catch (error) {
-                console.error(`Error listing from module at ${matched.modulePath}`, error);
+                throw new Error(`Error listing from module at ${matched.modulePath}: ${error.message}`);
             }
         }
         return { data: results };
@@ -104,6 +137,7 @@ export class AFS extends Emitter {
         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,
@@ -117,6 +151,7 @@ export class AFS extends Emitter {
         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) {
@@ -129,6 +164,7 @@ export class AFS extends Emitter {
         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 = {}) {
@@ -158,12 +194,14 @@ export class AFS extends Emitter {
             ? await dedupe.invoke({ data: mapped }, options).then((res) => res.data)
             : mapped;
         let formatted = deduped;
-        if (format === "tree") {
+        if (format === "simple-list" || format === "tree") {
             const valid = z.array(afsEntrySchema).safeParse(deduped);
-            if (valid.data)
-                formatted = this.buildTreeView(valid.data);
-            else
+            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);
@@ -191,7 +229,7 @@ export class AFS extends Emitter {
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error searching in module at ${modulePath}`, error);
+                throw new Error(`Error searching in module at ${modulePath}: ${error.message}`);
             }
         }
         return { data: results, message: messages.join("; ") };
@@ -230,6 +268,9 @@ export class AFS extends Emitter {
             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 = new Map();
@@ -251,23 +292,7 @@ export class AFS extends Emitter {
                 const isLast = index === keys.length - 1;
                 const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
                 const entry = entryMap.get(fullPath);
-                // Build metadata suffix
-                const metadataParts = [];
-                // Children count
-                const childrenCount = entry?.metadata?.childrenCount;
-                if (typeof childrenCount === "number") {
-                    metadataParts.push(`${childrenCount} items`);
-                }
-                // Children truncated
-                if (entry?.metadata?.childrenTruncated) {
-                    metadataParts.push("truncated");
-                }
-                // Executable
-                if (entry?.metadata?.execute) {
-                    metadataParts.push("executable");
-                }
-                const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
-                result += `${prefix}${isLast ? "└── " : "├── "}${key}${metadataSuffix}`;
+                result += `${prefix}${isLast ? "└── " : "├── "}${key}${entry ? this.buildMetadataSuffix(entry) : ""}`;
                 result += `\n`;
                 result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
             });
@@ -275,4 +300,47 @@ export class AFS extends Emitter {
         };
         return renderTree(tree);
     }
+    buildMetadataSuffix(entry) {
+        // Build metadata suffix
+        const metadataParts = [];
+        // Children count
+        const childrenCount = entry?.metadata?.childrenCount;
+        if (typeof childrenCount === "number") {
+            metadataParts.push(`${childrenCount} items`);
+        }
+        // Children truncated
+        if (entry?.metadata?.childrenTruncated) {
+            metadataParts.push("truncated");
+        }
+        // Gitignored
+        if (entry?.metadata?.gitignored) {
+            metadataParts.push("gitignored");
+        }
+        // Executable
+        if (entry?.metadata?.execute) {
+            metadataParts.push("executable");
+        }
+        const metadataSuffix = metadataParts.length > 0 ? ` [${metadataParts.join(", ")}]` : "";
+        return metadataSuffix;
+    }
+    physicalPath;
+    async initializePhysicalPath() {
+        this.physicalPath ??= (async () => {
+            const rootDir = nodejs.path.join(nodejs.os.tmpdir(), v7());
+            await nodejs.fs.mkdir(rootDir, { recursive: true });
+            for (const [modulePath, module] of this.modules) {
+                const physicalModulePath = nodejs.path.join(rootDir, modulePath);
+                await nodejs.fs.mkdir(nodejs.path.dirname(physicalModulePath), { recursive: true });
+                await module.symlinkToPhysical?.(physicalModulePath);
+            }
+            return rootDir;
+        })();
+        return this.physicalPath;
+    }
+    async cleanupPhysicalPath() {
+        if (this.physicalPath) {
+            await nodejs.fs.rm(await this.physicalPath, { recursive: true, force: true });
+            this.physicalPath = undefined;
+        }
+    }
 }

package/lib/esm/error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Base error class for all AFS errors.
+ */
+export declare class AFSError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+export declare class AFSReadonlyError extends AFSError {
+    constructor(message: string);
+}

package/lib/esm/error.js

@@ -0,0 +1,20 @@
+/**
+ * Base error class for all AFS errors.
+ */
+export class AFSError 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.
+ */
+export class AFSReadonlyError extends AFSError {
+    constructor(message) {
+        super(message, "AFS_READONLY");
+        this.name = "AFSReadonlyError";
+    }
+}

package/lib/esm/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./afs.js";
+export * from "./error.js";
 export * from "./type.js";

package/lib/esm/index.js

@@ -1,2 +1,3 @@
 export * from "./afs.js";
+export * from "./error.js";
 export * from "./type.js";