@loopstack/github-oauth-example 0.1.1

package/dist/workflows/github-repos-overview.workflow.yaml

@@ -0,0 +1,249 @@
+title: 'GitHub Repository Overview'
+
+description: |
+  Comprehensive GitHub example that exercises every GitHub tool.
+  Fetches user info, repository details, issues, pull requests, branches,
+  directory contents, workflow runs, and search results for a given repository.
+  If not authenticated, launches the OAuth sub-workflow and retries.
+
+ui:
+  form:
+    properties:
+      owner:
+        title: 'Repository Owner'
+        placeholder: 'octocat'
+      repo:
+        title: 'Repository Name'
+        placeholder: 'Hello-World'
+
+transitions:
+  # Step 1: Fetch authenticated user and orgs
+  - id: fetch_user
+    from: start
+    to: user_fetched
+    call:
+      - tool: gitHubGetAuthenticatedUser
+        id: user_fetch
+        args: {}
+        assign:
+          requiresAuthentication: ${{ result.data.error == "unauthorized" }}
+          user: ${{ result.data.user }}
+
+  # If unauthorized -> launch OAuth
+  - id: auth_required
+    from: user_fetched
+    to: awaiting_auth
+    if: ${{ state.requiresAuthentication }}
+    call:
+      - tool: task
+        id: launchAuth
+        args:
+          workflow: oAuth
+          args:
+            provider: 'github'
+            scopes:
+              - 'repo'
+              - 'read:org'
+              - 'workflow'
+          callback:
+            transition: auth_completed
+
+      - tool: createDocument
+        args:
+          id: authStatus
+          document: linkDocument
+          update:
+            content:
+              icon: 'LockKeyhole'
+              label: 'GitHub authentication required'
+              caption: 'Complete sign-in to continue'
+              href: '/pipelines/{{ runtime.tools.auth_required.launchAuth.data.pipelineId }}'
+              embed: true
+              expanded: true
+
+  # Auth completed -> retry from start
+  - id: auth_completed
+    from: awaiting_auth
+    to: start
+    trigger: manual
+    call:
+      - tool: createDocument
+        args:
+          id: authStatus
+          document: linkDocument
+          update:
+            content:
+              icon: 'ShieldCheck'
+              type: 'success'
+              label: 'GitHub authentication completed'
+              caption: 'You are now authenticated with GitHub.'
+              href: '/pipelines/{{ runtime.transition.payload.pipelineId }}'
+
+  # Step 2: Fetch user orgs
+  - id: fetch_orgs
+    from: user_fetched
+    to: orgs_fetched
+    call:
+      - tool: gitHubListUserOrgs
+        id: orgs_fetch
+        args:
+          perPage: 10
+        assign:
+          orgs: ${{ result.data.orgs }}
+
+  # Step 3: Fetch repo details and branches
+  - id: fetch_repo_details
+    from: orgs_fetched
+    to: repo_fetched
+    call:
+      - tool: gitHubGetRepo
+        id: repo_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+        assign:
+          repo: ${{ result.data.repo }}
+
+      - tool: gitHubListBranches
+        id: branches_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+        assign:
+          branches: ${{ result.data.branches }}
+
+  # Step 4: Fetch issues and PRs
+  - id: fetch_issues_prs
+    from: repo_fetched
+    to: issues_prs_fetched
+    call:
+      - tool: gitHubListIssues
+        id: issues_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+          state: 'open'
+          perPage: 10
+        assign:
+          issues: ${{ result.data.issues }}
+
+      - tool: gitHubListPullRequests
+        id: prs_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+          state: 'open'
+          perPage: 10
+        assign:
+          pullRequests: ${{ result.data.pullRequests }}
+
+  # Step 5: Fetch directory listing and workflow runs
+  - id: fetch_content_actions
+    from: issues_prs_fetched
+    to: content_actions_fetched
+    call:
+      - tool: gitHubListDirectory
+        id: dir_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+        assign:
+          directoryEntries: ${{ result.data.entries }}
+
+      - tool: gitHubListWorkflowRuns
+        id: runs_fetch
+        args:
+          owner: ${{ args.owner }}
+          repo: ${{ args.repo }}
+          perPage: 5
+        assign:
+          workflowRuns: ${{ result.data.runs }}
+
+  # Step 6: Search code in the repo
+  - id: fetch_search
+    from: content_actions_fetched
+    to: search_done
+    call:
+      - tool: gitHubSearchCode
+        id: code_search
+        args:
+          query: ${{ searchQuery() }}
+          perPage: 5
+        assign:
+          searchResults: ${{ result.data.results }}
+
+  # Display all results
+  - id: display_results
+    from: search_done
+    to: end
+    call:
+      - tool: createDocument
+        args:
+          document: markdown
+          update:
+            content:
+              markdown: |
+                ## Authenticated User
+                **{{ state.user.login }}** {{#if state.user.name}}({{ state.user.name }}){{/if}} — {{ state.user.publicRepos }} public repos
+
+                {{#if state.orgs}}
+                ### Organizations
+                {{#each state.orgs}}
+                - **{{ this.login }}** {{#if this.description}}— {{ this.description }}{{/if}}
+                {{/each}}
+                {{/if}}
+
+                ---
+
+                ## Repository: [{{ state.repo.fullName }}]({{ state.repo.htmlUrl }})
+                {{ state.repo.description }}
+
+                | Language | Stars | Forks | Open Issues | Default Branch |
+                |---|---|---|---|---|
+                | {{ state.repo.language }} | {{ state.repo.stars }} | {{ state.repo.forks }} | {{ state.repo.openIssues }} | {{ state.repo.defaultBranch }} |
+
+                ### Branches
+                {{#each state.branches}}
+                - `{{ this.name }}` {{#if this.protected}}(protected){{/if}}
+                {{/each}}
+
+                ---
+
+                ### Open Issues
+                {{#each state.issues}}
+                - [#{{ this.number }}]({{ this.htmlUrl }}) {{ this.title }} — @{{ this.user }}
+                {{/each}}
+                {{#unless state.issues}}
+                No open issues.
+                {{/unless}}
+
+                ### Open Pull Requests
+                {{#each state.pullRequests}}
+                - [#{{ this.number }}]({{ this.htmlUrl }}) {{ this.title }} — @{{ this.user }} {{#if this.draft}}(draft){{/if}}
+                {{/each}}
+                {{#unless state.pullRequests}}
+                No open pull requests.
+                {{/unless}}
+
+                ---
+
+                ### Root Directory
+                {{#each state.directoryEntries}}
+                - {{ this.type }} `{{ this.name }}`
+                {{/each}}
+
+                ### Recent Workflow Runs
+                {{#each state.workflowRuns}}
+                - [{{ this.name }}]({{ this.htmlUrl }}) — {{ this.status }} {{#if this.conclusion}}({{ this.conclusion }}){{/if}}
+                {{/each}}
+                {{#unless state.workflowRuns}}
+                No workflow runs found.
+                {{/unless}}
+
+                ### Code Search Results
+                {{#each state.searchResults}}
+                - `{{ this.path }}` in {{ this.repository }}
+                {{/each}}
+                {{#unless state.searchResults}}
+                No code search results.
+                {{/unless}}

package/dist/workflows/index.d.ts

@@ -0,0 +1,3 @@
+export * from './github-agent.workflow';
+export * from './github-repos-overview.workflow';
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC"}

package/dist/workflows/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./github-agent.workflow"), exports);
+__exportStar(require("./github-repos-overview.workflow"), exports);
+//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,mEAAiD"}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@loopstack/github-oauth-example",
+  "displayName": "GitHub OAuth Example",
+  "description": "An example module demonstrating how to list GitHub repositories and issues with OAuth authentication using the Loopstack automation framework. Shows the sub-workflow pattern for handling OAuth flows.",
+  "keywords": [
+    "example",
+    "github",
+    "loopstack",
+    "oauth"
+  ],
+  "version": "0.1.1",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://github.com/loopstack-ai"
+  },
+  "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/claude-module": "^0.21.1",
+    "@loopstack/common": "^0.24.0",
+    "@loopstack/core": "^0.24.0",
+    "@loopstack/create-chat-message-tool": "^0.20.7",
+    "@loopstack/github-module": "^0.1.0",
+    "@loopstack/oauth-module": "^0.1.6",
+    "@nestjs/common": "^11.1.14",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "jest": {
+    "testEnvironment": "node",
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "testTimeout": 10000,
+    "forceExit": true,
+    "maxWorkers": 1
+  },
+  "loopstack": {
+    "installModes": [
+      "add",
+      "install"
+    ],
+    "modules": [
+      {
+        "path": "src/github-example.module.ts",
+        "className": "GitHubExampleModule"
+      }
+    ],
+    "workflows": [
+      {
+        "path": "src/workflows/github-repos-overview.workflow.ts",
+        "className": "GitHubReposOverviewWorkflow",
+        "propertyName": "gitHubReposOverview"
+      },
+      {
+        "path": "src/workflows/github-agent.workflow.ts",
+        "className": "GitHubAgentWorkflow",
+        "propertyName": "gitHubAgent"
+      }
+    ]
+  }
+}

package/src/github-example.module.ts

@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { ClaudeModule } from '@loopstack/claude-module';
+import { LoopCoreModule } from '@loopstack/core';
+import { CreateChatMessageToolModule } from '@loopstack/create-chat-message-tool';
+import { GitHubModule } from '@loopstack/github-module';
+import { AuthenticateGitHubTask } from './tools';
+import { GitHubAgentWorkflow, GitHubReposOverviewWorkflow } from './workflows';
+
+@Module({
+  imports: [LoopCoreModule, CreateChatMessageToolModule, ClaudeModule, GitHubModule],
+  providers: [AuthenticateGitHubTask, GitHubReposOverviewWorkflow, GitHubAgentWorkflow],
+  exports: [AuthenticateGitHubTask, GitHubReposOverviewWorkflow, GitHubAgentWorkflow],
+})
+export class GitHubExampleModule {}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './github-example.module';
+export * from './tools';
+export * from './workflows';

package/src/tools/authenticate-github-task.tool.ts

@@ -0,0 +1,125 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  InjectDocument,
+  InjectTool,
+  Input,
+  RunContext,
+  Tool,
+  ToolInterface,
+  ToolResult,
+  ToolSideEffects,
+  WorkflowInterface,
+  WorkflowMetadataInterface,
+} from '@loopstack/common';
+import { CreateDocument, LinkDocument, Task } from '@loopstack/core';
+
+const AuthenticateGitHubTaskInputSchema = z
+  .object({
+    scopes: z.array(z.string()).describe('The OAuth scopes to request (e.g. repo, user, workflow, read:org)'),
+  })
+  .strict();
+
+type AuthenticateGitHubTaskInput = z.infer<typeof AuthenticateGitHubTaskInputSchema>;
+
+@Injectable()
+@Tool({
+  config: {
+    description:
+      'Launches GitHub OAuth authentication. Shows the user a sign-in prompt to authorize access to GitHub. ' +
+      'Use this when a GitHub tool returns an "unauthorized" error. ' +
+      'Pass the required OAuth scopes for the GitHub APIs you need access to. ' +
+      'IMPORTANT: When using this tool, it must be the ONLY tool call in your response. Do not combine it with other tool calls.',
+  },
+})
+export class AuthenticateGitHubTask implements ToolInterface<AuthenticateGitHubTaskInput> {
+  private readonly logger = new Logger(AuthenticateGitHubTask.name);
+
+  @InjectTool() private task: Task;
+  @InjectTool() private createDocument: CreateDocument;
+  @InjectDocument() private linkDocument: LinkDocument;
+
+  @Input({ schema: AuthenticateGitHubTaskInputSchema })
+  args: AuthenticateGitHubTaskInput;
+
+  async execute(
+    args: AuthenticateGitHubTaskInput,
+    ctx: RunContext,
+    parent: WorkflowInterface | ToolInterface,
+    metadata: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const taskResult = await this.task.execute(
+      { workflow: 'oAuth', args: { provider: 'github', scopes: args.scopes } },
+      ctx,
+      parent,
+    );
+
+    const effects: ToolSideEffects[] = [];
+
+    const linkResult = await this.createDocument.execute(
+      {
+        document: 'linkDocument',
+        id: 'github_auth_link',
+        validate: 'skip' as const,
+        update: {
+          content: {
+            icon: 'LockKeyhole',
+            label: 'GitHub authentication required',
+            caption: 'Complete sign-in to access GitHub',
+            href: `/pipelines/${String((taskResult.data as Record<string, unknown>).pipelineId)}`,
+            embed: true,
+            expanded: true,
+          },
+        },
+      },
+      ctx,
+      this,
+      metadata,
+    );
+    if (linkResult.effects) {
+      effects.push(...linkResult.effects);
+    }
+
+    return {
+      data: taskResult.data as Record<string, unknown>,
+      effects,
+    };
+  }
+
+  async complete(
+    result: Record<string, unknown>,
+    ctx: RunContext,
+    parent: WorkflowInterface | ToolInterface,
+    metadata: WorkflowMetadataInterface,
+  ): Promise<ToolResult> {
+    const data = result as { pipelineId?: string };
+
+    const effects: ToolSideEffects[] = [];
+
+    const linkResult = await this.createDocument.execute(
+      {
+        document: 'linkDocument',
+        id: 'github_auth_link',
+        validate: 'skip' as const,
+        update: {
+          content: {
+            icon: 'ShieldCheck',
+            label: 'GitHub authentication completed',
+            href: `/pipelines/${data.pipelineId}`,
+          },
+        },
+      },
+      ctx,
+      this,
+      metadata,
+    );
+    if (linkResult.effects) {
+      effects.push(...linkResult.effects);
+    }
+
+    return {
+      data: 'GitHub authentication completed successfully. You can now use GitHub tools.',
+      effects,
+    };
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1 @@
+export * from './authenticate-github-task.tool';