@aigne/example-afs-git 0.0.0 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-# AFS JSON Example
+# AFS Git Example
 
 <p align="center">
   <picture>
@@ -8,28 +8,26 @@
   </picture>
 </p>
 
-This example demonstrates how to create a chatbot that can interact with JSON and YAML files as a virtual file system using the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) and [AIGNE CLI](https://github.com/AIGNE-io/aigne-framework/blob/main/packages/cli/README.md). The example utilizes the `AFSJSON` module to provide JSON/YAML file access to AI agents through the **AIGNE File System (AFS)** interface.
+This example demonstrates how to create a chatbot that can interact with Git repositories using the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) and [AIGNE CLI](https://github.com/AIGNE-io/aigne-framework/blob/main/packages/cli/README.md). The example utilizes the `AFSGit` module to provide Git repository access to AI agents through the **AIGNE File System (AFS)** interface.
 
 **AIGNE File System (AFS)** is a virtual file system abstraction that provides AI agents with unified access to various storage backends. For comprehensive documentation, see [AFS Documentation](../../afs/README.md).
 
-**Note:** The AFSJSON module supports both JSON and YAML formats. File format is automatically detected based on the file extension (.json, .yaml, .yml).
-
 ## What You'll See
 
-**User asks:** "What's the email of the second user?"
+**User asks:** "What changed in the authentication code between main and develop?"
 
 **Behind the scenes:**
-1. LLM calls `afs_list` → lists JSON structure as directories/files
-2. Sees `/users` directory with `/users/0`, `/users/1`, `/users/2` subdirectories
-3. LLM calls `afs_read("/users/1/email")` → reads the email property
-4. LLM presents: "The email is alice@example.com"
+1. LLM calls `afs_list` → lists branches (`/main`, `/develop`)
+2. LLM calls `afs_read("/main/src/auth/index.ts")` → reads from main branch
+3. LLM calls `afs_read("/develop/src/auth/index.ts")` → reads from develop branch
+4. LLM compares and presents: "The develop branch added OAuth support with three new functions..."
 
-**The power:** AI agents can navigate JSON structures as if they were directories, making complex data queries simple and intuitive!
+**The power:** AI agents can intelligently navigate Git branches, compare code across versions, and search through repository history!
 
 ## Prerequisites
 
 * [Node.js](https://nodejs.org) (>=20.0) and npm installed on your machine
-* A JSON or YAML file to explore
+* A Git repository to explore
 * An [OpenAI API key](https://platform.openai.com/api-keys) for interacting with OpenAI's services
 * Optional dependencies (if running the example from source code):
   * [Pnpm](https://pnpm.io) for package management
@@ -42,68 +40,72 @@ This example demonstrates how to create a chatbot that can interact with JSON an
 ```bash
 export OPENAI_API_KEY=YOUR_OPENAI_API_KEY
 
-# Mount a JSON file (read-write by default)
-npx -y @aigne/example-afs-json --path ./config.json --interactive
+# Mount current Git repository (read-only by default)
+npx -y @aigne/example-afs-git --interactive
 
-# Mount a YAML file
-npx -y @aigne/example-afs-json --path ./config.yaml --interactive
+# Mount a specific repository
+npx -y @aigne/example-afs-git --path /path/to/repo --interactive
 
 # Ask a specific question
-npx -y @aigne/example-afs-json --path ./data.json --input "What users are in the JSON file?"
+npx -y @aigne/example-afs-git --input "What files changed in the last commit on main?"
+
+# Limit to specific branches
+npx -y @aigne/example-afs-git --branches main,develop --interactive
 
-# YAML file example
-npx -y @aigne/example-afs-json --path ./settings.yml --input "What's the database host?"
+# Enable read-write mode with auto-commit
+npx -y @aigne/example-afs-git --access-mode readwrite --auto-commit --interactive
 
-# Read-only mode (works with both JSON and YAML)
-npx -y @aigne/example-afs-json --path ./config.json --access-mode readonly --interactive
+# Read-write mode without auto-commit (manual commit control)
+npx -y @aigne/example-afs-git --access-mode readwrite --interactive
 ```
 
 ## See It In Action
 
-Here's what happens when you ask about JSON data:
+Here's what happens when you ask about code differences:
 
 ```
-Given JSON file (users.json):
-{
-  "users": [
-    { "name": "Bob", "email": "bob@example.com", "age": 30 },
-    { "name": "Alice", "email": "alice@example.com", "age": 25 },
-    { "name": "Charlie", "email": "charlie@example.com", "age": 35 }
-  ],
-  "config": {
-    "appName": "MyApp",
-    "version": "1.0.0"
-  }
-}
-
-👤 You: "What's the email of the second user?"
-
-🤖 Agent thinks: Let me explore the JSON structure...
+👤 You: "What changed in the authentication code between main and develop?"
+
+🤖 Agent thinks: I should list the available branches first...
    → Calls: afs_list("/")
 
-📁 Found structure:
-   • /users (directory - array)
-   • /config (directory - object)
+📁 Found branches:
+   • /main
+   • /develop
+   • /feature-oauth
+
+🤖 Agent thinks: Let me search for auth files in both branches...
+   → Calls: afs_search("/main", "auth")
+   → Calls: afs_search("/develop", "auth")
+
+📄 Found files:
+   • /main/src/auth/index.ts
+   • /develop/src/auth/index.ts
+   • /develop/src/auth/oauth.ts (new!)
 
-🤖 Agent thinks: Users is an array, let me check its contents...
-   → Calls: afs_list("/users")
+🤖 Agent thinks: Let me read both versions...
+   → Calls: afs_read("/main/src/auth/index.ts")
+   → Calls: afs_read("/develop/src/auth/index.ts")
 
-📄 Found items:
-   • /users/0 (first user)
-   • /users/1 (second user)
-   • /users/2 (third user)
+🤖 AI: "The develop branch has added OAuth support to the authentication system:
 
-🤖 Agent thinks: Let me read the email of the second user...
-   → Calls: afs_read("/users/1/email")
+       Key Changes:
+       • Added a new oauth.ts module with OAuth 2.0 flow
+       • Updated index.ts with three new functions:
+         - initOAuthFlow()
+         - handleOAuthCallback()
+         - refreshOAuthToken()
+       • Added support for Google and GitHub providers
 
-🤖 AI: "The email of the second user is alice@example.com"
+       The main branch still uses the original JWT-only authentication.
+       Would you like me to explain how the OAuth flow works?"
 ```
 
-**Key insight:** JSON structures become navigable file systems - arrays are directories with numeric indices, objects are directories with property names!
+**Key insight:** The agent can navigate between branches like directories, compare code, and identify what's new!
 
 ### Connect to an AI Model
 
-As an example, running `npx -y @aigne/example-afs-json --input "What's in this JSON?"` requires an AI model. If this is your first run, you need to connect one.
+As an example, running `npx -y @aigne/example-afs-git --input "What branches exist?"` requires an AI model. If this is your first run, you need to connect one.
 
 - Connect via the official AIGNE Hub
 - Connect via a self-hosted AIGNE Hub
@@ -126,7 +128,7 @@ git clone https://github.com/AIGNE-io/aigne-framework
 ### Install Dependencies
 
 ```bash
-cd aigne-framework/examples/afs-json
+cd aigne-framework/examples/afs-git
 
 pnpm install
 ```
@@ -134,51 +136,47 @@ pnpm install
 ### Run the Example
 
 ```bash
-# Run with a JSON file
-pnpm start --path ./data.json
+# Run with current repository (read-only by default)
+pnpm start
+
+# Run with a specific repository
+pnpm start --path /path/to/repo
 
 # Run in interactive chat mode
-pnpm start --path ./config.json --interactive
+pnpm start --interactive
+
+# Limit to specific branches
+pnpm start --branches main,develop --interactive
 
-# Read-only mode (no modifications allowed)
-pnpm start --path ./config.json --access-mode readonly --interactive
+# Enable read-write mode with auto-commit
+pnpm start --access-mode readwrite --auto-commit --interactive
+
+# Read-write mode without auto-commit
+pnpm start --access-mode readwrite --interactive
 ```
 
 ### Command Line Options
 
 | Option | Description | Default | Example |
 |--------|-------------|---------|---------|
-| `--path` | Path to the JSON or YAML file | Required | `--path ./data.json` or `--path ./config.yaml` |
-| `--access-mode` | Access mode: `readonly` or `readwrite` | `readwrite` | `--access-mode readonly` |
+| `--path` | Path to the git repository | Current directory | `--path /path/to/repo` |
+| `--branches` | Comma-separated list of branches to access | All branches | `--branches main,develop` |
+| `--access-mode` | Access mode: `readonly` or `readwrite` | `readonly` | `--access-mode readwrite` |
+| `--auto-commit` | Automatically commit changes (requires `readwrite` mode) | `false` | `--auto-commit` |
 | `--interactive` | Run in interactive chat mode | `false` | `--interactive` |
-| `--input` | Single question to ask | - | `--input "What's in this file?"` |
-
-**Supported file formats:**
-- `.json` - JSON files
-- `.yaml` - YAML files
-- `.yml` - YAML files
-
-File format is automatically detected from the extension.
+| `--input` | Single question to ask | - | `--input "What branches exist?"` |
 
 ## How It Works: 3 Simple Steps
 
-### 1. Create AFSJSON Module
+### 1. Create AFSGit Module
 
 ```typescript
-import { AFSJSON } from "@aigne/afs-json";
-
-// Works with JSON files
-const afsJson = new AFSJSON({
-  jsonPath: './data.json',
-  name: 'data',             // optional: module name
-  accessMode: 'readwrite'   // or 'readonly'
-});
+import { AFSGit } from "@aigne/afs-git";
 
-// Also works with YAML files
-const afsYaml = new AFSJSON({
-  jsonPath: './config.yaml',  // or './config.yml'
-  name: 'config',
-  accessMode: 'readwrite'
+const afsGit = new AFSGit({
+  repoPath: process.cwd(),
+  accessMode: 'readonly',  // or 'readwrite' for modifications
+  branches: ['main', 'develop']  // optional: limit branches
 });
 ```
 
@@ -190,7 +188,7 @@ import { AFSHistory } from "@aigne/afs-history";
 
 const afs = new AFS()
   .mount(new AFSHistory({ storage: { url: ":memory:" } }))
-  .mount(afsJson);  // Mounted at /modules/data
+  .mount(afsGit);  // Mounted at /modules/{repo-name}
 ```
 
 ### 3. Create an AI Agent
@@ -199,238 +197,170 @@ const afs = new AFS()
 import { AIAgent } from "@aigne/core";
 
 const agent = AIAgent.from({
-  instructions: "Help users query and modify JSON data.",
+  instructions: "Help users navigate and understand Git repositories.",
   inputKey: "message",
-  afs,  // Agent gets: afs_list, afs_read, afs_write, afs_search
+  afs,  // Agent gets: afs_list, afs_read, afs_search
 });
 ```
 
-**That's it!** The agent can now navigate JSON structures like a file system.
+**That's it!** The agent can now intelligently navigate branches and search through repository files.
 
 ### What the Agent Can Do
 
-**Read Operations:**
-- **`afs_list`** - List JSON structure (objects/arrays as directories)
-- **`afs_read`** - Read property values or nested structures
-- **`afs_search`** - Search for values in the JSON
-
-**Write Operations (readwrite mode):**
-- **`afs_write`** - Update or create properties
-- **`afs_delete`** - Delete properties or array elements
-- **`afs_rename`** - Rename properties
+**Read-Only Mode (default):**
+- **`afs_list`** - List branches and files (with recursive depth control)
+- **`afs_read`** - Read file contents from any branch
+- **`afs_search`** - Fast search using git grep (regex support)
 
-All write operations automatically save to the file in its original format (JSON or YAML)!
+**Read-Write Mode:**
+- **`afs_write`** - Create or modify files (uses git worktrees)
+- **`afs_delete`** - Delete files with auto-commit
+- **`afs_rename`** - Rename/move files with auto-commit
 
-## Path Structure
-
-```json
-// Given this JSON:
-{
-  "users": [
-    { "name": "Bob", "email": "bob@example.com" },
-    { "name": "Alice", "email": "alice@example.com" }
-  ],
-  "config": {
-    "theme": "dark",
-    "lang": "en"
-  }
-}
-
-// Mapped to AFS paths:
-/                           # Root
-├── users/                  # Array (directory)
-│   ├── 0/                  # First user (directory)
-│   │   ├── name            # File: "Bob"
-│   │   └── email           # File: "bob@example.com"
-│   └── 1/                  # Second user (directory)
-│       ├── name            # File: "Alice"
-│       └── email           # File: "alice@example.com"
-└── config/                 # Object (directory)
-    ├── theme               # File: "dark"
-    └── lang                # File: "en"
-```
+All operations use efficient git commands - no workspace pollution!
 
 ## Try These Examples
 
 ```bash
-# Query user data (JSON)
-npx -y @aigne/example-afs-json --path ./users.json --input "How many users are there?"
-
-# Query YAML configuration
-npx -y @aigne/example-afs-json --path ./config.yaml --input "What's the database host?"
+# List all branches
+npx -y @aigne/example-afs-git --input "What branches exist?"
 
-# Read specific values
-npx -y @aigne/example-afs-json --path ./config.json --input "What's the app version?"
+# Compare branches
+npx -y @aigne/example-afs-git --input "What files are different between main and develop?"
 
-# Search for values in YAML
-npx -y @aigne/example-afs-json --path ./settings.yml --input "Find all email addresses"
+# Search across branches
+npx -y @aigne/example-afs-git --input "Find all TODO comments in the main branch"
 
-# Update values (readwrite mode)
-npx -y @aigne/example-afs-json --path ./config.json --input "Update the theme to light"
-
-# Update YAML file
-npx -y @aigne/example-afs-json --path ./config.yaml --input "Change the database port to 3306"
+# Code review
+npx -y @aigne/example-afs-git --input "Review the authentication code in src/auth/"
 
 # Interactive mode - ask follow-up questions
-npx -y @aigne/example-afs-json --path ./data.json --interactive
+npx -y @aigne/example-afs-git --interactive
 ```
 
 **In chat mode, try:**
-- "What properties are in the root?"
-- "Show me all users"
-- "What's the email of the first user?"
-- "List all configuration settings"
-- "Update the version to 2.0.0"
-- "Add a new user named David"
+- "What branches are available?"
+- "Show me the README from the main branch"
+- "Search for 'authentication' in the develop branch"
+- "What files exist in /main/src?"
+- "Compare the package.json between main and feature-oauth"
+- "What TypeScript files changed recently?"
 
 ## Use Cases
 
-### Configuration Management
-Let AI help manage app configurations (JSON or YAML):
+### Code Review Assistance
+Let AI help review code across branches:
 ```typescript
-// JSON configuration
-const afs = new AFS()
-  .mount(new AFSJSON({
-    jsonPath: './config.json',
-    accessMode: 'readwrite'
-  }));
-
-// YAML configuration (common in Kubernetes, Docker Compose)
 const afs = new AFS()
-  .mount(new AFSJSON({
-    jsonPath: './config.yaml',
-    accessMode: 'readwrite'
+  .mount(new AFSGit({
+    repoPath: './my-project',
+    branches: ['main', 'feature-branch']
   }));
-// Ask: "Update the database port to 5432"
+// Ask: "Review the changes in feature-branch compared to main"
 ```
 
-### Data Analysis
-Query complex JSON data structures:
+### Multi-Branch Documentation
+Access documentation from different versions:
 ```typescript
 const afs = new AFS()
-  .mount(new AFSJSON({
-    jsonPath: './analytics.json',
-    accessMode: 'readonly'
+  .mount(new AFSGit({
+    repoPath: './docs-repo',
+    branches: ['v1.0', 'v2.0', 'latest']
   }));
-// Ask: "What's the total revenue for last month?"
+// Ask: "What's the difference in API docs between v1.0 and v2.0?"
 ```
 
-### API Response Exploration
-Navigate large API responses:
+### Repository Analysis
+Analyze code patterns across branches:
 ```typescript
 const afs = new AFS()
-  .mount(new AFSJSON({
-    jsonPath: './api-response.json',
+  .mount(new AFSGit({
+    repoPath: './codebase',
     accessMode: 'readonly'
   }));
-// Ask: "Find all error messages in the response"
+// Ask: "Find all deprecated functions across all branches"
 ```
 
-### Settings Editor
-Interactive settings modification:
+### Multi-Repository Access
+Mount multiple repositories simultaneously:
 ```typescript
 const afs = new AFS()
-  .mount(new AFSJSON({
-    jsonPath: './user-settings.json',
-    accessMode: 'readwrite'
-  }));
-// Ask: "Enable dark mode and set font size to 14"
+  .mount("/frontend", new AFSGit({ repoPath: './frontend' }))
+  .mount("/backend", new AFSGit({ repoPath: './backend' }))
+  .mount("/docs", new AFSGit({ repoPath: './docs' }));
+// Agent can search across all repositories
 ```
 
-### Multi-File Access
-Mount multiple JSON and YAML files:
+### Automated Code Modifications (Read-Write Mode)
+Let AI make commits with auto-commit:
 ```typescript
 const afs = new AFS()
-  .mount("/users", new AFSJSON({ jsonPath: './users.json' }))
-  .mount("/config", new AFSJSON({ jsonPath: './config.yaml' }))
-  .mount("/data", new AFSJSON({ jsonPath: './data.json' }))
-  .mount("/k8s", new AFSJSON({ jsonPath: './deployment.yml' }));
-// Agent can query across all files regardless of format
+  .mount(new AFSGit({
+    repoPath: './my-project',
+    accessMode: 'readwrite',
+    autoCommit: true,
+    commitAuthor: {
+      name: 'AI Agent',
+      email: 'agent@example.com'
+    }
+  }));
+// Ask: "Update the version in package.json to 2.0.0"
 ```
 
-## How JSON Maps to Paths
-
-### Objects as Directories
-```json
-{ "name": "Bob", "age": 30 }
-```
-→ `/name` (file), `/age` (file)
+## Path Structure
 
-### Arrays as Directories
-```json
-["apple", "banana", "orange"]
-```
-→ `/0` (file: "apple"), `/1` (file: "banana"), `/2` (file: "orange")
-
-### Nested Structures
-```json
-{
-  "user": {
-    "profile": {
-      "name": "Bob"
-    }
-  }
-}
 ```
-→ `/user/profile/name` (file: "Bob")
-
-### Arrays of Objects
-```json
-{
-  "users": [
-    { "name": "Bob", "email": "bob@example.com" },
-    { "name": "Alice", "email": "alice@example.com" }
-  ]
-}
+/                              # Root - lists all branches
+├── main/                      # Branch directory
+│   ├── src/
+│   │   └── index.ts          # Files: /main/src/index.ts
+│   ├── package.json
+│   └── README.md
+├── develop/                   # Another branch
+│   └── ...
+└── feature-auth/              # Feature branch
+    └── ...
 ```
-→ `/users/0/name` (file: "Bob")
-→ `/users/0/email` (file: "bob@example.com")
-→ `/users/1/name` (file: "Alice")
-→ `/users/1/email` (file: "alice@example.com")
 
 ## Advanced Features
 
-### Read-Only Mode
-Prevent accidental modifications:
+### Branch Filtering
+Only expose specific branches:
 ```typescript
-const afsJson = new AFSJSON({
-  jsonPath: './config.json',
-  accessMode: 'readonly'  // No write/delete operations allowed
+const afsGit = new AFSGit({
+  repoPath: './repo',
+  branches: ['main', 'develop']  // Only these branches visible
 });
 ```
 
-### Auto-Save on Write
-Changes are automatically saved to the JSON file:
+### Read-Write with Manual Control
+Make modifications without auto-commit:
 ```typescript
-// When agent calls afs_write, the JSON file is updated immediately
-await afs.write('/config/theme', { content: 'dark' });
-// config.json is now updated with theme: "dark"
+const afsGit = new AFSGit({
+  repoPath: './repo',
+  accessMode: 'readwrite',
+  autoCommit: false  // Agent can write, you commit manually
+});
 ```
 
-### Array Operations
-AI can intelligently modify arrays:
+### Efficient Search
+Uses git grep for fast searching:
 ```typescript
-// Add new array element
-// Ask: "Add a new user named David with email david@example.com"
-
-// Delete array element (indices shift automatically)
-// Ask: "Remove the second user"
-
-// Update array element
-// Ask: "Update the first user's email to newemail@example.com"
+// Agent automatically uses optimized git grep
+await afsGit.search('/main/src', 'TODO');
+// Much faster than reading every file!
 ```
 
 ## Related Examples
 
 - [AFS LocalFS Example](../afs-local-fs/README.md) - Local file system access
-- [AFS Git Example](../afs-git/README.md) - Git repository access
 - [AFS Memory Example](../afs-memory/README.md) - Conversational memory with user profiles
 - [AFS MCP Server Example](../afs-mcp-server/README.md) - Integration with MCP servers
 
 ## Related Packages
 
 - [@aigne/afs](../../afs/README.md) - AFS core package
-- [@aigne/afs-json](../../afs/json/README.md) - AFSJSON module documentation
+- [@aigne/afs-git](../../afs/git/README.md) - AFSGit module documentation
 
 ## TypeScript Support
 

package/index.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env npx -y bun
 
 import { AFS, type AFSAccessMode } from "@aigne/afs";
+import { AFSGit } from "@aigne/afs-git";
 import { AFSHistory } from "@aigne/afs-history";
-import { AFSJSON } from "@aigne/afs-json";
 import { loadAIGNEWithCmdOptions, runWithAIGNE } from "@aigne/cli/utils/run-with-aigne.js";
 import { AIAgent } from "@aigne/core";
 import yargs from "yargs";
@@ -10,7 +10,7 @@ import yargs from "yargs";
 const argv = yargs()
   .option("path", {
     type: "string",
-    describe: "Path to the json/yaml file to mount",
+    describe: "Path to the git repo to mount",
     default: ".",
   })
   .option("description", {
@@ -22,7 +22,12 @@ const argv = yargs()
     type: "string",
     choices: ["readonly", "readwrite"],
     default: "readonly",
-    describe: "Access mode for the mounted file system",
+    describe: "Access mode for the mounted repo",
+  })
+  .option("auto-commit", {
+    type: "boolean",
+    default: false,
+    describe: "Automatically commit changes to the mounted repo",
   })
   .demandOption("path")
   .strict(false)
@@ -33,10 +38,11 @@ const aigne = await loadAIGNEWithCmdOptions();
 const afs = new AFS()
   .mount(new AFSHistory({ storage: { url: ":memory:" } })) // In-memory history for this example
   .mount(
-    new AFSJSON({
-      jsonPath: argv.path,
+    new AFSGit({
+      repoPath: argv.path,
       description: argv.description,
       accessMode: argv.accessMode as AFSAccessMode,
+      autoCommit: argv.autoCommit,
     }),
   );
 
@@ -50,7 +56,7 @@ You should use the provided functions to list, search, and read files as needed
 
 {{ $afs.modules | yaml.stringify }}
 </afs_modules>
-`,
+  `,
   inputKey: "message",
   afs,
 });
@@ -59,6 +65,6 @@ await runWithAIGNE(agent, {
   aigne,
   chatLoopOptions: {
     welcome:
-      "Hello! I'm a chatbot that can help you interact with a json file mounted on AFS. Ask me anything about the file!",
+      "Hello! I'm a chatbot that can help you interact with a git repo mounted on AFS. Ask me anything about the repo!",
   },
 });

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@aigne/example-afs-git",
-  "version": "0.0.0",
-  "description": "A demonstration of using AIGNE Framework with AFS json module",
+  "version": "1.0.0",
+  "description": "A demonstration of using AIGNE Framework with AFS git module",
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
-  "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/afs-json",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/afs-git",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,9 +17,9 @@
   ],
   "dependencies": {
     "yargs": "^18.0.0",
-    "@aigne/afs-history": "^1.2.0-beta.11",
     "@aigne/afs": "^1.4.0-beta.10",
-    "@aigne/afs-json": "^1.0.0",
+    "@aigne/afs-history": "^1.2.0-beta.11",
+    "@aigne/afs-git": "^1.0.0",
     "@aigne/cli": "^1.59.0-beta.30",
     "@aigne/core": "^1.72.0-beta.24"
   },