@loopstack/github-module 0.1.0

package/src/tools/pull-requests/github-merge-pull-request.tool.ts

@@ -0,0 +1,108 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubMergePullRequestArgs = {
+  owner: string;
+  repo: string;
+  pullNumber: number;
+  mergeMethod?: string;
+  commitTitle?: string;
+  commitMessage?: string;
+};
+
+@Tool({
+  config: {
+    description: 'Merges a GitHub pull request. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubMergePullRequestTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubMergePullRequestTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        pullNumber: z.number(),
+        mergeMethod: z.enum(['merge', 'squash', 'rebase']).default('merge'),
+        commitTitle: z.string().optional(),
+        commitMessage: z.string().optional(),
+      })
+      .strict(),
+  })
+  args: GitHubMergePullRequestArgs;
+
+  async execute(args: GitHubMergePullRequestArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const requestBody: Record<string, unknown> = {
+      merge_method: args.mergeMethod ?? 'merge',
+    };
+
+    if (args.commitTitle) requestBody.commit_title = args.commitTitle;
+    if (args.commitMessage) requestBody.commit_message = args.commitMessage;
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/pulls/${args.pullNumber}/merge`;
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${errorBody}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const result = (await response.json()) as {
+      sha: string;
+      merged: boolean;
+      message: string;
+    };
+
+    return {
+      data: {
+        merge: {
+          sha: result.sha,
+          merged: result.merged,
+          message: result.message,
+        },
+      },
+    };
+  }
+}

package/src/tools/repos/github-create-repo.tool.ts

@@ -0,0 +1,111 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubCreateRepoArgs = {
+  name: string;
+  description?: string;
+  private?: boolean;
+  autoInit?: boolean;
+};
+
+@Tool({
+  config: {
+    description:
+      'Creates a new GitHub repository for the authenticated user. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubCreateRepoTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubCreateRepoTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        name: z.string(),
+        description: z.string().optional(),
+        private: z.boolean().default(false),
+        autoInit: z.boolean().default(false),
+      })
+      .strict(),
+  })
+  args: GitHubCreateRepoArgs;
+
+  async execute(args: GitHubCreateRepoArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const body: Record<string, unknown> = {
+      name: args.name,
+      private: args.private ?? false,
+      auto_init: args.autoInit ?? false,
+    };
+
+    if (args.description) body.description = args.description;
+
+    const response = await fetch('https://api.github.com/user/repos', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${errorBody}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const repo = (await response.json()) as {
+      id: number;
+      full_name: string;
+      name: string;
+      html_url: string;
+      private: boolean;
+      default_branch: string;
+    };
+
+    return {
+      data: {
+        repo: {
+          id: repo.id,
+          fullName: repo.full_name,
+          name: repo.name,
+          htmlUrl: repo.html_url,
+          private: repo.private,
+          defaultBranch: repo.default_branch,
+        },
+      },
+    };
+  }
+}

package/src/tools/repos/github-get-repo.tool.ts

@@ -0,0 +1,120 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubGetRepoArgs = {
+  owner: string;
+  repo: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Gets detailed information about a specific GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubGetRepoTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubGetRepoTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+      })
+      .strict(),
+  })
+  args: GitHubGetRepoArgs;
+
+  async execute(args: GitHubGetRepoArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const response = await fetch(
+      `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}`,
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+    );
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${body}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const repo = (await response.json()) as {
+      id: number;
+      full_name: string;
+      name: string;
+      owner: { login: string; avatar_url: string };
+      private: boolean;
+      html_url: string;
+      description: string | null;
+      language: string | null;
+      default_branch: string;
+      stargazers_count: number;
+      forks_count: number;
+      open_issues_count: number;
+      created_at: string;
+      updated_at: string;
+      topics: string[];
+      license: { spdx_id: string } | null;
+    };
+
+    return {
+      data: {
+        repo: {
+          id: repo.id,
+          fullName: repo.full_name,
+          name: repo.name,
+          owner: repo.owner.login,
+          ownerAvatar: repo.owner.avatar_url,
+          private: repo.private,
+          htmlUrl: repo.html_url,
+          description: repo.description,
+          language: repo.language,
+          defaultBranch: repo.default_branch,
+          stars: repo.stargazers_count,
+          forks: repo.forks_count,
+          openIssues: repo.open_issues_count,
+          createdAt: repo.created_at,
+          updatedAt: repo.updated_at,
+          topics: repo.topics,
+          license: repo.license?.spdx_id ?? null,
+        },
+      },
+    };
+  }
+}

package/src/tools/repos/github-list-branches.tool.ts

@@ -0,0 +1,97 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubListBranchesArgs = {
+  owner: string;
+  repo: string;
+  perPage?: number;
+};
+
+@Tool({
+  config: {
+    description:
+      'Lists branches for a GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubListBranchesTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubListBranchesTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        perPage: z.number().default(30),
+      })
+      .strict(),
+  })
+  args: GitHubListBranchesArgs;
+
+  async execute(args: GitHubListBranchesArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const params = new URLSearchParams({
+      per_page: String(args.perPage ?? 30),
+    });
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/branches?${params.toString()}`;
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${body}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const data = (await response.json()) as Array<{
+      name: string;
+      commit: { sha: string };
+      protected: boolean;
+    }>;
+
+    const branches = data.map((branch) => ({
+      name: branch.name,
+      commitSha: branch.commit.sha,
+      protected: branch['protected'],
+    }));
+
+    return {
+      data: { branches },
+    };
+  }
+}

