@agent-relay/github-primitive 4.0.9

package/README.md

@@ -0,0 +1,151 @@
+# @agent-relay/github-primitive
+
+GitHub workflow primitive for Agent Relay. It exposes a typed client and a
+workflow integration step that can run through the local `gh` CLI or a cloud
+GitHub proxy.
+
+## Runtime Selection
+
+The primitive supports three runtime modes:
+
+- `auto`: prefer cloud when Nango or relay-cloud credentials are present,
+  otherwise use the local `gh` CLI when available.
+- `local`: use `gh api` from the current machine.
+- `cloud`: use Nango first, then relay-cloud proxy when configured.
+
+```ts
+import { GitHubClient } from '@agent-relay/github-primitive';
+
+const github = await GitHubClient.create({
+  runtime: 'auto',
+});
+
+const repo = await github.getRepo('AgentWorkforce', 'relay');
+console.log(repo.defaultBranch);
+```
+
+## Actions
+
+The client and workflow step support:
+
+- Repositories: `listRepos`, `getRepo`
+- Issues: `listIssues`, `createIssue`, `updateIssue`, `closeIssue`
+- Pull requests: `listPRs`, `getPR`, `createPR`, `updatePR`, `mergePR`
+- Files: `listFiles`, `readFile`, `createFile`, `updateFile`, `deleteFile`
+- Branches and commits: `listBranches`, `createBranch`, `listCommits`, `createCommit`
+- Identity: `getUser`, `listOrganizations`
+
+## Workflow Step
+
+```ts
+import { createGitHubStep } from '@agent-relay/github-primitive/workflow-step';
+
+createGitHubStep({
+  name: 'read-readme',
+  action: 'readFile',
+  repo: 'AgentWorkforce/relay',
+  params: {
+    path: 'README.md',
+  },
+  output: {
+    mode: 'data',
+    format: 'text',
+  },
+});
+```
+
+See `examples/github-step.ts` for a workflow runner example and
+`examples/github-client.ts` for a standalone client example.
+
+## End-to-end PR workflow
+
+`examples/end-to-end-pr-workflow.ts` walks the full PR lifecycle against
+a single runtime:
+
+1. `getRepo` — inspect + log the selected runtime.
+2. `createBranch` off the base branch.
+3. `createFile` — write a marker file on the new branch.
+4. `createPR` — the core integration step cloud workflows migrate to.
+5. `getPR` — round-trip verify.
+6. `updatePR` — edit the PR body without code changes.
+7. `listPRs` — confirm indexability.
+8. (commented) `mergePR` — off by default so the example never merges
+   anything real.
+
+Run against a scratch repo:
+
+```
+GITHUB_REPO=AgentWorkforce/scratch npx tsx \
+  packages/github-primitive/examples/end-to-end-pr-workflow.ts
+```
+
+Runtime selection is automatic:
+
+| Path        | Triggered when                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------- |
+| Local `gh`  | `gh auth status` succeeds and no cloud creds are set                                                  |
+| Nango       | `NANGO_SECRET_KEY` + `NANGO_GITHUB_CONNECTION_ID` + `NANGO_GITHUB_PROVIDER_CONFIG_KEY` present        |
+| relay-cloud | `RELAY_CLOUD_API_URL` + `RELAY_CLOUD_API_TOKEN` + `WORKSPACE_ID` present (fallback when Nango absent) |
+
+## Multi-tenant routing
+
+In cloud, every workspace has its own GitHub App install — one Nango
+connection per tenant. `createGitHubStep` accepts a per-step `config`
+field so a single workflow can route different actions through
+different connections. One workflow, many tenants.
+
+`examples/multi-tenant-pr-workflow.ts` demonstrates this: it opens PRs
+in `AgentWorkforce/cloud` (via the AgentWorkforce app) AND in an
+MSD-owned repo (via MSD's app), from the same workflow definition, by
+varying the `config:` field on each step.
+
+### Cloud adoption: the resolver helper
+
+The primitive stays tenant-unaware — it takes a `GitHubRuntimeConfig`
+and does what it's told. The tenant lookup lives in cloud, in a small
+helper:
+
+```ts
+// cloud/packages/web/lib/github/connection-resolver.ts
+import type { GitHubRuntimeConfig } from '@agent-relay/github-primitive';
+
+export async function githubConfigForRepo(opts: {
+  repo: string; // "owner/repo"
+  workspaceId?: string; // optional — cloud-owned repos default
+}): Promise<GitHubRuntimeConfig> {
+  const connection = await resolveWorkspaceIntegration(opts.workspaceId, 'github', opts.repo);
+
+  return {
+    runtime: 'auto',
+    nango: {
+      connectionId: connection.connectionId,
+      providerConfigKey: connection.providerConfigKey, // 'github-agentworkforce' | 'github-msd' | 'github-nightcto' | ...
+      secretKey: process.env.NANGO_SECRET_KEY,
+    },
+    relayCloud: {
+      apiUrl: process.env.CLOUD_API_URL,
+      accessToken: process.env.CLOUD_API_TOKEN,
+      workspaceId: opts.workspaceId,
+    },
+  };
+}
+```
+
+Workflow authors in cloud then write:
+
+```ts
+createGitHubStep({
+  name: 'open-pr',
+  action: 'createPR',
+  repo: 'AgentWorkforce/cloud',
+  params: { title, head, base, body },
+  config: await githubConfigForRepo({
+    repo: 'AgentWorkforce/cloud',
+    workspaceId: process.env.RELAY_WORKSPACE_ID,
+  }),
+});
+```
+
+One resolver, one call-site shape. Adding a new GitHub App install is a
+`workspace_integrations` row + (optionally) a `NANGO_*` secret — no
+code change in the workflows that create PRs.

package/docs/actions.md

@@ -0,0 +1,49 @@
+# GitHub Primitive Actions
+
+All actions use the same adapter request layer, so local and cloud runtimes have
+the same behavior after runtime selection.
+
+## Repository
+
+- `listRepos`: lists repositories visible to the authenticated user.
+- `getRepo`: fetches a repository by owner and name.
+
+## Issues
+
+- `listIssues`: lists true issues and filters out pull request entries returned
+  by the GitHub issues endpoint.
+- `createIssue`: creates an issue.
+- `updateIssue`: updates title, body, state, assignee, or labels.
+- `closeIssue`: closes an issue with the same PATCH path used by
+  `updateIssue`.
+
+## Pull Requests
+
+- `listPRs`: lists pull requests.
+- `getPR`: fetches one pull request.
+- `createPR`: creates a pull request.
+- `updatePR`: updates title, body, state, base branch, or maintainer edit access.
+- `mergePR`: merges a pull request and then fetches the refreshed pull request.
+
+## Files
+
+- `listFiles`: lists directory contents, or returns a single file as a one-item
+  list.
+- `readFile`: decodes base64 file content from the GitHub contents API.
+- `createFile`: creates a file with a commit message.
+- `updateFile`: updates a file by SHA with a commit message.
+- `deleteFile`: deletes a file by SHA with a commit message.
+
+## Branches And Commits
+
+- `listBranches`: lists repository branches.
+- `createBranch`: creates a branch from `fromBranch` or the repository default
+  branch.
+- `listCommits`: lists commits with optional filters.
+- `createCommit`: creates a Git commit object without moving refs.
+
+## Identity
+
+- `getUser`: fetches the authenticated user, or a public user by username.
+- `listOrganizations`: lists organizations for the authenticated user, or for a
+  public user.

package/examples/end-to-end-pr-workflow.ts

@@ -0,0 +1,286 @@
+/**
+ * End-to-end pull-request workflow using the GitHub primitive.
+ *
+ * Demonstrates the full PR lifecycle from a single workflow definition:
+ *   1. Detect + log which runtime will be used (local gh vs Nango vs
+ *      relay-cloud proxy).
+ *   2. createBranch — branch off the default branch for the change.
+ *   3. createFile — write a timestamped marker file on the new branch.
+ *   4. createPR — open the pull request. This is the core interface the
+ *      cloud workflows need to swap to.
+ *   5. getPR — round-trip verify.
+ *   6. updatePR — add a description edit (shows mutation).
+ *   7. listPRs — confirm it appears in the default filter.
+ *   8. (commented out) mergePR — the last mile. Left off by default so
+ *      running this example does NOT merge anything against real repos.
+ *
+ * The same file runs identically in three environments because the
+ * primitive's runtime selection handles the transport:
+ *
+ *   - LOCAL              gh CLI (needs `gh auth status` to succeed)
+ *   - CLOUD (tenant)     Nango — NANGO_GITHUB_CONNECTION_ID +
+ *                        NANGO_GITHUB_PROVIDER_CONFIG_KEY +
+ *                        NANGO_SECRET_KEY
+ *   - CLOUD (fallback)   relay-cloud proxy — RELAY_CLOUD_API_URL +
+ *                        RELAY_CLOUD_API_TOKEN + WORKSPACE_ID
+ *
+ * Run:
+ *   GITHUB_REPO=AgentWorkforce/scratch npx tsx examples/end-to-end-pr-workflow.ts
+ *
+ * Defaults to AgentWorkforce/scratch (a sandbox repo) so no one
+ * accidentally opens a PR against a real repo. Override via env vars.
+ */
+
+import { WorkflowRunner, type RelayYamlConfig } from '@agent-relay/sdk/workflows';
+
+import { GitHubClient } from '../src/client.js';
+import { GitHubStepExecutor, createGitHubStep } from '../src/workflow-step.js';
+import type { GitHubRuntimeConfig } from '../src/types.js';
+
+const repo = process.env.GITHUB_REPO ?? 'AgentWorkforce/scratch';
+const baseBranch = process.env.GITHUB_BASE_BRANCH ?? 'main';
+const branchName = process.env.GITHUB_BRANCH_OVERRIDE ?? `examples/github-primitive-${Date.now()}`;
+const markerPath = `examples/github-primitive-runs/${Date.now()}.md`;
+
+const githubConfig: GitHubRuntimeConfig = {
+  // `auto` prefers cloud credentials when present, otherwise falls back
+  // to the local `gh` CLI. Override with GITHUB_RUNTIME=local|cloud when
+  // you want to pin a specific path.
+  runtime: (process.env.GITHUB_RUNTIME as GitHubRuntimeConfig['runtime']) ?? 'auto',
+
+  // Cloud path A — Nango. Per-tenant GitHub App installation. Cloud
+  // callers typically resolve this via a connection-resolver helper
+  // that maps { workspaceId, repo } -> { connectionId, providerConfigKey }.
+  nango: {
+    connectionId: process.env.NANGO_GITHUB_CONNECTION_ID,
+    providerConfigKey: process.env.NANGO_GITHUB_PROVIDER_CONFIG_KEY,
+    secretKey: process.env.NANGO_SECRET_KEY,
+  },
+
+  // Cloud path B — relay-cloud GitHub proxy. Used when Nango isn't
+  // wired but a relay-cloud bearer token is available.
+  relayCloud: {
+    apiUrl: process.env.RELAY_CLOUD_API_URL,
+    accessToken: process.env.RELAY_CLOUD_API_TOKEN,
+    workspaceId: process.env.WORKSPACE_ID,
+  },
+};
+
+const githubExecutor = new GitHubStepExecutor(githubConfig);
+
+const config: RelayYamlConfig = {
+  version: '1.0',
+  name: 'end-to-end-pr-workflow',
+  description:
+    'Walk through the full PR lifecycle — branch, commit, open, update, list — using the GitHub primitive.',
+  swarm: { pattern: 'pipeline' },
+  agents: [],
+  workflows: [
+    {
+      name: 'end-to-end-pr-workflow',
+      steps: [
+        // 1. Resolve the default branch — sanity check the connection
+        //    works before we start making mutations.
+        createGitHubStep({
+          name: 'inspect-repo',
+          action: 'getRepo',
+          repo,
+          output: {
+            mode: 'summary',
+            includeRuntime: true,
+            pretty: true,
+          },
+        }),
+
+        // 2. Create the feature branch off the base branch's HEAD.
+        //    Chains {{steps.inspect-repo.output.data.defaultBranch}}
+        //    when no base override is provided — here we keep it
+        //    explicit for readability.
+        createGitHubStep({
+          name: 'create-branch',
+          dependsOn: ['inspect-repo'],
+          action: 'createBranch',
+          repo,
+          params: {
+            branch: branchName,
+            source: baseBranch,
+          },
+          output: { mode: 'data', format: 'json', path: 'ref' },
+        }),
+
+        // 3. Write a marker file on the new branch. createFile handles
+        //    the blob + tree + commit dance for you.
+        createGitHubStep({
+          name: 'write-marker-file',
+          dependsOn: ['create-branch'],
+          action: 'createFile',
+          repo,
+          params: {
+            path: markerPath,
+            branch: branchName,
+            content: [
+              '# GitHub primitive example run',
+              '',
+              `- Runtime chosen: see workflow log for inspect-repo detection`,
+              `- Generated: ${new Date().toISOString()}`,
+              '',
+              'This file is created by',
+              '`packages/github-primitive/examples/end-to-end-pr-workflow.ts`',
+              'to prove the full PR lifecycle works against the configured runtime.',
+            ].join('\n'),
+            message: `examples: github-primitive demo run ${new Date().toISOString()}`,
+          },
+          output: { mode: 'data', format: 'json', path: 'commit.sha' },
+        }),
+
+        // 4. Open the pull request. This is the core step cloud
+        //    workflows need. title/body/head/base mirror the REST API
+        //    shape — no translation work at the call site.
+        createGitHubStep({
+          name: 'open-pr',
+          dependsOn: ['write-marker-file'],
+          action: 'createPR',
+          repo,
+          params: {
+            title: `examples: github-primitive end-to-end demo (${branchName})`,
+            head: branchName,
+            base: baseBranch,
+            body: [
+              '## Summary',
+              '',
+              'Automated PR opened by',
+              '`packages/github-primitive/examples/end-to-end-pr-workflow.ts`',
+              'to exercise the GitHub primitive interface end-to-end.',
+              '',
+              '## Runtime selection',
+              '',
+              'See the workflow log for the `inspect-repo` step — it logs the',
+              'selected runtime (`local`, `nango`, or `relay-cloud`).',
+              '',
+              '## Safe to close',
+              '',
+              'This PR is a demonstration. No one should merge it — close it',
+              'once you have inspected the end-to-end round-trip.',
+            ].join('\n'),
+            draft: true,
+          },
+          output: {
+            mode: 'data',
+            format: 'json',
+            includeRuntime: true,
+            includeMetadata: true,
+            pretty: true,
+          },
+        }),
+
+        // 5. Read the PR back to prove the resolver + runtime actually
+        //    persisted the change, and to surface the PR number for
+        //    downstream steps.
+        createGitHubStep({
+          name: 'verify-pr',
+          dependsOn: ['open-pr'],
+          action: 'getPR',
+          repo,
+          params: {
+            // The output of `open-pr` is the Pulls REST response; we pull
+            // the number off it for subsequent mutation.
+            number: '{{steps.open-pr.output.data.number}}',
+          },
+          output: {
+            mode: 'summary',
+            includeRuntime: true,
+            pretty: true,
+          },
+        }),
+
+        // 6. Update the PR — shows how to use updatePR for edits that
+        //    don't need code changes (body, title, draft state, etc.).
+        createGitHubStep({
+          name: 'edit-pr-body',
+          dependsOn: ['verify-pr'],
+          action: 'updatePR',
+          repo,
+          params: {
+            number: '{{steps.open-pr.output.data.number}}',
+            body: [
+              '## Summary',
+              '',
+              'Automated PR opened by the GitHub primitive end-to-end',
+              'example. This body was updated by the `edit-pr-body` step',
+              'to demonstrate `updatePR` works through the same adapter.',
+              '',
+              '## Safe to close',
+              '',
+              'Demo — close, do not merge.',
+            ].join('\n'),
+          },
+          output: { mode: 'result', format: 'json' },
+        }),
+
+        // 7. List open PRs to prove the new one is indexable.
+        createGitHubStep({
+          name: 'list-open-prs',
+          dependsOn: ['edit-pr-body'],
+          action: 'listPRs',
+          repo,
+          params: {
+            state: 'open',
+            perPage: 10,
+          },
+          output: { mode: 'summary', pretty: true },
+        }),
+
+        // 8. (Commented) The last mile — merge. Intentionally left off:
+        //    running this example against a real repo should not merge
+        //    anything. Uncomment when exercising a disposable scratch
+        //    repo or CI harness.
+        //
+        // createGitHubStep({
+        //   name: 'merge-pr',
+        //   dependsOn: ['list-open-prs'],
+        //   action: 'mergePR',
+        //   repo,
+        //   params: {
+        //     number: '{{steps.open-pr.output.data.number}}',
+        //     mergeMethod: 'squash',
+        //     commitTitle: 'examples: github-primitive demo (squash)',
+        //   },
+        //   output: { mode: 'data', format: 'json' },
+        // }),
+      ],
+    },
+  ],
+  errorHandling: { strategy: 'fail-fast' },
+};
+
+async function main(): Promise<void> {
+  const detection = await GitHubClient.detect(githubConfig);
+
+  console.log('────────────────────────────────────────');
+  console.log(`repo:                 ${repo}`);
+  console.log(`base branch:          ${baseBranch}`);
+  console.log(`feature branch:       ${branchName}`);
+  console.log(`runtime selected:     ${detection.runtime}`);
+  console.log(`detection source:     ${detection.source}`);
+  console.log(`local gh available:   ${detection.local.available}`);
+  console.log(`cloud available:      ${detection.cloud.available}`);
+  if (detection.reason) {
+    console.log(`reason:               ${detection.reason}`);
+  }
+  console.log('────────────────────────────────────────');
+
+  const runner = new WorkflowRunner({
+    cwd: process.cwd(),
+    executor: githubExecutor,
+  });
+
+  const result = await runner.execute(config);
+  console.log(`\nWorkflow completed: ${result.status}`);
+}
+
+if (process.argv[1] === new URL(import.meta.url).pathname) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.stack : error);
+    process.exitCode = 1;
+  });
+}

