@aigne/afs-json 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0 (2026-01-16)
+
+
+### Features
+
+* **afs:** add AFSJSON module support mount a JSON/yaml file to AFS ([6adedc6](https://github.com/AIGNE-io/aigne-framework/commit/6adedc624bedb1bc741da8534f2fbb41e1bc6623))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0-beta.10
+    * @aigne/core bumped to 1.72.0-beta.24
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.69-beta.24

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+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.
+
+## Limitations
+
+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.
+
+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.
+
+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.

package/README.md

@@ -0,0 +1,304 @@
+# @aigne/afs-json
+
+AFS module for mounting JSON and YAML files as virtual file systems.
+
+## Features
+
+- Mount JSON and YAML files to AFS virtual filesystem
+- Navigate JSON/YAML structure as directories and files
+- Support for nested objects and arrays
+- Read-only and read-write modes
+- Path-based access to JSON/YAML properties
+- Automatic format detection based on file extension (.json, .yaml, .yml)
+- Unified YAML parser supports both JSON and YAML formats
+
+## Installation
+
+```bash
+pnpm add @aigne/afs-json
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSJSON } from "@aigne/afs-json";
+
+const afs = new AFS();
+
+// Mount a JSON file
+afs.mount(
+  new AFSJSON({
+    name: "config",
+    jsonPath: "./config.json",
+  })
+);
+
+// Or mount a YAML file
+afs.mount(
+  new AFSJSON({
+    name: "app-config",
+    jsonPath: "./config.yaml",
+  })
+);
+
+// Read the entire JSON/YAML
+const result = await afs.read("/config/");
+console.log(result.data?.content);
+
+// Access nested properties as paths
+const result2 = await afs.read("/config/database/host");
+console.log(result2.data?.content); // "localhost"
+```
+
+### YAML File Support
+
+The module automatically detects file format based on extension and uses the appropriate parser:
+
+```typescript
+// Works with .yaml files
+const yamlConfig = new AFSJSON({ jsonPath: "./app.yaml" });
+
+// Works with .yml files
+const ymlConfig = new AFSJSON({ jsonPath: "./settings.yml" });
+
+// Works with .json files
+const jsonConfig = new AFSJSON({ jsonPath: "./data.json" });
+```
+
+**YAML Example:**
+
+```yaml
+# config.yaml
+database:
+  host: localhost
+  port: 5432
+  credentials:
+    username: admin
+    password: secret
+features:
+  - auth
+  - api
+  - ui
+version: "1.0.0"
+```
+
+This YAML structure becomes:
+```
+/config/                              # Root object
+/config/database/                     # Nested object (directory)
+/config/database/host                 # String value (file): "localhost"
+/config/database/port                 # Number value (file): 5432
+/config/database/credentials/         # Nested object (directory)
+/config/database/credentials/username # String value (file): "admin"
+/config/features/                     # Array (directory)
+/config/features/0                    # Array item (file): "auth"
+/config/version                       # String value (file): "1.0.0"
+```
+
+**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
+- The YAML parser can read both JSON and YAML formats
+
+### JSON File Structure Examples
+
+#### Example 1: Simple nested structure
+
+```json
+{
+  "database": {
+    "host": "localhost",
+    "port": 5432,
+    "credentials": {
+      "username": "admin",
+      "password": "secret"
+    }
+  },
+  "features": ["auth", "api", "ui"],
+  "version": "1.0.0"
+}
+```
+
+This structure becomes:
+```
+/config/                    # Root object
+/config/database/           # Nested object (directory)
+/config/database/host       # String value (file)
+/config/database/port       # Number value (file)
+/config/database/credentials/  # Nested object (directory)
+/config/features/           # Array (directory)
+/config/features/0          # Array item (file)
+/config/version             # String value (file)
+```
+
+#### Example 2: Array of objects
+
+```json
+{
+  "users": [
+    {
+      "name": "Alice",
+      "email": "alice@example.com",
+      "profile": {
+        "age": 30,
+        "city": "Beijing"
+      }
+    },
+    {
+      "name": "Bob",
+      "email": "bob@example.com",
+      "profile": {
+        "age": 25,
+        "city": "Shanghai"
+      }
+    }
+  ]
+}
+```
+
+This structure becomes:
+```
+/users/                     # Array (directory)
+/users/0/                   # First user object (directory)
+/users/0/name               # String value (file): "Alice"
+/users/0/email              # String value (file): "alice@example.com"
+/users/0/profile/           # Nested object (directory)
+/users/0/profile/age        # Number value (file): 30
+/users/0/profile/city       # String value (file): "Beijing"
+/users/1/                   # Second user object (directory)
+/users/1/name               # String value (file): "Bob"
+/users/1/email              # String value (file): "bob@example.com"
+/users/1/profile/           # Nested object (directory)
+/users/1/profile/age        # Number value (file): 25
+/users/1/profile/city       # String value (file): "Shanghai"
+```
+
+**Working with array objects:**
+
+```typescript
+// Read a property from an array object
+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 });
+
+// Add a new property to an array object
+await afs.write('/modules/users/0/active', { content: true });
+
+// List all properties of an array object
+const result = await afs.list('/modules/users/0');
+
+// Search within array objects
+const results = await afs.search('/modules/users', 'Beijing');
+
+// Delete from an array (shifts subsequent indices)
+await afs.delete('/modules/users/1', { recursive: true });
+// Now users/2 becomes users/1
+```
+
+### Options
+
+```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
+}
+```
+
+**Note:** File format is automatically detected from the `jsonPath` extension:
+- `.json` files are saved as JSON
+- `.yaml` or `.yml` files are saved as YAML
+
+### Read-only Mode
+
+```typescript
+afs.mount(
+  new AFSJSON({
+    name: "readonly-config",
+    jsonPath: "./config.json",
+    accessMode: "readonly",
+  })
+);
+
+// Reading is allowed
+await afs.read("/readonly-config/version");
+
+// Writing will throw an error
+await afs.write("/readonly-config/version", { content: "2.0.0" }); // Error!
+```
+
+### Writing to JSON/YAML
+
+```typescript
+// Mount a JSON file
+afs.mount(
+  new AFSJSON({
+    name: "settings",
+    jsonPath: "./settings.json",
+    accessMode: "readwrite",
+  })
+);
+
+// Or mount a YAML file
+afs.mount(
+  new AFSJSON({
+    name: "config",
+    jsonPath: "./config.yaml",
+    accessMode: "readwrite",
+  })
+);
+
+// Update a value
+await afs.write("/settings/theme", { content: "dark" });
+
+// Add a new property
+await afs.write("/settings/notifications/email", { content: true });
+
+// Changes are persisted to the file in its original format
+// - JSON files are saved as JSON with 2-space indentation
+// - YAML files are saved as YAML
+```
+
+## API
+
+### `list(path: string, options?: AFSListOptions): Promise<AFSListResult>`
+
+List entries at a given path. Objects and arrays are treated as directories.
+
+### `read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>`
+
+Read content at a given path. Returns the JSON/YAML value at that path.
+
+### `write(path: string, entry: AFSWriteEntryPayload, options?: AFSWriteOptions): Promise<AFSWriteResult>`
+
+Write content to a path. Updates are persisted to the file in its original format (JSON or YAML).
+
+### `delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult>`
+
+Delete a property from the JSON/YAML structure.
+
+### `search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>`
+
+Search for values within the JSON/YAML structure.
+
+## Use Cases
+
+- **Configuration Management**: Mount config files (JSON/YAML) and access settings via paths
+- **Data Exploration**: Navigate complex JSON/YAML structures as a file system
+- **API Testing**: Mount API responses and explore structure
+- **State Management**: Persist application state in JSON or YAML format
+- **Documentation**: Access structured documentation from JSON/YAML files
+- **Kubernetes Config**: Navigate and query YAML configuration files
+- **CI/CD Pipelines**: Access and modify YAML pipeline configurations
+
+## License
+
+Elastic-2.0

package/lib/cjs/index.d.ts

@@ -0,0 +1,108 @@
+import type { AFSAccessMode, AFSDeleteOptions, AFSDeleteResult, AFSListOptions, AFSListResult, AFSModule, AFSModuleLoadParams, AFSReadOptions, AFSReadResult, AFSRenameOptions, AFSRenameResult, AFSSearchOptions, AFSSearchResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
+import { z } from "zod";
+export interface AFSJSONOptions {
+    name?: string;
+    jsonPath: string;
+    description?: string;
+    /**
+     * Access mode for this module.
+     * - "readonly": Only read operations are allowed
+     * - "readwrite": All operations are allowed (default, unless agentSkills is enabled)
+     * @default "readwrite" (or "readonly" when agentSkills is true)
+     */
+    accessMode?: AFSAccessMode;
+    /**
+     * Enable automatic agent skill scanning for this module.
+     * When enabled, defaults accessMode to "readonly" if not explicitly set.
+     * @default false
+     */
+    agentSkills?: boolean;
+}
+/**
+ * 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.
+ */
+export declare class AFSJSON implements AFSModule {
+    options: AFSJSONOptions & {
+        cwd?: string;
+    };
+    static schema(): z.ZodObject<{
+        name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        jsonPath: z.ZodString;
+        description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        accessMode: z.ZodType<"readonly" | "readwrite" | undefined, z.ZodTypeDef, "readonly" | "readwrite" | undefined>;
+        agentSkills: z.ZodType<boolean | undefined, z.ZodTypeDef, boolean | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        jsonPath: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        agentSkills?: boolean | undefined;
+    }, {
+        jsonPath: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        agentSkills?: boolean | undefined;
+    }>;
+    static load({ filepath, parsed }: AFSModuleLoadParams): Promise<AFSJSON>;
+    private jsonData;
+    private fileStats;
+    private fileFormat;
+    constructor(options: AFSJSONOptions & {
+        cwd?: string;
+    });
+    name: string;
+    description?: string;
+    accessMode: AFSAccessMode;
+    agentSkills?: boolean;
+    /**
+     * Load JSON/YAML data from file. Called lazily on first access.
+     * Uses YAML parser which can handle both JSON and YAML formats.
+     */
+    private ensureLoaded;
+    /**
+     * Save JSON/YAML data back to file. Only called in readwrite mode.
+     */
+    private saveToFile;
+    /**
+     * Normalize path to ensure consistent format
+     */
+    private normalizePath;
+    /**
+     * Get path segments from normalized path
+     */
+    private getPathSegments;
+    /**
+     * Navigate to a value in the JSON structure using path segments
+     */
+    private getValueAtPath;
+    /**
+     * Set a value in the JSON structure at the given path
+     */
+    private setValueAtPath;
+    /**
+     * Delete a value from the JSON structure at the given path
+     */
+    private deleteValueAtPath;
+    /**
+     * Check if a value is a "directory" (object or array with children)
+     */
+    private isDirectory;
+    /**
+     * Get children of a directory value
+     */
+    private getChildren;
+    /**
+     * Convert a JSON value to an AFSEntry
+     */
+    private valueToAFSEntry;
+    list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    write(path: string, entry: 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?: AFSSearchOptions): Promise<AFSSearchResult>;
+}