@aigne/afs-git 1.1.0-beta → 1.2.0-beta

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.2.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-git-v1.1.0...afs-git-v1.2.0-beta) (2026-01-20)
+
+
+### Features
+
+* **afs-git:** support mount remote repo to AFS ([#926](https://github.com/AIGNE-io/aigne-framework/issues/926)) ([e4c78aa](https://github.com/AIGNE-io/aigne-framework/commit/e4c78aa207d76a8f15874931375f4b30b4c9af7f))
+* **afs:** add @aigne/afs-utils package ([#927](https://github.com/AIGNE-io/aigne-framework/issues/927)) ([3922635](https://github.com/AIGNE-io/aigne-framework/commit/3922635981aab4578607c5bf1fb882c8e45725ce))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs-utils bumped to 1.0.0
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.70-beta
+
+## [1.1.0](https://github.com/AIGNE-io/aigne-framework/compare/afs-git-v1.1.0-beta...afs-git-v1.1.0) (2026-01-16)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0
+    * @aigne/core bumped to 1.72.0
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.69
+
 ## [1.1.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-git-v1.0.0...afs-git-v1.1.0-beta) (2026-01-16)
 
 

package/README.md

@@ -20,6 +20,73 @@ npm install @aigne/afs-git
 
 ## Usage
 
+### Remote Repository
+
+Mount a remote Git repository by cloning it to a temporary directory or a specified path:
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSGit } from "@aigne/afs-git";
+
+const afs = new AFS();
+
+// Clone and mount a remote repository (clones to temp directory)
+const gitRemote = new AFSGit({
+  remoteUrl: 'https://github.com/user/repo.git',
+  depth: 1,              // Shallow clone
+  branches: ['main'],    // Single branch = --single-branch optimization
+  accessMode: 'readonly'
+});
+
+afs.mount(gitRemote);
+
+// Access files from remote repository
+const content = await afs.read('/modules/git/main/README.md');
+
+// Cleanup when done (removes cloned temp directory)
+await gitRemote.cleanup();
+```
+
+#### Private Repository with Authentication
+
+```typescript
+const gitRemote = new AFSGit({
+  remoteUrl: 'https://github.com/user/private-repo.git',
+  depth: 1,
+  cloneOptions: {
+    auth: {
+      username: 'your-username',
+      password: process.env.GITHUB_TOKEN  // Use personal access token
+    }
+  }
+});
+```
+
+#### Use Existing or Custom Clone Path
+
+If you already have a local clone or want to specify where to clone:
+
+```typescript
+const gitRemote = new AFSGit({
+  remoteUrl: 'https://github.com/user/repo.git',
+  repoPath: '/path/to/clone',  // Clone to this path if doesn't exist
+  autoCleanup: false            // Don't delete on cleanup()
+});
+```
+
+#### Remote Operations
+
+```typescript
+// Fetch latest changes from remote
+await gitRemote.fetch();
+
+// Pull latest changes for current branch
+await gitRemote.pull();
+
+// Push local changes (if accessMode is 'readwrite')
+await gitRemote.push();
+```
+
 ### Basic Setup (Read-Only)
 
 ```typescript
@@ -28,11 +95,13 @@ import { AFSGit } from "@aigne/afs-git";
 
 const afs = new AFS();
 
-// Mount a git repository in read-only mode
-afs.mount(new AFSGit({
+// Mount a local git repository in read-only mode
+const git = new AFSGit({
   repoPath: '/path/to/repo',
   accessMode: 'readonly'  // default
-}));
+});
+
+afs.mount(git);
 ```
 
 ### Path Structure
@@ -112,6 +181,7 @@ await afs.rename('/modules/git/main/old.txt', '/modules/git/main/new.txt');
 ### Advanced Configuration
 
 ```typescript
+// Local repository with advanced options
 const afsGit = new AFSGit({
   repoPath: '/path/to/repo',
   name: 'my-repo',
@@ -135,6 +205,35 @@ const afsGit = new AFSGit({
 await afsGit.cleanup();
 ```
 
+```typescript
+// Remote repository with all options
+const afsGit = new AFSGit({
+  remoteUrl: 'https://github.com/user/repo.git',
+  repoPath: '/custom/clone/path',  // Optional: specify clone location
+  name: 'my-remote-repo',
+  description: 'Remote repository',
+
+  // Clone options
+  depth: 1,                         // Shallow clone
+  branches: ['main'],               // Single branch = --single-branch optimization
+                                    // Multiple: ['main', 'develop'] = clone all, filter access
+
+  // Access control
+  accessMode: 'readonly',
+
+  // Auto cleanup
+  autoCleanup: true,                // Remove clone on cleanup()
+
+  // Authentication for private repos
+  cloneOptions: {
+    auth: {
+      username: 'user',
+      password: process.env.GIT_TOKEN
+    }
+  }
+});
+```
+
 ## How It Works
 
 ### Read-Only Mode
@@ -180,6 +279,50 @@ interface AFSGitOptions {
 }
 ```
 
+### Remote Repository Options
+
+When using `remoteUrl`, additional options are available:
+
+```typescript
+interface AFSGitOptions {
+  // Either repoPath or remoteUrl is required
+  repoPath?: string;             // Local repository path
+  remoteUrl?: string;            // Remote repository URL (https or git)
+
+  // Basic options
+  name?: string;                 // Module name (default: repo basename)
+  description?: string;          // Module description
+  branches?: string[];           // Branch access control & clone optimization
+                                 // Single: ['main'] = --single-branch clone
+                                 // Multiple: ['main', 'dev'] = clone all, filter access
+  accessMode?: 'readonly' | 'readwrite';  // Default: 'readonly'
+
+  // Commit options
+  autoCommit?: boolean;          // Auto-commit changes (default: false)
+  commitAuthor?: {               // Author for commits
+    name: string;
+    email: string;
+  };
+
+  // Remote clone options (only used with remoteUrl)
+  depth?: number;                // Clone depth for shallow clone (default: 1)
+  autoCleanup?: boolean;         // Auto cleanup cloned repo (default: true)
+  cloneOptions?: {
+    auth?: {                     // Authentication for private repos
+      username?: string;
+      password?: string;         // Use personal access token
+    };
+  };
+}
+```
+
+**Note:** When `remoteUrl` is provided:
+- If `repoPath` is not specified, clones to a temporary directory
+- If `repoPath` is specified and doesn't exist, clones to that path
+- If `repoPath` exists, uses the existing clone
+- `autoCleanup` only applies when repository was auto-cloned to temp directory
+- `branches` with single element uses `--single-branch` for faster clone
+
 ## Performance
 
 - **Read operations**: Very fast, uses direct git commands
@@ -196,16 +339,19 @@ interface AFSGitOptions {
 
 ## Example: AI Agent Code Review
 
+### Review Local Repository
+
 ```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({
+const git = new AFSGit({
   repoPath: process.cwd(),
   accessMode: 'readonly'
-}));
+});
+afs.mount(git);
 
 const aigne = new AIGNE({});
 
@@ -222,6 +368,39 @@ await aigne.invoke(agent, {
 });
 ```
 
+### Review Remote Repository
+
+```typescript
+import { AIGNE } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { AFSGit } from "@aigne/afs-git";
+
+const afs = new AFS();
+
+// Clone and mount remote repository
+const git = new AFSGit({
+  remoteUrl: 'https://github.com/user/project.git',
+  depth: 1,
+  branches: ['main']
+});
+afs.mount(git);
+
+const aigne = new AIGNE({});
+
+const agent = AIAgent.from({
+  name: "CodeReviewer",
+  instructions: "Review open source code and provide feedback",
+  afs
+});
+
+await aigne.invoke(agent, {
+  message: "Analyze the security of the authentication implementation"
+});
+
+// Cleanup cloned repository
+await git.cleanup();
+```
+
 ## License
 
 This project is licensed under the [Elastic-2.0](../../LICENSE.md) License.

package/lib/cjs/index.d.ts

@@ -2,8 +2,28 @@ import type { AFSAccessMode, AFSDeleteOptions, AFSDeleteResult, AFSListOptions,
 import { z } from "zod";
 export interface AFSGitOptions {
     name?: string;
-    repoPath: string;
+    /**
+     * Local path to git repository.
+     * If remoteUrl is provided and repoPath doesn't exist, will clone to this path.
+     * If remoteUrl is provided and repoPath is not specified, clones to temp directory.
+     */
+    repoPath?: string;
+    /**
+     * Remote repository URL (https or git protocol).
+     * If provided, will clone the repository if repoPath doesn't exist.
+     * Examples:
+     * - https://github.com/user/repo.git
+     * - git@github.com:user/repo.git
+     */
+    remoteUrl?: string;
     description?: string;
+    /**
+     * List of branches to expose/access.
+     * Also used for clone optimization when cloning from remoteUrl:
+     * - Single branch (e.g., ['main']): Uses --single-branch for faster clone
+     * - Multiple branches: Clones all branches, filters access to specified ones
+     * - Not specified: All branches are accessible
+     */
     branches?: string[];
     /**
      * Access mode for this module.
@@ -24,14 +44,38 @@ export interface AFSGitOptions {
         name: string;
         email: string;
     };
+    /**
+     * Clone depth for shallow clone (only used when cloning from remoteUrl)
+     * @default 1
+     */
+    depth?: number;
+    /**
+     * Automatically clean up cloned repository on cleanup()
+     * Only applies when repository was auto-cloned to temp directory
+     * @default true
+     */
+    autoCleanup?: boolean;
+    /**
+     * Git clone options (only used when cloning from remoteUrl)
+     */
+    cloneOptions?: {
+        /**
+         * Authentication credentials for private repositories
+         */
+        auth?: {
+            username?: string;
+            password?: string;
+        };
+    };
 }
 export declare class AFSGit implements AFSModule {
     options: AFSGitOptions & {
         cwd?: string;
     };
-    static schema(): z.ZodObject<{
+    static schema(): z.ZodEffects<z.ZodEffects<z.ZodObject<{
         name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-        repoPath: z.ZodString;
+        repoPath: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        remoteUrl: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
         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>;
@@ -43,9 +87,23 @@ export declare class AFSGit implements AFSModule {
             name: string;
             email: string;
         } | undefined>;
+        depth: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        autoCleanup: z.ZodType<boolean | undefined, z.ZodTypeDef, boolean | undefined>;
+        cloneOptions: z.ZodType<{
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined, z.ZodTypeDef, {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined>;
     }, "strip", z.ZodTypeAny, {
-        repoPath: string;
         name?: string | undefined;
+        repoPath?: string | undefined;
+        remoteUrl?: string | undefined;
         description?: string | undefined;
         branches?: string[] | undefined;
         accessMode?: "readonly" | "readwrite" | undefined;
@@ -54,9 +112,18 @@ export declare class AFSGit implements AFSModule {
             name: string;
             email: string;
         } | undefined;
+        depth?: number | undefined;
+        autoCleanup?: boolean | undefined;
+        cloneOptions?: {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined;
     }, {
-        repoPath: string;
         name?: string | undefined;
+        repoPath?: string | undefined;
+        remoteUrl?: string | undefined;
         description?: string | undefined;
         branches?: string[] | undefined;
         accessMode?: "readonly" | "readwrite" | undefined;
@@ -65,15 +132,100 @@ export declare class AFSGit implements AFSModule {
             name: string;
             email: string;
         } | undefined;
-    }>;
+        depth?: number | undefined;
+        autoCleanup?: boolean | undefined;
+        cloneOptions?: {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined;
+    }>, {
+        name?: string | undefined;
+        repoPath?: string | undefined;
+        remoteUrl?: string | undefined;
+        description?: string | undefined;
+        branches?: string[] | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        autoCommit?: boolean | undefined;
+        commitAuthor?: {
+            name: string;
+            email: string;
+        } | undefined;
+        depth?: number | undefined;
+        autoCleanup?: boolean | undefined;
+        cloneOptions?: {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        name?: string | undefined;
+        repoPath?: string | undefined;
+        remoteUrl?: string | undefined;
+        description?: string | undefined;
+        branches?: string[] | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        autoCommit?: boolean | undefined;
+        commitAuthor?: {
+            name: string;
+            email: string;
+        } | undefined;
+        depth?: number | undefined;
+        autoCleanup?: boolean | undefined;
+        cloneOptions?: {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined;
+    }>, {
+        name?: string | undefined;
+        repoPath?: string | undefined;
+        remoteUrl?: string | undefined;
+        description?: string | undefined;
+        branches?: string[] | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        autoCommit?: boolean | undefined;
+        commitAuthor?: {
+            name: string;
+            email: string;
+        } | undefined;
+        depth?: number | undefined;
+        autoCleanup?: boolean | undefined;
+        cloneOptions?: {
+            auth?: {
+                username?: string | undefined;
+                password?: string | undefined;
+            } | undefined;
+        } | undefined;
+    }, any>;
     static load({ filepath, parsed }: AFSModuleLoadParams): Promise<AFSGit>;
+    private initPromise;
     private git;
     private tempBase;
     private worktrees;
     private repoHash;
+    private isAutoCloned;
+    private clonedPath?;
+    private repoPath;
     constructor(options: AFSGitOptions & {
         cwd?: string;
     });
+    /**
+     * Wait for async initialization to complete
+     */
+    ready(): Promise<void>;
+    /**
+     * Async initialization logic (runs in constructor)
+     * Handles cloning remote repositories if needed
+     */
+    private initialize;
+    /**
+     * Clone a remote repository to local path
+     */
+    private static cloneRepository;
     name: string;
     description?: string;
     accessMode: AFSAccessMode;
@@ -122,6 +274,18 @@ export declare class AFSGit implements AFSModule {
         message?: string;
     }>;
     search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    /**
+     * Fetch latest changes from remote
+     */
+    fetch(): Promise<void>;
+    /**
+     * Pull latest changes from remote for current branch
+     */
+    pull(): Promise<void>;
+    /**
+     * Push local changes to remote
+     */
+    push(branch?: string): Promise<void>;
     /**
      * Cleanup all worktrees (useful when unmounting)
      */