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

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { throttling } from "@octokit/plugin-throttling";
 import { Octokit } from "@octokit/rest";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AFSNotFoundError, AFSReadonlyError } from "@aigne/afs";
 import { MappingCompiler } from "@aigne/afs-mapping";
 import { WorldMappingCore } from "@aigne/afs-world-mapping";
 import { z } from "zod";
@@ -380,7 +381,8 @@ var AFSGitHub = class {
 						path: "/{owner}/{repo}/issues/{$.number}",
 						summary: "$.title",
 						content: "$.body",
-						metadata: {
+						meta: {
+							kind: "github:issue",
 							type: "issue",
 							state: "$.state",
 							author: "$.user.login"
@@ -401,7 +403,7 @@ var AFSGitHub = class {
 					path: "/{owner}/{repo}/issues/{$.number}",
 					summary: "$.title",
 					content: "$.body",
-					metadata: {
+					meta: {
 						type: "issue",
 						state: "$.state",
 						author: "$.user.login"
@@ -424,7 +426,8 @@ var AFSGitHub = class {
 						path: "/{owner}/{repo}/pulls/{$.number}",
 						summary: "$.title",
 						content: "$.body",
-						metadata: {
+						meta: {
+							kind: "github:pull-request",
 							type: "pull_request",
 							state: "$.state",
 							author: "$.user.login"
@@ -445,7 +448,7 @@ var AFSGitHub = class {
 					path: "/{owner}/{repo}/pulls/{$.number}",
 					summary: "$.title",
 					content: "$.body",
-					metadata: {
+					meta: {
 						type: "pull_request",
 						state: "$.state",
 						author: "$.user.login"
@@ -567,7 +570,8 @@ var AFSGitHub = class {
 				id: "issues",
 				path: "/issues",
 				summary: "Repository Issues",
-				metadata: {
+				meta: {
+					kind: "github:directory",
 					childrenCount: -1,
 					description: "List and read repository issues"
 				}
@@ -576,7 +580,8 @@ var AFSGitHub = class {
 				id: "pulls",
 				path: "/pulls",
 				summary: "Pull Requests",
-				metadata: {
+				meta: {
+					kind: "github:directory",
 					childrenCount: -1,
 					description: "List and read pull requests"
 				}
@@ -585,7 +590,8 @@ var AFSGitHub = class {
 				id: "repo",
 				path: "/repo",
 				summary: "Repository Code",
-				metadata: {
+				meta: {
+					kind: "github:directory",
 					childrenCount: -1,
 					description: "Repository source code (via Contents API)"
 				}
@@ -593,6 +599,19 @@ var AFSGitHub = class {
 		];
 	}
 	/**
+	* Check if path points to a file (leaf node) like /issues/{n} or /pulls/{n}
+	* These are individual issues/PRs that don't have children.
+	*/
+	isFilePath(path) {
+		const segments = path.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+		if (this.options.mode === "single-repo") {
+			if (segments.length === 2 && (segments[0] === "issues" || segments[0] === "pulls")) return /^\d+$/.test(segments[1]);
+		} else if (this.options.mode === "org") {
+			if (segments.length === 3 && (segments[1] === "issues" || segments[1] === "pulls")) return /^\d+$/.test(segments[2]);
+		}
+		return false;
+	}
+	/**
 	* Check if path is root or empty
 	*/
 	isRootPath(path) {
@@ -612,13 +631,13 @@ var AFSGitHub = class {
 			childrenCount = 3;
 		} else {
 			summary = this.description ?? "GitHub";
-			childrenCount = -1;
+			childrenCount = void 0;
 		}
 		return {
 			id: this.name,
 			path: "/",
 			summary,
-			metadata: {
+			meta: {
 				childrenCount,
 				description: summary
 			}
@@ -633,7 +652,7 @@ var AFSGitHub = class {
 				id: `${repoPath}/issues`,
 				path: `${repoPath}/issues`,
 				summary: "Repository Issues",
-				metadata: {
+				meta: {
 					childrenCount: -1,
 					description: "List and read repository issues"
 				}
@@ -642,7 +661,7 @@ var AFSGitHub = class {
 				id: `${repoPath}/pulls`,
 				path: `${repoPath}/pulls`,
 				summary: "Pull Requests",
-				metadata: {
+				meta: {
 					childrenCount: -1,
 					description: "List and read pull requests"
 				}
@@ -651,7 +670,7 @@ var AFSGitHub = class {
 				id: `${repoPath}/repo`,
 				path: `${repoPath}/repo`,
 				summary: "Repository Code",
-				metadata: {
+				meta: {
 					childrenCount: -1,
 					description: "Repository source code (via Contents API)"
 				}
@@ -742,6 +761,8 @@ var AFSGitHub = class {
 	* - /repo -> list all branches
 	* - /repo/{branch} -> list branch root
 	* - /repo/{branch}/path -> list contents at path
+	*
+	* @throws AFSNotFoundError if path does not exist
 	*/
 	async listViaContentsAPI(path, _options) {
 		const { owner, repo, branch, filePath } = this.parseRepoPath(path);
@@ -753,7 +774,8 @@ var AFSGitHub = class {
 				id: `${repoPrefix}/${b.name}`,
 				path: `${repoPrefix}/${b.name}`,
 				summary: b.name + (b.name === defaultBranch ? " (default)" : ""),
-				metadata: {
+				meta: {
+					kind: "github:branch",
 					type: "branch",
 					sha: b.commit.sha,
 					protected: b.protected,
@@ -762,24 +784,23 @@ var AFSGitHub = class {
 				}
 			})) };
 		} catch (error) {
-			return {
-				data: [],
-				message: this.formatErrorMessage(error, `branches for ${owner}/${repo}`)
-			};
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
 		}
 		try {
 			const contents = await this.client.getContents(owner, repo, filePath, branch);
 			if (!Array.isArray(contents)) {
+				if (contents.type === "file") return { data: [] };
 				const entryPath = filePath ? `${repoPrefix}/${branch}/${contents.path}` : `${repoPrefix}/${branch}/${contents.name}`;
 				return { data: [{
 					id: entryPath,
 					path: entryPath,
 					summary: contents.name,
-					metadata: {
+					meta: {
+						kind: contents.type === "dir" ? "github:directory" : "github:file",
 						type: contents.type,
 						size: contents.size,
-						sha: contents.sha,
-						childrenCount: contents.type === "dir" ? -1 : void 0
+						sha: contents.sha
 					}
 				}] };
 			}
@@ -789,50 +810,94 @@ var AFSGitHub = class {
 					id: entryPath,
 					path: entryPath,
 					summary: item.name,
-					metadata: {
+					meta: {
+						kind: item.type === "dir" ? "github:directory" : "github:file",
 						type: item.type,
 						size: item.size,
-						sha: item.sha,
-						childrenCount: item.type === "dir" ? -1 : void 0
+						sha: item.sha
 					}
 				};
 			}) };
 		} catch (error) {
-			if (error?.status === 404) return {
-				data: [],
-				message: `Path not found: ${branch}/${filePath || ""}`
-			};
-			return {
-				data: [],
-				message: this.formatErrorMessage(error, `repository contents for ${owner}/${repo}`)
-			};
+			if (error?.status === 404) throw new AFSNotFoundError(path, `Path not found: ${branch}/${filePath || ""}`);
+			throw error;
 		}
 	}
 	/**
-	* Read file content via GitHub Contents API
-	* Path format: /repo/{branch}/{filePath}
+	* Read via GitHub Contents API
+	* Supports:
+	* - /repo - return repo virtual directory
+	* - /repo/{branch} - return branch directory entry
+	* - /repo/{branch}/{path} - return file/directory entry
+	*
+	* @throws AFSNotFoundError if path does not exist
 	*/
 	async readViaContentsAPI(path, _options) {
 		const { owner, repo, branch, filePath } = this.parseRepoPath(path);
 		const repoPrefix = this.getRepoPathPrefix(repo);
-		if (!branch) return {
-			data: void 0,
-			message: "Branch is required to read files"
-		};
-		if (!filePath) return {
-			data: void 0,
-			message: "Cannot read branch root as file"
-		};
+		if (!branch) return { data: {
+			id: `${repoPrefix}`,
+			path: repoPrefix,
+			summary: "Repository Code",
+			meta: { description: "Repository source code (via Contents API)" }
+		} };
+		if (!filePath) try {
+			const branches = await this.client.getBranches(owner, repo);
+			const defaultBranch = await this.client.getDefaultBranch(owner, repo);
+			const branchInfo = branches.find((b) => b.name === branch);
+			if (!branchInfo) throw new AFSNotFoundError(path, `Branch not found: ${branch}`);
+			let childrenCount;
+			try {
+				const contents = await this.client.getContents(owner, repo, "", branch);
+				if (Array.isArray(contents)) childrenCount = contents.length;
+			} catch {}
+			const entryPath = `${repoPrefix}/${branch}`;
+			return { data: {
+				id: entryPath,
+				path: entryPath,
+				summary: branch + (branch === defaultBranch ? " (default)" : ""),
+				meta: {
+					type: "branch",
+					sha: branchInfo.commit.sha,
+					protected: branchInfo.protected,
+					isDefault: branch === defaultBranch,
+					childrenCount
+				}
+			} };
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
+		}
 		try {
 			const contents = await this.client.getContents(owner, repo, filePath, branch);
-			if (Array.isArray(contents)) return {
-				data: void 0,
-				message: "Path is a directory, not a file"
-			};
-			if (contents.type !== "file") return {
-				data: void 0,
-				message: `Path is a ${contents.type}, not a file`
-			};
+			if (Array.isArray(contents)) {
+				const entryPath$1 = `${repoPrefix}/${branch}/${filePath}`;
+				return { data: {
+					id: entryPath$1,
+					path: entryPath$1,
+					summary: filePath.split("/").pop() || filePath,
+					meta: {
+						type: "dir",
+						childrenCount: contents.length,
+						branch
+					}
+				} };
+			}
+			if (contents.type === "dir") {
+				const entryPath$1 = `${repoPrefix}/${branch}/${filePath}`;
+				return { data: {
+					id: entryPath$1,
+					path: entryPath$1,
+					summary: contents.name,
+					meta: {
+						type: "dir",
+						sha: contents.sha,
+						branch
+					}
+				} };
+			}
+			if (contents.type !== "file") throw new AFSNotFoundError(path, `Unsupported type: ${contents.type}`);
 			let content;
 			if (contents.content) content = Buffer.from(contents.content, "base64").toString("utf-8");
 			else content = await this.client.getBlob(owner, repo, contents.sha);
@@ -842,7 +907,7 @@ var AFSGitHub = class {
 				path: entryPath,
 				summary: contents.name,
 				content,
-				metadata: {
+				meta: {
 					type: "file",
 					size: contents.size,
 					sha: contents.sha,
@@ -850,14 +915,9 @@ var AFSGitHub = class {
 				}
 			} };
 		} catch (error) {
-			if (error?.status === 404) return {
-				data: void 0,
-				message: `File not found: ${branch}/${filePath}`
-			};
-			return {
-				data: void 0,
-				message: this.formatErrorMessage(error, `file ${filePath} in ${owner}/${repo}@${branch}`)
-			};
+			if (error instanceof AFSNotFoundError) throw error;
+			if (error?.status === 404) throw new AFSNotFoundError(path, `Path not found: ${branch}/${filePath}`);
+			throw error;
 		}
 	}
 	/**
@@ -901,7 +961,7 @@ var AFSGitHub = class {
 			id: repo.name,
 			path: `/${repo.name}`,
 			summary: repo.description || repo.name,
-			metadata: {
+			meta: {
 				childrenCount: 3,
 				description: repo.description,
 				private: repo.private
@@ -937,41 +997,34 @@ var AFSGitHub = class {
 		return allRepos;
 	}
 	/**
-	* List entries at a path
+	* Apply limit to entries array
 	*/
-	async list(path, options) {
-		const maxDepth = options?.maxDepth ?? 1;
+	applyLimit(entries, limit) {
+		if (limit !== void 0 && limit > 0 && entries.length > limit) return entries.slice(0, limit);
+		return entries;
+	}
+	/**
+	* List immediate children at a path (maxDepth=1 only)
+	*/
+	async listImmediate(path, options) {
+		const actionsResult = this.listActions(path);
+		if (actionsResult) return actionsResult;
+		if (this.isFilePath(path)) return { data: [] };
 		if (this.isRepoPath(path)) return this.listViaContentsAPI(path, options);
 		if (this.isRootPath(path)) {
-			if (maxDepth === 0) return { data: [this.getRootEntry()] };
 			if (this.options.mode === "org") return this.listOrgRepos(!!this.options.auth?.token);
 			return { data: this.getVirtualDirectories() };
 		}
 		if (this.options.mode === "org" && this.isRepoRootPath(path)) {
 			const repoName = path.replace(/^\/+|\/+$/g, "");
-			if (maxDepth === 0) return { data: [{
-				id: repoName,
-				path: `/${repoName}`,
-				summary: `Repository: ${this.options.owner}/${repoName}`,
-				metadata: { childrenCount: 2 }
-			}] };
 			return { data: this.getRepoVirtualDirectories(`/${repoName}`) };
 		}
 		const fullPath = this.resolvePath(path);
-		if (!this.compiled) return {
-			data: [],
-			message: "Mapping not loaded"
-		};
+		if (!this.compiled) throw new AFSNotFoundError(path, "Mapping not loaded");
 		const resolved = this.compiled.resolve(fullPath);
-		if (!resolved || !resolved.operations.list) return {
-			data: [],
-			message: `No list operation for path: ${fullPath}`
-		};
+		if (!resolved || !resolved.operations.list) throw new AFSNotFoundError(path, `No list operation for path: ${fullPath}`);
 		const request = this.compiled.buildRequest(fullPath, "list", { query: options?.filter });
-		if (!request) return {
-			data: [],
-			message: "Failed to build request"
-		};
+		if (!request) throw new AFSNotFoundError(path, "Failed to build request");
 		try {
 			let responseData = (await this.client.request(`${request.method} ${request.path}`, request.params)).data;
 			if (Array.isArray(responseData) && fullPath.endsWith("/issues")) responseData = responseData.filter((item) => !item.pull_request);
@@ -985,16 +1038,132 @@ var AFSGitHub = class {
 			}
 			return { data: entries };
 		} catch (error) {
-			return {
-				data: [],
-				message: this.formatErrorMessage(error, `path "${path}"`)
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
+		}
+	}
+	/**
+	* Check if a path represents a directory (has children)
+	*/
+	isDirectoryPath(path) {
+		if (this.isRootPath(path)) return true;
+		if (this.isFilePath(path)) return false;
+		if (this.getVirtualDirectoryEntry(path)) return true;
+		if (this.isRepoPath(path)) return true;
+		const fullPath = this.resolvePath(path);
+		if (this.compiled) {
+			if (this.compiled.resolve(fullPath)?.operations.list) return true;
+		}
+		return false;
+	}
+	/**
+	* List entries at a path
+	*
+	* Per AFS semantics:
+	* - maxDepth=0: return empty array (no children)
+	* - maxDepth=1: return immediate children
+	* - maxDepth>1: recursively include deeper levels
+	* - limit: maximum number of entries to return
+	*
+	* @throws AFSNotFoundError if path does not exist
+	*/
+	async list(path, options) {
+		const maxDepth = options?.maxDepth ?? 1;
+		const limit = options?.limit;
+		if (maxDepth === 0) return { data: [] };
+		const result = await this.listImmediate(path, options);
+		let entries = result.data;
+		if (maxDepth > 1) {
+			const childEntries = [];
+			for (const entry of entries) if (this.isDirectoryPath(entry.path)) try {
+				const childResult = await this.listImmediate(entry.path, options);
+				childEntries.push(...childResult.data);
+			} catch {}
+			entries = [...entries, ...childEntries];
+		}
+		return {
+			data: this.applyLimit(entries, limit),
+			message: result.message
+		};
+	}
+	/**
+	* Check if path is a .meta path and extract the target path
+	*/
+	isMetaPath(path) {
+		const normalized = path.replace(/\/+$/, "");
+		if (normalized.endsWith("/.meta")) return {
+			isMeta: true,
+			targetPath: normalized.slice(0, -6) || "/"
+		};
+		return {
+			isMeta: false,
+			targetPath: path
+		};
+	}
+	/**
+	* Get entry info for a virtual directory path
+	*/
+	getVirtualDirectoryEntry(path) {
+		const segments = path.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+		if (segments.length === 0) return this.getRootEntry();
+		if (this.options.mode === "single-repo") {
+			if (segments.length === 1) {
+				const dir = this.getVirtualDirectories().find((d) => d.path === `/${segments[0]}`);
+				if (dir) return dir;
+			}
+		}
+		if (this.options.mode === "org") {
+			if (segments.length === 1) return {
+				id: segments[0],
+				path: `/${segments[0]}`,
+				summary: `Repository: ${this.options.owner}/${segments[0]}`,
+				meta: { childrenCount: 3 }
 			};
+			if (segments.length === 2) {
+				const repoName = segments[0];
+				const dir = this.getRepoVirtualDirectories(`/${repoName}`).find((d) => d.path === `/${repoName}/${segments[1]}`);
+				if (dir) return dir;
+			}
 		}
 	}
 	/**
 	* Read a single entry
+	*
+	* Supports:
+	* - Directory paths (returns entry info)
+	* - .meta paths (returns metadata)
+	* - Issue/PR paths (returns content via API)
+	* - Repo file paths (returns content via Contents API)
+	*
+	* @throws AFSNotFoundError if path does not exist
 	*/
 	async read(path, options) {
+		if (path === "/.meta/.capabilities") return this.readCapabilities();
+		const actionsMatch = path.match(/^(.*)\/\.actions\/([^/]+)$/);
+		if (actionsMatch) {
+			const actionsListPath = `${actionsMatch[1] || ""}/.actions`;
+			const actionName = actionsMatch[2];
+			const actionsResult = this.listActions(actionsListPath);
+			if (actionsResult) {
+				const actionEntry = actionsResult.data.find((entry) => entry.id === actionName);
+				if (actionEntry) return { data: actionEntry };
+			}
+			throw new AFSNotFoundError(path);
+		}
+		const { isMeta, targetPath } = this.isMetaPath(path);
+		if (isMeta) return this.readMeta(targetPath);
+		const virtualEntry = this.getVirtualDirectoryEntry(path);
+		if (virtualEntry) {
+			const cc = virtualEntry.meta?.childrenCount;
+			if ((cc === void 0 || cc === -1) && this.isDirectoryPath(path)) try {
+				const children = await this.listImmediate(path);
+				virtualEntry.meta = {
+					...virtualEntry.meta,
+					childrenCount: children.data.length
+				};
+			} catch {}
+			return { data: virtualEntry };
+		}
 		if (this.isRepoPath(path)) return this.readViaContentsAPI(path, options);
 		if (this.options.mode === "org" || this.options.mode === "single-repo") {
 			const segments = path.replace(/^\/+|\/+$/g, "").split("/");
@@ -1002,41 +1171,23 @@ var AFSGitHub = class {
 			const pullsIdx = segments.indexOf("pulls");
 			if (issuesIdx !== -1 && segments[issuesIdx + 1]) {
 				const issueNum = segments[issuesIdx + 1];
-				if (!/^\d+$/.test(issueNum)) return {
-					data: void 0,
-					message: "Invalid issue number"
-				};
+				if (!/^\d+$/.test(issueNum)) throw new AFSNotFoundError(path, "Invalid issue number");
 			}
 			if (pullsIdx !== -1 && segments[pullsIdx + 1]) {
 				const prNum = segments[pullsIdx + 1];
-				if (!/^\d+$/.test(prNum)) return {
-					data: void 0,
-					message: "Invalid pull request number"
-				};
+				if (!/^\d+$/.test(prNum)) throw new AFSNotFoundError(path, "Invalid pull request number");
 			}
 		}
 		const fullPath = this.resolvePath(path);
-		if (!this.compiled) return {
-			data: void 0,
-			message: "Mapping not loaded"
-		};
+		if (!this.compiled) throw new AFSNotFoundError(path, "Mapping not loaded");
 		const resolved = this.compiled.resolve(fullPath);
-		if (!resolved || !resolved.operations.read) return {
-			data: void 0,
-			message: `No read operation for path: ${fullPath}`
-		};
+		if (!resolved || !resolved.operations.read) throw new AFSNotFoundError(path, `No read operation for path: ${fullPath}`);
 		const request = this.compiled.buildRequest(fullPath, "read", {});
-		if (!request) return {
-			data: void 0,
-			message: "Failed to build request"
-		};
+		if (!request) throw new AFSNotFoundError(path, "Failed to build request");
 		try {
 			const response = await this.client.request(`${request.method} ${request.path}`, request.params);
 			const entries = this.compiled.projectResponse(fullPath, "read", response.data);
-			if (entries.length === 0) return {
-				data: void 0,
-				message: "No data returned"
-			};
+			if (entries.length === 0) throw new AFSNotFoundError(path, "No data returned");
 			const entry = entries[0];
 			if (this.options.mode === "single-repo") {
 				const prefix = `/${this.options.owner}/${this.options.repo}`;
@@ -1047,12 +1198,41 @@ var AFSGitHub = class {
 			}
 			return { data: entry };
 		} catch (error) {
-			return {
-				data: void 0,
-				message: this.formatErrorMessage(error, `path "${path}"`)
-			};
+			if (error instanceof AFSNotFoundError) throw error;
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
 		}
 	}
+	/**
+	* Read metadata for a path
+	* Returns an entry with meta field containing the metadata
+	*
+	* @throws AFSNotFoundError if path does not exist
+	*/
+	async readMeta(targetPath) {
+		const metaPath = targetPath === "/" ? "/.meta" : `${targetPath}/.meta`;
+		const virtualEntry = this.getVirtualDirectoryEntry(targetPath);
+		if (virtualEntry) return { data: {
+			id: `${virtualEntry.id}/.meta`,
+			path: metaPath,
+			summary: `Metadata for ${targetPath}`,
+			meta: virtualEntry.meta ?? {}
+		} };
+		const enrichedMeta = await this.getEnrichedMeta(targetPath);
+		if (enrichedMeta) return { data: {
+			id: `${targetPath}/.meta`,
+			path: metaPath,
+			summary: `Metadata for ${targetPath}`,
+			meta: enrichedMeta
+		} };
+		const readResult = await this.read(targetPath);
+		return { data: {
+			id: `${readResult.data.id}/.meta`,
+			path: metaPath,
+			summary: `Metadata for ${targetPath}`,
+			meta: readResult.data.meta ?? {}
+		} };
+	}
 	async loadMapping(mappingPath) {
 		const compiler = new MappingCompiler();
 		try {
@@ -1118,6 +1298,1044 @@ var AFSGitHub = class {
 			error: "Write operations not yet implemented"
 		};
 	}
+	/**
+	* Get metadata for a path without content.
+	* Supports issues, PRs, and virtual directories.
+	*/
+	async stat(path, _options) {
+		const parsed = this.parseIssuePRPath(path);
+		if (parsed?.type === "issue") return this.statIssue(parsed.number);
+		if (parsed?.type === "pull") return this.statPR(parsed.number);
+		const virtualEntry = this.getVirtualDirectoryEntry(path);
+		if (virtualEntry) return { data: virtualEntry };
+		throw new AFSNotFoundError(path);
+	}
+	async statIssue(issueNumber) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		try {
+			const issue = (await this.client.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
+				owner,
+				repo,
+				issue_number: issueNumber
+			})).data;
+			return { data: {
+				id: String(issue.number),
+				path: `/issues/${issue.number}`,
+				summary: issue.title,
+				meta: {
+					type: "issue",
+					state: issue.state,
+					title: issue.title,
+					author: issue.user?.login,
+					commentCount: issue.comments,
+					labels: (issue.labels ?? []).map((l) => l.name),
+					created_at: issue.created_at,
+					updated_at: issue.updated_at
+				}
+			} };
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(`/issues/${issueNumber}`);
+			throw error;
+		}
+	}
+	async statPR(prNumber) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		try {
+			const pr = (await this.client.request("GET /repos/{owner}/{repo}/pulls/{pull_number}", {
+				owner,
+				repo,
+				pull_number: prNumber
+			})).data;
+			return { data: {
+				id: String(pr.number),
+				path: `/pulls/${pr.number}`,
+				summary: pr.title,
+				meta: {
+					type: "pull_request",
+					state: pr.state,
+					title: pr.title,
+					author: pr.user?.login,
+					draft: pr.draft,
+					reviewers: (pr.requested_reviewers ?? []).map((r) => r.login),
+					labels: (pr.labels ?? []).map((l) => l.name),
+					created_at: pr.created_at,
+					updated_at: pr.updated_at,
+					merged_at: pr.merged_at
+				}
+			} };
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(`/pulls/${prNumber}`);
+			throw error;
+		}
+	}
+	/**
+	* Search issues and PRs using the GitHub Search API.
+	* Path determines scope: /issues searches issues, /pulls searches PRs, / searches both.
+	*/
+	async search(path, query, options) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		const sanitizedQuery = query.replace(/[\r\n]+/g, " ").replace(/ghp_[a-zA-Z0-9]+/g, "");
+		const normalized = path.replace(/^\/+|\/+$/g, "");
+		const isPulls = normalized === "pulls" || normalized.endsWith("/pulls");
+		const isIssues = normalized === "issues" || normalized.endsWith("/issues");
+		let q = sanitizedQuery.trim();
+		q += ` repo:${owner}/${repo}`;
+		if (isPulls) q += " is:pr";
+		else if (isIssues) q += " is:issue";
+		try {
+			return { data: (await this.client.request("GET /search/issues", {
+				q: q.trim(),
+				per_page: options?.limit ?? 30
+			})).data.items.map((item) => {
+				const hasPR = "pull_request" in item;
+				const type = hasPR ? "pulls" : "issues";
+				return {
+					id: String(item.number),
+					path: `/${type}/${item.number}`,
+					summary: item.title,
+					meta: {
+						type: hasPR ? "pull_request" : "issue",
+						state: item.state,
+						author: item.user?.login
+					}
+				};
+			}) };
+		} catch (error) {
+			if (error?.status === 422) return {
+				data: [],
+				message: "Invalid search query"
+			};
+			throw error;
+		}
+	}
+	/**
+	* Provide human/LLM-readable explanation of a path.
+	*/
+	async explain(path, _options) {
+		const normalized = path.replace(/^\/+|\/+$/g, "");
+		if (normalized === "") return this.explainRoot();
+		if (normalized === "issues") return this.explainIssuesDir();
+		if (normalized === "pulls") return this.explainPullsDir();
+		const parsed = this.parseIssuePRPath(path);
+		if (parsed?.type === "issue") return this.explainIssue(parsed.number);
+		if (parsed?.type === "pull") return this.explainPR(parsed.number);
+		throw new AFSNotFoundError(path);
+	}
+	async explainRoot() {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		const data = (await this.client.request("GET /repos/{owner}/{repo}", {
+			owner,
+			repo
+		})).data;
+		const lines = [
+			`# ${data.full_name}`,
+			"",
+			data.description ? `${data.description}` : "",
+			"",
+			`- **Language**: ${data.language ?? "N/A"}`,
+			`- **Stars**: ${data.stargazers_count ?? 0} ⭐`,
+			`- **Forks**: ${data.forks_count ?? 0}`,
+			`- **Open Issues**: ${data.open_issues_count ?? 0}`,
+			`- **Default Branch**: ${data.default_branch ?? "main"}`,
+			`- **License**: ${data.license?.spdx_id ?? "N/A"}`,
+			`- **Visibility**: ${data.private ? "Private" : "Public"}`,
+			"",
+			"## Structure",
+			"",
+			"- `/issues` — Repository issues",
+			"- `/pulls` — Pull requests",
+			"- `/repo` — Repository source code"
+		];
+		const topics = data.topics;
+		if (topics && topics.length > 0) lines.push("", `**Topics**: ${topics.join(", ")}`);
+		return {
+			format: "markdown",
+			content: lines.filter((l) => l !== void 0).join("\n")
+		};
+	}
+	async explainIssuesDir() {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		const [openResult, closedResult] = await Promise.all([this.client.request("GET /search/issues", {
+			q: `repo:${owner}/${repo} is:issue is:open`,
+			per_page: 1
+		}), this.client.request("GET /search/issues", {
+			q: `repo:${owner}/${repo} is:issue is:closed`,
+			per_page: 1
+		})]);
+		const openCount = openResult.data.total_count;
+		const closedCount = closedResult.data.total_count;
+		return {
+			format: "markdown",
+			content: [
+				`# Issues — ${owner}/${repo}`,
+				"",
+				`- **Open**: ${openCount}`,
+				`- **Closed**: ${closedCount}`,
+				`- **Total**: ${openCount + closedCount}`,
+				"",
+				"Use `list /issues` to browse issues.",
+				"Use `search /issues <query>` to find specific issues."
+			].join("\n")
+		};
+	}
+	async explainPullsDir() {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		const [openResult, closedResult, mergedResult] = await Promise.all([
+			this.client.request("GET /search/issues", {
+				q: `repo:${owner}/${repo} is:pr is:open`,
+				per_page: 1
+			}),
+			this.client.request("GET /search/issues", {
+				q: `repo:${owner}/${repo} is:pr is:closed`,
+				per_page: 1
+			}),
+			this.client.request("GET /search/issues", {
+				q: `repo:${owner}/${repo} is:pr is:merged`,
+				per_page: 1
+			})
+		]);
+		const openCount = openResult.data.total_count;
+		const closedCount = closedResult.data.total_count;
+		const mergedCount = mergedResult.data.total_count;
+		return {
+			format: "markdown",
+			content: [
+				`# Pull Requests — ${owner}/${repo}`,
+				"",
+				`- **Open**: ${openCount}`,
+				`- **Closed**: ${closedCount}`,
+				`- **Merged**: ${mergedCount}`,
+				"",
+				"Use `list /pulls` to browse pull requests.",
+				"Use `search /pulls <query>` to find specific PRs."
+			].join("\n")
+		};
+	}
+	async explainIssue(issueNumber) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		try {
+			const issue = (await this.client.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
+				owner,
+				repo,
+				issue_number: issueNumber
+			})).data;
+			const labels = (issue.labels ?? []).map((l) => l.name);
+			const assignees = (issue.assignees ?? []).map((a) => a.login);
+			return {
+				format: "markdown",
+				content: [
+					`# Issue #${issue.number}: ${issue.title}`,
+					"",
+					`- **State**: ${issue.state}`,
+					`- **Author**: ${issue.user?.login}`,
+					`- **Created**: ${issue.created_at}`,
+					`- **Updated**: ${issue.updated_at}`,
+					labels.length > 0 ? `- **Labels**: ${labels.join(", ")}` : null,
+					assignees.length > 0 ? `- **Assignees**: ${assignees.join(", ")}` : null,
+					`- **Comments**: ${issue.comments}`
+				].filter((l) => l !== null).join("\n")
+			};
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(`/issues/${issueNumber}`);
+			throw error;
+		}
+	}
+	async explainPR(prNumber) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		try {
+			const pr = (await this.client.request("GET /repos/{owner}/{repo}/pulls/{pull_number}", {
+				owner,
+				repo,
+				pull_number: prNumber
+			})).data;
+			const labels = (pr.labels ?? []).map((l) => l.name);
+			const reviewers = (pr.requested_reviewers ?? []).map((r) => r.login);
+			return {
+				format: "markdown",
+				content: [
+					`# PR #${pr.number}: ${pr.title}`,
+					"",
+					`- **State**: ${pr.state}${pr.draft ? " (draft)" : ""}`,
+					`- **Author**: ${pr.user?.login}`,
+					`- **Created**: ${pr.created_at}`,
+					`- **Updated**: ${pr.updated_at}`,
+					pr.merged_at ? `- **Merged**: ${pr.merged_at}` : null,
+					labels.length > 0 ? `- **Labels**: ${labels.join(", ")}` : null,
+					reviewers.length > 0 ? `- **Reviewers**: ${reviewers.join(", ")}` : null,
+					`- **Head**: ${pr.head?.ref} → **Base**: ${pr.base?.ref}`
+				].filter((l) => l !== null).join("\n")
+			};
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(`/pulls/${prNumber}`);
+			throw error;
+		}
+	}
+	async readCapabilities() {
+		return { data: {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			summary: "Provider capabilities manifest",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				description: this.description ?? `GitHub: ${this.options.owner}/${this.options.repo}`,
+				tools: [],
+				operations: {
+					read: true,
+					list: true,
+					write: false,
+					delete: false,
+					search: true,
+					exec: true,
+					stat: true,
+					explain: true
+				},
+				actions: [
+					{
+						kind: "github:issue",
+						description: "Issue lifecycle actions",
+						catalog: [
+							{
+								name: "close-issue",
+								description: "Close an issue"
+							},
+							{
+								name: "reopen-issue",
+								description: "Reopen a closed issue"
+							},
+							{
+								name: "add-comment",
+								description: "Add a comment to an issue"
+							},
+							{
+								name: "add-label",
+								description: "Add a label to an issue"
+							},
+							{
+								name: "remove-label",
+								description: "Remove a label from an issue"
+							}
+						],
+						discovery: { pathTemplate: "/issues/:number/.actions" }
+					},
+					{
+						kind: "github:pull_request",
+						description: "Pull request lifecycle actions",
+						catalog: [
+							{
+								name: "merge-pr",
+								description: "Merge a pull request"
+							},
+							{
+								name: "approve-pr",
+								description: "Approve a pull request"
+							},
+							{
+								name: "request-changes",
+								description: "Request changes on a pull request"
+							},
+							{
+								name: "add-comment",
+								description: "Add a comment to a pull request"
+							},
+							{
+								name: "add-label",
+								description: "Add a label to a pull request"
+							},
+							{
+								name: "remove-label",
+								description: "Remove a label from a pull request"
+							}
+						],
+						discovery: { pathTemplate: "/pulls/:number/.actions" }
+					},
+					{
+						kind: "github:repo",
+						description: "Repository file operations",
+						catalog: [
+							{
+								name: "read-file",
+								description: "Read a file from the repository"
+							},
+							{
+								name: "write-file",
+								description: "Write a file to the repository"
+							},
+							{
+								name: "create-branch",
+								description: "Create a new branch"
+							}
+						],
+						discovery: { pathTemplate: "/repo/:branch/.actions" }
+					}
+				]
+			}
+		} };
+	}
+	/**
+	* Get enriched metadata for an issue or PR path.
+	* Returns labels, assignees, milestone, reactions from GitHub API.
+	*/
+	async getEnrichedMeta(path) {
+		const parsed = this.parseIssuePRPath(path);
+		if (!parsed) return null;
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		if (parsed.type === "issue") try {
+			const issue = (await this.client.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
+				owner,
+				repo,
+				issue_number: parsed.number
+			})).data;
+			return {
+				type: "issue",
+				state: issue.state,
+				author: issue.user?.login,
+				labels: (issue.labels ?? []).map((l) => l.name),
+				assignees: (issue.assignees ?? []).map((a) => a.login),
+				milestone: issue.milestone?.title ?? null,
+				reactions: issue.reactions ? this.extractReactions(issue.reactions) : this.zeroReactions(),
+				commentCount: issue.comments,
+				created_at: issue.created_at,
+				updated_at: issue.updated_at
+			};
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
+		}
+		if (parsed.type === "pull") try {
+			const pr = (await this.client.request("GET /repos/{owner}/{repo}/pulls/{pull_number}", {
+				owner,
+				repo,
+				pull_number: parsed.number
+			})).data;
+			return {
+				type: "pull_request",
+				state: pr.state,
+				author: pr.user?.login,
+				draft: pr.draft,
+				labels: (pr.labels ?? []).map((l) => l.name),
+				assignees: (pr.assignees ?? []).map((a) => a.login),
+				milestone: pr.milestone?.title ?? null,
+				reactions: pr.reactions ? this.extractReactions(pr.reactions) : this.zeroReactions(),
+				reviewers: (pr.requested_reviewers ?? []).map((r) => r.login),
+				commentCount: pr.comments,
+				merged_at: pr.merged_at,
+				created_at: pr.created_at,
+				updated_at: pr.updated_at
+			};
+		} catch (error) {
+			if (error?.status === 404) throw new AFSNotFoundError(path);
+			throw error;
+		}
+		return null;
+	}
+	extractReactions(reactions) {
+		return {
+			"+1": reactions["+1"] ?? 0,
+			"-1": reactions["-1"] ?? 0,
+			laugh: reactions.laugh ?? 0,
+			hooray: reactions.hooray ?? 0,
+			confused: reactions.confused ?? 0,
+			heart: reactions.heart ?? 0,
+			rocket: reactions.rocket ?? 0,
+			eyes: reactions.eyes ?? 0
+		};
+	}
+	zeroReactions() {
+		return {
+			"+1": 0,
+			"-1": 0,
+			laugh: 0,
+			hooray: 0,
+			confused: 0,
+			heart: 0,
+			rocket: 0,
+			eyes: 0
+		};
+	}
+	/**
+	* Parse a path to determine if it's an issue or PR path.
+	* Returns { type, number } or null.
+	*/
+	parseIssuePRPath(path) {
+		const segments = path.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+		if (this.options.mode === "single-repo") {
+			if (segments.length === 2 && segments[0] === "issues" && /^\d+$/.test(segments[1])) return {
+				type: "issue",
+				number: Number.parseInt(segments[1], 10)
+			};
+			if (segments.length === 2 && segments[0] === "pulls" && /^\d+$/.test(segments[1])) return {
+				type: "pull",
+				number: Number.parseInt(segments[1], 10)
+			};
+		} else if (this.options.mode === "org") {
+			if (segments.length === 3 && segments[1] === "issues" && /^\d+$/.test(segments[2])) return {
+				type: "issue",
+				number: Number.parseInt(segments[2], 10)
+			};
+			if (segments.length === 3 && segments[1] === "pulls" && /^\d+$/.test(segments[2])) return {
+				type: "pull",
+				number: Number.parseInt(segments[2], 10)
+			};
+		}
+		return null;
+	}
+	/**
+	* List available actions at a path.
+	* Returns null if the path is not an .actions path.
+	*/
+	listActions(path) {
+		const normalized = path.replace(/^\/+|\/+$/g, "");
+		if (normalized === ".actions") return { data: [
+			{
+				id: "create-issue",
+				path: "/.actions/create-issue",
+				summary: "Create a new issue",
+				meta: {
+					kind: "afs:executable",
+					name: "create-issue"
+				}
+			},
+			{
+				id: "create-pr",
+				path: "/.actions/create-pr",
+				summary: "Create a new pull request",
+				meta: {
+					kind: "afs:executable",
+					name: "create-pr"
+				}
+			},
+			{
+				id: "create-file",
+				path: "/.actions/create-file",
+				summary: "Create a file in the repository",
+				meta: {
+					kind: "afs:executable",
+					name: "create-file"
+				}
+			},
+			{
+				id: "update-file",
+				path: "/.actions/update-file",
+				summary: "Update a file in the repository",
+				meta: {
+					kind: "afs:executable",
+					name: "update-file"
+				}
+			}
+		] };
+		const issueActionsMatch = normalized.match(/^issues\/(\d+)\/\.actions$/);
+		if (issueActionsMatch) {
+			const num = issueActionsMatch[1];
+			return { data: [
+				{
+					id: "close-issue",
+					path: `/issues/${num}/.actions/close-issue`,
+					summary: "Close this issue",
+					meta: {
+						kind: "afs:executable",
+						name: "close-issue"
+					}
+				},
+				{
+					id: "reopen-issue",
+					path: `/issues/${num}/.actions/reopen-issue`,
+					summary: "Reopen this issue",
+					meta: {
+						kind: "afs:executable",
+						name: "reopen-issue"
+					}
+				},
+				{
+					id: "add-comment",
+					path: `/issues/${num}/.actions/add-comment`,
+					summary: "Add a comment",
+					meta: {
+						kind: "afs:executable",
+						name: "add-comment"
+					}
+				},
+				{
+					id: "add-label",
+					path: `/issues/${num}/.actions/add-label`,
+					summary: "Add a label",
+					meta: {
+						kind: "afs:executable",
+						name: "add-label"
+					}
+				},
+				{
+					id: "remove-label",
+					path: `/issues/${num}/.actions/remove-label`,
+					summary: "Remove a label",
+					meta: {
+						kind: "afs:executable",
+						name: "remove-label"
+					}
+				}
+			] };
+		}
+		const prActionsMatch = normalized.match(/^pulls\/(\d+)\/\.actions$/);
+		if (prActionsMatch) {
+			const num = prActionsMatch[1];
+			return { data: [
+				{
+					id: "merge-pr",
+					path: `/pulls/${num}/.actions/merge-pr`,
+					summary: "Merge this pull request",
+					meta: {
+						kind: "afs:executable",
+						name: "merge-pr"
+					}
+				},
+				{
+					id: "request-review",
+					path: `/pulls/${num}/.actions/request-review`,
+					summary: "Request a review",
+					meta: {
+						kind: "afs:executable",
+						name: "request-review"
+					}
+				},
+				{
+					id: "add-comment",
+					path: `/pulls/${num}/.actions/add-comment`,
+					summary: "Add a comment",
+					meta: {
+						kind: "afs:executable",
+						name: "add-comment"
+					}
+				},
+				{
+					id: "add-label",
+					path: `/pulls/${num}/.actions/add-label`,
+					summary: "Add a label",
+					meta: {
+						kind: "afs:executable",
+						name: "add-label"
+					}
+				},
+				{
+					id: "remove-label",
+					path: `/pulls/${num}/.actions/remove-label`,
+					summary: "Remove a label",
+					meta: {
+						kind: "afs:executable",
+						name: "remove-label"
+					}
+				}
+			] };
+		}
+		return null;
+	}
+	/**
+	* Execute an action at a path.
+	* Path format: /{resource}/.actions/{action-name}
+	*/
+	async exec(path, args, _options) {
+		if (this.accessMode === "readonly") throw new AFSReadonlyError("Cannot exec on a readonly provider");
+		const actionMatch = path.replace(/^\/+|\/+$/g, "").match(/^(?:(.+)\/)?\.actions\/([^/]+)$/);
+		if (!actionMatch) return {
+			success: false,
+			error: {
+				code: "INVALID_PATH",
+				message: `Invalid action path: ${path}`
+			}
+		};
+		const resourcePath = actionMatch[1] || "";
+		const actionName = actionMatch[2];
+		try {
+			if (resourcePath === "") return await this.execRootAction(actionName, args);
+			const issueMatch = resourcePath.match(/^issues\/(\d+)$/);
+			if (issueMatch) {
+				const issueNumber = Number.parseInt(issueMatch[1], 10);
+				return await this.execIssueAction(issueNumber, actionName, args);
+			}
+			const prMatch = resourcePath.match(/^pulls\/(\d+)$/);
+			if (prMatch) {
+				const prNumber = Number.parseInt(prMatch[1], 10);
+				return await this.execPRAction(prNumber, actionName, args);
+			}
+			return {
+				success: false,
+				error: {
+					code: "NOT_FOUND",
+					message: `No actions for path: /${resourcePath}`
+				}
+			};
+		} catch (error) {
+			return this.handleExecError(error);
+		}
+	}
+	async execRootAction(actionName, args) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		switch (actionName) {
+			case "create-issue": {
+				const title = args.title;
+				if (!title) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "title is required"
+					}
+				};
+				const issue = (await this.client.request("POST /repos/{owner}/{repo}/issues", {
+					owner,
+					repo,
+					title,
+					body: args.body ?? void 0,
+					labels: args.labels ?? void 0,
+					assignees: args.assignees ?? void 0
+				})).data;
+				return {
+					success: true,
+					data: {
+						number: issue.number,
+						url: issue.html_url
+					}
+				};
+			}
+			case "create-pr": {
+				const title = args.title;
+				const head = args.head;
+				const base = args.base;
+				if (!title || !head || !base) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "title, head, and base are required"
+					}
+				};
+				if (head === base) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "head and base must be different branches"
+					}
+				};
+				const pr = (await this.client.request("POST /repos/{owner}/{repo}/pulls", {
+					owner,
+					repo,
+					title,
+					body: args.body ?? void 0,
+					head,
+					base,
+					draft: args.draft ?? false
+				})).data;
+				return {
+					success: true,
+					data: {
+						number: pr.number,
+						url: pr.html_url
+					}
+				};
+			}
+			case "create-file": {
+				const filePath = args.path;
+				if (!filePath) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "path is required"
+					}
+				};
+				if (filePath.includes("..") || filePath.startsWith("/")) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "path must not contain '..' or start with '/'"
+					}
+				};
+				const content = args.content ?? "";
+				const message = args.message ?? `Create ${filePath}`;
+				const result = (await this.client.request("PUT /repos/{owner}/{repo}/contents/{path}", {
+					owner,
+					repo,
+					path: filePath,
+					message,
+					content: Buffer.from(content).toString("base64"),
+					branch: args.branch ?? void 0
+				})).data;
+				const fileInfo = result.content;
+				const commitInfo = result.commit;
+				return {
+					success: true,
+					data: {
+						sha: fileInfo?.sha,
+						commitSha: commitInfo?.sha
+					}
+				};
+			}
+			case "update-file": {
+				const filePath = args.path;
+				const sha = args.sha;
+				if (!filePath) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "path is required"
+					}
+				};
+				if (!sha) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "sha is required (optimistic lock)"
+					}
+				};
+				if (filePath.includes("..") || filePath.startsWith("/")) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "path must not contain '..' or start with '/'"
+					}
+				};
+				const content = args.content ?? "";
+				const message = args.message ?? `Update ${filePath}`;
+				const result = (await this.client.request("PUT /repos/{owner}/{repo}/contents/{path}", {
+					owner,
+					repo,
+					path: filePath,
+					message,
+					content: Buffer.from(content).toString("base64"),
+					sha,
+					branch: args.branch ?? void 0
+				})).data;
+				const fileInfo = result.content;
+				const commitInfo = result.commit;
+				return {
+					success: true,
+					data: {
+						sha: fileInfo?.sha,
+						commitSha: commitInfo?.sha
+					}
+				};
+			}
+			default: return {
+				success: false,
+				error: {
+					code: "NOT_FOUND",
+					message: `Unknown action: ${actionName}`
+				}
+			};
+		}
+	}
+	async execIssueAction(issueNumber, actionName, args) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		switch (actionName) {
+			case "close-issue": return {
+				success: true,
+				data: { state: (await this.client.request("PATCH /repos/{owner}/{repo}/issues/{issue_number}", {
+					owner,
+					repo,
+					issue_number: issueNumber,
+					state: "closed",
+					state_reason: args.reason ?? void 0
+				})).data.state }
+			};
+			case "reopen-issue": return {
+				success: true,
+				data: { state: (await this.client.request("PATCH /repos/{owner}/{repo}/issues/{issue_number}", {
+					owner,
+					repo,
+					issue_number: issueNumber,
+					state: "open"
+				})).data.state }
+			};
+			case "add-comment": {
+				const body = args.body;
+				if (!body) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "body is required"
+					}
+				};
+				return {
+					success: true,
+					data: { id: (await this.client.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+						owner,
+						repo,
+						issue_number: issueNumber,
+						body
+					})).data.id }
+				};
+			}
+			case "add-label": {
+				const label = args.label;
+				if (!label) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "label is required"
+					}
+				};
+				if (label.length > 200) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "label name exceeds maximum length (200)"
+					}
+				};
+				await this.client.request("POST /repos/{owner}/{repo}/issues/{issue_number}/labels", {
+					owner,
+					repo,
+					issue_number: issueNumber,
+					labels: [label]
+				});
+				return {
+					success: true,
+					data: { label }
+				};
+			}
+			case "remove-label": {
+				const label = args.label;
+				if (!label) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "label is required"
+					}
+				};
+				try {
+					await this.client.request("DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}", {
+						owner,
+						repo,
+						issue_number: issueNumber,
+						name: label
+					});
+					return {
+						success: true,
+						data: { label }
+					};
+				} catch (error) {
+					if (error?.status === 404) return {
+						success: false,
+						error: {
+							code: "NOT_FOUND",
+							message: `Label "${label}" not found`
+						}
+					};
+					throw error;
+				}
+			}
+			default: return {
+				success: false,
+				error: {
+					code: "NOT_FOUND",
+					message: `Unknown issue action: ${actionName}`
+				}
+			};
+		}
+	}
+	async execPRAction(prNumber, actionName, args) {
+		const owner = this.options.owner;
+		const repo = this.options.repo;
+		switch (actionName) {
+			case "merge-pr": {
+				const method = args.method ?? "merge";
+				const result = (await this.client.request("PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge", {
+					owner,
+					repo,
+					pull_number: prNumber,
+					merge_method: method,
+					commit_title: args.commitTitle ?? void 0,
+					commit_message: args.commitMessage ?? void 0
+				})).data;
+				return {
+					success: true,
+					data: {
+						merged: result.merged,
+						sha: result.sha
+					}
+				};
+			}
+			case "request-review": {
+				const reviewers = args.reviewers;
+				if (!reviewers || reviewers.length === 0) return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "reviewers is required"
+					}
+				};
+				await this.client.request("POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers", {
+					owner,
+					repo,
+					pull_number: prNumber,
+					reviewers
+				});
+				return {
+					success: true,
+					data: { reviewers }
+				};
+			}
+			case "add-comment": return this.execIssueAction(prNumber, "add-comment", args);
+			case "add-label": return this.execIssueAction(prNumber, "add-label", args);
+			case "remove-label": return this.execIssueAction(prNumber, "remove-label", args);
+			default: return {
+				success: false,
+				error: {
+					code: "NOT_FOUND",
+					message: `Unknown PR action: ${actionName}`
+				}
+			};
+		}
+	}
+	/**
+	* Handle errors from action execution.
+	* Sanitizes error messages to prevent token leaks.
+	*/
+	handleExecError(error) {
+		const status = error?.status;
+		const sanitized = (error instanceof Error ? error.message : String(error)).replace(/ghp_[a-zA-Z0-9]+/g, "[REDACTED]");
+		if (status === 403) return {
+			success: false,
+			error: {
+				code: "FORBIDDEN",
+				message: `Insufficient permissions. Check that your token has the required access.`
+			}
+		};
+		if (status === 404) return {
+			success: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Resource not found: ${sanitized}`
+			}
+		};
+		if (status === 405 || status === 409) return {
+			success: false,
+			error: {
+				code: "CONFLICT",
+				message: sanitized
+			}
+		};
+		if (status === 422) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: sanitized
+			}
+		};
+		return {
+			success: false,
+			error: {
+				code: "INTERNAL_ERROR",
+				message: sanitized
+			}
+		};
+	}
 };
 
 //#endregion