@tpmjs/tools-github 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @tpmjs/tools-github
+
+GitHub API tools for AI agents. Manage repos, issues, pull requests, commits, branches, releases, gists, and Actions workflows.
+
+## Installation
+
+```bash
+npm install @tpmjs/tools-github
+```
+
+## Setup
+
+Set your GitHub personal access token:
+
+```bash
+export GITHUB_TOKEN="ghp_..."
+```
+
+## Usage
+
+```typescript
+import { getRepo, listIssues, searchCode } from '@tpmjs/tools-github';
+
+const repo = await getRepo.execute({ owner: 'vercel', repo: 'next.js' });
+const issues = await listIssues.execute({ owner: 'vercel', repo: 'next.js', state: 'open', per_page: 5 });
+const results = await searchCode.execute({ q: 'useState language:typescript', per_page: 10 });
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `getRepo` | Get details of a GitHub repository |
+| `listRepos` | List repositories for a user or organization |
+| `searchRepositories` | Search GitHub repositories by query |
+| `createIssue` | Create a new issue on a repository |
+| `getIssue` | Get details of a specific issue |
+| `listIssues` | List issues with state and label filters |
+| `createIssueComment` | Add a comment to an issue or PR |
+| `getPullRequest` | Get details of a specific pull request |
+| `listPullRequests` | List pull requests with filters |
+| `getFileContent` | Get file or directory contents from a repo |
+| `searchCode` | Search for code across GitHub |
+| `listBranches` | List branches on a repository |
+| `getCommit` | Get details of a specific commit |
+| `listCommits` | List commits with path and author filters |
+| `listReleases` | List releases on a repository |
+| `getRelease` | Get a specific release by tag name |
+| `createGist` | Create a new GitHub Gist |
+| `listGists` | List gists for a user |
+| `listWorkflowRuns` | List GitHub Actions workflow runs |
+| `getWorkflowRun` | Get details of a workflow run |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as ai from 'ai';
+
+/**
+ * @tpmjs/tools-github — GitHub API Tools for AI Agents
+ *
+ * Full access to the GitHub REST API: repos, issues, pull requests, commits,
+ * releases, gists, workflow runs, and code search.
+ *
+ * @requires GITHUB_TOKEN environment variable
+ */
+interface GetRepoInput {
+    owner: string;
+    repo: string;
+}
+declare const getRepo: ai.Tool<GetRepoInput, Record<string, unknown>>;
+interface ListReposInput {
+    username: string;
+    sort?: string;
+    direction?: string;
+    per_page?: number;
+}
+declare const listRepos: ai.Tool<ListReposInput, unknown[]>;
+interface SearchRepositoriesInput {
+    q: string;
+    sort?: string;
+    order?: string;
+    per_page?: number;
+}
+declare const searchRepositories: ai.Tool<SearchRepositoriesInput, Record<string, unknown>>;
+interface CreateIssueInput {
+    owner: string;
+    repo: string;
+    title: string;
+    body?: string;
+    labels?: string[];
+    assignees?: string[];
+}
+declare const createIssue: ai.Tool<CreateIssueInput, Record<string, unknown>>;
+interface GetIssueInput {
+    owner: string;
+    repo: string;
+    issue_number: number;
+}
+declare const getIssue: ai.Tool<GetIssueInput, Record<string, unknown>>;
+interface ListIssuesInput {
+    owner: string;
+    repo: string;
+    state?: string;
+    labels?: string;
+    sort?: string;
+    per_page?: number;
+}
+declare const listIssues: ai.Tool<ListIssuesInput, unknown[]>;
+interface CreateIssueCommentInput {
+    owner: string;
+    repo: string;
+    issue_number: number;
+    body: string;
+}
+declare const createIssueComment: ai.Tool<CreateIssueCommentInput, Record<string, unknown>>;
+interface GetPullRequestInput {
+    owner: string;
+    repo: string;
+    pull_number: number;
+}
+declare const getPullRequest: ai.Tool<GetPullRequestInput, Record<string, unknown>>;
+interface ListPullRequestsInput {
+    owner: string;
+    repo: string;
+    state?: string;
+    head?: string;
+    base?: string;
+    sort?: string;
+    per_page?: number;
+}
+declare const listPullRequests: ai.Tool<ListPullRequestsInput, unknown[]>;
+interface GetFileContentInput {
+    owner: string;
+    repo: string;
+    path: string;
+    ref?: string;
+}
+declare const getFileContent: ai.Tool<GetFileContentInput, Record<string, unknown>>;
+interface SearchCodeInput {
+    q: string;
+    sort?: string;
+    order?: string;
+    per_page?: number;
+}
+declare const searchCode: ai.Tool<SearchCodeInput, Record<string, unknown>>;
+interface ListBranchesInput {
+    owner: string;
+    repo: string;
+    per_page?: number;
+}
+declare const listBranches: ai.Tool<ListBranchesInput, unknown[]>;
+interface GetCommitInput {
+    owner: string;
+    repo: string;
+    ref: string;
+}
+declare const getCommit: ai.Tool<GetCommitInput, Record<string, unknown>>;
+interface ListCommitsInput {
+    owner: string;
+    repo: string;
+    sha?: string;
+    path?: string;
+    author?: string;
+    since?: string;
+    until?: string;
+    per_page?: number;
+}
+declare const listCommits: ai.Tool<ListCommitsInput, unknown[]>;
+interface ListReleasesInput {
+    owner: string;
+    repo: string;
+    per_page?: number;
+}
+declare const listReleases: ai.Tool<ListReleasesInput, unknown[]>;
+interface GetReleaseInput {
+    owner: string;
+    repo: string;
+    tag: string;
+}
+declare const getRelease: ai.Tool<GetReleaseInput, Record<string, unknown>>;
+interface CreateGistInput {
+    description?: string;
+    files: Record<string, {
+        content: string;
+    }>;
+    public?: boolean;
+}
+declare const createGist: ai.Tool<CreateGistInput, Record<string, unknown>>;
+interface ListGistsInput {
+    username?: string;
+    per_page?: number;
+}
+declare const listGists: ai.Tool<ListGistsInput, unknown[]>;
+interface ListWorkflowRunsInput {
+    owner: string;
+    repo: string;
+    status?: string;
+    per_page?: number;
+}
+declare const listWorkflowRuns: ai.Tool<ListWorkflowRunsInput, Record<string, unknown>>;
+interface GetWorkflowRunInput {
+    owner: string;
+    repo: string;
+    run_id: number;
+}
+declare const getWorkflowRun: ai.Tool<GetWorkflowRunInput, Record<string, unknown>>;
+declare const _default: {
+    getRepo: ai.Tool<GetRepoInput, Record<string, unknown>>;
+    listRepos: ai.Tool<ListReposInput, unknown[]>;
+    searchRepositories: ai.Tool<SearchRepositoriesInput, Record<string, unknown>>;
+    createIssue: ai.Tool<CreateIssueInput, Record<string, unknown>>;
+    getIssue: ai.Tool<GetIssueInput, Record<string, unknown>>;
+    listIssues: ai.Tool<ListIssuesInput, unknown[]>;
+    createIssueComment: ai.Tool<CreateIssueCommentInput, Record<string, unknown>>;
+    getPullRequest: ai.Tool<GetPullRequestInput, Record<string, unknown>>;
+    listPullRequests: ai.Tool<ListPullRequestsInput, unknown[]>;
+    getFileContent: ai.Tool<GetFileContentInput, Record<string, unknown>>;
+    searchCode: ai.Tool<SearchCodeInput, Record<string, unknown>>;
+    listBranches: ai.Tool<ListBranchesInput, unknown[]>;
+    getCommit: ai.Tool<GetCommitInput, Record<string, unknown>>;
+    listCommits: ai.Tool<ListCommitsInput, unknown[]>;
+    listReleases: ai.Tool<ListReleasesInput, unknown[]>;
+    getRelease: ai.Tool<GetReleaseInput, Record<string, unknown>>;
+    createGist: ai.Tool<CreateGistInput, Record<string, unknown>>;
+    listGists: ai.Tool<ListGistsInput, unknown[]>;
+    listWorkflowRuns: ai.Tool<ListWorkflowRunsInput, Record<string, unknown>>;
+    getWorkflowRun: ai.Tool<GetWorkflowRunInput, Record<string, unknown>>;
+};
+
+export { type CreateGistInput, type CreateIssueCommentInput, type CreateIssueInput, type GetCommitInput, type GetFileContentInput, type GetIssueInput, type GetPullRequestInput, type GetReleaseInput, type GetRepoInput, type GetWorkflowRunInput, type ListBranchesInput, type ListCommitsInput, type ListGistsInput, type ListIssuesInput, type ListPullRequestsInput, type ListReleasesInput, type ListReposInput, type ListWorkflowRunsInput, type SearchCodeInput, type SearchRepositoriesInput, createGist, createIssue, createIssueComment, _default as default, getCommit, getFileContent, getIssue, getPullRequest, getRelease, getRepo, getWorkflowRun, listBranches, listCommits, listGists, listIssues, listPullRequests, listReleases, listRepos, listWorkflowRuns, searchCode, searchRepositories };

package/dist/index.js

@@ -0,0 +1,734 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var BASE_URL = "https://api.github.com";
+function getApiKey() {
+  const key = process.env.GITHUB_TOKEN;
+  if (!key) {
+    throw new Error(
+      "GITHUB_TOKEN environment variable is required. Get your token from https://github.com/settings/tokens"
+    );
+  }
+  return key;
+}
+async function apiRequest(method, path, body) {
+  const key = getApiKey();
+  const headers = {
+    Authorization: `Bearer ${key}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-API-Version": "2022-11-28",
+    "Content-Type": "application/json"
+  };
+  const options = { method, headers };
+  if (body !== void 0) {
+    options.body = JSON.stringify(body);
+  }
+  const response = await fetch(`${BASE_URL}${path}`, options);
+  if (!response.ok) {
+    await handleApiError(response);
+  }
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+  return JSON.parse(text);
+}
+async function handleApiError(response) {
+  let errorMessage;
+  try {
+    const errorData = await response.json();
+    errorMessage = errorData.message || errorData.error || `HTTP ${response.status}`;
+  } catch {
+    errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+  }
+  switch (response.status) {
+    case 400:
+      throw new Error(`Bad request: ${errorMessage}`);
+    case 401:
+      throw new Error("Authentication failed: Invalid GitHub token. Check GITHUB_TOKEN.");
+    case 403:
+      throw new Error(`Access forbidden: ${errorMessage}`);
+    case 404:
+      throw new Error(`Not found: ${errorMessage}`);
+    case 422:
+      throw new Error(`Validation error: ${errorMessage}`);
+    case 429:
+      throw new Error(`Rate limit exceeded: ${errorMessage}`);
+    default:
+      throw new Error(`GitHub API error (${response.status}): ${errorMessage}`);
+  }
+}
+function buildQueryString(params) {
+  const entries = Object.entries(params).filter(
+    ([, v]) => v !== void 0 && v !== null && v !== ""
+  );
+  if (entries.length === 0) return "";
+  return "?" + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+}
+var getRepo = tool({
+  description: "Get detailed information about a GitHub repository including description, stars, forks, and topics.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner (username or organization)." },
+      repo: { type: "string", description: "Repository name." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      return await apiRequest("GET", `/repos/${input.owner}/${input.repo}`);
+    } catch (error) {
+      throw new Error(`Failed to get repository: ${error.message}`);
+    }
+  }
+});
+var listRepos = tool({
+  description: "List public repositories for a specified user with optional sorting and pagination.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      username: { type: "string", description: "GitHub username to list repositories for." },
+      sort: {
+        type: "string",
+        description: "Sort by: created, updated, pushed, full_name (default: full_name)."
+      },
+      direction: { type: "string", description: "Sort direction: asc or desc (default: asc)." },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["username"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.username) {
+        throw new Error("Username is required");
+      }
+      const qs = buildQueryString({
+        sort: input.sort,
+        direction: input.direction,
+        per_page: input.per_page
+      });
+      return await apiRequest("GET", `/users/${input.username}/repos${qs}`);
+    } catch (error) {
+      throw new Error(`Failed to list repositories: ${error.message}`);
+    }
+  }
+});
+var searchRepositories = tool({
+  description: "Search for GitHub repositories by keyword, language, stars, or other criteria using GitHub search syntax.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      q: {
+        type: "string",
+        description: 'Search query (e.g., "react language:typescript stars:>1000"). See GitHub search syntax.'
+      },
+      sort: {
+        type: "string",
+        description: "Sort by: stars, forks, help-wanted-issues, updated (default: best match)."
+      },
+      order: { type: "string", description: "Sort order: asc or desc (default: desc)." },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["q"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.q) {
+        throw new Error("Search query is required");
+      }
+      const qs = buildQueryString({
+        q: input.q,
+        sort: input.sort,
+        order: input.order,
+        per_page: input.per_page
+      });
+      return await apiRequest("GET", `/search/repositories${qs}`);
+    } catch (error) {
+      throw new Error(`Failed to search repositories: ${error.message}`);
+    }
+  }
+});
+var createIssue = tool({
+  description: "Create a new issue in a GitHub repository with title, body, labels, and assignees.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      title: { type: "string", description: "Issue title." },
+      body: { type: "string", description: "Issue body content (supports Markdown)." },
+      labels: {
+        type: "array",
+        items: { type: "string" },
+        description: "Array of label names to add to the issue."
+      },
+      assignees: {
+        type: "array",
+        items: { type: "string" },
+        description: "Array of GitHub usernames to assign to the issue."
+      }
+    },
+    required: ["owner", "repo", "title"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.title) {
+        throw new Error("Owner, repo, and title are required");
+      }
+      return await apiRequest(
+        "POST",
+        `/repos/${input.owner}/${input.repo}/issues`,
+        {
+          title: input.title,
+          body: input.body,
+          labels: input.labels,
+          assignees: input.assignees
+        }
+      );
+    } catch (error) {
+      throw new Error(`Failed to create issue: ${error.message}`);
+    }
+  }
+});
+var getIssue = tool({
+  description: "Get details of a specific issue by its number including comments count and state.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      issue_number: { type: "number", description: "Issue number." }
+    },
+    required: ["owner", "repo", "issue_number"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.issue_number) {
+        throw new Error("Owner, repo, and issue_number are required");
+      }
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/issues/${input.issue_number}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get issue: ${error.message}`);
+    }
+  }
+});
+var listIssues = tool({
+  description: "List issues for a repository with optional filtering by state, labels, and sorting options.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      state: {
+        type: "string",
+        description: "Filter by state: open, closed, or all (default: open)."
+      },
+      labels: {
+        type: "string",
+        description: "Comma-separated list of label names to filter by."
+      },
+      sort: {
+        type: "string",
+        description: "Sort by: created, updated, comments (default: created)."
+      },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({
+        state: input.state,
+        labels: input.labels,
+        sort: input.sort,
+        per_page: input.per_page
+      });
+      return await apiRequest("GET", `/repos/${input.owner}/${input.repo}/issues${qs}`);
+    } catch (error) {
+      throw new Error(`Failed to list issues: ${error.message}`);
+    }
+  }
+});
+var createIssueComment = tool({
+  description: "Add a comment to an existing issue with Markdown-formatted content.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      issue_number: { type: "number", description: "Issue number to comment on." },
+      body: { type: "string", description: "Comment body (supports Markdown)." }
+    },
+    required: ["owner", "repo", "issue_number", "body"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.issue_number || !input.body) {
+        throw new Error("Owner, repo, issue_number, and body are required");
+      }
+      return await apiRequest(
+        "POST",
+        `/repos/${input.owner}/${input.repo}/issues/${input.issue_number}/comments`,
+        { body: input.body }
+      );
+    } catch (error) {
+      throw new Error(`Failed to create issue comment: ${error.message}`);
+    }
+  }
+});
+var getPullRequest = tool({
+  description: "Get details of a specific pull request including mergeable state, review status, and commits.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      pull_number: { type: "number", description: "Pull request number." }
+    },
+    required: ["owner", "repo", "pull_number"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.pull_number) {
+        throw new Error("Owner, repo, and pull_number are required");
+      }
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/pulls/${input.pull_number}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get pull request: ${error.message}`);
+    }
+  }
+});
+var listPullRequests = tool({
+  description: "List pull requests for a repository with optional filtering by state, branch, and sorting.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      state: {
+        type: "string",
+        description: "Filter by state: open, closed, or all (default: open)."
+      },
+      head: {
+        type: "string",
+        description: "Filter by head branch (format: user:ref-name or organization:ref-name)."
+      },
+      base: { type: "string", description: "Filter by base branch name." },
+      sort: {
+        type: "string",
+        description: "Sort by: created, updated, popularity, long-running (default: created)."
+      },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({
+        state: input.state,
+        head: input.head,
+        base: input.base,
+        sort: input.sort,
+        per_page: input.per_page
+      });
+      return await apiRequest("GET", `/repos/${input.owner}/${input.repo}/pulls${qs}`);
+    } catch (error) {
+      throw new Error(`Failed to list pull requests: ${error.message}`);
+    }
+  }
+});
+var getFileContent = tool({
+  description: "Get the contents of a file or directory in a repository at a specific ref (branch, tag, or commit SHA).",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      path: { type: "string", description: "File or directory path within the repository." },
+      ref: {
+        type: "string",
+        description: "Git ref (branch name, tag, or commit SHA). Defaults to default branch."
+      }
+    },
+    required: ["owner", "repo", "path"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.path) {
+        throw new Error("Owner, repo, and path are required");
+      }
+      const qs = buildQueryString({ ref: input.ref });
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/contents/${input.path}${qs}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get file content: ${error.message}`);
+    }
+  }
+});
+var searchCode = tool({
+  description: "Search for code across all GitHub repositories using keyword, filename, language, or other filters.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      q: {
+        type: "string",
+        description: 'Search query (e.g., "addClass in:file language:js repo:jquery/jquery"). See GitHub search syntax.'
+      },
+      sort: { type: "string", description: "Sort by: indexed (default: best match)." },
+      order: { type: "string", description: "Sort order: asc or desc (default: desc)." },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["q"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.q) {
+        throw new Error("Search query is required");
+      }
+      const qs = buildQueryString({
+        q: input.q,
+        sort: input.sort,
+        order: input.order,
+        per_page: input.per_page
+      });
+      return await apiRequest("GET", `/search/code${qs}`);
+    } catch (error) {
+      throw new Error(`Failed to search code: ${error.message}`);
+    }
+  }
+});
+var listBranches = tool({
+  description: "List all branches in a repository with their latest commit SHA and protection status.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({ per_page: input.per_page });
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/branches${qs}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to list branches: ${error.message}`);
+    }
+  }
+});
+var getCommit = tool({
+  description: "Get detailed information about a specific commit including changes, author, and committer.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      ref: { type: "string", description: "Commit SHA, branch name, or tag." }
+    },
+    required: ["owner", "repo", "ref"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.ref) {
+        throw new Error("Owner, repo, and ref are required");
+      }
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/commits/${input.ref}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get commit: ${error.message}`);
+    }
+  }
+});
+var listCommits = tool({
+  description: "List commits in a repository with optional filtering by branch, path, author, and date range.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      sha: {
+        type: "string",
+        description: "SHA or branch to start listing from (defaults to default branch)."
+      },
+      path: { type: "string", description: "Only commits containing this file path." },
+      author: { type: "string", description: "GitHub username or email to filter by author." },
+      since: {
+        type: "string",
+        description: "Only commits after this date (ISO 8601 timestamp)."
+      },
+      until: {
+        type: "string",
+        description: "Only commits before this date (ISO 8601 timestamp)."
+      },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({
+        sha: input.sha,
+        path: input.path,
+        author: input.author,
+        since: input.since,
+        until: input.until,
+        per_page: input.per_page
+      });
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/commits${qs}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to list commits: ${error.message}`);
+    }
+  }
+});
+var listReleases = tool({
+  description: "List published releases for a repository including tags, assets, and release notes.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({ per_page: input.per_page });
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/releases${qs}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to list releases: ${error.message}`);
+    }
+  }
+});
+var getRelease = tool({
+  description: "Get details of a specific release by its tag name including assets and body.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      tag: { type: "string", description: 'Release tag name (e.g., "v1.0.0").' }
+    },
+    required: ["owner", "repo", "tag"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.tag) {
+        throw new Error("Owner, repo, and tag are required");
+      }
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/releases/tags/${input.tag}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get release: ${error.message}`);
+    }
+  }
+});
+var createGist = tool({
+  description: "Create a new gist with one or more files. Gists can be public or secret (unlisted).",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      description: { type: "string", description: "Description of the gist." },
+      files: {
+        type: "object",
+        additionalProperties: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "File content." }
+          },
+          required: ["content"]
+        },
+        description: "Files to include in the gist as an object with filename keys and { content } values."
+      },
+      public: {
+        type: "boolean",
+        description: "Whether the gist is public (true) or secret/unlisted (false)."
+      }
+    },
+    required: ["files"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.files || Object.keys(input.files).length === 0) {
+        throw new Error("At least one file is required");
+      }
+      return await apiRequest("POST", "/gists", {
+        description: input.description,
+        files: input.files,
+        public: input.public ?? true
+      });
+    } catch (error) {
+      throw new Error(`Failed to create gist: ${error.message}`);
+    }
+  }
+});
+var listGists = tool({
+  description: "List public gists for a specified user, or list all public gists if no username provided.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      username: {
+        type: "string",
+        description: "GitHub username to list gists for. Omit to list all public gists."
+      },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      const qs = buildQueryString({ per_page: input.per_page });
+      const path = input.username ? `/users/${input.username}/gists${qs}` : `/gists${qs}`;
+      return await apiRequest("GET", path);
+    } catch (error) {
+      throw new Error(`Failed to list gists: ${error.message}`);
+    }
+  }
+});
+var listWorkflowRuns = tool({
+  description: "List GitHub Actions workflow runs for a repository with optional filtering by status.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      status: {
+        type: "string",
+        description: "Filter by status: completed, action_required, cancelled, failure, neutral, skipped, stale, success, timed_out, in_progress, queued, requested, waiting."
+      },
+      per_page: { type: "number", description: "Results per page (1-100, default: 30)." }
+    },
+    required: ["owner", "repo"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo) {
+        throw new Error("Owner and repo are required");
+      }
+      const qs = buildQueryString({ status: input.status, per_page: input.per_page });
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/actions/runs${qs}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to list workflow runs: ${error.message}`);
+    }
+  }
+});
+var getWorkflowRun = tool({
+  description: "Get details of a specific workflow run including status, conclusion, and job information.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      owner: { type: "string", description: "Repository owner." },
+      repo: { type: "string", description: "Repository name." },
+      run_id: { type: "number", description: "Workflow run ID." }
+    },
+    required: ["owner", "repo", "run_id"],
+    additionalProperties: false
+  }),
+  async execute(input) {
+    try {
+      if (!input.owner || !input.repo || !input.run_id) {
+        throw new Error("Owner, repo, and run_id are required");
+      }
+      return await apiRequest(
+        "GET",
+        `/repos/${input.owner}/${input.repo}/actions/runs/${input.run_id}`
+      );
+    } catch (error) {
+      throw new Error(`Failed to get workflow run: ${error.message}`);
+    }
+  }
+});
+var index_default = {
+  // Repositories
+  getRepo,
+  listRepos,
+  searchRepositories,
+  // Issues
+  createIssue,
+  getIssue,
+  listIssues,
+  createIssueComment,
+  // Pull Requests
+  getPullRequest,
+  listPullRequests,
+  // Content
+  getFileContent,
+  searchCode,
+  // Branches & Commits
+  listBranches,
+  getCommit,
+  listCommits,
+  // Releases
+  listReleases,
+  getRelease,
+  // Gists
+  createGist,
+  listGists,
+  // Actions
+  listWorkflowRuns,
+  getWorkflowRun
+};
+
+export { createGist, createIssue, createIssueComment, index_default as default, getCommit, getFileContent, getIssue, getPullRequest, getRelease, getRepo, getWorkflowRun, listBranches, listCommits, listGists, listIssues, listPullRequests, listReleases, listRepos, listWorkflowRuns, searchCode, searchRepositories };

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "@tpmjs/tools-github",
+  "version": "0.1.0",
+  "description": "GitHub API tools for AI agents. Manage repos, issues, pull requests, commits, branches, releases, and gists.",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "github",
+    "git",
+    "devops",
+    "agent"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "@tpmjs/tsconfig": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "ai": "6.0.49"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tpmjs/tpmjs.git",
+    "directory": "packages/tools/official/github"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "ops",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "getRepo",
+        "description": "Get details of a GitHub repository including stars, forks, and language."
+      },
+      {
+        "name": "listRepos",
+        "description": "List repositories for a user or organization with optional filtering."
+      },
+      {
+        "name": "createIssue",
+        "description": "Create a new issue on a GitHub repository."
+      },
+      {
+        "name": "getIssue",
+        "description": "Get details of a specific issue by number."
+      },
+      {
+        "name": "listIssues",
+        "description": "List issues on a repository with state and label filters."
+      },
+      {
+        "name": "createIssueComment",
+        "description": "Add a comment to an existing GitHub issue or pull request."
+      },
+      {
+        "name": "getPullRequest",
+        "description": "Get details of a specific pull request by number."
+      },
+      {
+        "name": "listPullRequests",
+        "description": "List pull requests on a repository with state and head/base filters."
+      },
+      {
+        "name": "getFileContent",
+        "description": "Get the contents of a file or directory from a GitHub repository."
+      },
+      {
+        "name": "searchCode",
+        "description": "Search for code across GitHub repositories."
+      },
+      {
+        "name": "searchRepositories",
+        "description": "Search GitHub repositories by query with sort and order options."
+      },
+      {
+        "name": "listBranches",
+        "description": "List branches on a GitHub repository."
+      },
+      {
+        "name": "getCommit",
+        "description": "Get details of a specific commit by SHA."
+      },
+      {
+        "name": "listCommits",
+        "description": "List commits on a repository with optional path and author filters."
+      },
+      {
+        "name": "listReleases",
+        "description": "List releases on a GitHub repository."
+      },
+      {
+        "name": "getRelease",
+        "description": "Get details of a specific release by tag name."
+      },
+      {
+        "name": "createGist",
+        "description": "Create a new GitHub Gist with one or more files."
+      },
+      {
+        "name": "listGists",
+        "description": "List gists for the authenticated user or a specific user."
+      },
+      {
+        "name": "listWorkflowRuns",
+        "description": "List recent GitHub Actions workflow runs for a repository."
+      },
+      {
+        "name": "getWorkflowRun",
+        "description": "Get details of a specific GitHub Actions workflow run."
+      }
+    ]
+  }
+}