@aigne/afs-json 1.11.0-beta.9 → 1.12.0-beta.12

package/dist/index.mjs

@@ -1,22 +1,35 @@
 import { __decorate } from "./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, join } from "node:path";
-import { AFSNotFoundError } from "@aigne/afs";
+import { createHash } from "node:crypto";
+import { AFSConflictError, AFSNotFoundError, getPlatform, orderByRequested, orderEntries } from "@aigne/afs";
 import { AFSBaseProvider, Delete, Explain, List, Meta, Read, Rename, Search, Stat, Write } from "@aigne/afs/provider";
 import { camelize, optionalize, zodParse } from "@aigne/afs/utils/zod";
+import { resolveLocalPath } from "@aigne/afs-provider-utils";
+import { dump, load } from "js-yaml";
 import { joinURL } from "ufo";
-import { parse, stringify } from "yaml";
 import { z } from "zod";
 
 //#region src/index.ts
 const LIST_MAX_LIMIT = 1e3;
+const JSON_AS_FORMATS = [
+	"content",
+	"compact",
+	"tree"
+];
 /** 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";
+function assertLocalPathWithinCwd(resolvedPath, cwd, rawPath) {
+	const { path } = getPlatform();
+	const root = path.resolve(cwd);
+	const candidate = path.resolve(resolvedPath);
+	const rootPrefix = root.endsWith("/") || root.endsWith("\\") ? root : `${root}/`;
+	const windowsRootPrefix = root.endsWith("\\") ? root : `${root}\\`;
+	if (candidate !== root && !candidate.startsWith(rootPrefix) && !candidate.startsWith(windowsRootPrefix)) throw new Error(`Local path escapes configured base directory: ${rawPath}`);
+	return candidate;
+}
 const afsJSONOptionsSchema = camelize(z.object({
 	name: optionalize(z.string()),
 	jsonPath: z.string().describe("The path to the JSON/YAML file to mount"),
@@ -37,7 +50,7 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 	static manifest() {
 		return {
 			name: "json",
-			description: "Mount a JSON or YAML file as a virtual filesystem",
+			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: z.object({ localPath: z.string() }),
@@ -45,12 +58,56 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 				"json",
 				"yaml",
 				"structured-data"
-			]
+			],
+			capabilityTags: [
+				"read-write",
+				"crud",
+				"search",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "sandboxed",
+				resourceAccess: []
+			},
+			capabilities: { filesystem: {
+				read: true,
+				write: true
+			} }
+		};
+	}
+	static treeSchema() {
+		return {
+			operations: [
+				"list",
+				"read",
+				"write",
+				"delete",
+				"search",
+				"stat",
+				"explain"
+			],
+			tree: {
+				"/": { kind: "json:root" },
+				"/{key}": { kind: "json:value" }
+			},
+			auth: { type: "none" },
+			bestFor: [
+				"JSON/YAML navigation",
+				"structured data editing",
+				"config files"
+			],
+			notFor: ["binary files", "large datasets"]
 		};
 	}
 	static async load({ basePath, config } = {}) {
+		const raw = config;
+		const normalized = raw?.localPath && !raw.jsonPath ? {
+			...raw,
+			jsonPath: raw.localPath
+		} : raw;
 		return new AFSJSON({
-			...await AFSJSON.schema().parseAsync(config),
+			...await AFSJSON.schema().parseAsync(normalized),
 			cwd: basePath
 		});
 	}
@@ -67,22 +124,17 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		this.options = options;
 		if (options.localPath && !options.jsonPath) options.jsonPath = options.localPath;
 		zodParse(afsJSONOptionsSchema, options);
-		let jsonPath;
-		jsonPath = options.jsonPath.replaceAll("${CWD}", process.cwd());
-		if (jsonPath.startsWith("~/")) jsonPath = join(process.env.HOME || "", jsonPath.slice(2));
-		if (!isAbsolute(jsonPath)) jsonPath = join(options.cwd || process.cwd(), jsonPath);
-		if (!existsSync(jsonPath)) {
-			mkdirSync(dirname(jsonPath), { recursive: true });
-			writeFileSync(jsonPath, "{}", "utf8");
-		}
-		const ext = extname(jsonPath).toLowerCase();
+		let jsonPath = resolveLocalPath(options.jsonPath, { cwd: options.cwd });
+		if (options.cwd) jsonPath = assertLocalPathWithinCwd(jsonPath, options.cwd, options.jsonPath);
+		const platform = getPlatform();
+		const ext = platform.path.extname(jsonPath).toLowerCase();
 		this.fileFormat = ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
 		const extensions = [
 			".json",
 			".yaml",
 			".yml"
 		];
-		let name = basename(jsonPath);
+		let name = platform.path.basename(jsonPath);
 		for (const e of extensions) if (name.endsWith(e)) {
 			name = name.slice(0, -e.length);
 			break;
@@ -93,6 +145,12 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		this.accessMode = options.accessMode ?? (options.agentSkills ? "readonly" : "readwrite");
 		this.resolvedJsonPath = jsonPath;
 	}
+	async supportedAs(path) {
+		await this.ensureLoaded();
+		const normalizedPath = this.normalizePath(path);
+		const segments = this.getPathSegments(normalizedPath);
+		return this.getValueAtPath(this.jsonData, segments) === void 0 ? [] : [...JSON_AS_FORMATS];
+	}
 	/**
 	* Read metadata for a JSON node via /.meta or /path/.meta
 	* Returns stored metadata merged with computed type information
@@ -144,7 +202,17 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		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) => ({
+		const rootChildrenToProcess = rootChildren.length > maxChildren ? rootChildren.slice(0, maxChildren) : rootChildren;
+		const orderBy = ctx.options?.orderBy;
+		if (maxDepth === 1 && orderByRequested(orderBy)) {
+			const { entries: ordered, applied } = orderEntries(rootChildrenToProcess.map((child) => this.valueToAFSEntry(normalizedPath === "/" ? `/${child.key}` : `${normalizedPath}/${child.key}`, child.value)), orderBy);
+			const data = ordered.slice(0, limit);
+			return applied ? { data } : {
+				data,
+				meta: { orderByIgnored: true }
+			};
+		}
+		const queue = rootChildrenToProcess.map((child) => ({
 			path: normalizedPath === "/" ? `/${child.key}` : `${normalizedPath}/${child.key}`,
 			value: child.value,
 			depth: 1
@@ -169,14 +237,37 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 				}
 			}
 		}
+		if (orderByRequested(orderBy)) return {
+			data: entries,
+			meta: { orderByIgnored: true }
+		};
 		return { data: entries };
 	}
+	/**
+	* AFSJSON handles `handleDepth` itself, so it doesn't get the base.ts
+	* orderBy fallback — it implements ordering natively in listHandler and
+	* declares the sub-capability here (consumed by both base.list's
+	* no-silent-drop check and the /.meta/.capabilities manifest).
+	*/
+	getOperationsDeclaration() {
+		const ops = super.getOperationsDeclaration();
+		if (typeof ops.list === "boolean" ? ops.list : ops.list?.supported === true) ops.list = {
+			supported: true,
+			features: { orderBy: true }
+		};
+		return ops;
+	}
 	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 AFSNotFoundError(normalizedPath);
