@aigne/afs-git 1.11.0-beta → 1.11.0-beta.10

package/dist/index.cjs

@@ -1,19 +1,24 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+const require_decorate = require('./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.cjs');
 let node_child_process = require("node:child_process");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_os = require("node:os");
 let node_path = require("node:path");
 let node_util = require("node:util");
+let _aigne_afs = require("@aigne/afs");
+let _aigne_afs_provider = require("@aigne/afs/provider");
 let _aigne_afs_utils_zod = require("@aigne/afs/utils/zod");
 let simple_git = require("simple-git");
 let zod = require("zod");
 
 //#region src/index.ts
-const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
 const LIST_MAX_LIMIT = 1e3;
+const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
 const afsGitOptionsSchema = (0, _aigne_afs_utils_zod.camelize)(zod.z.object({
 	name: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string()),
-	repoPath: zod.z.string().describe("The path to the git repository"),
+	repoPath: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string().describe("The path to the git repository")),
+	remoteUrl: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string().describe("Remote repository URL (https or git protocol)")),
 	description: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string().describe("A description of the repository")),
 	branches: (0, _aigne_afs_utils_zod.optionalize)(zod.z.array(zod.z.string()).describe("List of branches to expose")),
 	accessMode: (0, _aigne_afs_utils_zod.optionalize)(zod.z.enum(["readonly", "readwrite"]).describe("Access mode for this module")),