package/src/tools/repos/github-list-repos.tool.ts

@@ -0,0 +1,115 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubListReposArgs = {
+  visibility?: string;
+  sort?: string;
+  perPage?: number;
+  page?: number;
+};
+
+@Tool({
+  config: {
+    description:
+      'Lists repositories for the authenticated GitHub user. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubListReposTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubListReposTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        visibility: z.enum(['all', 'public', 'private']).default('all'),
+        sort: z.enum(['created', 'updated', 'pushed', 'full_name']).default('updated'),
+        perPage: z.number().default(30),
+        page: z.number().default(1),
+      })
+      .strict(),
+  })
+  args: GitHubListReposArgs;
+
+  async execute(args: GitHubListReposArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const params = new URLSearchParams({
+      visibility: args.visibility ?? 'all',
+      sort: args.sort ?? 'updated',
+      per_page: String(args.perPage ?? 30),
+      page: String(args.page ?? 1),
+    });
+
+    const response = await fetch(`https://api.github.com/user/repos?${params.toString()}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${body}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const data = (await response.json()) as Array<{
+      id: number;
+      full_name: string;
+      name: string;
+      owner: { login: string };
+      private: boolean;
+      html_url: string;
+      description: string | null;
+      language: string | null;
+      default_branch: string;
+      updated_at: string;
+    }>;
+
+    const repos = data.map((repo) => ({
+      id: repo.id,
+      fullName: repo.full_name,
+      name: repo.name,
+      owner: repo.owner.login,
+      private: repo.private,
+      htmlUrl: repo.html_url,
+      description: repo.description,
+      language: repo.language,
+      defaultBranch: repo.default_branch,
+      updatedAt: repo.updated_at,
+    }));
+
+    return {
+      data: { repos },
+    };
+  }
+}

package/src/tools/search/github-search-code.tool.ts

@@ -0,0 +1,105 @@
+import { Inject, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { Input, RunContext, Tool, ToolInterface, ToolResult } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+export type GitHubSearchCodeArgs = {
+  query: string;
+  perPage?: number;
+  page?: number;
+};
+
+@Tool({
+  config: {
+    description:
+      'Searches for code across GitHub repositories using the GitHub search syntax. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubSearchCodeTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubSearchCodeTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        query: z.string(),
+        perPage: z.number().default(30),
+        page: z.number().default(1),
+      })
+      .strict(),
+  })
+  args: GitHubSearchCodeArgs;
+
+  async execute(args: GitHubSearchCodeArgs, ctx: RunContext): Promise<ToolResult> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'github');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid GitHub token found. Please authenticate first.',
+        },
+      };
+    }
+
+    const params = new URLSearchParams({
+      q: args.query,
+      per_page: String(args.perPage ?? 30),
+      page: String(args.page ?? 1),
+    });
+
+    const response = await fetch(`https://api.github.com/search/code?${params.toString()}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`GitHub API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'GitHub token was rejected. Please re-authenticate.',
+        },
+      };
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`GitHub API error: ${response.status} ${body}`);
+      return {
+        data: {
+          error: 'api_error',
+          message: `GitHub API error: ${response.statusText}`,
+        },
+      };
+    }
+
+    const data = (await response.json()) as {
+      total_count: number;
+      items: Array<{
+        name: string;
+        path: string;
+        sha: string;
+        html_url: string;
+        repository: { full_name: string };
+      }>;
+    };
+
+    const results = data.items.map((item) => ({
+      name: item.name,
+      path: item.path,
+      sha: item.sha,
+      htmlUrl: item.html_url,
+      repository: item.repository.full_name,
+    }));
+
+    return {
+      data: { totalCount: data.total_count, results },
+    };
+  }
+}