@aigne/afs-git 1.11.0-beta.6 → 1.11.0-beta.7

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
 import { AFSNotFoundError } from "@aigne/afs";
-import { AFSBaseProvider, Delete, List, Meta, Read, Rename, Search, Stat, Write } from "@aigne/afs/provider";
+import { AFSBaseProvider, Actions, Delete, Explain, List, Meta, Read, Rename, Search, Stat, Write } from "@aigne/afs/provider";
 import { camelize, optionalize, zodParse } from "@aigne/afs/utils/zod";
 import { simpleGit } from "simple-git";
 import { z } from "zod";
@@ -37,10 +37,10 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	static schema() {
 		return afsGitOptionsSchema;
 	}
-	static async load({ filepath, parsed }) {
+	static async load({ basePath, config } = {}) {
 		const instance = new AFSGit({
-			...await AFSGit.schema().parseAsync(parsed),
-			cwd: dirname(filepath)
+			...await AFSGit.schema().parseAsync(config),
+			cwd: basePath
 		});
 		await instance.ready();
 		return instance;
@@ -145,21 +145,24 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	}
 	/**
 	* List root (branches)
+	* Note: list() returns only children (branches), never the path itself (per new semantics)
 	*/
 	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();
-		if (maxDepth === 0) return { data: [this.buildEntry("/", { metadata: { childrenCount: branches.length } })] };
 		const entries = [];
-		entries.push(this.buildEntry("/", { metadata: { childrenCount: branches.length } }));
 		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, { metadata: { childrenCount: branchChildrenCount } }));
