@aigne/afs-json 1.1.0 → 1.11.0-beta.1

package/LICENSE.md

@@ -1,93 +1,26 @@
-Elastic License 2.0
+# Proprietary License
 
-URL: https://www.elastic.co/licensing/elastic-license
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
 
-## Acceptance
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
 
-By using the software, you agree to all of the terms and conditions below.
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
 
-## Copyright License
+## No License Granted
 
-The licensor grants you a non-exclusive, royalty-free, worldwide,
-non-sublicensable, non-transferable license to use, copy, distribute, make
-available, and prepare derivative works of the software, in each case subject to
-the limitations and conditions below.
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
 
-## Limitations
+## Public Artifact Distribution
 
-You may not provide the software to third parties as a hosted or managed
-service, where the service provides users with access to any substantial set of
-the features or functionality of the software.
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
 
-You may not move, change, disable, or circumvent the license key functionality
-in the software, and you may not remove or obscure any functionality in the
-software that is protected by the license key.
+## Contact
 
-You may not alter, remove, or obscure any licensing, copyright, or other notices
-of the licensor in the software. Any use of the licensor’s trademarks is subject
-to applicable law.
-
-## Patents
-
-The licensor grants you a license, under any patent claims the licensor can
-license, or becomes able to license, to make, have made, use, sell, offer for
-sale, import and have imported the software, in each case subject to the
-limitations and conditions in this license. This license does not cover any
-patent claims that you cause to be infringed by modifications or additions to
-the software. If you or your company make any written claim that the software
-infringes or contributes to infringement of any patent, your patent license for
-the software granted under these terms ends immediately. If your company makes
-such a claim, your patent license ends immediately for work on behalf of your
-company.
-
-## Notices
-
-You must ensure that anyone who gets a copy of any part of the software from you
-also gets a copy of these terms.
-
-If you modify the software, you must include in any modified copies of the
-software prominent notices stating that you have modified the software.
-
-## No Other Rights
-
-These terms do not imply any licenses other than those expressly granted in
-these terms.
-
-## Termination
-
-If you use the software in violation of these terms, such use is not licensed,
-and your licenses will automatically terminate. If the licensor provides you
-with a notice of your violation, and you cease all violation of this license no
-later than 30 days after you receive that notice, your licenses will be
-reinstated retroactively. However, if you violate these terms after such
-reinstatement, any additional violation of these terms will cause your licenses
-to terminate automatically and permanently.
-
-## No Liability
-
-*As far as the law allows, the software comes as is, without any warranty or
-condition, and the licensor will not be liable to you for any damages arising
-out of these terms or the use or nature of the software, under any kind of
-legal claim.*
-
-## Definitions
-
-The **licensor** is the entity offering these terms, and the **software** is the
-software the licensor makes available under these terms, including any portion
-of it.
-
-**you** refers to the individual or entity agreeing to these terms.
-
-**your company** is any legal entity, sole proprietorship, or other kind of
-organization that you work for, plus all organizations that have control over,
-are under the control of, or are under common control with that
-organization. **control** means ownership of substantially all the assets of an
-entity, or the power to direct its management and policies by vote, contract, or
-otherwise. Control can be direct or indirect.
-
-**your licenses** are all the licenses granted to you for the software under
-these terms.
-
-**use** means anything you do with the software requiring one of your licenses.
-
-**trademark** means trademarks, service marks, and similar rights.
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -33,7 +33,7 @@ afs.mount(
   new AFSJSON({
     name: "config",
     jsonPath: "./config.json",
-  })
+  }),
 );
 
 // Or mount a YAML file
@@ -41,7 +41,7 @@ afs.mount(
   new AFSJSON({
     name: "app-config",
     jsonPath: "./config.yaml",
-  })
+  }),
 );
 
 // Read the entire JSON/YAML
@@ -86,6 +86,7 @@ version: "1.0.0"
 ```
 
 This YAML structure becomes:
+
 ```
 /config/                              # Root object
 /config/database/                     # Nested object (directory)
@@ -99,6 +100,7 @@ This YAML structure becomes:
 ```
 
 **Format Detection and Persistence:**
+
 - Format is detected automatically from file extension (.json, .yaml, .yml)
 - When writing to a YAML file, changes are saved in YAML format
 - When writing to a JSON file, changes are saved in JSON format
@@ -124,6 +126,7 @@ This YAML structure becomes:
 ```
 
 This structure becomes:
+
 ```
 /config/                    # Root object
 /config/database/           # Nested object (directory)
@@ -161,6 +164,7 @@ This structure becomes:
 ```
 
 This structure becomes:
