@loopstack/github-oauth-example 0.1.1

package/src/workflows/github-agent.workflow.ts

@@ -0,0 +1,118 @@
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  ClaudeGenerateText,
+  ClaudeMessageDocument,
+  DelegateToolCalls,
+  UpdateToolResult,
+} from '@loopstack/claude-module';
+import {
+  InjectDocument,
+  InjectTool,
+  InjectWorkflow,
+  Runtime,
+  State,
+  Workflow,
+  WorkflowInterface,
+} from '@loopstack/common';
+import { CreateDocument, LinkDocument, Task } from '@loopstack/core';
+import {
+  GitHubCreateIssueCommentTool,
+  GitHubCreateIssueTool,
+  GitHubCreateOrUpdateFileTool,
+  GitHubCreatePullRequestTool,
+  GitHubCreateRepoTool,
+  GitHubGetAuthenticatedUserTool,
+  GitHubGetCommitTool,
+  GitHubGetFileContentTool,
+  GitHubGetIssueTool,
+  GitHubGetPullRequestTool,
+  GitHubGetRepoTool,
+  GitHubGetWorkflowRunTool,
+  GitHubListBranchesTool,
+  GitHubListDirectoryTool,
+  GitHubListIssuesTool,
+  GitHubListPrReviewsTool,
+  GitHubListPullRequestsTool,
+  GitHubListReposTool,
+  GitHubListUserOrgsTool,
+  GitHubListWorkflowRunsTool,
+  GitHubMergePullRequestTool,
+  GitHubSearchCodeTool,
+  GitHubSearchIssuesTool,
+  GitHubSearchReposTool,
+  GitHubTriggerWorkflowTool,
+} from '@loopstack/github-module';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+import { AuthenticateGitHubTask } from '../tools/authenticate-github-task.tool';
+
+@Injectable()
+@Workflow({
+  configFile: __dirname + '/github-agent.workflow.yaml',
+})
+export class GitHubAgentWorkflow implements WorkflowInterface {
+  @InjectTool() createDocument: CreateDocument;
+  @InjectTool() claudeGenerateText: ClaudeGenerateText;
+  @InjectTool() delegateToolCalls: DelegateToolCalls;
+  @InjectTool() updateToolResult: UpdateToolResult;
+  @InjectTool() task: Task;
+  @InjectTool() authenticateGitHub: AuthenticateGitHubTask;
+
+  @InjectDocument() claudeMessageDocument: ClaudeMessageDocument;
+  @InjectDocument() linkDocument: LinkDocument;
+
+  // GitHub Repos tools
+  @InjectTool() gitHubListRepos: GitHubListReposTool;
+  @InjectTool() gitHubGetRepo: GitHubGetRepoTool;
+  @InjectTool() gitHubCreateRepo: GitHubCreateRepoTool;
+  @InjectTool() gitHubListBranches: GitHubListBranchesTool;
+
+  // GitHub Issues tools
+  @InjectTool() gitHubListIssues: GitHubListIssuesTool;
+  @InjectTool() gitHubGetIssue: GitHubGetIssueTool;
+  @InjectTool() gitHubCreateIssue: GitHubCreateIssueTool;
+  @InjectTool() gitHubCreateIssueComment: GitHubCreateIssueCommentTool;
+
+  // GitHub Pull Requests tools
+  @InjectTool() gitHubListPullRequests: GitHubListPullRequestsTool;
+  @InjectTool() gitHubGetPullRequest: GitHubGetPullRequestTool;
+  @InjectTool() gitHubCreatePullRequest: GitHubCreatePullRequestTool;
+  @InjectTool() gitHubMergePullRequest: GitHubMergePullRequestTool;
+  @InjectTool() gitHubListPrReviews: GitHubListPrReviewsTool;
+
+  // GitHub Content / Git Ops tools
+  @InjectTool() gitHubGetFileContent: GitHubGetFileContentTool;
+  @InjectTool() gitHubCreateOrUpdateFile: GitHubCreateOrUpdateFileTool;
+  @InjectTool() gitHubListDirectory: GitHubListDirectoryTool;
+  @InjectTool() gitHubGetCommit: GitHubGetCommitTool;
+
+  // GitHub Actions tools
+  @InjectTool() gitHubListWorkflowRuns: GitHubListWorkflowRunsTool;
+  @InjectTool() gitHubTriggerWorkflow: GitHubTriggerWorkflowTool;
+  @InjectTool() gitHubGetWorkflowRun: GitHubGetWorkflowRunTool;
+
+  // GitHub Search tools
+  @InjectTool() gitHubSearchCode: GitHubSearchCodeTool;
+  @InjectTool() gitHubSearchRepos: GitHubSearchReposTool;
+  @InjectTool() gitHubSearchIssues: GitHubSearchIssuesTool;
+
+  // GitHub Users & Orgs tools
+  @InjectTool() gitHubGetAuthenticatedUser: GitHubGetAuthenticatedUserTool;
+  @InjectTool() gitHubListUserOrgs: GitHubListUserOrgsTool;
+
+  @InjectWorkflow() oAuth: OAuthWorkflow;
+
+  @State({
+    schema: z.object({
+      llmResult: z.any().optional(),
+      delegateResult: z.any().optional(),
+    }),
+  })
+  state: {
+    llmResult?: any;
+    delegateResult?: any;
+  };
+
+  @Runtime()
+  runtime: any;
+}