+			entries.push(this.buildEntry(encodedPath, { meta: {
+				kind: "git:branch",
+				childrenCount: branchChildrenCount
+			} }));
 			if (maxDepth > 1) {
 				const branchResult = await this.listWithGitLsTree(name, "", {
 					maxDepth: maxDepth - 1,
@@ -195,7 +198,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	async readRootMetaHandler(_ctx) {
 		await this.ready();
 		const branches = await this.getBranches();
-		return this.buildEntry("/.meta", { metadata: {
+		return this.buildEntry("/.meta", { meta: {
 			childrenCount: branches.length,
 			type: "root"
 		} });
@@ -209,9 +212,11 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		await this.ensureBranchExists(branch);
 		const childrenCount = await this.getChildrenCount(branch, "");
 		const metaPath = `${`/${this.encodeBranchName(branch)}`}/.meta`;
-		return this.buildEntry(metaPath, { metadata: {
+		const lastCommit = await this.getLastCommit(branch);
+		return this.buildEntry(metaPath, { meta: {
 			childrenCount,
-			type: "branch"
+			type: "branch",
+			lastCommit
 		} });
 	}
 	/**
@@ -232,7 +237,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		const metaPath = `/${this.encodeBranchName(branch)}/${filePath}/.meta`;
 		let childrenCount;
 		if (isDir) childrenCount = await this.getChildrenCount(branch, filePath);
-		return this.buildEntry(metaPath, { metadata: {
+		return this.buildEntry(metaPath, { meta: {
 			childrenCount,
 			type: isDir ? "directory" : "file",
 			gitObjectType: objectType
@@ -244,7 +249,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	async readRootHandler(_ctx) {
 		await this.ready();
 		const branches = await this.getBranches();
-		return this.buildEntry("/", { metadata: { childrenCount: branches.length } });
+		return this.buildEntry("/", { meta: { childrenCount: branches.length } });
 	}
 	/**
 	* Read branch root
@@ -255,7 +260,11 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		await this.ensureBranchExists(branch);
 		const branchPath = this.buildBranchPath(branch);
 		const childrenCount = await this.getChildrenCount(branch, "");
-		return this.buildEntry(branchPath, { metadata: { childrenCount } });
+		const lastCommit = await this.getLastCommit(branch);
+		return this.buildEntry(branchPath, { meta: {
+			childrenCount,
+			lastCommit
+		} });
 	}
 	/**
 	* Read file or directory in branch
@@ -272,23 +281,23 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 			if (stats.isDirectory()) {
 				const files = await readdir(fullPath);
 				const afsPath$2 = this.buildBranchPath(branch, filePath);
-				return this.buildEntry(afsPath$2, { metadata: { childrenCount: files.length } });
+				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 metadata$1 = {
+			const meta$1 = {
 				size: stats.size,
 				mimeType: mimeType$1
 			};
 			if (isBinary$1) {
 				content$1 = (await readFile(fullPath)).toString("base64");
-				metadata$1.contentType = "base64";
+				meta$1.contentType = "base64";
 			} else content$1 = await readFile(fullPath, "utf8");
 			const afsPath$1 = this.buildBranchPath(branch, filePath);
 			return this.buildEntry(afsPath$1, {
 				content: content$1,
-				metadata: metadata$1,
+				meta: meta$1,
 				createdAt: stats.birthtime,
 				updatedAt: stats.mtime
 			});
@@ -302,7 +311,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		if (objectType === "tree") {
 			const afsPath$1 = this.buildBranchPath(branch, filePath);
 			const childrenCount = await this.getChildrenCount(branch, filePath);
-			return this.buildEntry(afsPath$1, { metadata: { childrenCount } });
+			return this.buildEntry(afsPath$1, { meta: { childrenCount } });
 		}
 		const size = await this.git.raw([
 			"cat-file",
@@ -312,7 +321,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		const mimeType = this.getMimeType(filePath);
 		const isBinary = this.isBinaryFile(filePath);
 		let content;
-		const metadata = {
+		const meta = {
 			size,
 			mimeType
 		};
@@ -327,12 +336,12 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 				maxBuffer: 10 * 1024 * 1024
 			});
 			content = stdout.toString("base64");
-			metadata.contentType = "base64";
+			meta.contentType = "base64";
 		} else content = await this.git.show([`${branch}:${filePath}`]);
 		const afsPath = this.buildBranchPath(branch, filePath);
 		return this.buildEntry(afsPath, {
 			content,
-			metadata
+			meta
 		});
 	}
 	/**
@@ -385,8 +394,8 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 			summary: payload.summary,
 			createdAt: stats.birthtime,
 			updatedAt: stats.mtime,
-			metadata: {
-				...payload.metadata,
+			meta: {
+				...payload.meta,
 				size: stats.size
 			},
 			userId: payload.userId,
@@ -553,30 +562,611 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	*/
 	async statRootHandler(_ctx) {
 		const entry = await this.readRootHandler(_ctx);
-		return { data: {
-			path: entry?.path ?? "/",
-			childrenCount: entry?.metadata?.childrenCount
-		} };
+		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);
-		return { data: {
-			path: entry?.path ?? `/${ctx.params.branch}`,
-			childrenCount: entry?.metadata?.childrenCount
-		} };
+		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);
-		return { data: {
-			path: entry?.path ?? `/${ctx.params.branch}/${ctx.params.path}`,
-			childrenCount: entry?.metadata?.childrenCount
-		} };
+		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 {
+			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 AFSNotFoundError(this.buildBranchPath(branch, filePath));
+		const isDir = objectType === "tree";
+		const lines = [];
+		lines.push(`# ${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 = 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 = 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 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 AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${ctx.params.index}`);
+		const commits = await this.getCommitList(branch, 1, index);
+		if (commits.length === 0) throw new 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 AFSNotFoundError(`/${this.encodeBranchName(branch)}/.log/${ctx.params.index}/.meta`);
+		const commits = await this.getCommitList(branch, 1, index);
+		if (commits.length === 0) throw new 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 /)
@@ -640,6 +1230,65 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 		}
 	}
 	/**
+	* 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) {
@@ -663,6 +1312,7 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 	}
 	/**
 	* 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;
@@ -677,25 +1327,8 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 				treeish
 			]).then((t) => t.trim()).catch(() => null);
 			if (pathType === null) throw new AFSNotFoundError(this.buildBranchPath(branch, path));
-			if (pathType === "blob") {
-				const size = await this.git.raw([
-					"cat-file",
-					"-s",
-					treeish
-				]).then((s) => Number.parseInt(s.trim(), 10));
-				const afsPath$1 = this.buildBranchPath(branch, path);
-				entries.push(this.buildEntry(afsPath$1, { metadata: { size } }));
-				return { data: entries };
-			}
-			if (maxDepth === 0) {
-				const afsPath$1 = this.buildBranchPath(branch, path);
-				const childrenCount$1 = await this.getChildrenCount(branch, path);
-				entries.push(this.buildEntry(afsPath$1, { metadata: { childrenCount: childrenCount$1 } }));
-				return { data: entries };
-			}
-			const afsPath = this.buildBranchPath(branch, path);
-			const childrenCount = await this.getChildrenCount(branch, path);
-			entries.push(this.buildEntry(afsPath, { metadata: { childrenCount } }));
+			if (pathType === "blob") return { data: [] };
+			if (maxDepth === 0) return { data: [] };
 			const queue = [{
 				path: targetPath,
 				depth: 0
@@ -717,11 +1350,12 @@ var AFSGit = class AFSGit extends AFSBaseProvider {
 					const isDirectory = type === "tree";
 					const size = sizeStr === "-" ? void 0 : Number.parseInt(sizeStr, 10);
 					const fullPath = itemPath ? `${itemPath}/${name}` : name;
-					const afsPath$1 = this.buildBranchPath(branch, fullPath);
-					const childrenCount$1 = isDirectory ? await this.getChildrenCount(branch, fullPath) : void 0;
-					entries.push(this.buildEntry(afsPath$1, { metadata: {
+					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: childrenCount$1
+						childrenCount
 					} }));
 					if (isDirectory && depth + 1 < maxDepth) queue.push({
 						path: fullPath,
@@ -856,7 +1490,20 @@ __decorate([Search("/:branch/:path+")], AFSGit.prototype, "searchHandler", null)
 __decorate([Stat("/")], AFSGit.prototype, "statRootHandler", null);
 __decorate([Stat("/:branch")], AFSGit.prototype, "statBranchRootHandler", null);
 __decorate([Stat("/:branch/:path+")], AFSGit.prototype, "statHandler", null);
+__decorate([Explain("/")], AFSGit.prototype, "explainRootHandler", null);
+__decorate([Explain("/:branch")], AFSGit.prototype, "explainBranchHandler", null);
+__decorate([Explain("/:branch/:path+")], AFSGit.prototype, "explainPathHandler", null);
+__decorate([Read("/.meta/.capabilities")], AFSGit.prototype, "readCapabilitiesHandler", null);
+__decorate([Actions("/:branch")], AFSGit.prototype, "listBranchActions", null);
+__decorate([Actions.Exec("/:branch", "diff")], AFSGit.prototype, "diffAction", null);
+__decorate([Actions.Exec("/:branch", "create-branch")], AFSGit.prototype, "createBranchAction", null);
+__decorate([Actions.Exec("/:branch", "commit")], AFSGit.prototype, "commitAction", null);
+__decorate([Actions.Exec("/:branch", "merge")], AFSGit.prototype, "mergeAction", null);
+__decorate([List("/:branch/.log")], AFSGit.prototype, "listLogHandler", null);
+__decorate([Read("/:branch/.log/:index")], AFSGit.prototype, "readLogEntryHandler", null);
+__decorate([Read("/:branch/.log/:index/.meta")], AFSGit.prototype, "readLogEntryMetaHandler", null);
+var src_default = AFSGit;
 
 //#endregion
-export { AFSGit };
+export { AFSGit, src_default as default };
 //# sourceMappingURL=index.mjs.map