@aigne/afs 1.3.0 → 1.4.0-beta.10

package/lib/esm/afs.d.ts

@@ -1,12 +1,19 @@
 import { Emitter } from "strict-event-emitter";
-import type { AFSDeleteOptions, AFSEntry, AFSListOptions, AFSModule, AFSRenameOptions, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload, AFSWriteOptions } from "./type.js";
+import { type AFSContext, type AFSDeleteOptions, type AFSDeleteResult, type AFSExecOptions, type AFSExecResult, type AFSModule, type AFSReadOptions, type AFSReadResult, type AFSRenameOptions, type AFSRenameResult, type AFSRoot, type AFSRootEvents, type AFSRootListOptions, type AFSRootListResult, type AFSRootSearchOptions, type AFSRootSearchResult, type AFSWriteEntryPayload, type AFSWriteOptions, type AFSWriteResult } from "./type.js";
 export interface AFSOptions {
     modules?: AFSModule[];
+    context?: AFSContext;
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    options: AFSOptions;
     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;
@@ -14,32 +21,22 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         description?: string;
         module: AFSModule;
     }[]>;
-    list(path: string, options?: AFSListOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
-    read(path: string): Promise<{
-        result?: AFSEntry;
-        message?: string;
-    }>;
-    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<{
-        result: AFSEntry;
-        message?: string;
-    }>;
-    delete(path: string, options?: AFSDeleteOptions): Promise<{
-        message?: string;
-    }>;
-    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<{
-        message?: string;
-    }>;
-    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
-        list: AFSEntry[];
-        message?: string;
-    }>;
+    list(path: string, options?: AFSRootListOptions): Promise<AFSRootListResult>;
+    private _list;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, content: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    rename(oldPath: string, newPath: string, options?: AFSRenameOptions): Promise<AFSRenameResult>;
+    search(path: string, query: string, options?: AFSRootSearchOptions): Promise<AFSRootSearchResult>;
+    private processWithPreset;
+    private _select;
+    private _search;
     private findModules;
-    exec(path: string, args: Record<string, any>, options: {
-        context: any;
-    }): Promise<{
-        result: Record<string, any>;
-    }>;
+    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,22 +1,39 @@
+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";
 export class AFS extends Emitter {
+    options;
     name = "AFSRoot";
-    constructor(options) {
+    constructor(options = {}) {
         super();
+        this.options = options;
         for (const module of options?.modules ?? []) {
             this.mount(module);
         }
     }
     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}`);
         }
@@ -32,74 +49,101 @@ export class AFS extends Emitter {
             module,
         }));
     }
-    async list(path, options) {
-        const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
-        if (!(maxDepth >= 0))
-            throw new Error(`Invalid maxDepth: ${maxDepth}`);
+    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, undefined, preset, {
+            ...options,
+            defaultSelect: () => this._list(path, options),
+        });
+    }
+    async _list(path, options = {}) {
         const results = [];
-        const messages = [];
+        // 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;
             }
             if (!matched.module.list)
                 continue;
             try {
-                const { list, message } = await matched.module.list(matched.subpath, {
+                const { data } = await matched.module.list(matched.subpath, {
                     ...options,
                     maxDepth: matched.maxDepth,
                 });
-                if (list.length) {
-                    results.push(...list.map((entry) => ({
-                        ...entry,
-                        path: joinURL(matched.modulePath, entry.path),
-                    })));
-                }
-                else {
-                    results.push(moduleEntry);
-                }
-                if (message)
-                    messages.push(message);
+                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 { list: results, message: messages.join("; ").trim() || undefined };
+        return { data: results };
     }
-    async read(path) {
+    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?.result) {
+            if (res?.data) {
                 return {
                     ...res,
-                    result: {
-                        ...res.result,
-                        path: joinURL(modulePath, res.result.path),
+                    data: {
+                        ...res.data,
+                        path: joinURL(modulePath, res.data.path),
                     },
                 };
             }
         }
-        return { result: undefined, message: "File not found" };
+        return { data: undefined, 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,
-            result: {
-                ...res.result,
-                path: joinURL(module.modulePath, res.result.path),
+            data: {
+                ...res.data,
+                path: joinURL(module.modulePath, res.data.path),
             },
         };
     }
@@ -107,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) {
@@ -119,17 +164,64 @@ 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) {
+    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 = 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);
+        const results = (await Promise.all(data.map((p) => this.read(p).then((res) => res.data)))).filter((i) => !!i);
+        return { data: results };
+    }
+    async _search(path, query, options) {
         const results = [];
         const messages = [];
         for (const { module, modulePath, subpath } of this.findModules(path)) {
             if (!module.search)
                 continue;
             try {
-                const { list, message } = await module.search(subpath, query, options);
-                results.push(...list.map((entry) => ({
+                const { data, message } = await module.search(subpath, query, options);
+                results.push(...data.map((entry) => ({
                     ...entry,
                     path: joinURL(modulePath, entry.path),
                 })));
@@ -137,10 +229,10 @@ 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 { list: results, message: messages.join("; ") };
+        return { data: results, message: messages.join("; ") };
     }
     findModules(path, options) {
         const maxDepth = Math.max(options?.maxDepth ?? DEFAULT_MAX_DEPTH, 1);
@@ -176,4 +268,79 @@ 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();
+        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) {
+        // 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";