@github-tools/sdk 0.0.1

package/dist/index.mjs

@@ -0,0 +1,626 @@
+import { Octokit } from "@octokit/rest";
+import { tool } from "ai";
+import { z } from "zod";
+
+//#region src/client.ts
+function createOctokit(token) {
+	return new Octokit({ auth: token });
+}
+
+//#endregion
+//#region src/tools/repository.ts
+const getRepository = (octokit) => tool({
+	description: "Get information about a GitHub repository including description, stars, forks, language, and default branch",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner (user or organization)"),
+		repo: z.string().describe("Repository name")
+	}),
+	execute: async ({ owner, repo }) => {
+		const { data } = await octokit.repos.get({
+			owner,
+			repo
+		});
+		return {
+			name: data.name,
+			fullName: data.full_name,
+			description: data.description,
+			url: data.html_url,
+			defaultBranch: data.default_branch,
+			stars: data.stargazers_count,
+			forks: data.forks_count,
+			openIssues: data.open_issues_count,
+			language: data.language,
+			private: data.private,
+			createdAt: data.created_at,
+			updatedAt: data.updated_at
+		};
+	}
+});
+const listBranches = (octokit) => tool({
+	description: "List branches in a GitHub repository",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		perPage: z.number().optional().default(30).describe("Number of branches to return (max 100)")
+	}),
+	execute: async ({ owner, repo, perPage }) => {
+		const { data } = await octokit.repos.listBranches({
+			owner,
+			repo,
+			per_page: perPage
+		});
+		return data.map((branch) => ({
+			name: branch.name,
+			sha: branch.commit.sha,
+			protected: branch.protected
+		}));
+	}
+});
+const getFileContent = (octokit) => tool({
+	description: "Get the content of a file from a GitHub repository",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		path: z.string().describe("Path to the file in the repository"),
+		ref: z.string().optional().describe("Branch, tag, or commit SHA (defaults to the default branch)")
+	}),
+	execute: async ({ owner, repo, path, ref }) => {
+		const { data } = await octokit.repos.getContent({
+			owner,
+			repo,
+			path,
+			ref
+		});
+		if (Array.isArray(data)) return {
+			type: "directory",
+			entries: data.map((e) => ({
+				name: e.name,
+				type: e.type,
+				path: e.path
+			}))
+		};
+		if (data.type !== "file") return {
+			type: data.type,
+			path: data.path
+		};
+		const content = Buffer.from(data.content, "base64").toString("utf-8");
+		return {
+			type: "file",
+			path: data.path,
+			sha: data.sha,
+			size: data.size,
+			content
+		};
+	}
+});
+const createOrUpdateFile = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Create or update a file in a GitHub repository. Provide the SHA when updating an existing file.",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		path: z.string().describe("Path to the file in the repository"),
+		message: z.string().describe("Commit message"),
+		content: z.string().describe("File content (plain text, will be base64-encoded automatically)"),
+		branch: z.string().optional().describe("Branch to commit to (defaults to the default branch)"),
+		sha: z.string().optional().describe("SHA of the file being replaced (required when updating an existing file)")
+	}),
+	execute: async ({ owner, repo, path, message, content, branch, sha }) => {
+		const encoded = Buffer.from(content).toString("base64");
+		const { data } = await octokit.repos.createOrUpdateFileContents({
+			owner,
+			repo,
+			path,
+			message,
+			content: encoded,
+			branch,
+			sha
+		});
+		return {
+			path: data.content?.path,
+			sha: data.content?.sha,
+			commitSha: data.commit.sha,
+			commitUrl: data.commit.html_url
+		};
+	}
+});
+
+//#endregion
+//#region src/tools/pull-requests.ts
+const listPullRequests = (octokit) => tool({
+	description: "List pull requests for a GitHub repository",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		state: z.enum([
+			"open",
+			"closed",
+			"all"
+		]).optional().default("open").describe("Filter by state"),
+		perPage: z.number().optional().default(30).describe("Number of results to return (max 100)")
+	}),
+	execute: async ({ owner, repo, state, perPage }) => {
+		const { data } = await octokit.pulls.list({
+			owner,
+			repo,
+			state,
+			per_page: perPage
+		});
+		return data.map((pr) => ({
+			number: pr.number,
+			title: pr.title,
+			state: pr.state,
+			url: pr.html_url,
+			author: pr.user?.login,
+			branch: pr.head.ref,
+			base: pr.base.ref,
+			draft: pr.draft,
+			createdAt: pr.created_at,
+			updatedAt: pr.updated_at
+		}));
+	}
+});
+const getPullRequest = (octokit) => tool({
+	description: "Get detailed information about a specific pull request",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		pullNumber: z.number().describe("Pull request number")
+	}),
+	execute: async ({ owner, repo, pullNumber }) => {
+		const { data } = await octokit.pulls.get({
+			owner,
+			repo,
+			pull_number: pullNumber
+		});
+		return {
+			number: data.number,
+			title: data.title,
+			body: data.body,
+			state: data.state,
+			url: data.html_url,
+			author: data.user?.login,
+			branch: data.head.ref,
+			base: data.base.ref,
+			draft: data.draft,
+			merged: data.merged,
+			mergeable: data.mergeable,
+			additions: data.additions,
+			deletions: data.deletions,
+			changedFiles: data.changed_files,
+			createdAt: data.created_at,
+			updatedAt: data.updated_at,
+			mergedAt: data.merged_at
+		};
+	}
+});
+const createPullRequest = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Create a new pull request in a GitHub repository",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		title: z.string().describe("Pull request title"),
+		body: z.string().optional().describe("Pull request description (supports Markdown)"),
+		head: z.string().describe("Branch containing the changes (format: branch or username:branch)"),
+		base: z.string().describe("Branch to merge into"),
+		draft: z.boolean().optional().default(false).describe("Create as draft pull request")
+	}),
+	execute: async ({ owner, repo, title, body, head, base, draft }) => {
+		const { data } = await octokit.pulls.create({
+			owner,
+			repo,
+			title,
+			body,
+			head,
+			base,
+			draft
+		});
+		return {
+			number: data.number,
+			title: data.title,
+			url: data.html_url,
+			state: data.state,
+			draft: data.draft,
+			branch: data.head.ref,
+			base: data.base.ref
+		};
+	}
+});
+const mergePullRequest = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Merge a pull request",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		pullNumber: z.number().describe("Pull request number"),
+		commitTitle: z.string().optional().describe("Title for the automatic merge commit"),
+		commitMessage: z.string().optional().describe("Extra detail to append to automatic commit message"),
+		mergeMethod: z.enum([
+			"merge",
+			"squash",
+			"rebase"
+		]).optional().default("merge").describe("Merge strategy")
+	}),
+	execute: async ({ owner, repo, pullNumber, commitTitle, commitMessage, mergeMethod }) => {
+		const { data } = await octokit.pulls.merge({
+			owner,
+			repo,
+			pull_number: pullNumber,
+			commit_title: commitTitle,
+			commit_message: commitMessage,
+			merge_method: mergeMethod
+		});
+		return {
+			merged: data.merged,
+			message: data.message,
+			sha: data.sha
+		};
+	}
+});
+const addPullRequestComment = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Add a comment to a pull request",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		pullNumber: z.number().describe("Pull request number"),
+		body: z.string().describe("Comment text (supports Markdown)")
+	}),
+	execute: async ({ owner, repo, pullNumber, body }) => {
+		const { data } = await octokit.issues.createComment({
+			owner,
+			repo,
+			issue_number: pullNumber,
+			body
+		});
+		return {
+			id: data.id,
+			url: data.html_url,
+			body: data.body,
+			author: data.user?.login,
+			createdAt: data.created_at
+		};
+	}
+});
+
+//#endregion
+//#region src/tools/issues.ts
+const listIssues = (octokit) => tool({
+	description: "List issues for a GitHub repository (excludes pull requests)",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		state: z.enum([
+			"open",
+			"closed",
+			"all"
+		]).optional().default("open").describe("Filter by state"),
+		labels: z.string().optional().describe("Comma-separated list of label names to filter by"),
+		perPage: z.number().optional().default(30).describe("Number of results to return (max 100)")
+	}),
+	execute: async ({ owner, repo, state, labels, perPage }) => {
+		const { data } = await octokit.issues.listForRepo({
+			owner,
+			repo,
+			state,
+			labels,
+			per_page: perPage
+		});
+		return data.filter((issue) => !issue.pull_request).map((issue) => ({
+			number: issue.number,
+			title: issue.title,
+			state: issue.state,
+			url: issue.html_url,
+			author: issue.user?.login,
+			labels: issue.labels.map((l) => typeof l === "string" ? l : l.name),
+			createdAt: issue.created_at,
+			updatedAt: issue.updated_at
+		}));
+	}
+});
+const getIssue = (octokit) => tool({
+	description: "Get detailed information about a specific issue",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		issueNumber: z.number().describe("Issue number")
+	}),
+	execute: async ({ owner, repo, issueNumber }) => {
+		const { data } = await octokit.issues.get({
+			owner,
+			repo,
+			issue_number: issueNumber
+		});
+		return {
+			number: data.number,
+			title: data.title,
+			body: data.body,
+			state: data.state,
+			url: data.html_url,
+			author: data.user?.login,
+			assignees: data.assignees?.map((a) => a.login),
+			labels: data.labels.map((l) => typeof l === "string" ? l : l.name),
+			comments: data.comments,
+			createdAt: data.created_at,
+			updatedAt: data.updated_at,
+			closedAt: data.closed_at
+		};
+	}
+});
+const createIssue = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Create a new issue in a GitHub repository",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		title: z.string().describe("Issue title"),
+		body: z.string().optional().describe("Issue description (supports Markdown)"),
+		labels: z.array(z.string()).optional().describe("Labels to apply to the issue"),
+		assignees: z.array(z.string()).optional().describe("GitHub usernames to assign to the issue")
+	}),
+	execute: async ({ owner, repo, title, body, labels, assignees }) => {
+		const { data } = await octokit.issues.create({
+			owner,
+			repo,
+			title,
+			body,
+			labels,
+			assignees
+		});
+		return {
+			number: data.number,
+			title: data.title,
+			url: data.html_url,
+			state: data.state,
+			labels: data.labels.map((l) => typeof l === "string" ? l : l.name)
+		};
+	}
+});
+const addIssueComment = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Add a comment to a GitHub issue",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		issueNumber: z.number().describe("Issue number"),
+		body: z.string().describe("Comment text (supports Markdown)")
+	}),
+	execute: async ({ owner, repo, issueNumber, body }) => {
+		const { data } = await octokit.issues.createComment({
+			owner,
+			repo,
+			issue_number: issueNumber,
+			body
+		});
+		return {
+			id: data.id,
+			url: data.html_url,
+			body: data.body,
+			author: data.user?.login,
+			createdAt: data.created_at
+		};
+	}
+});
+const closeIssue = (octokit, { needsApproval = true } = {}) => tool({
+	description: "Close an open GitHub issue",
+	needsApproval,
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		issueNumber: z.number().describe("Issue number to close"),
+		stateReason: z.enum(["completed", "not_planned"]).optional().default("completed").describe("Reason for closing")
+	}),
+	execute: async ({ owner, repo, issueNumber, stateReason }) => {
+		const { data } = await octokit.issues.update({
+			owner,
+			repo,
+			issue_number: issueNumber,
+			state: "closed",
+			state_reason: stateReason
+		});
+		return {
+			number: data.number,
+			title: data.title,
+			state: data.state,
+			url: data.html_url,
+			closedAt: data.closed_at
+		};
+	}
+});
+
+//#endregion
+//#region src/tools/search.ts
+const searchCode = (octokit) => tool({
+	description: "Search for code in GitHub repositories. Use qualifiers like \"repo:owner/name\" to scope the search.",
+	inputSchema: z.object({
+		query: z.string().describe("Search query. Supports GitHub search qualifiers, e.g. \"useState repo:facebook/react\""),
+		perPage: z.number().optional().default(10).describe("Number of results to return (max 30)")
+	}),
+	execute: async ({ query, perPage }) => {
+		const { data } = await octokit.search.code({
+			q: query,
+			per_page: perPage
+		});
+		return {
+			totalCount: data.total_count,
+			items: data.items.map((item) => ({
+				name: item.name,
+				path: item.path,
+				url: item.html_url,
+				repository: item.repository.full_name,
+				sha: item.sha
+			}))
+		};
+	}
+});
+const searchRepositories = (octokit) => tool({
+	description: "Search for GitHub repositories by keyword, topic, language, or other qualifiers",
+	inputSchema: z.object({
+		query: z.string().describe("Search query. Supports GitHub search qualifiers, e.g. \"nuxt language:typescript stars:>1000\""),
+		perPage: z.number().optional().default(10).describe("Number of results to return (max 30)"),
+		sort: z.enum([
+			"stars",
+			"forks",
+			"help-wanted-issues",
+			"updated"
+		]).optional().describe("Sort field"),
+		order: z.enum(["asc", "desc"]).optional().default("desc").describe("Sort order")
+	}),
+	execute: async ({ query, perPage, sort, order }) => {
+		const { data } = await octokit.search.repos({
+			q: query,
+			per_page: perPage,
+			sort,
+			order
+		});
+		return {
+			totalCount: data.total_count,
+			items: data.items.map((repo) => ({
+				name: repo.name,
+				fullName: repo.full_name,
+				description: repo.description,
+				url: repo.html_url,
+				stars: repo.stargazers_count,
+				forks: repo.forks_count,
+				language: repo.language,
+				topics: repo.topics
+			}))
+		};
+	}
+});
+
+//#endregion
+//#region src/tools/commits.ts
+const listCommits = (octokit) => tool({
+	description: "List commits for a GitHub repository. Filter by file path to see who changed a specific file and when (git blame alternative). Filter by author, branch, or date range.",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		path: z.string().optional().describe("Only commits containing this file path"),
+		sha: z.string().optional().describe("Branch name or commit SHA to start listing from"),
+		author: z.string().optional().describe("GitHub username or email to filter commits by"),
+		since: z.string().optional().describe("Only commits after this date (ISO 8601 format)"),
+		until: z.string().optional().describe("Only commits before this date (ISO 8601 format)"),
+		perPage: z.number().optional().default(30).describe("Number of results to return (max 100)")
+	}),
+	execute: async ({ owner, repo, path, sha, author, since, until, perPage }) => {
+		const { data } = await octokit.repos.listCommits({
+			owner,
+			repo,
+			path,
+			sha,
+			author,
+			since,
+			until,
+			per_page: perPage
+		});
+		return data.map((commit) => ({
+			sha: commit.sha,
+			message: commit.commit.message,
+			author: commit.commit.author?.name,
+			authorLogin: commit.author?.login,
+			date: commit.commit.author?.date,
+			url: commit.html_url
+		}));
+	}
+});
+const getCommit = (octokit) => tool({
+	description: "Get detailed information about a specific commit, including the list of files changed with additions and deletions",
+	inputSchema: z.object({
+		owner: z.string().describe("Repository owner"),
+		repo: z.string().describe("Repository name"),
+		ref: z.string().describe("Commit SHA, branch name, or tag")
+	}),
+	execute: async ({ owner, repo, ref }) => {
+		const { data } = await octokit.repos.getCommit({
+			owner,
+			repo,
+			ref
+		});
+		return {
+			sha: data.sha,
+			message: data.commit.message,
+			author: data.commit.author?.name,
+			authorLogin: data.author?.login,
+			date: data.commit.author?.date,
+			url: data.html_url,
+			stats: data.stats ? {
+				additions: data.stats.additions,
+				deletions: data.stats.deletions,
+				total: data.stats.total
+			} : null,
+			files: data.files?.map((file) => ({
+				filename: file.filename,
+				status: file.status,
+				additions: file.additions,
+				deletions: file.deletions,
+				patch: file.patch
+			}))
+		};
+	}
+});
+
+//#endregion
+//#region src/index.ts
+function resolveApproval(toolName, config) {
+	if (typeof config === "boolean") return config;
+	return config[toolName] ?? true;
+}
+/**
+* Create a set of GitHub tools for the Vercel AI SDK.
+*
+* Write operations require user approval by default.
+* Control this globally or per-tool via `requireApproval`.
+*
+* @example
+* ```ts
+* // All writes need approval (default)
+* createGithubTools({ token })
+*
+* // No approval at all
+* createGithubTools({ token, requireApproval: false })
+*
+* // Granular: only destructive actions need approval
+* createGithubTools({
+*   token,
+*   requireApproval: {
+*     mergePullRequest: true,
+*     createOrUpdateFile: true,
+*     closeIssue: true,
+*     createPullRequest: false,
+*     addPullRequestComment: false,
+*     createIssue: false,
+*     addIssueComment: false,
+*   }
+* })
+* ```
+*/
+function createGithubTools({ token, requireApproval = true }) {
+	const octokit = createOctokit(token);
+	const approval = (name) => ({ needsApproval: resolveApproval(name, requireApproval) });
+	return {
+		getRepository: getRepository(octokit),
+		listBranches: listBranches(octokit),
+		getFileContent: getFileContent(octokit),
+		listPullRequests: listPullRequests(octokit),
+		getPullRequest: getPullRequest(octokit),
+		listIssues: listIssues(octokit),
+		getIssue: getIssue(octokit),
+		searchCode: searchCode(octokit),
+		searchRepositories: searchRepositories(octokit),
+		listCommits: listCommits(octokit),
+		getCommit: getCommit(octokit),
+		createOrUpdateFile: createOrUpdateFile(octokit, approval("createOrUpdateFile")),
+		createPullRequest: createPullRequest(octokit, approval("createPullRequest")),
+		mergePullRequest: mergePullRequest(octokit, approval("mergePullRequest")),
+		addPullRequestComment: addPullRequestComment(octokit, approval("addPullRequestComment")),
+		createIssue: createIssue(octokit, approval("createIssue")),
+		addIssueComment: addIssueComment(octokit, approval("addIssueComment")),
+		closeIssue: closeIssue(octokit, approval("closeIssue"))
+	};
+}
+
+//#endregion
+export { addIssueComment, addPullRequestComment, closeIssue, createGithubTools, createIssue, createOctokit, createOrUpdateFile, createPullRequest, getCommit, getFileContent, getIssue, getPullRequest, getRepository, listBranches, listCommits, listIssues, listPullRequests, mergePullRequest, searchCode, searchRepositories };
+//# sourceMappingURL=index.mjs.map