+		const as = ctx.options?.as;
+		if (as) {
+			if (!this.isJsonAsFormat(as)) throw new AFSNotFoundError(joinURL(normalizedPath, ".as", as));
+			return this.buildJsonAsEntry(normalizedPath, value, as);
+		}
 		return this.valueToAFSEntry(normalizedPath, value);
 	}
 	/**
@@ -192,6 +283,15 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		await this.ensureLoaded();
 		const normalizedPath = ctx.params.path ? `/${ctx.params.path}` : "/";
 		const segments = this.getPathSegments(normalizedPath);
+		const ifMatch = ctx.options?.ifMatch;
+		if (ifMatch !== void 0) {
+			const currentValue = this.getValueAtPath(this.jsonData, segments);
+			const currentVersion = this.computeVersion(currentValue);
+			if (ifMatch !== currentVersion) throw new AFSConflictError(normalizedPath, {
+				cid: currentVersion,
+				mtime: this.fileStats.mtime ? this.fileStats.mtime.getTime() : null
+			});
+		}
 		if (payload.content !== void 0) this.setValueAtPath(this.jsonData, segments, payload.content);
 		if (payload.meta !== void 0 && typeof payload.meta === "object") {
 			const finalMeta = {
@@ -214,7 +314,8 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 			updatedAt: this.fileStats.mtime,
 			meta: {
 				...storedMeta,
-				childrenCount: isDir ? children.length : void 0
+				childrenCount: isDir ? children.length : void 0,
+				version: this.computeVersion(newValue)
 			},
 			userId: payload.userId,
 			sessionId: payload.sessionId,
@@ -290,6 +391,7 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		const children = isDir ? this.getChildren(value) : [];
 		const meta = { ...this.loadMeta(normalizedPath) };
 		if (isDir) meta.childrenCount = children.length;
+		meta.version = this.computeVersion(value);
 		return { data: {
 			id: segments.length > 0 ? segments[segments.length - 1] : "/",
 			path: normalizedPath,
@@ -298,6 +400,16 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 			meta
 		} };
 	}
+	/**
+	* Compute an opaque version string for a JSON value at a given path.
+	* Used as the ifMatch token for optimistic-concurrency writes. SHA-256 over
+	* the canonical JSON serialization keeps the token stable across mounts of
+	* the same content. Clients treat this as opaque — see AFSWriteOptions.ifMatch.
+	*/
+	computeVersion(value) {
+		const canonical = value === void 0 ? " undefined" : JSON.stringify(value) ?? "null";
+		return createHash("sha256").update(canonical).digest("hex");
+	}
 	async readCapabilitiesHandler(_ctx) {
 		await this.ensureLoaded();
 		const operations = [
@@ -308,6 +420,11 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 			"search"
 		];
 		if (this.accessMode === "readwrite") operations.push("write", "delete", "rename");
+		const baseOps = this.getOperationsDeclaration();
+		if (typeof baseOps.write === "boolean" ? baseOps.write : baseOps.write?.supported === true) baseOps.write = {
+			supported: true,
+			features: { ifMatch: true }
+		};
 		return {
 			id: "/.meta/.capabilities",
 			path: "/.meta/.capabilities",
@@ -317,7 +434,7 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 				description: this.description || `JSON/YAML virtual filesystem (${this.fileFormat} format)`,
 				tools: [],
 				actions: [],
-				operations: this.getOperationsDeclaration()
+				operations: baseOps
 			},
 			meta: {
 				kind: "afs:capabilities",
@@ -491,16 +608,20 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 	*/
 	async ensureLoaded() {
 		if (this.jsonData !== null) return;
+		const platform = getPlatform();
 		try {
-			const stats = await stat(this.resolvedJsonPath);
+			const stats = await platform.fs.stat(this.resolvedJsonPath);
 			this.fileStats = {
-				birthtime: stats.birthtime,
-				mtime: stats.mtime
+				birthtime: stats.birthtime ? new Date(stats.birthtime) : void 0,
+				mtime: stats.mtime ? new Date(stats.mtime) : void 0
 			};
-			this.jsonData = parse(await readFile(this.resolvedJsonPath, "utf8"));
-		} catch (error) {
-			if (error.code === "ENOENT") this.jsonData = {};
-			else throw error;
+			this.jsonData = load(await platform.fs.readTextFile(this.resolvedJsonPath));
+		} catch {
+			try {
+				await platform.fs.mkdir(platform.path.dirname(this.resolvedJsonPath), { recursive: true });
+				await platform.fs.writeFile(this.resolvedJsonPath, "{}");
+			} catch {}
+			this.jsonData = {};
 		}
 	}
 	/**
@@ -508,22 +629,34 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 	*/
 	async saveToFile() {
 		let content;
-		if (this.fileFormat === "yaml") content = stringify(this.jsonData);
+		if (this.fileFormat === "yaml") content = dump(this.jsonData);
 		else content = JSON.stringify(this.jsonData, null, 2);
-		await writeFile(this.resolvedJsonPath, content, "utf8");
-		const stats = await stat(this.resolvedJsonPath);
+		const platform = getPlatform();
+		await platform.fs.writeFile(this.resolvedJsonPath, content);
+		const stats = await platform.fs.stat(this.resolvedJsonPath);
 		this.fileStats = {
-			birthtime: this.fileStats.birthtime || stats.birthtime,
-			mtime: stats.mtime
+			birthtime: this.fileStats.birthtime,
+			mtime: stats.mtime ? new Date(stats.mtime) : void 0
 		};
 	}
 	/**
 	* Get path segments from normalized path
 	*/
+	/**
+	* Dangerous property names that must never be used as object keys.
+	* Prevents prototype pollution attacks (e.g., writing to /__proto__/polluted).
+	*/
+	static DANGEROUS_KEYS = new Set([
+		"__proto__",
+		"constructor",
+		"prototype"
+	]);
 	getPathSegments(path) {
 		const normalized = this.normalizePath(path);
 		if (normalized === "/") return [];
-		return normalized.slice(1).split("/");
+		const segments = normalized.slice(1).split("/");
+		for (const segment of segments) if (AFSJSON.DANGEROUS_KEYS.has(segment)) throw new Error(`Path segment "${segment}" is not allowed (prototype pollution guard)`);
+		return segments;
 	}
 	/**
 	* Navigate to a value in the JSON structure using path segments
@@ -608,6 +741,9 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		if (typeof value === "object" && value !== null) return true;
 		return false;
 	}
+	isJsonAsFormat(value) {
+		return typeof value === "string" && JSON_AS_FORMATS.includes(value);
+	}
 	/**
 	* Get children of a directory value (filters out .afs meta key)
 	*/
@@ -622,6 +758,48 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 		}));
 		return [];
 	}