+
 ```
 /users/                     # Array (directory)
 /users/0/                   # First user object (directory)
@@ -181,23 +185,23 @@ This structure becomes:
 
 ```typescript
 // Read a property from an array object
-const { data } = await afs.read('/modules/users/0/name');
+const { data } = await afs.read("/modules/users/0/name");
 console.log(data?.content); // "Alice"
 
 // Update a nested property in an array object
-await afs.write('/modules/users/0/profile/age', { content: 31 });
+await afs.write("/modules/users/0/profile/age", { content: 31 });
 
 // Add a new property to an array object
-await afs.write('/modules/users/0/active', { content: true });
+await afs.write("/modules/users/0/active", { content: true });
 
 // List all properties of an array object
-const result = await afs.list('/modules/users/0');
+const result = await afs.list("/modules/users/0");
 
 // Search within array objects
-const results = await afs.search('/modules/users', 'Beijing');
+const results = await afs.search("/modules/users", "Beijing");
 
 // Delete from an array (shifts subsequent indices)
-await afs.delete('/modules/users/1', { recursive: true });
+await afs.delete("/modules/users/1", { recursive: true });
 // Now users/2 becomes users/1
 ```
 
@@ -205,15 +209,16 @@ await afs.delete('/modules/users/1', { recursive: true });
 
 ```typescript
 interface AFSJSONOptions {
-  name?: string;              // Module name (default: basename of jsonPath without extension)
-  jsonPath: string;           // Path to JSON or YAML file
-  description?: string;       // Module description
-  accessMode?: "readonly" | "readwrite";  // Access mode (default: "readwrite")
-  agentSkills?: boolean;      // Enable agent skill scanning
+  name?: string; // Module name (default: basename of jsonPath without extension)
+  jsonPath: string; // Path to JSON or YAML file
+  description?: string; // Module description
+  accessMode?: "readonly" | "readwrite"; // Access mode (default: "readwrite")
+  agentSkills?: boolean; // Enable agent skill scanning
 }
 ```
 
 **Note:** File format is automatically detected from the `jsonPath` extension:
+
 - `.json` files are saved as JSON
 - `.yaml` or `.yml` files are saved as YAML
 
@@ -225,7 +230,7 @@ afs.mount(
     name: "readonly-config",
     jsonPath: "./config.json",
     accessMode: "readonly",
-  })
+  }),
 );
 
 // Reading is allowed
@@ -244,7 +249,7 @@ afs.mount(
     name: "settings",
     jsonPath: "./settings.json",
     accessMode: "readwrite",
-  })
+  }),
 );
 
 // Or mount a YAML file
@@ -253,7 +258,7 @@ afs.mount(
     name: "config",
     jsonPath: "./config.yaml",
     accessMode: "readwrite",
-  })
+  }),
 );
 
 // Update a value
@@ -299,6 +304,3 @@ Search for values within the JSON/YAML structure.
 - **Kubernetes Config**: Navigate and query YAML configuration files
 - **CI/CD Pipelines**: Access and modify YAML pipeline configurations
 
-## License
-
-Elastic-2.0

package/dist/index.cjs

@@ -0,0 +1,366 @@
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let _aigne_afs_utils_zod = require("@aigne/afs/utils/zod");
+let yaml = require("yaml");
+let zod = require("zod");
+
+//#region src/index.ts
+const LIST_MAX_LIMIT = 1e3;
+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"),
+	description: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string().describe("A description of the JSON module")),
+	accessMode: (0, _aigne_afs_utils_zod.optionalize)(zod.z.enum(["readonly", "readwrite"]).describe("Access mode for this module")),
+	agentSkills: (0, _aigne_afs_utils_zod.optionalize)(zod.z.boolean().describe("Enable automatic agent skill scanning for this module"))
+}));
+/**
+* AFS module for mounting JSON/YAML files as virtual file systems.
+*
+* 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 {
+	static schema() {
+		return afsJSONOptionsSchema;
+	}
+	static async load({ filepath, parsed }) {
+		return new AFSJSON({
+			...await AFSJSON.schema().parseAsync(parsed),
+			cwd: (0, node_path.dirname)(filepath)
+		});
+	}
+	jsonData = null;
+	fileStats = {};
+	fileFormat = "json";
+	constructor(options) {
+		this.options = options;
+		(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);
+		const ext = (0, node_path.extname)(jsonPath).toLowerCase();
+		this.fileFormat = ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
+		const extensions = [
+			".json",
+			".yaml",
+			".yml"
+		];
+		let name = (0, node_path.basename)(jsonPath);
+		for (const e of extensions) if (name.endsWith(e)) {
+			name = name.slice(0, -e.length);
+			break;
+		}
+		this.name = options.name || name || "json";
+		this.description = options.description;
+		this.agentSkills = options.agentSkills;
+		this.accessMode = options.accessMode ?? (options.agentSkills ? "readonly" : "readwrite");
+		this.options.jsonPath = jsonPath;
+	}
+	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.
+	*/
+	async ensureLoaded() {
+		if (this.jsonData !== null) return;
+		try {
+			const stats = await (0, node_fs_promises.stat)(this.options.jsonPath);
+			this.fileStats = {
+				birthtime: stats.birthtime,
+				mtime: stats.mtime
+			};
+			this.jsonData = (0, yaml.parse)(await (0, node_fs_promises.readFile)(this.options.jsonPath, "utf8"));
+		} catch (error) {
+			if (error.code === "ENOENT") this.jsonData = {};
+			else throw error;
+		}
+	}
+	/**
+	* Save JSON/YAML data back to file. Only called in readwrite mode.
+	*/
+	async saveToFile() {
+		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);
+		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) {
+		const normalized = this.normalizePath(path);
+		if (normalized === "/") return [];
+		return normalized.slice(1).split("/");
+	}
+	/**
+	* Navigate to a value in the JSON structure using path segments
+	*/
+	getValueAtPath(data, segments) {
+		let current = data;
+		for (const segment of segments) {
+			if (current == null) return void 0;
+			if (Array.isArray(current)) {
+				const index = Number.parseInt(segment, 10);
+				if (Number.isNaN(index) || index < 0 || index >= current.length) return;
+				current = current[index];
+			} else if (typeof current === "object") current = current[segment];
+			else return;
+		}
+		return current;
+	}
+	/**
+	* Set a value in the JSON structure at the given path
+	*/
+	setValueAtPath(data, segments, value) {
+		if (segments.length === 0) throw new Error("Cannot set value at root path");
+		let current = data;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			const nextSegment = segments[i + 1];
+			if (Array.isArray(current)) {
+				const index = Number.parseInt(segment, 10);
+				if (Number.isNaN(index) || index < 0) throw new Error(`Invalid array index: ${segment}`);
+				while (current.length <= index) current.push(null);
+				if (current[index] == null) current[index] = !Number.isNaN(Number.parseInt(nextSegment, 10)) ? [] : {};
+				current = current[index];
+			} else if (typeof current === "object") {
+				if (current[segment] == null) current[segment] = !Number.isNaN(Number.parseInt(nextSegment, 10)) ? [] : {};
+				current = current[segment];
+			} else throw new Error(`Cannot set property on non-object at ${segments.slice(0, i + 1).join("/")}`);
+		}
+		const lastSegment = segments[segments.length - 1];
+		if (Array.isArray(current)) {
+			const index = Number.parseInt(lastSegment, 10);
+			if (Number.isNaN(index) || index < 0) throw new Error(`Invalid array index: ${lastSegment}`);
+			current[index] = value;
+		} else if (typeof current === "object") current[lastSegment] = value;
+		else throw new Error("Cannot set property on non-object");
+	}
+	/**
+	* Delete a value from the JSON structure at the given path
+	*/
+	deleteValueAtPath(data, segments) {
+		if (segments.length === 0) throw new Error("Cannot delete root path");
+		let current = data;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			if (Array.isArray(current)) {
+				const index = Number.parseInt(segment, 10);
+				if (Number.isNaN(index) || index < 0 || index >= current.length) return false;
+				current = current[index];
+			} else if (typeof current === "object") {
+				if (!(segment in current)) return false;
+				current = current[segment];
+			} else return false;
+		}
+		const lastSegment = segments[segments.length - 1];
+		if (Array.isArray(current)) {
+			const index = Number.parseInt(lastSegment, 10);
+			if (Number.isNaN(index) || index < 0 || index >= current.length) return false;
+			current.splice(index, 1);
+			return true;
+		}
+		if (typeof current === "object") {
+			if (!(lastSegment in current)) return false;
+			delete current[lastSegment];
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Check if a value is a "directory" (object or array with children)
+	*/
+	isDirectory(value) {
+		if (Array.isArray(value)) return true;
+		if (typeof value === "object" && value !== null) return true;
+		return false;
+	}
+	/**
+	* Get children of a directory value
+	*/
+	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]) => ({
+			key,
+			value: val
+		}));
+		return [];
+	}
+	/**
+	* Convert a JSON value to an AFSEntry
+	*/
+	valueToAFSEntry(path, value) {
+		const isDir = this.isDirectory(value);
+		const children = isDir ? this.getChildren(value) : [];
+		return {
+			id: path,
+			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",
+				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
+		};
+	}
+};
+
+//#endregion
+exports.AFSJSON = AFSJSON;