package/src/workflows/github-agent.workflow.yaml

@@ -0,0 +1,154 @@
+title: 'GitHub Agent'
+
+description: |
+  An interactive chat agent with access to GitHub.
+  Ask it to manage repositories, issues, pull requests, browse code, check CI/CD status,
+  search across GitHub, and more. Handles OAuth authentication automatically when needed —
+  the agent detects unauthorized errors and launches authentication on its own.
+
+ui:
+  actions:
+    - type: custom
+      widget: prompt-input
+      enabledWhen:
+        - waiting_for_user
+      options:
+        transition: user_message
+        label: Send Message
+
+transitions:
+  - id: setup
+    from: start
+    to: waiting_for_user
+    call:
+      - tool: createDocument
+        args:
+          document: claudeMessageDocument
+          update:
+            meta:
+              hidden: true
+            content:
+              role: user
+              content: |
+                You are a helpful GitHub assistant. You have access to the user's
+                GitHub account through the tools provided to you.
+
+                You can help with:
+                - **Repositories**: List repos, get repo details, create repos, list branches
+                - **Issues**: List issues, get issue details, create issues, comment on issues
+                - **Pull Requests**: List PRs, get PR details, create PRs, merge PRs, list reviews
+                - **Code & Content**: Read files, create/update files, browse directories, view commits
+                - **Actions (CI/CD)**: List workflow runs, trigger workflows, check run status
+                - **Search**: Search code, repositories, and issues across GitHub
+                - **Users & Orgs**: Get user profile, list organizations
+
+                When a tool returns `{ error: "unauthorized" }` or `{ error: "401" }`, call the
+                `authenticateGitHub` tool with the required OAuth scopes to let the user sign in.
+                After authentication completes, retry the original request.
+
+                Common scopes: repo, user, workflow, read:org
+
+                IMPORTANT: When using authenticateGitHub, it must be the ONLY tool call in your response.
+
+                Be concise and helpful. Format results clearly using markdown.
+                When showing repository or issue information, include links where available.
+
+  - id: user_message
+    from: waiting_for_user
+    to: ready
+    trigger: manual
+    call:
+      - tool: createDocument
+        args:
+          document: claudeMessageDocument
+          update:
+            content:
+              role: user
+              content: ${{ runtime.transition.payload }}
+
+  - id: llm_turn
+    from: ready
+    to: prompt_executed
+    call:
+      - id: llm_call
+        tool: claudeGenerateText
+        args:
+          system: |
+            You are a helpful GitHub assistant with access to repository, issue, PR, code, actions,
+            and search tools. When a tool returns an unauthorized error, use authenticateGitHub
+            to let the user sign in, then retry. Be concise and format results using markdown.
+          claude:
+            model: claude-sonnet-4-6
+          messagesSearchTag: message
+          tools:
+            - gitHubListRepos
+            - gitHubGetRepo
+            - gitHubCreateRepo
+            - gitHubListBranches
+            - gitHubListIssues
+            - gitHubGetIssue
+            - gitHubCreateIssue
+            - gitHubCreateIssueComment
+            - gitHubListPullRequests
+            - gitHubGetPullRequest
+            - gitHubCreatePullRequest
+            - gitHubMergePullRequest
+            - gitHubListPrReviews
+            - gitHubGetFileContent
+            - gitHubCreateOrUpdateFile
+            - gitHubListDirectory
+            - gitHubGetCommit
+            - gitHubListWorkflowRuns
+            - gitHubTriggerWorkflow
+            - gitHubGetWorkflowRun
+            - gitHubSearchCode
+            - gitHubSearchRepos
+            - gitHubSearchIssues
+            - gitHubGetAuthenticatedUser
+            - gitHubListUserOrgs
+            - authenticateGitHub
+        assign:
+          llmResult: ${{ result.data }}
+
+  - id: execute_tool_calls
+    from: prompt_executed
+    to: awaiting_tools
+    if: ${{ state.llmResult.stop_reason == 'tool_use' }}
+    call:
+      - tool: delegateToolCalls
+        args:
+          message: ${{ state.llmResult }}
+          document: claudeMessageDocument
+          callback:
+            transition: tool_result_received
+        assign:
+          delegateResult: ${{ result.data }}
+
+  - id: tool_result_received
+    from: awaiting_tools
+    to: awaiting_tools
+    trigger: manual
+    call:
+      - tool: updateToolResult
+        args:
+          delegateResult: ${{ state.delegateResult }}
+          completedTool: ${{ runtime.transition.payload }}
+          document: claudeMessageDocument
+        assign:
+          delegateResult: ${{ result.data }}
+
+  - id: all_tools_complete
+    from: awaiting_tools
+    to: ready
+    if: ${{ state.delegateResult.allCompleted }}
+
+  - id: respond
+    from: prompt_executed
+    to: waiting_for_user
+    call:
+      - tool: createDocument
+        args:
+          id: ${{ state.llmResult.id }}
+          document: claudeMessageDocument
+          update:
+            content: ${{ state.llmResult }}