+	compactJsonValue(value) {
+		if (!this.isDirectoryValue(value)) return value;
+		if (Array.isArray(value)) return {
+			type: "array",
+			length: value.length,
+			sample: value.slice(0, 3).map((item) => this.compactJsonValue(item))
+		};
+		const entries = Object.entries(value).filter(([key]) => !this.isMetaKey(key));
+		const preview = {};
+		for (const [key, child] of entries) {
+			if (Object.keys(preview).length >= 6) break;
+			if (!this.isDirectoryValue(child)) preview[key] = child;
+		}
+		return {
+			type: "object",
+			keys: entries.map(([key]) => key).slice(0, 12),
+			...Object.keys(preview).length > 0 ? { preview } : {}
+		};
+	}
+	stripMetaFromValue(value) {
+		if (!this.isDirectoryValue(value)) return value;
+		if (Array.isArray(value)) return value.map((item) => this.stripMetaFromValue(item));
+		const result = {};
+		for (const [key, child] of Object.entries(value)) if (!this.isMetaKey(key)) result[key] = this.stripMetaFromValue(child);
+		return result;
+	}
+	buildJsonAsEntry(path, value, as) {
+		let content;
+		if (as === "content") content = value;
+		else if (as === "tree") content = this.stripMetaFromValue(value);
+		else content = this.compactJsonValue(value);
+		return {
+			id: `${path}.as:${as}`,
+			path: joinURL(path, ".as", as),
+			content,
+			meta: {
+				kind: `json:${as}`,
+				representation: as
+			},
+			actions: []
+		};
+	}
 	/**
 	* Convert a JSON value to an AFSEntry
 	*/
@@ -633,7 +811,8 @@ var AFSJSON = class AFSJSON extends AFSBaseProvider {
 			content: isDir ? void 0 : value,
 			meta: {
 				kind,
-				childrenCount: isDir ? children.length : void 0
+				childrenCount: isDir ? children.length : void 0,
+				version: this.computeVersion(value)
 			},
 			createdAt: this.fileStats.birthtime,
 			updatedAt: this.fileStats.mtime