@loopstack/github-module 0.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@loopstack/github-module",
+  "displayName": "GitHub Module",
+  "description": "GitHub integration for the Loopstack automation framework. Provides a GitHub OAuth provider and tools for GitHub services such as repositories, issues, pull requests, actions, and more.",
+  "keywords": [
+    "authentication",
+    "github",
+    "loopstack",
+    "module",
+    "oauth"
+  ],
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "jest --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/oauth-module": "^0.1.3",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node",
+    "maxWorkers": 1
+  },
+  "loopstack": {
+    "modules": [
+      {
+        "path": "src/github.module.ts",
+        "className": "GitHubModule"
+      },
+      {
+        "package": "@loopstack/oauth-module",
+        "className": "OAuthModule"
+      }
+    ],
+    "workflows": [
+      {
+        "package": "@loopstack/oauth-module",
+        "className": "OAuthWorkflow",
+        "propertyName": "oAuth"
+      }
+    ],
+    "installModes": [
+      "add",
+      "install"
+    ]
+  }
+}

package/src/github-oauth.provider.ts

@@ -0,0 +1,85 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { OAuthProviderInterface, OAuthProviderRegistry, OAuthTokenSet } from '@loopstack/oauth-module';
+
+@Injectable()
+export class GitHubOAuthProvider implements OAuthProviderInterface, OnModuleInit {
+  private readonly logger = new Logger(GitHubOAuthProvider.name);
+
+  readonly providerId = 'github';
+  readonly defaultScopes = ['repo', 'user', 'workflow', 'read:org'];
+
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly providerRegistry: OAuthProviderRegistry,
+  ) {}
+
+  onModuleInit(): void {
+    this.providerRegistry.register(this);
+    this.logger.log('GitHub OAuth provider registered');
+  }
+
+  private get clientId(): string {
+    const id = this.configService.get<string>('GITHUB_CLIENT_ID');
+    if (!id) throw new Error('GITHUB_CLIENT_ID is not configured');
+    return id;
+  }
+
+  private get clientSecret(): string {
+    const secret = this.configService.get<string>('GITHUB_CLIENT_SECRET');
+    if (!secret) throw new Error('GITHUB_CLIENT_SECRET is not configured');
+    return secret;
+  }
+
+  private get redirectUri(): string {
+    return this.configService.get<string>('GITHUB_OAUTH_REDIRECT_URI', '/oauth/callback');
+  }
+
+  buildAuthUrl(scopes: string[], state: string): string {
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      scope: scopes.join(' '),
+      state,
+    });
+    return `https://github.com/login/oauth/authorize?${params.toString()}`;
+  }
+
+  async exchangeCode(code: string): Promise<OAuthTokenSet> {
+    const response = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: new URLSearchParams({
+        code,
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
+        redirect_uri: this.redirectUri,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      this.logger.error(`Token exchange failed: ${response.status} ${errorBody}`);
+      throw new Error(`GitHub token exchange failed: ${response.statusText}`);
+    }
+
+    const tokens = (await response.json()) as {
+      access_token: string;
+      token_type: string;
+      scope: string;
+    };
+
+    return {
+      accessToken: tokens.access_token,
+      expiresIn: 315360000,
+      scope: tokens.scope,
+    };
+  }
+
+  refreshToken(): Promise<OAuthTokenSet> {
+    throw new Error('GitHub tokens do not expire and cannot be refreshed.');
+  }
+}

package/src/github.module.ts