package/src/workflows/github-repos-overview.workflow.ts

@@ -0,0 +1,254 @@
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  Context,
+  DefineHelper,
+  InjectDocument,
+  InjectTool,
+  InjectWorkflow,
+  Input,
+  Runtime,
+  State,
+  Workflow,
+  WorkflowInterface,
+} from '@loopstack/common';
+import { CreateDocument, LinkDocument, MarkdownDocument, Task } from '@loopstack/core';
+import { CreateChatMessage } from '@loopstack/create-chat-message-tool';
+import {
+  GitHubCreateIssueCommentTool,
+  GitHubCreateIssueTool,
+  GitHubCreateOrUpdateFileTool,
+  GitHubCreatePullRequestTool,
+  GitHubCreateRepoTool,
+  GitHubGetAuthenticatedUserTool,
+  GitHubGetCommitTool,
+  GitHubGetFileContentTool,
+  GitHubGetIssueTool,
+  GitHubGetPullRequestTool,
+  GitHubGetRepoTool,
+  GitHubGetWorkflowRunTool,
+  GitHubListBranchesTool,
+  GitHubListDirectoryTool,
+  GitHubListIssuesTool,
+  GitHubListPrReviewsTool,
+  GitHubListPullRequestsTool,
+  GitHubListReposTool,
+  GitHubListUserOrgsTool,
+  GitHubListWorkflowRunsTool,
+  GitHubMergePullRequestTool,
+  GitHubSearchCodeTool,
+  GitHubSearchIssuesTool,
+  GitHubSearchReposTool,
+  GitHubTriggerWorkflowTool,
+} from '@loopstack/github-module';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+
+@Injectable()
+@Workflow({
+  configFile: __dirname + '/github-repos-overview.workflow.yaml',
+})
+export class GitHubReposOverviewWorkflow implements WorkflowInterface {
+  // Core tools
+  @InjectTool() private task: Task;
+  @InjectTool() private createDocument: CreateDocument;
+  @InjectTool() private createChatMessage: CreateChatMessage;
+
+  // GitHub — Users
+  @InjectTool() private gitHubGetAuthenticatedUser: GitHubGetAuthenticatedUserTool;
+  @InjectTool() private gitHubListUserOrgs: GitHubListUserOrgsTool;
+
+  // GitHub — Repos
+  @InjectTool() private gitHubListRepos: GitHubListReposTool;
+  @InjectTool() private gitHubGetRepo: GitHubGetRepoTool;
+  @InjectTool() private gitHubCreateRepo: GitHubCreateRepoTool;
+  @InjectTool() private gitHubListBranches: GitHubListBranchesTool;
+
+  // GitHub — Issues
+  @InjectTool() private gitHubListIssues: GitHubListIssuesTool;
+  @InjectTool() private gitHubGetIssue: GitHubGetIssueTool;
+  @InjectTool() private gitHubCreateIssue: GitHubCreateIssueTool;
+  @InjectTool() private gitHubCreateIssueComment: GitHubCreateIssueCommentTool;
+
+  // GitHub — Pull Requests
+  @InjectTool() private gitHubListPullRequests: GitHubListPullRequestsTool;
+  @InjectTool() private gitHubGetPullRequest: GitHubGetPullRequestTool;
+  @InjectTool() private gitHubCreatePullRequest: GitHubCreatePullRequestTool;
+  @InjectTool() private gitHubMergePullRequest: GitHubMergePullRequestTool;
+  @InjectTool() private gitHubListPrReviews: GitHubListPrReviewsTool;
+
+  // GitHub — Content
+  @InjectTool() private gitHubGetFileContent: GitHubGetFileContentTool;
+  @InjectTool() private gitHubCreateOrUpdateFile: GitHubCreateOrUpdateFileTool;
+  @InjectTool() private gitHubListDirectory: GitHubListDirectoryTool;
+  @InjectTool() private gitHubGetCommit: GitHubGetCommitTool;
+
+  // GitHub — Actions
+  @InjectTool() private gitHubListWorkflowRuns: GitHubListWorkflowRunsTool;
+  @InjectTool() private gitHubTriggerWorkflow: GitHubTriggerWorkflowTool;
+  @InjectTool() private gitHubGetWorkflowRun: GitHubGetWorkflowRunTool;
+
+  // GitHub — Search
+  @InjectTool() private gitHubSearchCode: GitHubSearchCodeTool;
+  @InjectTool() private gitHubSearchRepos: GitHubSearchReposTool;
+  @InjectTool() private gitHubSearchIssues: GitHubSearchIssuesTool;
+
+  // Documents
+  @InjectDocument() private linkDocument: LinkDocument;
+  @InjectDocument() private markdown: MarkdownDocument;
+
+  @InjectWorkflow() oAuth: OAuthWorkflow;
+
+  @Input({
+    schema: z
+      .object({
+        owner: z.string().default('octocat'),
+        repo: z.string().default('Hello-World'),
+      })
+      .strict(),
+  })
+  args: {
+    owner: string;
+    repo: string;
+  };
+
+  @Context()
+  context: any;
+
+  @Runtime()
+  runtime: any;
+
+  @State({
+    schema: z
+      .object({
+        requiresAuthentication: z.boolean().optional(),
+        user: z
+          .object({
+            login: z.string(),
+            name: z.string().nullable(),
+            htmlUrl: z.string(),
+            publicRepos: z.number(),
+          })
+          .optional(),
+        orgs: z
+          .array(
+            z.object({
+              login: z.string(),
+              description: z.string().nullable(),
+            }),
+          )
+          .optional(),
+        repo: z
+          .object({
+            fullName: z.string(),
+            description: z.string().nullable(),
+            language: z.string().nullable(),
+            stars: z.number(),
+            forks: z.number(),
+            openIssues: z.number(),
+            defaultBranch: z.string(),
+            htmlUrl: z.string(),
+          })
+          .optional(),
+        branches: z
+          .array(
+            z.object({
+              name: z.string(),
+              protected: z.boolean(),
+            }),
+          )
+          .optional(),
+        issues: z
+          .array(
+            z.object({
+              number: z.number(),
+              title: z.string(),
+              state: z.string(),
+              user: z.string(),
+              htmlUrl: z.string(),
+            }),
+          )
+          .optional(),
+        pullRequests: z
+          .array(
+            z.object({
+              number: z.number(),
+              title: z.string(),
+              state: z.string(),
+              user: z.string(),
+              draft: z.boolean(),
+              htmlUrl: z.string(),
+            }),
+          )
+          .optional(),
+        directoryEntries: z
+          .array(
+            z.object({
+              name: z.string(),
+              type: z.string(),
+              path: z.string(),
+            }),
+          )
+          .optional(),
+        workflowRuns: z
+          .array(
+            z.object({
+              id: z.number(),
+              name: z.string(),
+              status: z.string(),
+              conclusion: z.string().nullable(),
+              htmlUrl: z.string(),
+            }),
+          )
+          .optional(),
+        searchResults: z
+          .array(
+            z.object({
+              name: z.string(),
+              path: z.string(),
+              repository: z.string(),
+            }),
+          )
+          .optional(),
+      })
+      .strict(),
+  })
+  state: {
+    requiresAuthentication?: boolean;
+    user?: { login: string; name: string | null; htmlUrl: string; publicRepos: number };
+    orgs?: Array<{ login: string; description: string | null }>;
+    repo?: {
+      fullName: string;
+      description: string | null;
+      language: string | null;
+      stars: number;
+      forks: number;
+      openIssues: number;
+      defaultBranch: string;
+      htmlUrl: string;
+    };
+    branches?: Array<{ name: string; protected: boolean }>;
+    issues?: Array<{ number: number; title: string; state: string; user: string; htmlUrl: string }>;
+    pullRequests?: Array<{
+      number: number;
+      title: string;
+      state: string;
+      user: string;
+      draft: boolean;
+      htmlUrl: string;
+    }>;
+    directoryEntries?: Array<{ name: string; type: string; path: string }>;
+    workflowRuns?: Array<{
+      id: number;
+      name: string;
+      status: string;
+      conclusion: string | null;
+      htmlUrl: string;
+    }>;
+    searchResults?: Array<{ name: string; path: string; repository: string }>;
+  };
+
+  @DefineHelper()
+  searchQuery() {
+    return `repo:${this.args.owner}/${this.args.repo}`;
+  }
+}