@loopstack/github-module 0.1.0

package/src/tools/content/github-create-or-update-file.tool.ts

@@ -0,0 +1,124 @@
+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 GitHubCreateOrUpdateFileArgs = {
+  owner: string;
+  repo: string;
+  path: string;
+  content: string;
+  message: string;
+  sha?: string;
+  branch?: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Creates or updates a file in a GitHub repository. Content is provided as plain text and encoded to base64 before sending. To update an existing file, provide the sha of the file being replaced. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubCreateOrUpdateFileTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubCreateOrUpdateFileTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        path: z.string(),
+        content: z.string(),
+        message: z.string(),
+        sha: z.string().optional(),
+        branch: z.string().optional(),
+      })
+      .strict(),
+  })
+  args: GitHubCreateOrUpdateFileArgs;
+
+  async execute(args: GitHubCreateOrUpdateFileArgs, 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> = {
+      message: args.message,
+      content: Buffer.from(args.content).toString('base64'),
+    };
+
+    if (args.sha) requestBody.sha = args.sha;
+    if (args.branch) requestBody.branch = args.branch;
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/contents/${args.path}`;
+    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 data = (await response.json()) as {
+      content: {
+        name: string;
+        path: string;
+        sha: string;
+        html_url: string;
+      };
+      commit: {
+        sha: string;
+        message: string;
+      };
+    };
+
+    return {
+      data: {
+        file: {
+          name: data.content.name,
+          path: data.content.path,
+          sha: data.content.sha,
+          htmlUrl: data.content.html_url,
+        },
+        commit: {
+          sha: data.commit.sha,
+          message: data.commit.message,
+        },
+      },
+    };
+  }
+}

package/src/tools/content/github-get-commit.tool.ts

@@ -0,0 +1,124 @@
+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 GitHubGetCommitArgs = {
+  owner: string;
+  repo: string;
+  ref: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Gets detailed information about a specific commit in a GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubGetCommitTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubGetCommitTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        ref: z.string(),
+      })
+      .strict(),
+  })
+  args: GitHubGetCommitArgs;
+
+  async execute(args: GitHubGetCommitArgs, 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 url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/commits/${encodeURIComponent(args.ref)}`;
+    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 {
+      sha: string;
+      commit: {
+        message: string;
+        author: { name: string; email: string; date: string };
+        committer: { name: string; email: string; date: string };
+      };
+      author: { login: string } | null;
+      html_url: string;
+      stats: { additions: number; deletions: number; total: number };
+      files: Array<{
+        filename: string;
+        status: string;
+        additions: number;
+        deletions: number;
+        changes: number;
+      }>;
+    };
+
+    return {
+      data: {
+        commit: {
+          sha: data.sha,
+          message: data.commit.message,
+          author: {
+            name: data.commit.author.name,
+            email: data.commit.author.email,
+            date: data.commit.author.date,
+            login: data.author?.login ?? null,
+          },
+          committer: {
+            name: data.commit.committer.name,
+            date: data.commit.committer.date,
+          },
+          htmlUrl: data.html_url,
+          stats: data.stats,
+          files: data.files.map((f) => ({
+            filename: f.filename,
+            status: f.status,
+            additions: f.additions,
+            deletions: f.deletions,
+            changes: f.changes,
+          })),
+        },
+      },
+    };
+  }
+}

package/src/tools/content/github-get-file-content.tool.ts