@@ -0,0 +1,63 @@
+import { Module } from '@nestjs/common';
+import { OAuthModule } from '@loopstack/oauth-module';
+import { GitHubOAuthProvider } from './github-oauth.provider';
+import { GitHubGetWorkflowRunTool } from './tools/actions/github-get-workflow-run.tool';
+import { GitHubListWorkflowRunsTool } from './tools/actions/github-list-workflow-runs.tool';
+import { GitHubTriggerWorkflowTool } from './tools/actions/github-trigger-workflow.tool';
+import { GitHubCreateOrUpdateFileTool } from './tools/content/github-create-or-update-file.tool';
+import { GitHubGetCommitTool } from './tools/content/github-get-commit.tool';
+import { GitHubGetFileContentTool } from './tools/content/github-get-file-content.tool';
+import { GitHubListDirectoryTool } from './tools/content/github-list-directory.tool';
+import { GitHubCreateIssueCommentTool } from './tools/issues/github-create-issue-comment.tool';
+import { GitHubCreateIssueTool } from './tools/issues/github-create-issue.tool';
+import { GitHubGetIssueTool } from './tools/issues/github-get-issue.tool';
+import { GitHubListIssuesTool } from './tools/issues/github-list-issues.tool';
+import { GitHubCreatePullRequestTool } from './tools/pull-requests/github-create-pull-request.tool';
+import { GitHubGetPullRequestTool } from './tools/pull-requests/github-get-pull-request.tool';
+import { GitHubListPrReviewsTool } from './tools/pull-requests/github-list-pr-reviews.tool';
+import { GitHubListPullRequestsTool } from './tools/pull-requests/github-list-pull-requests.tool';
+import { GitHubMergePullRequestTool } from './tools/pull-requests/github-merge-pull-request.tool';
+import { GitHubCreateRepoTool } from './tools/repos/github-create-repo.tool';
+import { GitHubGetRepoTool } from './tools/repos/github-get-repo.tool';
+import { GitHubListBranchesTool } from './tools/repos/github-list-branches.tool';
+import { GitHubListReposTool } from './tools/repos/github-list-repos.tool';
+import { GitHubSearchCodeTool } from './tools/search/github-search-code.tool';
+import { GitHubSearchIssuesTool } from './tools/search/github-search-issues.tool';
+import { GitHubSearchReposTool } from './tools/search/github-search-repos.tool';
+import { GitHubGetAuthenticatedUserTool } from './tools/users/github-get-authenticated-user.tool';
+import { GitHubListUserOrgsTool } from './tools/users/github-list-user-orgs.tool';
+
+const tools = [
+  GitHubListReposTool,
+  GitHubGetRepoTool,
+  GitHubCreateRepoTool,
+  GitHubListBranchesTool,
+  GitHubListIssuesTool,
+  GitHubGetIssueTool,
+  GitHubCreateIssueTool,
+  GitHubCreateIssueCommentTool,
+  GitHubListPullRequestsTool,
+  GitHubGetPullRequestTool,
+  GitHubCreatePullRequestTool,
+  GitHubMergePullRequestTool,
+  GitHubListPrReviewsTool,
+  GitHubGetFileContentTool,
+  GitHubCreateOrUpdateFileTool,
+  GitHubListDirectoryTool,
+  GitHubGetCommitTool,
+  GitHubListWorkflowRunsTool,
+  GitHubTriggerWorkflowTool,
+  GitHubGetWorkflowRunTool,
+  GitHubSearchCodeTool,
+  GitHubSearchReposTool,
+  GitHubSearchIssuesTool,
+  GitHubGetAuthenticatedUserTool,
+  GitHubListUserOrgsTool,
+];
+
+@Module({
+  imports: [OAuthModule],
+  providers: [GitHubOAuthProvider, ...tools],
+  exports: [GitHubOAuthProvider, ...tools],
+})
+export class GitHubModule {}

package/src/index.ts

@@ -0,0 +1,27 @@
+export * from './github.module';
+export * from './github-oauth.provider';
+export * from './tools/repos/github-list-repos.tool';
+export * from './tools/repos/github-get-repo.tool';
+export * from './tools/repos/github-create-repo.tool';
+export * from './tools/repos/github-list-branches.tool';
+export * from './tools/issues/github-list-issues.tool';
+export * from './tools/issues/github-get-issue.tool';
+export * from './tools/issues/github-create-issue.tool';
+export * from './tools/issues/github-create-issue-comment.tool';
+export * from './tools/pull-requests/github-list-pull-requests.tool';
+export * from './tools/pull-requests/github-get-pull-request.tool';
+export * from './tools/pull-requests/github-create-pull-request.tool';
+export * from './tools/pull-requests/github-merge-pull-request.tool';
+export * from './tools/pull-requests/github-list-pr-reviews.tool';
+export * from './tools/content/github-get-file-content.tool';
+export * from './tools/content/github-create-or-update-file.tool';
+export * from './tools/content/github-list-directory.tool';
+export * from './tools/content/github-get-commit.tool';
+export * from './tools/actions/github-list-workflow-runs.tool';
+export * from './tools/actions/github-trigger-workflow.tool';
+export * from './tools/actions/github-get-workflow-run.tool';
+export * from './tools/search/github-search-code.tool';
+export * from './tools/search/github-search-repos.tool';
+export * from './tools/search/github-search-issues.tool';
+export * from './tools/users/github-get-authenticated-user.tool';
+export * from './tools/users/github-list-user-orgs.tool';

