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

package/dist/index.cjs

@@ -1,11 +1,23 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+const require_decorate = require('./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.cjs');
+let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
+let _aigne_afs = require("@aigne/afs");
+let _aigne_afs_provider = require("@aigne/afs/provider");
 let _aigne_afs_utils_zod = require("@aigne/afs/utils/zod");
+let ufo = require("ufo");
 let yaml = require("yaml");
 let zod = require("zod");
 
 //#region src/index.ts
 const LIST_MAX_LIMIT = 1e3;
+/** Hidden key for storing AFS metadata (mirrors FS provider's .afs directory) */
+const AFS_KEY = ".afs";
+/** Subkey for storing metadata (mirrors FS provider's meta.yaml file) */
+const META_KEY = "meta";
+/** Subkey for storing child node metadata (mirrors FS provider's .nodes directory) */
+const NODES_KEY = ".nodes";
 const afsJSONOptionsSchema = (0, _aigne_afs_utils_zod.camelize)(zod.z.object({
 	name: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string()),
 	jsonPath: zod.z.string().describe("The path to the JSON/YAML file to mount"),
@@ -19,26 +31,51 @@ const afsJSONOptionsSchema = (0, _aigne_afs_utils_zod.camelize)(zod.z.object({
 * JSON/YAML objects are treated as directories, and properties/array items as files.
 * Supports nested structures and path-based access to data values.
 */
-var AFSJSON = class AFSJSON {
+var AFSJSON = class AFSJSON extends _aigne_afs_provider.AFSBaseProvider {
 	static schema() {
 		return afsJSONOptionsSchema;
 	}
-	static async load({ filepath, parsed }) {
+	static manifest() {
+		return {
+			name: "json",
+			description: "JSON or YAML file — navigate and edit structured data as a tree.\n- Objects and arrays become directories, primitives become leaf nodes\n- Read/write individual values, search across structure\n- Path structure: `/{key}/{nested-key}` (arrays indexed by position)",
+			uriTemplate: "json://{localPath+}",
+			category: "structured-data",
+			schema: zod.z.object({ localPath: zod.z.string() }),
+			tags: [
+				"json",
+				"yaml",
+				"structured-data"
+			]
+		};
+	}
+	static async load({ basePath, config } = {}) {
 		return new AFSJSON({
-			...await AFSJSON.schema().parseAsync(parsed),
-			cwd: (0, node_path.dirname)(filepath)
+			...await AFSJSON.schema().parseAsync(config),
+			cwd: basePath
 		});
 	}
+	name;
+	description;
+	accessMode;
+	agentSkills;
 	jsonData = null;
 	fileStats = {};
 	fileFormat = "json";
+	resolvedJsonPath;
 	constructor(options) {
+		super();
 		this.options = options;
+		if (options.localPath && !options.jsonPath) options.jsonPath = options.localPath;
 		(0, _aigne_afs_utils_zod.zodParse)(afsJSONOptionsSchema, options);
 		let jsonPath;
 		jsonPath = options.jsonPath.replaceAll("${CWD}", process.cwd());
 		if (jsonPath.startsWith("~/")) jsonPath = (0, node_path.join)(process.env.HOME || "", jsonPath.slice(2));
 		if (!(0, node_path.isAbsolute)(jsonPath)) jsonPath = (0, node_path.join)(options.cwd || process.cwd(), jsonPath);
+		if (!(0, node_fs.existsSync)(jsonPath)) {
+			(0, node_fs.mkdirSync)((0, node_path.dirname)(jsonPath), { recursive: true });
+			(0, node_fs.writeFileSync)(jsonPath, "{}", "utf8");
+		}
 		const ext = (0, node_path.extname)(jsonPath).toLowerCase();
 		this.fileFormat = ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
 		const extensions = [
@@ -55,12 +92,400 @@ var AFSJSON = class AFSJSON {
 		this.description = options.description;
 		this.agentSkills = options.agentSkills;
 		this.accessMode = options.accessMode ?? (options.agentSkills ? "readonly" : "readwrite");
-		this.options.jsonPath = jsonPath;
+		this.resolvedJsonPath = jsonPath;
+	}
+	/**
+	* Read metadata for a JSON node via /.meta or /path/.meta
+	* Returns stored metadata merged with computed type information
+	* Note: Meta is read-only. To write metadata, use write() with payload.meta.
+	*/
+	async readMetaHandler(ctx) {
+		await this.ensureLoaded();
+		const nodePath = (0, ufo.joinURL)("/", ctx.params.path ?? "");
+		const segments = this.getPathSegments(nodePath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(nodePath);
+		const isDir = this.isDirectoryValue(value);
+		const children = isDir ? this.getChildren(value) : [];
+		let type;
+		if (Array.isArray(value)) type = "array";
+		else if (value === null) type = "null";
+		else if (typeof value === "object") type = "object";
+		else type = typeof value;
+		const storedMeta = this.loadMeta(nodePath) || {};
+		const computedMeta = {
+			type,
+			path: nodePath
+		};
+		if (isDir) {
+			computedMeta.childrenCount = children.length;
+			if (Array.isArray(value)) computedMeta.length = value.length;
+			else computedMeta.keys = Object.keys(value).filter((k) => !this.isMetaKey(k));
+		} else computedMeta.value = value;
+		if (this.fileStats.birthtime) computedMeta.created = this.fileStats.birthtime;
+		if (this.fileStats.mtime) computedMeta.modified = this.fileStats.mtime;
+		return this.buildEntry((0, ufo.joinURL)(nodePath, ".meta"), {
+			meta: storedMeta,
+			content: computedMeta,
+			createdAt: this.fileStats.birthtime,
+			updatedAt: this.fileStats.mtime
+		});
+	}
+	async listHandler(ctx) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const options = ctx.options;
+		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const maxChildren = typeof options?.maxChildren === "number" ? options.maxChildren : Number.MAX_SAFE_INTEGER;
+		const maxDepth = options?.maxDepth ?? 1;
+		const segments = this.getPathSegments(normalizedPath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		if (maxDepth === 0) return { data: [] };
+		if (!this.isDirectoryValue(value)) return { data: [] };
+		const entries = [];
+		const rootChildren = this.getChildren(value);
+		const queue = (rootChildren.length > maxChildren ? rootChildren.slice(0, maxChildren) : rootChildren).map((child) => ({
+			path: normalizedPath === "/" ? `/${child.key}` : `${normalizedPath}/${child.key}`,
+			value: child.value,
+			depth: 1
+		}));
+		while (queue.length > 0) {
+			const item = queue.shift();
+			if (!item) break;
+			const { path: itemPath, value: itemValue, depth } = item;
+			const entry = this.valueToAFSEntry(itemPath, itemValue);
+			entries.push(entry);
+			if (entries.length >= limit) break;
+			if (this.isDirectoryValue(itemValue) && depth < maxDepth) {
+				const children = this.getChildren(itemValue);
+				const childrenToProcess = children.length > maxChildren ? children.slice(0, maxChildren) : children;
+				for (const child of childrenToProcess) {
+					const childPath = itemPath === "/" ? `/${child.key}` : `${itemPath}/${child.key}`;
+					queue.push({
+						path: childPath,
+						value: child.value,
+						depth: depth + 1
+					});
+				}
+			}
+		}
+		return { data: entries };
+	}
+	async readHandler(ctx) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const segments = this.getPathSegments(normalizedPath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		return this.valueToAFSEntry(normalizedPath, value);
+	}
+	/**
+	* Write handler - supports writing content and/or metadata
+	*
+	* | payload | behavior |
+	* |---------|----------|
+	* | { content } | write content only |
+	* | { metadata } | write metadata only (to .afs storage) |
+	* | { content, metadata } | write both |
+	*/
+	async writeHandler(ctx, payload) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const segments = this.getPathSegments(normalizedPath);
+		if (payload.content !== void 0) this.setValueAtPath(this.jsonData, segments, payload.content);
+		if (payload.meta !== void 0 && typeof payload.meta === "object") {
+			const finalMeta = {
+				...this.loadMeta(normalizedPath) || {},
+				...payload.meta
+			};
+			this.saveMeta(normalizedPath, finalMeta);
+		}
+		await this.saveToFile();
+		const newValue = this.getValueAtPath(this.jsonData, segments);
+		const isDir = this.isDirectoryValue(newValue);
+		const children = isDir ? this.getChildren(newValue) : [];
+		const storedMeta = this.loadMeta(normalizedPath) || {};
+		return { data: {
+			id: normalizedPath,
+			path: normalizedPath,
+			content: payload.content !== void 0 ? payload.content : newValue,
+			summary: payload.summary,
+			createdAt: this.fileStats.birthtime,
+			updatedAt: this.fileStats.mtime,
+			meta: {
+				...storedMeta,
+				childrenCount: isDir ? children.length : void 0
+			},
+			userId: payload.userId,
+			sessionId: payload.sessionId,
+			linkTo: payload.linkTo
+		} };
+	}
+	async deleteHandler(ctx) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const options = ctx.options;
+		const segments = this.getPathSegments(normalizedPath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		if (this.isDirectoryValue(value) && this.getChildren(value).length > 0 && !options?.recursive) throw new Error(`Cannot delete directory '${normalizedPath}' without recursive option. Set recursive: true to delete directories.`);
+		this.deleteValueAtPath(this.jsonData, segments);
+		await this.saveToFile();
+		return { message: `Successfully deleted: ${normalizedPath}` };
+	}
+	async renameHandler(ctx, newPath) {
+		await this.ensureLoaded();
+		const normalizedOldPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const normalizedNewPath = this.normalizePath(newPath);
+		const options = ctx.options;
+		const oldSegments = this.getPathSegments(normalizedOldPath);
+		const newSegments = this.getPathSegments(normalizedNewPath);
+		const oldValue = this.getValueAtPath(this.jsonData, oldSegments);
+		if (oldValue === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedOldPath);
+		if (this.getValueAtPath(this.jsonData, newSegments) !== void 0 && !options?.overwrite) throw new Error(`Destination '${normalizedNewPath}' already exists. Set overwrite: true to replace it.`);
+		this.setValueAtPath(this.jsonData, newSegments, oldValue);
+		this.deleteValueAtPath(this.jsonData, oldSegments);
+		await this.saveToFile();
+		return { message: `Successfully renamed '${normalizedOldPath}' to '${normalizedNewPath}'` };
+	}
+	async searchHandler(ctx, query, options) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const caseSensitive = options?.caseSensitive ?? false;
+		const segments = this.getPathSegments(normalizedPath);
+		const rootValue = this.getValueAtPath(this.jsonData, segments);
+		if (rootValue === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		const entries = [];
+		const searchQuery = caseSensitive ? query : query.toLowerCase();
+		const searchInValue = (valuePath, value) => {
+			if (entries.length >= limit) return;
+			let matched = false;
+			if (!this.isDirectoryValue(value)) {
+				const valueStr = typeof value === "string" ? value : JSON.stringify(value);
+				if ((caseSensitive ? valueStr : valueStr.toLowerCase()).includes(searchQuery)) matched = true;
+			}
+			if (matched) entries.push(this.valueToAFSEntry(valuePath, value));
+			if (this.isDirectoryValue(value)) {
+				const children = this.getChildren(value);
+				for (const child of children) {
+					if (entries.length >= limit) break;
+					searchInValue(valuePath === "/" ? `/${child.key}` : `${valuePath}/${child.key}`, child.value);
+				}
+			}
+		};
+		searchInValue(normalizedPath, rootValue);
+		return {
+			data: entries,
+			message: entries.length >= limit ? `Results truncated to limit ${limit}` : void 0
+		};
+	}
+	async statHandler(ctx) {
+		await this.ensureLoaded();
+		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const segments = this.getPathSegments(normalizedPath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		const isDir = this.isDirectoryValue(value);
+		const children = isDir ? this.getChildren(value) : [];
+		const meta = { ...this.loadMeta(normalizedPath) };
+		if (isDir) meta.childrenCount = children.length;
+		return { data: {
+			id: segments.length > 0 ? segments[segments.length - 1] : "/",
+			path: normalizedPath,
+			createdAt: this.fileStats.birthtime,
+			updatedAt: this.fileStats.mtime,
+			meta
+		} };
+	}
+	async readCapabilitiesHandler(_ctx) {
+		await this.ensureLoaded();
+		const operations = [
+			"list",
+			"read",
+			"stat",
+			"explain",
+			"search"
+		];
+		if (this.accessMode === "readwrite") operations.push("write", "delete", "rename");
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				description: this.description || `JSON/YAML virtual filesystem (${this.fileFormat} format)`,
+				tools: [],
+				actions: [],
+				operations: this.getOperationsDeclaration()
+			},
+			meta: {
+				kind: "afs:capabilities",
+				operations
+			}
+		};
+	}
+	async explainHandler(ctx) {
+		await this.ensureLoaded();
+		const normalizedPath = (0, ufo.joinURL)("/", ctx.params.path ?? "");
+		const format = ctx.options?.format || "markdown";
+		const segments = this.getPathSegments(normalizedPath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(normalizedPath);
+		const nodeName = segments.length > 0 ? segments[segments.length - 1] : "/";
+		const isDir = this.isDirectoryValue(value);
+		const storedMeta = this.loadMeta(normalizedPath);
+		const lines = [];
+		if (format === "markdown") {
+			lines.push(`# ${nodeName}`);
+			lines.push("");
+			lines.push(`**Path:** \`${normalizedPath}\``);
+			lines.push(`**Format:** ${this.fileFormat.toUpperCase()}`);
+			if (normalizedPath === "/") {
+				const topType = Array.isArray(this.jsonData) ? "array" : "object";
+				const children = this.getChildren(this.jsonData);
+				lines.push(`**Structure:** ${topType}`);
+				lines.push(`**Top-level keys:** ${children.length}`);
+				if (children.length > 0) {
+					lines.push("");
+					lines.push("## Keys");
+					lines.push("");
+					for (const child of children.slice(0, 30)) {
+						const childVal = child.value;
+						const childType = this.describeType(childVal);
+						lines.push(`- \`${child.key}\` — ${childType}`);
+					}
+					if (children.length > 30) lines.push(`- ... and ${children.length - 30} more`);
+				}
+			} else if (Array.isArray(value)) {
+				lines.push(`**Type:** array`);
+				lines.push(`**Elements:** ${value.length}`);
+				if (value.length > 0) {
+					const elementType = this.describeType(value[0]);
+					const isHomogeneous = value.every((v) => this.describeType(v) === elementType);
+					lines.push(`**Element type:** ${isHomogeneous ? elementType : "mixed"}`);
+				}
+			} else if (typeof value === "object" && value !== null) {
+				const children = this.getChildren(value);
+				lines.push(`**Type:** object`);
+				lines.push(`**Keys:** ${children.length}`);
+				if (children.length > 0) {
+					lines.push("");
+					lines.push("## Keys");
+					lines.push("");
+					for (const child of children.slice(0, 30)) {
+						const childType = this.describeType(child.value);
+						lines.push(`- \`${child.key}\` — ${childType}`);
+					}
+					if (children.length > 30) lines.push(`- ... and ${children.length - 30} more`);
+				}
+			} else {
+				const valType = value === null ? "null" : typeof value;
+				lines.push(`**Type:** ${valType}`);
+				const valStr = String(value);
+				if (valStr.length > 200) lines.push(`**Value:** ${valStr.slice(0, 200)}...`);
+				else lines.push(`**Value:** ${valStr}`);
+			}
+			if (storedMeta) {
+				lines.push("");
+				lines.push("## Metadata");
+				for (const [key, val] of Object.entries(storedMeta)) lines.push(`- **${key}:** ${JSON.stringify(val)}`);
+			}
+		} else {
+			lines.push(`${nodeName} (${isDir ? "directory" : "value"})`);
+			lines.push(`Path: ${normalizedPath}`);
+			lines.push(`Format: ${this.fileFormat}`);
+			if (isDir) {
+				const children = this.getChildren(value);
+				lines.push(`Children: ${children.length}`);
+			} else {
+				const valStr = String(value);
+				lines.push(`Type: ${value === null ? "null" : typeof value}`);
+				lines.push(`Value: ${valStr.length > 200 ? `${valStr.slice(0, 200)}...` : valStr}`);
+			}
+		}
+		return {
+			content: lines.join("\n"),
+			format
+		};
+	}
+	/**
+	* Get a human-readable type description for a JSON value.
+	*/
+	describeType(value) {
+		if (value === null) return "null";
+		if (Array.isArray(value)) return `array[${value.length}]`;
+		if (typeof value === "object") return `object{${Object.keys(value).filter((k) => !this.isMetaKey(k)).length} keys}`;
+		return typeof value;
+	}
+	/**
+	* Check if a key is a hidden meta key that should be filtered from listings
+	*/
+	isMetaKey(key) {
+		return key === AFS_KEY;
+	}
+	/**
+	* Load metadata for a node.
+	*
+	* Storage location depends on node type (mirrors FS provider's .afs structure):
+	* - Objects: `.afs.meta` key within the object itself
+	* - Primitives: parent's `.afs[".nodes"][key].meta`
+	*/
+	loadMeta(nodePath) {
+		const segments = this.getPathSegments(nodePath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) return null;
+		if (this.isDirectoryValue(value) && !Array.isArray(value)) {
+			const afs$1 = value[AFS_KEY];
+			if (afs$1 && typeof afs$1 === "object" && !Array.isArray(afs$1)) {
+				const meta$1 = afs$1[META_KEY];
+				if (meta$1 && typeof meta$1 === "object" && !Array.isArray(meta$1)) return meta$1;
+			}
+			return null;
+		}
+		if (segments.length === 0) return null;
+		const parentSegments = segments.slice(0, -1);
+		const nodeKey = segments[segments.length - 1];
+		const parentValue = this.getValueAtPath(this.jsonData, parentSegments);
+		if (!parentValue || Array.isArray(parentValue) || typeof parentValue !== "object") return null;
+		const afs = parentValue[AFS_KEY];
+		if (!afs || typeof afs !== "object" || Array.isArray(afs)) return null;
+		const nodes = afs[NODES_KEY];
+		if (!nodes || typeof nodes !== "object" || Array.isArray(nodes)) return null;
+		const nodeEntry = nodes[nodeKey];
+		if (!nodeEntry || typeof nodeEntry !== "object" || Array.isArray(nodeEntry)) return null;
+		const meta = nodeEntry[META_KEY];
+		if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+		return meta;
+	}
+	/**
+	* Save metadata for a node.
+	*
+	* Storage location depends on node type (mirrors FS provider's .afs structure):
+	* - Objects: `.afs.meta` key within the object itself
+	* - Primitives: parent's `.afs[".nodes"][key].meta`
+	*/
+	saveMeta(nodePath, meta) {
+		const segments = this.getPathSegments(nodePath);
+		const value = this.getValueAtPath(this.jsonData, segments);
+		if (value === void 0) throw new _aigne_afs.AFSNotFoundError(nodePath);
+		if (this.isDirectoryValue(value) && !Array.isArray(value)) {
+			if (!value[AFS_KEY]) value[AFS_KEY] = {};
+			value[AFS_KEY][META_KEY] = meta;
+			return;
+		}
+		if (segments.length === 0) throw new Error("Cannot save meta for root when root is not an object");
+		const parentSegments = segments.slice(0, -1);
+		const nodeKey = segments[segments.length - 1];
+		const parentValue = this.getValueAtPath(this.jsonData, parentSegments);
+		if (!parentValue || typeof parentValue !== "object") throw new Error(`Parent path is not an object`);
+		if (Array.isArray(parentValue)) throw new Error(`Cannot save meta for array elements`);
+		if (!parentValue[AFS_KEY]) parentValue[AFS_KEY] = {};
+		if (!parentValue[AFS_KEY][NODES_KEY]) parentValue[AFS_KEY][NODES_KEY] = {};
+		if (!parentValue[AFS_KEY][NODES_KEY][nodeKey]) parentValue[AFS_KEY][NODES_KEY][nodeKey] = {};
+		parentValue[AFS_KEY][NODES_KEY][nodeKey][META_KEY] = meta;
 	}
-	name;
-	description;
-	accessMode;
-	agentSkills;
 	/**
 	* Load JSON/YAML data from file. Called lazily on first access.
 	* Uses YAML parser which can handle both JSON and YAML formats.
@@ -68,12 +493,12 @@ var AFSJSON = class AFSJSON {
 	async ensureLoaded() {
 		if (this.jsonData !== null) return;
 		try {
-			const stats = await (0, node_fs_promises.stat)(this.options.jsonPath);
+			const stats = await (0, node_fs_promises.stat)(this.resolvedJsonPath);
 			this.fileStats = {
 				birthtime: stats.birthtime,
 				mtime: stats.mtime
 			};
-			this.jsonData = (0, yaml.parse)(await (0, node_fs_promises.readFile)(this.options.jsonPath, "utf8"));
+			this.jsonData = (0, yaml.parse)(await (0, node_fs_promises.readFile)(this.resolvedJsonPath, "utf8"));
 		} catch (error) {
 			if (error.code === "ENOENT") this.jsonData = {};
 			else throw error;
@@ -86,22 +511,14 @@ var AFSJSON = class AFSJSON {
 		let content;
 		if (this.fileFormat === "yaml") content = (0, yaml.stringify)(this.jsonData);
 		else content = JSON.stringify(this.jsonData, null, 2);
-		await (0, node_fs_promises.writeFile)(this.options.jsonPath, content, "utf8");
-		const stats = await (0, node_fs_promises.stat)(this.options.jsonPath);
+		await (0, node_fs_promises.writeFile)(this.resolvedJsonPath, content, "utf8");
+		const stats = await (0, node_fs_promises.stat)(this.resolvedJsonPath);
 		this.fileStats = {
 			birthtime: this.fileStats.birthtime || stats.birthtime,
 			mtime: stats.mtime
 		};
 	}
 	/**
-	* Normalize path to ensure consistent format
-	*/
-	normalizePath(path) {
-		let normalized = path.startsWith("/") ? path : `/${path}`;
-		if (normalized.length > 1 && normalized.endsWith("/")) normalized = normalized.slice(0, -1);
-		return normalized;
-	}
-	/**
 	* Get path segments from normalized path
 	*/
 	getPathSegments(path) {
@@ -187,20 +604,20 @@ var AFSJSON = class AFSJSON {
 	/**
 	* Check if a value is a "directory" (object or array with children)
 	*/
-	isDirectory(value) {
+	isDirectoryValue(value) {
 		if (Array.isArray(value)) return true;
 		if (typeof value === "object" && value !== null) return true;
 		return false;
 	}
 	/**
-	* Get children of a directory value
+	* Get children of a directory value (filters out .afs meta key)
 	*/
 	getChildren(value) {
 		if (Array.isArray(value)) return value.map((item, index) => ({
 			key: String(index),
 			value: item
 		}));
-		if (typeof value === "object" && value !== null) return Object.entries(value).map(([key, val]) => ({
+		if (typeof value === "object" && value !== null) return Object.entries(value).filter(([key]) => !this.isMetaKey(key)).map(([key, val]) => ({
 			key,
 			value: val
 		}));
@@ -210,157 +627,32 @@ var AFSJSON = class AFSJSON {
 	* Convert a JSON value to an AFSEntry
 	*/
 	valueToAFSEntry(path, value) {
-		const isDir = this.isDirectory(value);
+		const isDir = this.isDirectoryValue(value);
 		const children = isDir ? this.getChildren(value) : [];
-		return {
-			id: path,
-			path,
+		const kind = Array.isArray(value) ? "json:array" : isDir ? "json:object" : "json:value";
+		return this.buildEntry(path, {
 			content: isDir ? void 0 : value,
-			createdAt: this.fileStats.birthtime,
-			updatedAt: this.fileStats.mtime,
-			metadata: {
-				type: isDir ? "directory" : "file",
-				childrenCount: isDir ? children.length : void 0
-			}
-		};
-	}
-	async list(path, options) {
-		await this.ensureLoaded();
-		const normalizedPath = this.normalizePath(path);
-		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
-		const maxChildren = typeof options?.maxChildren === "number" ? options.maxChildren : Number.MAX_SAFE_INTEGER;
-		const maxDepth = options?.maxDepth ?? 1;
-		const segments = this.getPathSegments(normalizedPath);
-		const value = this.getValueAtPath(this.jsonData, segments);
-		if (value === void 0) throw new Error(`Path not found: ${normalizedPath}`);
-		const entries = [];
-		const queue = [{
-			path: normalizedPath,
-			value,
-			depth: 0
-		}];
-		while (queue.length > 0) {
-			const item = queue.shift();
-			if (!item) break;
-			const { path: itemPath, value: itemValue, depth } = item;
-			const entry = this.valueToAFSEntry(itemPath, itemValue);
-			entries.push(entry);
-			if (entries.length >= limit) {
-				if (entry.metadata) entry.metadata.childrenTruncated = true;
-				break;
-			}
-			if (this.isDirectory(itemValue) && depth < maxDepth) {
-				const children = this.getChildren(itemValue);
-				const childrenToProcess = children.length > maxChildren ? children.slice(0, maxChildren) : children;
-				if (childrenToProcess.length < children.length && entry.metadata) entry.metadata.childrenTruncated = true;
-				for (const child of childrenToProcess) {
-					const childPath = itemPath === "/" ? `/${child.key}` : `${itemPath}/${child.key}`;
-					queue.push({
-						path: childPath,
-						value: child.value,
-						depth: depth + 1
-					});
-				}
-			}
-		}
-		return { data: entries };
-	}
-	async read(path, _options) {
-		await this.ensureLoaded();
-		const normalizedPath = this.normalizePath(path);
-		const segments = this.getPathSegments(normalizedPath);
-		const value = this.getValueAtPath(this.jsonData, segments);
-		if (value === void 0) return {
-			data: void 0,
-			message: `Path not found: ${normalizedPath}`
-		};
-		return { data: this.valueToAFSEntry(normalizedPath, value) };
-	}
-	async write(path, entry, _options) {
-		await this.ensureLoaded();
-		const normalizedPath = this.normalizePath(path);
-		const segments = this.getPathSegments(normalizedPath);
-		this.setValueAtPath(this.jsonData, segments, entry.content);
-		await this.saveToFile();
-		const newValue = this.getValueAtPath(this.jsonData, segments);
-		const isDir = this.isDirectory(newValue);
-		const children = isDir ? this.getChildren(newValue) : [];
-		return { data: {
-			id: normalizedPath,
-			path: normalizedPath,
-			content: entry.content,
-			summary: entry.summary,
-			description: entry.description,
-			createdAt: this.fileStats.birthtime,
-			updatedAt: this.fileStats.mtime,
-			metadata: {
-				...entry.metadata,
-				type: isDir ? "directory" : "file",
+			meta: {
+				kind,
 				childrenCount: isDir ? children.length : void 0
 			},
-			userId: entry.userId,
-			sessionId: entry.sessionId,
-			linkTo: entry.linkTo
-		} };
-	}
-	async delete(path, options) {
-		await this.ensureLoaded();
-		const normalizedPath = this.normalizePath(path);
-		const segments = this.getPathSegments(normalizedPath);
-		const value = this.getValueAtPath(this.jsonData, segments);
-		if (value === void 0) throw new Error(`Path not found: ${normalizedPath}`);
-		if (this.isDirectory(value) && this.getChildren(value).length > 0 && !options?.recursive) throw new Error(`Cannot delete directory '${normalizedPath}' without recursive option. Set recursive: true to delete directories.`);
-		this.deleteValueAtPath(this.jsonData, segments);
-		await this.saveToFile();
-		return { message: `Successfully deleted: ${normalizedPath}` };
-	}
-	async rename(oldPath, newPath, options) {
-		await this.ensureLoaded();
-		const normalizedOldPath = this.normalizePath(oldPath);
-		const normalizedNewPath = this.normalizePath(newPath);
-		const oldSegments = this.getPathSegments(normalizedOldPath);
-		const newSegments = this.getPathSegments(normalizedNewPath);
-		const oldValue = this.getValueAtPath(this.jsonData, oldSegments);
-		if (oldValue === void 0) throw new Error(`Source path not found: ${normalizedOldPath}`);
-		if (this.getValueAtPath(this.jsonData, newSegments) !== void 0 && !options?.overwrite) throw new Error(`Destination '${normalizedNewPath}' already exists. Set overwrite: true to replace it.`);
-		this.setValueAtPath(this.jsonData, newSegments, oldValue);
-		this.deleteValueAtPath(this.jsonData, oldSegments);
-		await this.saveToFile();
-		return { message: `Successfully renamed '${normalizedOldPath}' to '${normalizedNewPath}'` };
-	}
-	async search(path, query, options) {
-		await this.ensureLoaded();
-		const normalizedPath = this.normalizePath(path);
-		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
-		const caseSensitive = options?.caseSensitive ?? false;
-		const segments = this.getPathSegments(normalizedPath);
-		const rootValue = this.getValueAtPath(this.jsonData, segments);
-		if (rootValue === void 0) throw new Error(`Path not found: ${normalizedPath}`);
-		const entries = [];
-		const searchQuery = caseSensitive ? query : query.toLowerCase();
-		const searchInValue = (valuePath, value) => {
-			if (entries.length >= limit) return;
-			let matched = false;
-			if (!this.isDirectory(value)) {
-				const valueStr = typeof value === "string" ? value : JSON.stringify(value);
-				if ((caseSensitive ? valueStr : valueStr.toLowerCase()).includes(searchQuery)) matched = true;
-			}
-			if (matched) entries.push(this.valueToAFSEntry(valuePath, value));
-			if (this.isDirectory(value)) {
-				const children = this.getChildren(value);
-				for (const child of children) {
-					if (entries.length >= limit) break;
-					searchInValue(valuePath === "/" ? `/${child.key}` : `${valuePath}/${child.key}`, child.value);
-				}
-			}
-		};
-		searchInValue(normalizedPath, rootValue);
-		return {
-			data: entries,
-			message: entries.length >= limit ? `Results truncated to limit ${limit}` : void 0
-		};
+			createdAt: this.fileStats.birthtime,
+			updatedAt: this.fileStats.mtime
+		});
 	}
 };
+require_decorate.__decorate([(0, _aigne_afs_provider.Meta)("/:path*")], AFSJSON.prototype, "readMetaHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.List)("/:path*", { handleDepth: true })], AFSJSON.prototype, "listHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/:path*")], AFSJSON.prototype, "readHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Write)("/:path*")], AFSJSON.prototype, "writeHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Delete)("/:path*")], AFSJSON.prototype, "deleteHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Rename)("/:path*")], AFSJSON.prototype, "renameHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Search)("/:path*")], AFSJSON.prototype, "searchHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Stat)("/:path*")], AFSJSON.prototype, "statHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/.meta/.capabilities")], AFSJSON.prototype, "readCapabilitiesHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Explain)("/:path*")], AFSJSON.prototype, "explainHandler", null);
+var src_default = AFSJSON;
 
 //#endregion
-exports.AFSJSON = AFSJSON;
+exports.AFSJSON = AFSJSON;
+exports.default = src_default;