package/examples/github-client.ts

@@ -0,0 +1,38 @@
+import { GitHubClient } from '../src/client.js';
+import type { GitHubRuntimeConfig } from '../src/types.js';
+
+const [owner = 'AgentWorkforce', repo = 'relay'] = (process.env.GITHUB_REPO || 'AgentWorkforce/relay').split(
+  '/'
+);
+
+const githubConfig: GitHubRuntimeConfig = {
+  runtime: (process.env.GITHUB_RUNTIME as GitHubRuntimeConfig['runtime']) ?? 'auto',
+  nango: {
+    connectionId: process.env.NANGO_GITHUB_CONNECTION_ID,
+    providerConfigKey: process.env.NANGO_GITHUB_PROVIDER_CONFIG_KEY,
+  },
+  relayCloud: {
+    apiUrl: process.env.RELAY_CLOUD_API_URL,
+    accessToken: process.env.RELAY_CLOUD_API_TOKEN,
+    workspaceId: process.env.WORKSPACE_ID,
+  },
+};
+
+async function main(): Promise<void> {
+  const github = await GitHubClient.create(githubConfig);
+  const runtime = await github.getRuntime();
+  const repository = await github.getRepo(owner, repo);
+  const branches = await github.listBranches(owner, repo);
+
+  console.log(`Runtime: ${runtime}`);
+  console.log(`Repository: ${repository.fullName}`);
+  console.log(`Default branch: ${repository.defaultBranch}`);
+  console.log(`Branches: ${branches.map((branch) => branch.name).join(', ')}`);
+}
+
+if (process.argv[1] === new URL(import.meta.url).pathname) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.stack : error);
+    process.exitCode = 1;
+  });
+}