package/src/tools/actions/github-get-workflow-run.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 GitHubGetWorkflowRunArgs = {
+  owner: string;
+  repo: string;
+  runId: number;
+};
+
+@Tool({
+  config: {
+    description:
+      'Gets detailed information about a specific GitHub Actions workflow run. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubGetWorkflowRunTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubGetWorkflowRunTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        runId: z.number(),
+      })
+      .strict(),
+  })
+  args: GitHubGetWorkflowRunArgs;
+
+  async execute(args: GitHubGetWorkflowRunArgs, 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)}/actions/runs/${args.runId}`;
+    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 run = (await response.json()) as {
+      id: number;
+      name: string;
+      status: string;
+      conclusion: string | null;
+      head_branch: string;
+      head_sha: string;
+      event: string;
+      workflow_id: number;
+      run_number: number;
+      run_attempt: number;
+      created_at: string;
+      updated_at: string;
+      run_started_at: string;
+      html_url: string;
+    };
+
+    return {
+      data: {
+        run: {
+          id: run.id,
+          name: run.name,
+          status: run.status,
+          conclusion: run.conclusion,
+          headBranch: run.head_branch,
+          headSha: run.head_sha,
+          event: run.event,
+          workflowId: run.workflow_id,
+          runNumber: run.run_number,
+          runAttempt: run.run_attempt,
+          createdAt: run.created_at,
+          updatedAt: run.updated_at,
+          runStartedAt: run.run_started_at,
+          htmlUrl: run.html_url,
+        },
+      },
+    };
+  }
+}

package/src/tools/actions/github-list-workflow-runs.tool.ts

@@ -0,0 +1,141 @@
+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 GitHubListWorkflowRunsArgs = {
+  owner: string;
+  repo: string;
+  branch?: string;
+  status?: string;
+  perPage?: number;
+  page?: number;
+};
+
+@Tool({
+  config: {
+    description:
+      'Lists workflow runs for a GitHub repository. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubListWorkflowRunsTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubListWorkflowRunsTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        branch: z.string().optional(),
+        status: z
+          .enum([
+            'completed',
+            'action_required',
+            'cancelled',
+            'failure',
+            'neutral',
+            'skipped',
+            'stale',
+            'success',
+            'timed_out',
+            'in_progress',
+            'queued',
+            'requested',
+            'waiting',
+            'pending',
+          ])
+          .optional(),
+        perPage: z.number().default(30),
+        page: z.number().default(1),
+      })
+      .strict(),
+  })
+  args: GitHubListWorkflowRunsArgs;
+
+  async execute(args: GitHubListWorkflowRunsArgs, 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),
+      page: String(args.page ?? 1),
+    });
+
+    if (args.branch) params.set('branch', args.branch);
+    if (args.status) params.set('status', args.status);
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/actions/runs?${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 {
+      total_count: number;
+      workflow_runs: Array<{
+        id: number;
+        name: string;
+        status: string;
+        conclusion: string | null;
+        head_branch: string;
+        head_sha: string;
+        event: string;
+        created_at: string;
+        updated_at: string;
+        html_url: string;
+      }>;
+    };
+
+    const runs = data.workflow_runs.map((run) => ({
+      id: run.id,
+      name: run.name,
+      status: run.status,
+      conclusion: run.conclusion,
+      headBranch: run.head_branch,
+      headSha: run.head_sha,
+      event: run.event,
+      createdAt: run.created_at,
+      updatedAt: run.updated_at,
+      htmlUrl: run.html_url,
+    }));
+
+    return {
+      data: { totalCount: data.total_count, runs },
+    };
+  }
+}

package/src/tools/actions/github-trigger-workflow.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 GitHubTriggerWorkflowArgs = {
+  owner: string;
+  repo: string;
+  workflowId: string;
+  ref: string;
+  inputs?: Record<string, string>;
+};
+
+@Tool({
+  config: {
+    description:
+      'Triggers a GitHub Actions workflow dispatch event. Returns 204 No Content on success. Returns { error: "unauthorized" } if no valid token is available.',
+  },
+})
+export class GitHubTriggerWorkflowTool implements ToolInterface {
+  private readonly logger = new Logger(GitHubTriggerWorkflowTool.name);
+
+  @Inject()
+  private tokenStore: OAuthTokenStore;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        workflowId: z.string(),
+        ref: z.string(),
+        inputs: z.record(z.string(), z.string()).optional(),
+      })
+      .strict(),
+  })
+  args: GitHubTriggerWorkflowArgs;
+
+  async execute(args: GitHubTriggerWorkflowArgs, 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> = {
+      ref: args.ref,
+    };
+
+    if (args.inputs) requestBody.inputs = args.inputs;
+
+    const url = `https://api.github.com/repos/${encodeURIComponent(args.owner)}/${encodeURIComponent(args.repo)}/actions/workflows/${encodeURIComponent(args.workflowId)}/dispatches`;
+    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 && response.status !== 204) {
+      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}`,
+        },
+      };
+    }
+
+    return {
+      data: {
+        triggered: true,
+        message: 'Workflow dispatch event triggered successfully.',
+      },
+    };
+  }
+}