@@ -0,0 +1,112 @@
+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 GitHubGetFileContentArgs = {
+  owner: string;
+  repo: string;
+  path: string;
+  ref?: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Gets the content of a file from a GitHub repository. Decodes base64-encoded content from the API. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubGetFileContentTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubGetFileContentTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        path: z.string(),
+        ref: z.string().optional(),
+      })
+      .strict(),
+  })
+  args: GitHubGetFileContentArgs;
+
+  async execute(args: GitHubGetFileContentArgs, 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();
+    if (args.ref) params.set('ref', args.ref);
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/contents/${args.path}${params.toString() ? `?${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 {
+      name: string;
+      path: string;
+      sha: string;
+      size: number;
+      type: string;
+      content?: string;
+      encoding?: string;
+      html_url: string;
+    };
+
+    let content: string | null = null;
+    if (data.content && data.encoding === 'base64') {
+      content = Buffer.from(data.content, 'base64').toString('utf-8');
+    }
+
+    return {
+      data: {
+        file: {
+          name: data.name,
+          path: data.path,
+          sha: data.sha,
+          size: data.size,
+          type: data.type,
+          content,
+          htmlUrl: data.html_url,
+        },
+      },
+    };
+  }
+}

package/src/tools/content/github-list-directory.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 GitHubListDirectoryArgs = {
+  owner: string;
+  repo: string;
+  path?: string;
+  ref?: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Lists the contents of a directory in a GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubListDirectoryTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubListDirectoryTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        path: z.string().default(''),
+        ref: z.string().optional(),
+      })
+      .strict(),
+  })
+  args: GitHubListDirectoryArgs;
+
+  async execute(args: GitHubListDirectoryArgs, 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();
+    if (args.ref) params.set('ref', args.ref);
+
+    const dirPath = args.path ?? '';
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/contents/${dirPath}${params.toString() ? `?${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;
+      path: string;
+      sha: string;
+      size: number;
+      type: string;
+      html_url: string;
+    }>;
+
+    const entries = data.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      sha: entry.sha,
+      size: entry.size,
+      type: entry.type,
+      htmlUrl: entry.html_url,
+    }));
+
+    return {
+      data: { entries },
+    };
+  }
+}

package/src/tools/issues/github-create-issue-comment.tool.ts

@@ -0,0 +1,100 @@
+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 GitHubCreateIssueCommentArgs = {
+  owner: string;
+  repo: string;
+  issueNumber: number;
+  body: string;
+};
+
+@Tool({
+  config: {
+    description:
+      'Creates a comment on a GitHub issue or pull request. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubCreateIssueCommentTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubCreateIssueCommentTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        issueNumber: z.number(),
+        body: z.string(),
+      })
+      .strict(),
+  })
+  args: GitHubCreateIssueCommentArgs;
+
+  async execute(args: GitHubCreateIssueCommentArgs, 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 url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/issues/${args.issueNumber}/comments`;
+    const response = await fetch(url, {
+      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: args.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 comment = (await response.json()) as {
+      id: number;
+      html_url: string;
+      created_at: string;
+      user: { login: string };
+    };
+
+    return {
+      data: {
+        comment: {
+          id: comment.id,
+          htmlUrl: comment.html_url,
+          createdAt: comment.created_at,
+          user: comment.user.login,
+        },
+      },
+    };
+  }
+}

package/src/tools/issues/github-create-issue.tool.ts

@@ -0,0 +1,114 @@
+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 GitHubCreateIssueArgs = {
+  owner: string;
+  repo: string;
+  title: string;
+  body?: string;
+  labels?: string[];
+  assignees?: string[];
+};
+
+@Tool({
+  config: {
+    description:
+      'Creates a new issue in a GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubCreateIssueTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubCreateIssueTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        title: z.string(),
+        body: z.string().optional(),
+        labels: z.array(z.string()).optional(),
+        assignees: z.array(z.string()).optional(),
+      })
+      .strict(),
+  })
+  args: GitHubCreateIssueArgs;
+
+  async execute(args: GitHubCreateIssueArgs, 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> = {
+      title: args.title,
+    };
+
+    if (args.body) requestBody.body = args.body;
+    if (args.labels) requestBody.labels = args.labels;
+    if (args.assignees) requestBody.assignees = args.assignees;
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/issues`;
+    const response = await fetch(url, {
+      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(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 issue = (await response.json()) as {
+      id: number;
+      number: number;
+      title: string;
+      html_url: string;
+      state: string;
+    };
+
+    return {
+      data: {
+        issue: {
+          id: issue.id,
+          number: issue.number,
+          title: issue.title,
+          htmlUrl: issue.html_url,
+          state: issue.state,
+        },
+      },
+    };
+  }
+}