package/examples/github-step.ts

@@ -0,0 +1,105 @@
+import { WorkflowRunner, type RelayYamlConfig } from '@agent-relay/sdk/workflows';
+
+import { GitHubClient } from '../src/client.js';
+import { GitHubStepExecutor, createGitHubStep } from '../src/workflow-step.js';
+import type { GitHubRuntimeConfig } from '../src/types.js';
+
+const repo = process.env.GITHUB_REPO ?? 'AgentWorkforce/relay';
+
+const githubConfig: GitHubRuntimeConfig = {
+  runtime: (process.env.GITHUB_RUNTIME as GitHubRuntimeConfig['runtime']) ?? 'auto',
+  nango: {
+    connectionId: process.env.NANGO_GITHUB_CONNECTION_ID,
+    providerConfigKey: process.env.NANGO_GITHUB_PROVIDER_CONFIG_KEY,
+  },
+  relayCloud: {
+    apiUrl: process.env.RELAY_CLOUD_API_URL,
+    accessToken: process.env.RELAY_CLOUD_API_TOKEN,
+    workspaceId: process.env.WORKSPACE_ID,
+  },
+};
+
+const githubExecutor = new GitHubStepExecutor(githubConfig);
+
+const config: RelayYamlConfig = {
+  version: '1.0',
+  name: 'github-primitive-workflow',
+  description: 'GitHub primitive workflow with runtime auto-detection and chained output.',
+  swarm: {
+    pattern: 'pipeline',
+  },
+  agents: [],
+  workflows: [
+    {
+      name: 'github-primitive-workflow',
+      steps: [
+        createGitHubStep({
+          name: 'inspect-repository',
+          action: 'getRepo',
+          repo,
+          output: {
+            mode: 'summary',
+            includeRuntime: true,
+            pretty: true,
+          },
+        }),
+        createGitHubStep({
+          name: 'list-open-issues',
+          dependsOn: ['inspect-repository'],
+          action: 'listIssues',
+          repo,
+          params: {
+            state: 'open',
+            perPage: 5,
+          },
+          output: {
+            mode: 'summary',
+            includeRuntime: true,
+            pretty: true,
+          },
+        }),
+        createGitHubStep({
+          name: 'read-readme',
+          dependsOn: ['list-open-issues'],
+          action: 'readFile',
+          repo,
+          params: {
+            path: 'README.md',
+          },
+          output: {
+            mode: 'data',
+            format: 'text',
+          },
+        }),
+      ],
+    },
+  ],
+  errorHandling: {
+    strategy: 'fail-fast',
+  },
+};
+
+async function main(): Promise<void> {
+  const detection = await GitHubClient.detect(githubConfig);
+
+  console.log(`GitHub runtime selected: ${detection.runtime}`);
+  console.log(`Detection source: ${detection.source}`);
+  console.log(`Local gh CLI: ${detection.local.available ? 'available' : 'unavailable'}`);
+  console.log(`Cloud GitHub: ${detection.cloud.available ? 'available' : 'unavailable'}`);
+  console.log(detection.reason);
+
+  const runner = new WorkflowRunner({
+    cwd: process.cwd(),
+    executor: githubExecutor,
+  });
+
+  const result = await runner.execute(config);
+  console.log(`GitHub workflow completed: ${result.status}`);
+}
+
+if (process.argv[1] === new URL(import.meta.url).pathname) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.stack : error);
+    process.exitCode = 1;
+  });
+}