@aigne/afs-git 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 1.0.0 (2026-01-16)
+
+
+### Features
+
+* **afs:** add AFSGit module support mount a git repo to AFS ([e1e030c](https://github.com/AIGNE-io/aigne-framework/commit/e1e030c181860d06c1c945b4acdcf67d9d708662))
+
+
+### Bug Fixes
+
+* **afs:** support read binary file as base64 string ([3480f9f](https://github.com/AIGNE-io/aigne-framework/commit/3480f9fe90647eba3bf2ff37e22c334599b72e35))
+
+
+### 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,227 @@
+# AFSGit
+
+**AFSGit** is an AFS (Agentic File System) module that provides access to Git repository contents through a virtual file system interface. It allows AI agents to navigate different branches, read files, search content, and optionally make modifications using Git worktrees.
+
+## Features
+
+- **Branch Navigation**: Access all branches as top-level directories
+- **Read Operations**: Read files using efficient git commands (no worktree needed)
+- **Directory Listing**: List files recursively with depth control
+- **Search**: Search content across branches using git grep
+- **Write Operations**: Modify files with automatic git worktree management
+- **Auto-commit**: Optional automatic commits for write operations
+- **No Workspace Pollution**: Uses git worktrees for modifications, keeping main repository clean
+
+## Installation
+
+```bash
+npm install @aigne/afs-git
+```
+
+## Usage
+
+### Basic Setup (Read-Only)
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSGit } from "@aigne/afs-git";
+
+const afs = new AFS();
+
+// Mount a git repository in read-only mode
+afs.mount(new AFSGit({
+  repoPath: '/path/to/repo',
+  accessMode: 'readonly'  // default
+}));
+```
+
+### Path Structure
+
+```
+/                              # Root - lists all branches
+├── main/                      # Branch directory
+│   ├── src/
+│   │   └── index.ts          # Files accessible at /main/src/index.ts
+│   ├── package.json
+│   └── README.md
+├── develop/                   # Another branch
+│   └── ...
+└── feature-auth/              # Feature branch
+    └── ...
+```
+
+### Read-Only Operations
+
+```typescript
+// List all branches
+const branches = await afs.list('/modules/git');
+// Returns: ['/main', '/develop', '/feature-auth']
+
+// List files in a branch
+const files = await afs.list('/modules/git/main');
+// Returns files at root of main branch
+
+// List files recursively
+const allFiles = await afs.list('/modules/git/main', { maxDepth: 10 });
+
+// Read file content
+const content = await afs.read('/modules/git/main/README.md');
+console.log(content.data?.content);
+
+// Search across branch
+const results = await afs.search('/modules/git/main', 'TODO');
+// Uses git grep for fast searching
+```
+
+### Read-Write Mode with Auto-Commit
+
+```typescript
+import { AFSGit } from "@aigne/afs-git";
+
+const afsGit = new AFSGit({
+  repoPath: '/path/to/repo',
+  accessMode: 'readwrite',
+  autoCommit: true,
+  commitAuthor: {
+    name: 'AI Agent',
+    email: 'agent@example.com'
+  }
+});
+
+afs.mount(afsGit);
+
+// Write a new file (creates worktree automatically)
+await afs.write('/modules/git/main/newfile.txt', {
+  content: 'Hello World'
+});
+// Automatically committed with message "Update newfile.txt"
+
+// Update existing file
+await afs.write('/modules/git/main/src/index.ts', {
+  content: updatedCode
+});
+
+// Delete file
+await afs.delete('/modules/git/main/oldfile.txt');
+// Automatically committed
+
+// Rename/move file
+await afs.rename('/modules/git/main/old.txt', '/modules/git/main/new.txt');
+```
+
+### Advanced Configuration
+
+```typescript
+const afsGit = new AFSGit({
+  repoPath: '/path/to/repo',
+  name: 'my-repo',
+  description: 'My project repository',
+
+  // Limit accessible branches
+  branches: ['main', 'develop'],
+
+  // Access control
+  accessMode: 'readwrite',
+
+  // Auto-commit settings
+  autoCommit: true,
+  commitAuthor: {
+    name: 'AI Agent',
+    email: 'agent@example.com'
+  }
+});
+
+// Cleanup worktrees when done
+await afsGit.cleanup();
+```
+
+## How It Works
+
+### Read-Only Mode
+
+In read-only mode, AFSGit uses direct git commands without creating worktrees:
+
+- **List operations**: Uses `git ls-tree` to list files
+- **Read operations**: Uses `git show` to read file content
+- **Search operations**: Uses `git grep` for fast content search
+
+This is extremely efficient as it doesn't require any file system operations.
+
+### Read-Write Mode
+
+When write operations are needed, AFSGit:
+
+1. **Lazy Worktree Creation**: Creates a git worktree only when first write operation occurs
+2. **Reuses Worktrees**: Subsequent operations on the same branch reuse the existing worktree
+3. **Current Branch Optimization**: Uses main repository path for the currently checked-out branch
+4. **Auto-commit**: Optionally commits each change automatically with descriptive messages
+
+Worktrees are created in temporary directories and cleaned up when the module is unmounted.
+
+## Configuration Options
+
+### AFSGitOptions
+
+```typescript
+interface AFSGitOptions {
+  // Required
+  repoPath: string;              // Path to git repository
+
+  // Optional
+  name?: string;                 // Module name (default: repo basename)
+  description?: string;          // Module description
+  branches?: string[];           // Limit accessible branches
+  accessMode?: 'readonly' | 'readwrite';  // Default: 'readonly'
+  autoCommit?: boolean;          // Auto-commit changes (default: false)
+  commitAuthor?: {               // Author for commits
+    name: string;
+    email: string;
+  };
+}
+```
+
+## Performance
+
+- **Read operations**: Very fast, uses direct git commands
+- **List operations**: Fast for shallow depths, may be slower for deep recursion
+- **Search operations**: Fast, uses optimized git grep
+- **Write operations**: First write to a branch creates worktree (slower), subsequent writes are fast
+
+## Limitations
+
+- Write operations are only supported on files, not directories
+- Cannot write to root or branch root paths
+- Cannot rename files across different branches
+- Binary files are supported for read, but may require special handling for write
+
+## Example: AI Agent Code Review
+
+```typescript
+import { AIGNE } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { AFSGit } from "@aigne/afs-git";
+
+const afs = new AFS();
+afs.mount(new AFSGit({
+  repoPath: process.cwd(),
+  accessMode: 'readonly'
+}));
+
+const aigne = new AIGNE({});
+
+// AI agent can now review code across branches
+const agent = AIAgent.from({
+  name: "CodeReviewer",
+  instructions: "Review code and suggest improvements",
+  afs
+});
+
+// Agent can list files, read code, search for patterns
+await aigne.invoke(agent, {
+  message: "Review the authentication code in src/auth/"
+});
+```
+
+## License
+
+This project is licensed under the [Elastic-2.0](../../LICENSE.md) License.

package/lib/cjs/index.d.ts

@@ -0,0 +1,129 @@
+import type { AFSAccessMode, AFSDeleteOptions, AFSDeleteResult, AFSListOptions, AFSListResult, AFSModule, AFSModuleLoadParams, AFSReadOptions, AFSReadResult, AFSRenameOptions, AFSSearchOptions, AFSSearchResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
+import { z } from "zod";
+export interface AFSGitOptions {
+    name?: string;
+    repoPath: string;
+    description?: string;
+    branches?: string[];
+    /**
+     * Access mode for this module.
+     * - "readonly": Only read operations are allowed, uses git commands (no worktree)
+     * - "readwrite": All operations are allowed, creates worktrees as needed
+     * @default "readonly"
+     */
+    accessMode?: AFSAccessMode;
+    /**
+     * Automatically commit changes after write operations
+     * @default false
+     */
+    autoCommit?: boolean;
+    /**
+     * Author information for commits when autoCommit is enabled
+     */
+    commitAuthor?: {
+        name: string;
+        email: string;
+    };
+}
+export declare class AFSGit implements AFSModule {
+    options: AFSGitOptions & {
+        cwd?: string;
+    };
+    static schema(): z.ZodObject<{
+        name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        repoPath: z.ZodString;
+        description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        branches: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+        accessMode: z.ZodType<"readonly" | "readwrite" | undefined, z.ZodTypeDef, "readonly" | "readwrite" | undefined>;
+        autoCommit: z.ZodType<boolean | undefined, z.ZodTypeDef, boolean | undefined>;
+        commitAuthor: z.ZodType<{
+            name: string;
+            email: string;
+        } | undefined, z.ZodTypeDef, {
+            name: string;
+            email: string;
+        } | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        repoPath: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        branches?: string[] | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        autoCommit?: boolean | undefined;
+        commitAuthor?: {
+            name: string;
+            email: string;
+        } | undefined;
+    }, {
+        repoPath: string;
+        name?: string | undefined;
+        description?: string | undefined;
+        branches?: string[] | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        autoCommit?: boolean | undefined;
+        commitAuthor?: {
+            name: string;
+            email: string;
+        } | undefined;
+    }>;
+    static load({ filepath, parsed }: AFSModuleLoadParams): Promise<AFSGit>;
+    private git;
+    private tempBase;
+    private worktrees;
+    private repoHash;
+    constructor(options: AFSGitOptions & {
+        cwd?: string;
+    });
+    name: string;
+    description?: string;
+    accessMode: AFSAccessMode;
+    /**
+     * Parse AFS path into branch and file path
+     * Branch names may contain slashes and are encoded with ~ in paths
+     * Examples:
+     *   "/" -> { branch: undefined, filePath: "" }
+     *   "/main" -> { branch: "main", filePath: "" }
+     *   "/feature~new-feature" -> { branch: "feature/new-feature", filePath: "" }
+     *   "/main/src/index.ts" -> { branch: "main", filePath: "src/index.ts" }
+     */
+    private parsePath;
+    /**
+     * Detect MIME type based on file extension
+     */
+    private getMimeType;
+    /**
+     * Check if file is likely binary based on extension
+     */
+    private isBinaryFile;
+    /**
+     * Get list of available branches
+     */
+    private getBranches;
+    /**
+     * Ensure worktree exists for a branch (lazy creation)
+     */
+    private ensureWorktree;
+    /**
+     * List files using git ls-tree (no worktree needed)
+     */
+    private listWithGitLsTree;
+    /**
+     * Build AFS path with encoded branch name
+     * Branch names with slashes are encoded by replacing / with ~
+     * @param branch Branch name (may contain slashes)
+     * @param filePath File path within branch
+     */
+    private buildPath;
+    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<{
+        message?: string;
+    }>;
+    search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    /**
+     * Cleanup all worktrees (useful when unmounting)
+     */
+    cleanup(): Promise<void>;
+}