@@ -21,317 +26,377 @@ const afsGitOptionsSchema = (0, _aigne_afs_utils_zod.camelize)(zod.z.object({
 	commitAuthor: (0, _aigne_afs_utils_zod.optionalize)(zod.z.object({
 		name: zod.z.string(),
 		email: zod.z.string()
-	}))
-}));
-var AFSGit = class AFSGit {
+	})),
+	depth: (0, _aigne_afs_utils_zod.optionalize)(zod.z.number().describe("Clone depth for shallow clone")),
+	autoCleanup: (0, _aigne_afs_utils_zod.optionalize)(zod.z.boolean().describe("Automatically clean up cloned repository on cleanup()")),
+	cloneOptions: (0, _aigne_afs_utils_zod.optionalize)(zod.z.object({ auth: (0, _aigne_afs_utils_zod.optionalize)(zod.z.object({
+		username: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string()),
+		password: (0, _aigne_afs_utils_zod.optionalize)(zod.z.string())
+	})) }))
+}).refine((data) => data.repoPath || data.remoteUrl, { message: "Either repoPath or remoteUrl must be provided" }));
+var AFSGit = class AFSGit extends _aigne_afs_provider.AFSBaseProvider {
 	static schema() {
 		return afsGitOptionsSchema;
 	}
-	static async load({ filepath, parsed }) {
-		return new AFSGit({
-			...await AFSGit.schema().parseAsync(parsed),
-			cwd: (0, node_path.dirname)(filepath)
+	static manifest() {
+		return {
+			name: "git",
+			description: "Git repository browser with branch-based access.\n- Browse branches, read files at any ref, search across repository\n- Exec actions (readwrite): `diff`, `create-branch`, `commit`, `merge`\n- Virtual `.log/` tree exposes commit history per branch\n- Path structure: `/{branch}/{file-path}` (branch `/` encoded as `~`)",
+			uriTemplate: "git://{localPath+}",
+			category: "version-control",
+			schema: zod.z.object({
+				localPath: zod.z.string(),
+				branch: zod.z.string().optional(),
+				remoteUrl: zod.z.string().optional()
+			}),
+			tags: ["git", "version-control"]
+		};
+	}
+	static async load({ basePath, config } = {}) {
+		const instance = new AFSGit({
+			...await AFSGit.schema().parseAsync(config),
+			cwd: basePath
 		});
+		await instance.ready();
+		return instance;
 	}
+	name;
+	description;
+	accessMode;
+	initPromise;
 	git;
 	tempBase;
 	worktrees = /* @__PURE__ */ new Map();
 	repoHash;
+	isAutoCloned = false;
+	clonedPath;
+	repoPath;
 	constructor(options) {
+		super();
 		this.options = options;
+		if (options.localPath && !options.repoPath) options.repoPath = options.localPath;
+		if (options.branch && !options.branches) options.branches = [options.branch];
 		(0, _aigne_afs_utils_zod.zodParse)(afsGitOptionsSchema, options);
 		let repoPath;
-		if ((0, node_path.isAbsolute)(options.repoPath)) repoPath = options.repoPath;
-		else repoPath = (0, node_path.join)(options.cwd || process.cwd(), options.repoPath);
-		this.options.repoPath = repoPath;
-		this.name = options.name || (0, node_path.basename)(repoPath) || "git";
+		let repoName;
+		if (options.repoPath) {
+			repoPath = (0, node_path.isAbsolute)(options.repoPath) ? options.repoPath : (0, node_path.join)(options.cwd || process.cwd(), options.repoPath);
+			repoName = (0, node_path.basename)(repoPath);
+		} else if (options.remoteUrl) {
+			const urlParts = options.remoteUrl.split("/");
+			repoName = urlParts[urlParts.length - 1]?.replace(/\.git$/, "") || "git";
+			const repoHash = (0, node_crypto.createHash)("md5").update(options.remoteUrl).digest("hex").substring(0, 8);
+			repoPath = (0, node_path.join)((0, node_os.tmpdir)(), `afs-git-remote-${repoHash}`);
+		} else throw new Error("Either repoPath or remoteUrl must be provided");
+		if (options.repoPath && !options.remoteUrl) {
+			const { existsSync, mkdirSync } = require("node:fs");
+			const { execSync } = require("node:child_process");
+			if (!existsSync(repoPath)) mkdirSync(repoPath, { recursive: true });
+			if (!existsSync((0, node_path.join)(repoPath, ".git"))) execSync("git init -b main", {
+				cwd: repoPath,
+				stdio: "ignore"
+			});
+		}
+		this.repoPath = repoPath;
+		this.name = options.name || repoName;
 		this.description = options.description;
 		this.accessMode = options.accessMode ?? "readonly";
-		this.git = (0, simple_git.simpleGit)(repoPath);
 		this.repoHash = (0, node_crypto.createHash)("md5").update(repoPath).digest("hex").substring(0, 8);
 		this.tempBase = (0, node_path.join)((0, node_os.tmpdir)(), `afs-git-${this.repoHash}`);
-	}
-	name;
-	description;
-	accessMode;
-	/**
-	* 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" }
-	*/
-	parsePath(path) {
-		const segments = (0, node_path.join)("/", path).split("/").filter(Boolean);
-		if (segments.length === 0) return {
-			branch: void 0,
-			filePath: ""
-		};
-		return {
-			branch: segments[0].replace(/~/g, "/"),
-			filePath: segments.slice(1).join("/")
-		};
-	}
-	/**
-	* Detect MIME type based on file extension
-	*/
-	getMimeType(filePath) {
-		return {
-			png: "image/png",
-			jpg: "image/jpeg",
-			jpeg: "image/jpeg",
-			gif: "image/gif",
-			bmp: "image/bmp",
-			webp: "image/webp",
-			svg: "image/svg+xml",
-			ico: "image/x-icon",
-			pdf: "application/pdf",
-			txt: "text/plain",
-			md: "text/markdown",
-			js: "text/javascript",
-			ts: "text/typescript",
-			json: "application/json",
-			html: "text/html",
-			css: "text/css",
-			xml: "text/xml"
-		}[filePath.split(".").pop()?.toLowerCase() || ""] || "application/octet-stream";
+		this.git = null;
+		this.initPromise = this.initialize();
 	}
 	/**
-	* Check if file is likely binary based on extension
+	* Wait for async initialization to complete
 	*/
-	isBinaryFile(filePath) {
-		const ext = filePath.split(".").pop()?.toLowerCase();
-		return [
-			"png",
-			"jpg",
-			"jpeg",
-			"gif",
-			"bmp",
-			"webp",
-			"ico",
-			"pdf",
-			"zip",
-			"tar",
-			"gz",
-			"exe",
-			"dll",
-			"so",
-			"dylib",
-			"wasm"
-		].includes(ext || "");
+	async ready() {
+		await this.initPromise;
 	}
 	/**
-	* Get list of available branches
+	* Async initialization logic (runs in constructor)
+	* Handles cloning remote repositories if needed
 	*/
-	async getBranches() {
-		const allBranches = (await this.git.branchLocal()).all;
-		if (this.options.branches && this.options.branches.length > 0) return allBranches.filter((branch) => this.options.branches.includes(branch));
-		return allBranches;
+	async initialize() {
+		const options = this.options;
+		if (options.remoteUrl) {
+			const targetPath = options.repoPath ? (0, node_path.isAbsolute)(options.repoPath) ? options.repoPath : (0, node_path.join)(options.cwd || process.cwd(), options.repoPath) : this.repoPath;
+			if (!options.repoPath) this.isAutoCloned = true;
+			const exists = await (0, node_fs_promises.stat)(targetPath).then(() => true).catch(() => false);
+			let needsClone = !exists;
+			if (exists) {
+				if (!await (0, simple_git.simpleGit)(targetPath).checkIsRepo().catch(() => false)) {
+					await (0, node_fs_promises.rm)(targetPath, {
+						recursive: true,
+						force: true
+					});
+					needsClone = true;
+				}
+			}
+			if (needsClone) {
+				const singleBranch = options.branches?.length === 1 ? options.branches[0] : void 0;
+				await AFSGit.cloneRepository(options.remoteUrl, targetPath, {
+					depth: options.depth ?? 1,
+					branch: singleBranch,
+					auth: options.cloneOptions?.auth
+				});
+			}
+			if (targetPath !== this.repoPath) {
+				this.repoPath = targetPath;
+				this.repoHash = (0, node_crypto.createHash)("md5").update(targetPath).digest("hex").substring(0, 8);
+				this.tempBase = (0, node_path.join)((0, node_os.tmpdir)(), `afs-git-${this.repoHash}`);
+			}
+			this.clonedPath = this.isAutoCloned ? targetPath : void 0;
+		}
+		this.git = (0, simple_git.simpleGit)(this.repoPath);
+		if (!await this.git.checkIsRepo()) throw new Error(`Not a git repository: ${this.repoPath}`);
 	}
 	/**
-	* Ensure worktree exists for a branch (lazy creation)
+	* Clone a remote repository to local path
 	*/
-	async ensureWorktree(branch) {
-		if (this.worktrees.has(branch)) return this.worktrees.get(branch);
-		if ((await this.git.revparse(["--abbrev-ref", "HEAD"])).trim() === branch) {
-			this.worktrees.set(branch, this.options.repoPath);
-			return this.options.repoPath;
-		}
-		const worktreePath = (0, node_path.join)(this.tempBase, branch);
-		if (!await (0, node_fs_promises.stat)(worktreePath).then(() => true).catch(() => false)) {
-			await (0, node_fs_promises.mkdir)(this.tempBase, { recursive: true });
-			await this.git.raw([
-				"worktree",
-				"add",
-				worktreePath,
-				branch
-			]);
+	static async cloneRepository(remoteUrl, targetPath, options = {}) {
+		const git = (0, simple_git.simpleGit)();
+		const cloneArgs = [];
+		if (options.depth) cloneArgs.push("--depth", options.depth.toString());
+		if (options.branch) cloneArgs.push("--branch", options.branch, "--single-branch");
+		let cloneUrl = remoteUrl;
+		if (options.auth?.username && options.auth?.password) {
+			if (remoteUrl.startsWith("https://")) {
+				const url = new URL(remoteUrl);
+				url.username = encodeURIComponent(options.auth.username);
+				url.password = encodeURIComponent(options.auth.password);
+				cloneUrl = url.toString();
+			}
 		}
-		this.worktrees.set(branch, worktreePath);
-		return worktreePath;
+		await git.clone(cloneUrl, targetPath, cloneArgs);
 	}
 	/**
-	* List files using git ls-tree (no worktree needed)
+	* List root (branches)
+	* Note: list() returns only children (branches), never the path itself (per new semantics)
 	*/
-	async listWithGitLsTree(branch, path, options) {
+	async listRootHandler(ctx) {
+		await this.ready();
+		const options = ctx.options;
 		const maxDepth = options?.maxDepth ?? 1;
 		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		if (maxDepth === 0) return { data: [] };
+		const branches = await this.getBranches();
 		const entries = [];
-		const targetPath = path || "";
-		const treeish = targetPath ? `${branch}:${targetPath}` : branch;
-		try {
-			const pathType = await this.git.raw([
-				"cat-file",
-				"-t",
-				treeish
-			]).then((t) => t.trim()).catch(() => null);
-			if (pathType === null) return { data: [] };
-			if (pathType === "blob") {
-				const size = await this.git.raw([
-					"cat-file",
-					"-s",
-					treeish
-				]).then((s) => Number.parseInt(s.trim(), 10));
-				const afsPath = this.buildPath(branch, path);
-				entries.push({
-					id: afsPath,
-					path: afsPath,
-					metadata: {
-						type: "file",
-						size
-					}
+		for (const name of branches) {
+			if (entries.length >= limit) break;
+			const encodedPath = this.buildBranchPath(name);
+			const branchChildrenCount = await this.getChildrenCount(name, "");
+			entries.push(this.buildEntry(encodedPath, { meta: {
+				kind: "git:branch",
+				childrenCount: branchChildrenCount
+			} }));
+			if (maxDepth > 1) {
+				const branchResult = await this.listWithGitLsTree(name, "", {
+					maxDepth: maxDepth - 1,
+					limit: limit - entries.length
 				});
-				return { data: entries };
-			}
-			const queue = [{
-				path: targetPath,
-				depth: 0
-			}];
-			while (queue.length > 0) {
-				const { path: itemPath, depth } = queue.shift();
-				const itemTreeish = itemPath ? `${branch}:${itemPath}` : branch;
-				const lines = (await this.git.raw([
-					"ls-tree",
-					"-l",
-					itemTreeish
-				])).split("\n").filter((line) => line.trim()).slice(0, limit - entries.length);
-				for (const line of lines) {
-					const match = line.match(/^(\d+)\s+(blob|tree)\s+(\w+)\s+(-|\d+)\s+(.+)$/);
-					if (!match) continue;
-					const type = match[2];
-					const sizeStr = match[4];
-					const name = match[5];
-					const isDirectory = type === "tree";
-					const size = sizeStr === "-" ? void 0 : Number.parseInt(sizeStr, 10);
-					const fullPath = itemPath ? `${itemPath}/${name}` : name;
-					const afsPath = this.buildPath(branch, fullPath);
-					entries.push({
-						id: afsPath,
-						path: afsPath,
-						metadata: {
-							type: isDirectory ? "directory" : "file",
-							size
-						}
-					});
-					if (isDirectory && depth + 1 < maxDepth) queue.push({
-						path: fullPath,
-						depth: depth + 1
-					});
-					if (entries.length >= limit) return { data: entries };
-				}
+				entries.push(...branchResult.data);
 			}
-			return { data: entries };
-		} catch (error) {
-			return {
-				data: [],
-				message: error.message
-			};
 		}
+		return { data: entries };
 	}
 	/**
-	* 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
+	* List branch root (matches /main, /develop, etc.)
 	*/
-	buildPath(branch, filePath) {
-		const encodedBranch = branch.replace(/\//g, "~");
-		if (!filePath) return `/${encodedBranch}`;
-		return `/${encodedBranch}/${filePath}`;
+	async listBranchRootHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		return this.listWithGitLsTree(branch, "", ctx.options);
 	}
-	async list(path, options) {
-		const { branch, filePath } = this.parsePath(path);
-		if (!branch) return { data: (await this.getBranches()).map((name) => {
-			const encodedPath = this.buildPath(name);
-			return {
-				id: encodedPath,
-				path: encodedPath,
-				metadata: { type: "directory" }
+	/**
+	* List files in branch with subpath (matches /main/src, /main/src/foo, etc.)
+	*/
+	async listBranchHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const filePath = ctx.params.path;
+		return this.listWithGitLsTree(branch, filePath, ctx.options);
+	}
+	/**
+	* Read root metadata (introspection only, read-only)
+	*/
+	async readRootMetaHandler(_ctx) {
+		await this.ready();
+		const branches = await this.getBranches();
+		return this.buildEntry("/.meta", { meta: {
+			childrenCount: branches.length,
+			type: "root"
+		} });
+	}
+	/**
+	* Read branch root metadata (introspection only, read-only)
+	*/
+	async readBranchMetaHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const childrenCount = await this.getChildrenCount(branch, "");
+		const metaPath = `${`/${this.encodeBranchName(branch)}`}/.meta`;
+		const lastCommit = await this.getLastCommit(branch);
+		return this.buildEntry(metaPath, { meta: {
+			childrenCount,
+			type: "branch",
+			lastCommit
+		} });
+	}
+	/**
+	* Read file or directory metadata in branch (introspection only, read-only)
+	*/
+	async readPathMetaHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const filePath = ctx.params.path;
+		const objectType = await this.git.raw([
+			"cat-file",
+			"-t",
+			`${branch}:${filePath}`
+		]).then((t) => t.trim()).catch(() => null);
+		if (objectType === null) throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch, filePath));
+		const isDir = objectType === "tree";
+		const metaPath = `/${this.encodeBranchName(branch)}/${filePath}/.meta`;
+		let childrenCount;
+		if (isDir) childrenCount = await this.getChildrenCount(branch, filePath);
+		return this.buildEntry(metaPath, { meta: {
+			childrenCount,
+			type: isDir ? "directory" : "file",
+			gitObjectType: objectType
+		} });
+	}
+	/**
+	* Read root
+	*/
+	async readRootHandler(_ctx) {
+		await this.ready();
+		const branches = await this.getBranches();
+		return this.buildEntry("/", { meta: { childrenCount: branches.length } });
+	}
+	/**
+	* Read branch root
+	*/
+	async readBranchRootHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const branchPath = this.buildBranchPath(branch);
+		const childrenCount = await this.getChildrenCount(branch, "");
+		const lastCommit = await this.getLastCommit(branch);
+		return this.buildEntry(branchPath, { meta: {
+			childrenCount,
+			lastCommit
+		} });
+	}
+	/**
+	* Read file or directory in branch
+	*/
+	async readBranchHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const filePath = ctx.params.path;
+		const worktreePath = this.worktrees.get(branch);
+		if (worktreePath) try {
+			const fullPath = (0, node_path.join)(worktreePath, filePath);
+			const stats = await (0, node_fs_promises.stat)(fullPath);
+			if (stats.isDirectory()) {
+				const files = await (0, node_fs_promises.readdir)(fullPath);
+				const afsPath$2 = this.buildBranchPath(branch, filePath);
+				return this.buildEntry(afsPath$2, { meta: { childrenCount: files.length } });
+			}
+			const mimeType$1 = this.getMimeType(filePath);
+			const isBinary$1 = this.isBinaryFile(filePath);
+			let content$1;
+			const meta$1 = {
+				size: stats.size,
+				mimeType: mimeType$1
 			};
-		}) };
-		return this.listWithGitLsTree(branch, filePath, options);
-	}
-	async read(path, _options) {
-		const { branch, filePath } = this.parsePath(path);
-		if (!branch) return { data: {
-			id: "/",
-			path: "/",
-			metadata: { type: "directory" }
-		} };
-		if (!filePath) {
-			const branchPath = this.buildPath(branch);
-			return { data: {
-				id: branchPath,
-				path: branchPath,
-				metadata: { type: "directory" }
-			} };
+			if (isBinary$1) {
+				content$1 = (await (0, node_fs_promises.readFile)(fullPath)).toString("base64");
+				meta$1.contentType = "base64";
+			} else content$1 = await (0, node_fs_promises.readFile)(fullPath, "utf8");
+			const afsPath$1 = this.buildBranchPath(branch, filePath);
+			return this.buildEntry(afsPath$1, {
+				content: content$1,
+				meta: meta$1,
+				createdAt: stats.birthtime,
+				updatedAt: stats.mtime
+			});
+		} catch {}
+		const objectType = await this.git.raw([
+			"cat-file",
+			"-t",
+			`${branch}:${filePath}`
+		]).then((t) => t.trim()).catch(() => null);
+		if (objectType === null) throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch, filePath));
+		if (objectType === "tree") {
+			const afsPath$1 = this.buildBranchPath(branch, filePath);
+			const childrenCount = await this.getChildrenCount(branch, filePath);
+			return this.buildEntry(afsPath$1, { meta: { childrenCount } });
 		}
-		try {
-			if (await this.git.raw([
-				"cat-file",
-				"-t",
-				`${branch}:${filePath}`
-			]).then((t) => t.trim()) === "tree") {
-				const afsPath$1 = this.buildPath(branch, filePath);
-				return { data: {
-					id: afsPath$1,
-					path: afsPath$1,
-					metadata: { type: "directory" }
-				} };
-			}
-			const size = await this.git.raw([
+		const size = await this.git.raw([
+			"cat-file",
+			"-s",
+			`${branch}:${filePath}`
+		]).then((s) => Number.parseInt(s.trim(), 10));
+		const mimeType = this.getMimeType(filePath);
+		const isBinary = this.isBinaryFile(filePath);
+		let content;
+		const meta = {
+			size,
+			mimeType
+		};
+		if (isBinary) {
+			const { stdout } = await execFileAsync("git", [
 				"cat-file",
-				"-s",
+				"-p",
 				`${branch}:${filePath}`
-			]).then((s) => Number.parseInt(s.trim(), 10));
-			const mimeType = this.getMimeType(filePath);
-			const isBinary = this.isBinaryFile(filePath);
-			let content;
-			const metadata = {
-				type: "file",
-				size,
-				mimeType
-			};
-			if (isBinary) {
-				const { stdout } = await execFileAsync("git", [
-					"cat-file",
-					"-p",
-					`${branch}:${filePath}`
-				], {
-					cwd: this.options.repoPath,
-					encoding: "buffer",
-					maxBuffer: 10 * 1024 * 1024
-				});
-				content = stdout.toString("base64");
-				metadata.contentType = "base64";
-			} else content = await this.git.show([`${branch}:${filePath}`]);
-			const afsPath = this.buildPath(branch, filePath);
-			return { data: {
-				id: afsPath,
-				path: afsPath,
-				content,
-				metadata
-			} };
-		} catch (error) {
-			return {
-				data: void 0,
-				message: error.message
-			};
-		}
+			], {
+				cwd: this.options.repoPath,
+				encoding: "buffer",
+				maxBuffer: 10 * 1024 * 1024
+			});
+			content = stdout.toString("base64");
+			meta.contentType = "base64";
+		} else content = await this.git.show([`${branch}:${filePath}`]);
+		const afsPath = this.buildBranchPath(branch, filePath);
+		return this.buildEntry(afsPath, {
+			content,
+			meta
+		});
+	}
+	/**
+	* Write to root is not allowed
+	*/
+	async writeRootHandler() {
+		throw new Error("Cannot write to root");
+	}
+	/**
+	* Write to branch root is not allowed
+	*/
+	async writeBranchRootHandler() {
+		throw new Error("Cannot write to branch root");
 	}
-	async write(path, entry, options) {
-		const { branch, filePath } = this.parsePath(path);
-		if (!branch || !filePath) throw new Error("Cannot write to root or branch root");
+	/**
+	* Write file in branch
+	*/
+	async writeHandler(ctx, payload) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		const filePath = ctx.params.path;
+		const append = ctx.options?.append ?? false;
 		const worktreePath = await this.ensureWorktree(branch);
 		const fullPath = (0, node_path.join)(worktreePath, filePath);
-		const append = options?.append ?? false;
 		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(fullPath), { recursive: true });
-		if (entry.content !== void 0) {
+		if (payload.content !== void 0) {
 			let contentToWrite;
-			if (typeof entry.content === "string") contentToWrite = entry.content;
-			else contentToWrite = JSON.stringify(entry.content, null, 2);
+			if (typeof payload.content === "string") contentToWrite = payload.content;
+			else contentToWrite = JSON.stringify(payload.content, null, 2);
 			await (0, node_fs_promises.writeFile)(fullPath, contentToWrite, {
 				encoding: "utf8",
 				flag: append ? "a" : "w"
@@ -347,31 +412,56 @@ var AFSGit = class AFSGit {
 			await gitInstance.commit(`Update ${filePath}`);
 		}
 		const stats = await (0, node_fs_promises.stat)(fullPath);
-		const afsPath = this.buildPath(branch, filePath);
+		const afsPath = this.buildBranchPath(branch, filePath);
 		return { data: {
 			id: afsPath,
 			path: afsPath,
-			content: entry.content,
-			summary: entry.summary,
+			content: payload.content,
+			summary: payload.summary,
 			createdAt: stats.birthtime,
 			updatedAt: stats.mtime,
-			metadata: {
-				...entry.metadata,
-				type: stats.isDirectory() ? "directory" : "file",
+			meta: {
+				...payload.meta,
 				size: stats.size
 			},
-			userId: entry.userId,
-			sessionId: entry.sessionId,
-			linkTo: entry.linkTo
+			userId: payload.userId,
+			sessionId: payload.sessionId,
+			linkTo: payload.linkTo
 		} };
 	}
-	async delete(path, options) {
-		const { branch, filePath } = this.parsePath(path);
-		if (!branch || !filePath) throw new Error("Cannot delete root or branch root");
+	/**
+	* Delete root is not allowed
+	*/
+	async deleteRootHandler() {
+		throw new Error("Cannot delete root");
+	}
+	/**
+	* Delete branch root is not allowed
+	*/
+	async deleteBranchRootHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		throw new Error("Cannot delete branch root");
+	}
+	/**
+	* Delete file in branch
+	*/
+	async deleteHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		const filePath = ctx.params.path;
+		const recursive = ctx.options?.recursive ?? false;
 		const worktreePath = await this.ensureWorktree(branch);
 		const fullPath = (0, node_path.join)(worktreePath, filePath);
-		const recursive = options?.recursive ?? false;
-		if ((await (0, node_fs_promises.stat)(fullPath)).isDirectory() && !recursive) throw new Error(`Cannot delete directory '${path}' without recursive option. Set recursive: true to delete directories.`);
+		let stats;
+		try {
+			stats = await (0, node_fs_promises.stat)(fullPath);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch, filePath));
+			throw error;
+		}
+		if (stats.isDirectory() && !recursive) throw new Error(`Cannot delete directory '/${ctx.params.branch}/${filePath}' without recursive option. Set recursive: true to delete directories.`);
 		await (0, node_fs_promises.rm)(fullPath, {
 			recursive,
 			force: true
@@ -385,19 +475,28 @@ var AFSGit = class AFSGit {
 			}
 			await gitInstance.commit(`Delete ${filePath}`);
 		}
-		return { message: `Successfully deleted: ${path}` };
+		return { message: `Successfully deleted: /${ctx.params.branch}/${filePath}` };
 	}
-	async rename(oldPath, newPath, options) {
-		const { branch: oldBranch, filePath: oldFilePath } = this.parsePath(oldPath);
+	/**
+	* Rename file in branch
+	*/
+	async renameHandler(ctx, newPath) {
+		await this.ready();
+		const oldBranch = this.decodeBranchName(ctx.params.branch);
+		const oldFilePath = ctx.params.path;
 		const { branch: newBranch, filePath: newFilePath } = this.parsePath(newPath);
-		if (!oldBranch || !oldFilePath) throw new Error("Cannot rename from root or branch root");
+		const overwrite = ctx.options?.overwrite ?? false;
 		if (!newBranch || !newFilePath) throw new Error("Cannot rename to root or branch root");
 		if (oldBranch !== newBranch) throw new Error("Cannot rename across branches");
 		const worktreePath = await this.ensureWorktree(oldBranch);
 		const oldFullPath = (0, node_path.join)(worktreePath, oldFilePath);
 		const newFullPath = (0, node_path.join)(worktreePath, newFilePath);
-		const overwrite = options?.overwrite ?? false;
-		await (0, node_fs_promises.stat)(oldFullPath);
+		try {
+			await (0, node_fs_promises.stat)(oldFullPath);
+		} catch (error) {
+			if (error.code === "ENOENT") throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(oldBranch, oldFilePath));
+			throw error;
+		}
 		try {
 			await (0, node_fs_promises.stat)(newFullPath);
 			if (!overwrite) throw new Error(`Destination '${newPath}' already exists. Set overwrite: true to replace it.`);
@@ -415,14 +514,26 @@ var AFSGit = class AFSGit {
 			}
 			await gitInstance.commit(`Rename ${oldFilePath} to ${newFilePath}`);
 		}
-		return { message: `Successfully renamed '${oldPath}' to '${newPath}'` };
+		return { message: `Successfully renamed '/${ctx.params.branch}/${oldFilePath}' to '${newPath}'` };
 	}
-	async search(path, query, options) {
-		const { branch, filePath } = this.parsePath(path);
-		if (!branch) return {
-			data: [],
-			message: "Search requires a branch path"
-		};
+	/**
+	* Search files in branch root
+	*/
+	async searchBranchRootHandler(ctx, query, options) {
+		return this.searchInBranch(ctx.params.branch, "", query, options);
+	}
+	/**
+	* Search files in branch path
+	*/
+	async searchHandler(ctx, query, options) {
+		return this.searchInBranch(ctx.params.branch, ctx.params.path, query, options);
+	}
+	/**
+	* Internal search implementation
+	*/
+	async searchInBranch(encodedBranch, filePath, query, options) {
+		await this.ready();
+		const branch = this.decodeBranchName(encodedBranch);
 		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
 		try {
 			const args = [
@@ -452,15 +563,12 @@ var AFSGit = class AFSGit {
 					lineNum = matchNoBranch[2];
 					content = matchNoBranch[3];
 				}
-				const afsPath = this.buildPath(branch, matchPath);
+				const afsPath = this.buildBranchPath(branch, matchPath);
 				if (processedFiles.has(afsPath)) continue;
 				processedFiles.add(afsPath);
-				entries.push({
-					id: afsPath,
-					path: afsPath,
-					summary: `Line ${lineNum}: ${content}`,
-					metadata: { type: "file" }
-				});
+				const entry = this.buildEntry(afsPath);
+				entry.summary = `Line ${lineNum}: ${content}`;
+				entries.push(entry);
 				if (entries.length >= limit) break;
 			}
 			return {
@@ -476,26 +584,952 @@ var AFSGit = class AFSGit {
 		}
 	}
 	/**
-	* Cleanup all worktrees (useful when unmounting)
+	* Stat root
 	*/
-	async cleanup() {
-		for (const [_branch, worktreePath] of this.worktrees) try {
-			await this.git.raw([
-				"worktree",
-				"remove",
-				worktreePath,
-				"--force"
-			]);
-		} catch (_error) {}
-		this.worktrees.clear();
+	async statRootHandler(_ctx) {
+		const entry = await this.readRootHandler(_ctx);
+		if (!entry) return { data: void 0 };
+		const { content: _content, ...rest } = entry;
+		return { data: rest };
+	}
+	/**
+	* Stat branch root
+	*/
+	async statBranchRootHandler(ctx) {
+		const entry = await this.readBranchRootHandler(ctx);
+		if (!entry) return { data: void 0 };
+		const { content: _content, ...rest } = entry;
+		return { data: rest };
+	}
+	/**
+	* Stat file or directory in branch
+	*/
+	async statHandler(ctx) {
+		const entry = await this.readBranchHandler(ctx);
+		if (!entry) return { data: void 0 };
+		const { content: _content, ...rest } = entry;
+		return { data: rest };
+	}
+	/**
+	* Explain root → repo info, branch list, default branch
+	*/
+	async explainRootHandler(_ctx) {
+		await this.ready();
+		const format = _ctx.options?.format || "markdown";
+		const branches = await this.getBranches();
+		const currentBranch = await this.git.revparse(["--abbrev-ref", "HEAD"]).then((b) => b.trim());
+		let remoteUrl;
 		try {
-			await (0, node_fs_promises.rm)(this.tempBase, {
+			remoteUrl = await this.git.remote(["get-url", "origin"]).then((u) => u?.trim());
+		} catch {}
+		const lines = [];
+		lines.push("# Git Repository");
+		lines.push("");
+		lines.push(`**Provider:** ${this.name}`);
+		if (this.description) lines.push(`**Description:** ${this.description}`);
+		lines.push(`**Default Branch:** ${currentBranch}`);
+		if (remoteUrl) lines.push(`**Remote:** ${remoteUrl}`);
+		lines.push(`**Branches:** ${branches.length}`);
+		lines.push("");
+		lines.push("## Branches");
+		lines.push("");
+		for (const branch of branches) lines.push(`- ${branch}`);
+		return {
+			content: lines.join("\n"),
+			format
+		};
+	}
+	/**
+	* Explain branch → branch name, HEAD commit, file count
+	*/
+	async explainBranchHandler(ctx) {
+		await this.ready();
+		const format = ctx.options?.format || "markdown";
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const lastCommit = await this.getLastCommit(branch);
+		const fileCount = await this.getTreeFileCount(branch, "");
+		const lines = [];
+		lines.push(`# Branch: ${branch}`);
+		lines.push("");
+		lines.push(`**HEAD Commit:** ${lastCommit.shortHash} - ${lastCommit.message}`);
+		lines.push(`**Author:** ${lastCommit.author}`);
+		lines.push(`**Date:** ${lastCommit.date}`);
+		lines.push(`**Files:** ${fileCount} entries in tree`);
+		return {
+			content: lines.join("\n"),
+			format
+		};
+	}
+	/**
+	* Explain file or directory → path, size, last modified commit
+	*/
+	async explainPathHandler(ctx) {
+		await this.ready();
+		const format = ctx.options?.format || "markdown";
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const filePath = ctx.params.path;
+		const objectType = await this.git.raw([
+			"cat-file",
+			"-t",
+			`${branch}:${filePath}`
+		]).then((t) => t.trim()).catch(() => null);
+		if (objectType === null) throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch, filePath));
+		const isDir = objectType === "tree";
+		const lines = [];
+		lines.push(`# ${(0, node_path.basename)(filePath)}`);
+		lines.push("");
+		lines.push(`**Path:** ${filePath}`);
+		lines.push(`**Type:** ${isDir ? "directory" : "file"}`);
+		if (!isDir) {
+			const size = await this.git.raw([
+				"cat-file",
+				"-s",
+				`${branch}:${filePath}`
+			]).then((s) => Number.parseInt(s.trim(), 10));
+			lines.push(`**Size:** ${size} bytes`);
+		}
+		try {
+			const logLines = (await this.git.raw([
+				"log",
+				"-1",
+				"--format=%H%n%h%n%an%n%aI%n%s",
+				branch,
+				"--",
+				filePath
+			])).trim().split("\n");
+			if (logLines.length >= 5) {
+				lines.push("");
+				lines.push("## Last Modified");
+				lines.push(`**Commit:** ${logLines[1]} - ${logLines[4]}`);
+				lines.push(`**Author:** ${logLines[2]}`);
+				lines.push(`**Date:** ${logLines[3]}`);
+			}
+		} catch {}
+		return {
+			content: lines.join("\n"),
+			format
+		};
+	}
+	async readCapabilitiesHandler(_ctx) {
+		const operations = [
+			"list",
+			"read",
+			"stat",
+			"explain",
+			"search"
+		];
+		if (this.accessMode === "readwrite") operations.push("write", "delete", "rename");
+		const actionCatalogs = [];
+		if (this.accessMode === "readwrite") actionCatalogs.push({
+			description: "Git workflow actions",
+			catalog: [
+				{
+					name: "diff",
+					description: "Compare two branches or refs",
+					inputSchema: {
+						type: "object",
+						properties: {
+							from: {
+								type: "string",
+								description: "Source ref"
+							},
+							to: {
+								type: "string",
+								description: "Target ref"
+							},
+							path: {
+								type: "string",
+								description: "Optional path filter"
+							}
+						},
+						required: ["from", "to"]
+					}
+				},
+				{
+					name: "create-branch",
+					description: "Create a new branch",
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "New branch name"
+							},
+							from: {
+								type: "string",
+								description: "Source ref (defaults to current HEAD)"
+							}
+						},
+						required: ["name"]
+					}
+				},
+				{
+					name: "commit",
+					description: "Commit staged changes",
+					inputSchema: {
+						type: "object",
+						properties: {
+							message: {
+								type: "string",
+								description: "Commit message"
+							},
+							author: {
+								type: "object",
+								properties: {
+									name: { type: "string" },
+									email: { type: "string" }
+								}
+							}
+						},
+						required: ["message"]
+					}
+				},
+				{
+					name: "merge",
+					description: "Merge a branch into the current branch",
+					inputSchema: {
+						type: "object",
+						properties: {
+							branch: {
+								type: "string",
+								description: "Branch to merge"
+							},
+							message: {
+								type: "string",
+								description: "Custom merge message"
+							}
+						},
+						required: ["branch"]
+					}
+				}
+			],
+			discovery: {
+				pathTemplate: "/:branch/.actions",
+				note: "Git workflow actions (readwrite mode only)"
+			}
+		});
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				description: this.description || "Git repository provider",
+				tools: [],
+				actions: actionCatalogs,
+				operations: this.getOperationsDeclaration()
+			},
+			meta: {
+				kind: "afs:capabilities",
+				operations
+			}
+		};
+	}
+	/**
+	* List available actions for a branch
+	*/
+	async listBranchActions(ctx) {
+		if (this.accessMode !== "readwrite") return { data: [] };
+		const basePath = `/${ctx.params.branch}/.actions`;
+		return { data: [
+			{
+				id: "diff",
+				path: `${basePath}/diff`,
+				summary: "Compare two branches or refs",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							from: {
+								type: "string",
+								description: "Source ref"
+							},
+							to: {
+								type: "string",
+								description: "Target ref"
+							},
+							path: {
+								type: "string",
+								description: "Optional path filter"
+							}
+						},
+						required: ["from", "to"]
+					}
+				}
+			},
+			{
+				id: "create-branch",
+				path: `${basePath}/create-branch`,
+				summary: "Create a new branch from this ref",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							name: {
+								type: "string",
+								description: "New branch name"
+							},
+							from: {
+								type: "string",
+								description: "Source ref (defaults to current HEAD)"
+							}
+						},
+						required: ["name"]
+					}
+				}
+			},
+			{
+				id: "commit",
+				path: `${basePath}/commit`,
+				summary: "Commit staged changes",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							message: {
+								type: "string",
+								description: "Commit message"
+							},
+							author: {
+								type: "object",
+								properties: {
+									name: { type: "string" },
+									email: { type: "string" }
+								}
+							}
+						},
+						required: ["message"]
+					}
+				}
+			},
+			{
+				id: "merge",
+				path: `${basePath}/merge`,
+				summary: "Merge another branch into this branch",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							branch: {
+								type: "string",
+								description: "Branch to merge"
+							},
+							message: {
+								type: "string",
+								description: "Custom merge message"
+							}
+						},
+						required: ["branch"]
+					}
+				}
+			}
+		] };
+	}
+	/**
+	* diff action — compare two branches or refs
+	*/
+	async diffAction(_ctx, args) {
+		await this.ready();
+		const from = args.from;
+		const to = args.to;
+		const pathFilter = args.path;
+		if (!from || !to) return {
+			success: false,
+			error: {
+				code: "INVALID_ARGS",
+				message: "from and to are required"
+			}
+		};
+		try {
+			const diffArgs = [
+				"diff",
+				"--stat",
+				"--name-only",
+				`${from}...${to}`
+			];
+			if (pathFilter) diffArgs.push("--", pathFilter);
+			const files = (await this.git.raw(diffArgs)).trim().split("\n").filter((l) => l.trim()).map((path) => ({ path }));
+			const patchArgs = ["diff", `${from}...${to}`];
+			if (pathFilter) patchArgs.push("--", pathFilter);
+			return {
+				success: true,
+				data: {
+					from,
+					to,
+					files,
+					patch: await this.git.raw(patchArgs),
+					filesChanged: files.length
+				}
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: {
+					code: "DIFF_FAILED",
+					message: error.message.replace(this.repoPath, "<repo>")
+				}
+			};
+		}
+	}
+	/**
+	* create-branch action — create a new branch
+	*/
+	async createBranchAction(_ctx, args) {
+		await this.ready();
+		const name = args.name;
+		const from = args.from;
+		if (!name) return {
+			success: false,
+			error: {
+				code: "INVALID_ARGS",
+				message: "name is required"
+			}
+		};
+		if (name.includes("..")) return {
+			success: false,
+			error: {
+				code: "INVALID_NAME",
+				message: "Branch name contains invalid characters"
+			}
+		};
+		try {
+			if (from) await this.git.raw([
+				"branch",
+				name,
+				from
+			]);
+			else await this.git.raw(["branch", name]);
+			return {
+				success: true,
+				data: {
+					branch: name,
+					hash: await this.git.revparse([name]).then((h) => h.trim())
+				}
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: {
+					code: "CREATE_BRANCH_FAILED",
+					message: error.message.replace(this.repoPath, "<repo>")
+				}
+			};
+		}
+	}
+	/**
+	* commit action — commit staged changes
+	*/
+	async commitAction(_ctx, args) {
+		await this.ready();
+		const message = args.message;
+		if (!message) return {
+			success: false,
+			error: {
+				code: "INVALID_ARGS",
+				message: "message is required"
+			}
+		};
+		const author = args.author;
+		try {
+			const git = (0, simple_git.simpleGit)(this.repoPath);
+			const status = await git.status();
+			if (status.staged.length === 0 && status.files.filter((f) => f.index !== " " && f.index !== "?").length === 0) return {
+				success: false,
+				error: {
+					code: "NO_CHANGES",
+					message: "No staged changes to commit"
+				}
+			};
+			if (author?.name) await git.addConfig("user.name", author.name, void 0, "local");
+			if (author?.email) await git.addConfig("user.email", author.email, void 0, "local");
+			const result = await git.commit(message);
+			return {
+				success: true,
+				data: {
+					hash: result.commit || "",
+					message,
+					filesChanged: result.summary.changes
+				}
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: {
+					code: "COMMIT_FAILED",
+					message: error.message.replace(this.repoPath, "<repo>")
+				}
+			};
+		}
+	}
+	/**
+	* merge action — merge a branch into current branch
+	*/
+	async mergeAction(_ctx, args) {
+		await this.ready();
+		const branch = args.branch;
+		if (!branch) return {
+			success: false,
+			error: {
+				code: "INVALID_ARGS",
+				message: "branch is required"
+			}
+		};
+		const customMessage = args.message;
+		try {
+			const git = (0, simple_git.simpleGit)(this.repoPath);
+			if (!(await git.branchLocal()).all.includes(branch)) return {
+				success: false,
+				error: {
+					code: "BRANCH_NOT_FOUND",
+					message: `Branch '${branch}' not found`
+				}
+			};
+			const mergeArgs = [branch];
+			if (customMessage) mergeArgs.push("-m", customMessage);
+			const result = await git.merge(mergeArgs);
+			return {
+				success: true,
+				data: {
+					hash: await git.revparse(["HEAD"]).then((h) => h.trim()),
+					merged: branch,
+					conflicts: result.conflicts || []
+				}
+			};
+		} catch (error) {
+			try {
+				await (0, simple_git.simpleGit)(this.repoPath).merge(["--abort"]);
+			} catch {}
+			return {
+				success: false,
+				error: {
+					code: "MERGE_FAILED",
+					message: error.message.replace(this.repoPath, "<repo>")
+				}
+			};
+		}
+	}
+	/**
+	* List .log/ → commit list with pagination
+	*/
+	async listLogHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const options = ctx.options;
+		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const offset = options?.offset || 0;
+		const commits = await this.getCommitList(branch, limit, offset);
+		const branchEncoded = this.encodeBranchName(branch);
+		return { data: commits.map((commit, i) => this.buildEntry(`/${branchEncoded}/.log/${offset + i}`, { meta: {
+			hash: commit.hash,
+			shortHash: commit.shortHash,
+			author: commit.author,
+			date: commit.date,
+			message: commit.message
+		} })) };
+	}
+	/**
+	* Read .log/{index} → commit diff/patch content
+	*/
+	async readLogEntryHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const index = Number.parseInt(ctx.params.index, 10);
+		if (Number.isNaN(index) || index < 0) throw new _aigne_afs.AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${ctx.params.index}`);
+		const commits = await this.getCommitList(branch, 1, index);
+		if (commits.length === 0) throw new _aigne_afs.AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${index}`);
+		const commit = commits[0];
+		let diff;
+		try {
+			diff = await this.git.raw([
+				"show",
+				"--stat",
+				"--patch",
+				commit.hash
+			]);
+		} catch {
+			diff = "";
+		}
+		const branchEncoded = this.encodeBranchName(branch);
+		return this.buildEntry(`/${branchEncoded}/.log/${index}`, {
+			content: diff,
+			meta: {
+				hash: commit.hash,
+				shortHash: commit.shortHash,
+				author: commit.author,
+				date: commit.date,
+				message: commit.message
+			}
+		});
+	}
+	/**
+	* Read .log/{index}/.meta → commit metadata only (no diff)
+	*/
+	async readLogEntryMetaHandler(ctx) {
+		await this.ready();
+		const branch = this.decodeBranchName(ctx.params.branch);
+		await this.ensureBranchExists(branch);
+		const index = Number.parseInt(ctx.params.index, 10);
+		if (Number.isNaN(index) || index < 0) throw new _aigne_afs.AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${ctx.params.index}/.meta`);
+		const commits = await this.getCommitList(branch, 1, index);
+		if (commits.length === 0) throw new _aigne_afs.AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${index}/.meta`);
+		const commit = commits[0];
+		const branchEncoded = this.encodeBranchName(branch);
+		return this.buildEntry(`/${branchEncoded}/.log/${index}/.meta`, { meta: {
+			hash: commit.hash,
+			shortHash: commit.shortHash,
+			author: commit.author,
+			date: commit.date,
+			message: commit.message
+		} });
+	}
+	/**
+	* Decode branch name (replace ~ with /)
+	*/
+	decodeBranchName(encoded) {
+		return encoded.replace(/~/g, "/");
+	}
+	/**
+	* Encode branch name (replace / with ~)
+	*/
+	encodeBranchName(branch) {
+		return branch.replace(/\//g, "~");
+	}
+	/**
+	* Parse AFS path into branch and file path
+	* Branch names may contain slashes and are encoded with ~ in paths
+	*/
+	parsePath(path) {
+		const segments = (0, node_path.join)("/", path).split("/").filter(Boolean);
+		if (segments.length === 0) return {
+			branch: void 0,
+			filePath: ""
+		};
+		return {
+			branch: segments[0].replace(/~/g, "/"),
+			filePath: segments.slice(1).join("/")
+		};
+	}
+	/**
+	* Build AFS path with encoded branch name
+	* Branch names with slashes are encoded by replacing / with ~
+	*/
+	buildBranchPath(branch, filePath) {
+		const encodedBranch = this.encodeBranchName(branch);
+		if (!filePath) return `/${encodedBranch}`;
+		return `/${encodedBranch}/${filePath}`;
+	}
+	/**
+	* Get list of available branches
+	*/
+	async getBranches() {
+		const allBranches = (await this.git.branchLocal()).all;
+		if (this.options.branches && this.options.branches.length > 0) return allBranches.filter((branch) => this.options.branches.includes(branch));
+		return allBranches;
+	}
+	/**
+	* Check if a branch exists, throw AFSNotFoundError if not
+	*/
+	async ensureBranchExists(branch) {
+		if (!(await this.getBranches()).includes(branch)) throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch));
+	}
+	/**
+	* Get the number of children for a tree (directory) in git
+	*/
+	async getChildrenCount(branch, path) {
+		try {
+			const treeish = path ? `${branch}:${path}` : branch;
+			return (await this.git.raw(["ls-tree", treeish])).split("\n").filter((line) => line.trim()).length;
+		} catch {
+			return 0;
+		}
+	}
+	/**
+	* Get the last commit on a branch
+	*/
+	async getLastCommit(branch) {
+		const lines = (await this.git.raw([
+			"log",
+			"-1",
+			"--format=%H%n%h%n%an%n%aI%n%s",
+			branch
+		])).trim().split("\n");
+		return {
+			hash: lines[0] || "",
+			shortHash: lines[1] || "",
+			author: lines[2] || "",
+			date: lines[3] || "",
+			message: lines[4] || ""
+		};
+	}
+	/**
+	* Count total files in a tree (recursively)
+	*/
+	async getTreeFileCount(branch, path) {
+		try {
+			const treeish = path ? `${branch}:${path}` : branch;
+			return (await this.git.raw([
+				"ls-tree",
+				"-r",
+				treeish
+			])).split("\n").filter((line) => line.trim()).length;
+		} catch {
+			return 0;
+		}
+	}
+	/**
+	* Get a list of commits on a branch with limit/offset
+	*/
+	async getCommitList(branch, limit, offset) {
+		try {
+			const args = [
+				"log",
+				`--skip=${offset}`,
+				`-${limit}`,
+				"--format=%H%n%h%n%an%n%aI%n%s%n---COMMIT_SEP---",
+				branch
+			];
+			return (await this.git.raw(args)).split("---COMMIT_SEP---").filter((b) => b.trim()).map((block) => {
+				const lines = block.trim().split("\n");
+				return {
+					hash: lines[0] || "",
+					shortHash: lines[1] || "",
+					author: lines[2] || "",
+					date: lines[3] || "",
+					message: lines[4] || ""
+				};
+			});
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Ensure worktree exists for a branch (lazy creation)
+	*/
+	async ensureWorktree(branch) {
+		if (this.worktrees.has(branch)) return this.worktrees.get(branch);
+		if ((await this.git.revparse(["--abbrev-ref", "HEAD"])).trim() === branch) {
+			this.worktrees.set(branch, this.repoPath);
+			return this.repoPath;
+		}
+		const worktreePath = (0, node_path.join)(this.tempBase, branch);
+		if (!await (0, node_fs_promises.stat)(worktreePath).then(() => true).catch(() => false)) {
+			await (0, node_fs_promises.mkdir)(this.tempBase, { recursive: true });
+			await this.git.raw([
+				"worktree",
+				"add",
+				worktreePath,
+				branch
+			]);
+		}
+		this.worktrees.set(branch, worktreePath);
+		return worktreePath;
+	}
+	/**
+	* List files using git ls-tree (no worktree needed)
+	* Note: list() returns only children, never the path itself (per new semantics)
+	*/
+	async listWithGitLsTree(branch, path, options) {
+		const maxDepth = options?.maxDepth ?? 1;
+		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const entries = [];
+		const targetPath = path || "";
+		const treeish = targetPath ? `${branch}:${targetPath}` : branch;
+		try {
+			const pathType = await this.git.raw([
+				"cat-file",
+				"-t",
+				treeish
+			]).then((t) => t.trim()).catch(() => null);
+			if (pathType === null) throw new _aigne_afs.AFSNotFoundError(this.buildBranchPath(branch, path));
+			if (pathType === "blob") return { data: [] };
+			if (maxDepth === 0) return { data: [] };
+			const queue = [{
+				path: targetPath,
+				depth: 0
+			}];
+			while (queue.length > 0) {
+				const { path: itemPath, depth } = queue.shift();
+				const itemTreeish = itemPath ? `${branch}:${itemPath}` : branch;
+				const lines = (await this.git.raw([
+					"ls-tree",
+					"-l",
+					itemTreeish
+				])).split("\n").filter((line) => line.trim()).slice(0, limit - entries.length);
+				for (const line of lines) {
+					const match = line.match(/^(\d+)\s+(blob|tree)\s+(\w+)\s+(-|\d+)\s+(.+)$/);
+					if (!match) continue;
+					const type = match[2];
+					const sizeStr = match[4];
+					const name = match[5];
+					const isDirectory = type === "tree";
+					const size = sizeStr === "-" ? void 0 : Number.parseInt(sizeStr, 10);
+					const fullPath = itemPath ? `${itemPath}/${name}` : name;
+					const afsPath = this.buildBranchPath(branch, fullPath);
+					const childrenCount = isDirectory ? await this.getChildrenCount(branch, fullPath) : void 0;
+					entries.push(this.buildEntry(afsPath, { meta: {
+						kind: isDirectory ? "git:directory" : "git:file",
+						size,
+						childrenCount
+					} }));
+					if (isDirectory && depth + 1 < maxDepth) queue.push({
+						path: fullPath,
+						depth: depth + 1
+					});
+					if (entries.length >= limit) return { data: entries };
+				}
+			}
+			return { data: entries };
+		} catch (error) {
+			if (error instanceof _aigne_afs.AFSNotFoundError) throw error;
+			throw new Error(`Failed to list: ${error.message}`);
+		}
+	}
+	/**
+	* Detect MIME type based on file extension
+	*/
+	getMimeType(filePath) {
+		return {
+			png: "image/png",
+			jpg: "image/jpeg",
+			jpeg: "image/jpeg",
+			gif: "image/gif",
+			bmp: "image/bmp",
+			webp: "image/webp",
+			svg: "image/svg+xml",
+			ico: "image/x-icon",
+			pdf: "application/pdf",
+			txt: "text/plain",
+			md: "text/markdown",
+			js: "text/javascript",
+			ts: "text/typescript",
+			json: "application/json",
+			html: "text/html",
+			css: "text/css",
+			xml: "text/xml"
+		}[filePath.split(".").pop()?.toLowerCase() || ""] || "application/octet-stream";
+	}
+	/**
+	* Check if file is likely binary based on extension
+	*/
+	isBinaryFile(filePath) {
+		const ext = filePath.split(".").pop()?.toLowerCase();
+		return [
+			"png",
+			"jpg",
+			"jpeg",
+			"gif",
+			"bmp",
+			"webp",
+			"ico",
+			"pdf",
+			"zip",
+			"tar",
+			"gz",
+			"exe",
+			"dll",
+			"so",
+			"dylib",
+			"wasm"
+		].includes(ext || "");
+	}
+	/**
+	* Fetch latest changes from remote
+	*/
+	async fetch() {
+		await this.ready();
+		await this.git.fetch();
+	}
+	/**
+	* Pull latest changes from remote for current branch
+	*/
+	async pull() {
+		await this.ready();
+		await this.git.pull();
+	}
+	/**
+	* Push local changes to remote
+	*/
+	async push(branch) {
+		await this.ready();
+		if (branch) await this.git.push("origin", branch);
+		else await this.git.push();
+	}
+	/**
+	* Cleanup all worktrees (useful when unmounting)
+	*/
+	async cleanup() {
+		await this.ready();
+		for (const [_branch, worktreePath] of this.worktrees) try {
+			await this.git.raw([
+				"worktree",
+				"remove",
+				worktreePath,
+				"--force"
+			]);
+		} catch (_error) {}
+		this.worktrees.clear();
+		try {
+			await (0, node_fs_promises.rm)(this.tempBase, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		const autoCleanup = this.options.autoCleanup ?? true;
+		if (this.isAutoCloned && autoCleanup && this.clonedPath) try {
+			await (0, node_fs_promises.rm)(this.clonedPath, {
 				recursive: true,
 				force: true
 			});
 		} catch {}
 	}
 };
+require_decorate.__decorate([(0, _aigne_afs_provider.List)("/", { handleDepth: true })], AFSGit.prototype, "listRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.List)("/:branch", { handleDepth: true })], AFSGit.prototype, "listBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.List)("/:branch/:path+", { handleDepth: true })], AFSGit.prototype, "listBranchHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Meta)("/")], AFSGit.prototype, "readRootMetaHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Meta)("/:branch")], AFSGit.prototype, "readBranchMetaHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Meta)("/:branch/:path+")], AFSGit.prototype, "readPathMetaHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/")], AFSGit.prototype, "readRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/:branch")], AFSGit.prototype, "readBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/:branch/:path+")], AFSGit.prototype, "readBranchHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Write)("/")], AFSGit.prototype, "writeRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Write)("/:branch")], AFSGit.prototype, "writeBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Write)("/:branch/:path+")], AFSGit.prototype, "writeHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Delete)("/")], AFSGit.prototype, "deleteRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Delete)("/:branch")], AFSGit.prototype, "deleteBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Delete)("/:branch/:path+")], AFSGit.prototype, "deleteHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Rename)("/:branch/:path+")], AFSGit.prototype, "renameHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Search)("/:branch")], AFSGit.prototype, "searchBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Search)("/:branch/:path+")], AFSGit.prototype, "searchHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Stat)("/")], AFSGit.prototype, "statRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Stat)("/:branch")], AFSGit.prototype, "statBranchRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Stat)("/:branch/:path+")], AFSGit.prototype, "statHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Explain)("/")], AFSGit.prototype, "explainRootHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Explain)("/:branch")], AFSGit.prototype, "explainBranchHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Explain)("/:branch/:path+")], AFSGit.prototype, "explainPathHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/.meta/.capabilities")], AFSGit.prototype, "readCapabilitiesHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Actions)("/:branch")], AFSGit.prototype, "listBranchActions", null);
+require_decorate.__decorate([_aigne_afs_provider.Actions.Exec("/:branch", "diff")], AFSGit.prototype, "diffAction", null);
+require_decorate.__decorate([_aigne_afs_provider.Actions.Exec("/:branch", "create-branch")], AFSGit.prototype, "createBranchAction", null);
+require_decorate.__decorate([_aigne_afs_provider.Actions.Exec("/:branch", "commit")], AFSGit.prototype, "commitAction", null);
+require_decorate.__decorate([_aigne_afs_provider.Actions.Exec("/:branch", "merge")], AFSGit.prototype, "mergeAction", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.List)("/:branch/.log")], AFSGit.prototype, "listLogHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/:branch/.log/:index")], AFSGit.prototype, "readLogEntryHandler", null);
+require_decorate.__decorate([(0, _aigne_afs_provider.Read)("/:branch/.log/:index/.meta")], AFSGit.prototype, "readLogEntryMetaHandler", null);
+var src_default = AFSGit;
 
 //#endregion
-exports.AFSGit = AFSGit;
+exports.AFSGit = AFSGit;
+exports.default = src_default;