@commandable/integration-data 0.4.0 → 0.5.0

package/integrations/github/__tests__/write_handlers.test.ts

@@ -0,0 +1,496 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import { createCredentialStore, createIntegrationNode, createProxy, createToolbox, hasEnv } from '../../__tests__/liveHarness.js'
+
+// LIVE GitHub write tests -- runs once per available credential variant.
+// Required env vars (at least one):
+// - _GITHUB_CLASSIC_PAT    (tests all write tools including create_repo/delete_repo)
+// - _GITHUB_FINE_GRAINED_PAT  (tests write tools; create_repo/delete_repo are excluded for this variant)
+// Plus:
+// - _GITHUB_TEST_OWNER
+// - _GITHUB_TEST_REPO
+
+const env = process.env as Record<string, string | undefined>
+
+interface VariantConfig {
+  key: string
+  token: string
+}
+
+const variants: VariantConfig[] = [
+  { key: 'classic_pat', token: env._GITHUB_CLASSIC_PAT || '' },
+  { key: 'fine_grained_pat', token: env._GITHUB_FINE_GRAINED_PAT || '' },
+].filter(v => v.token.trim().length > 0)
+
+const hasWriteEnv = hasEnv('_GITHUB_TEST_OWNER', '_GITHUB_TEST_REPO')
+const suiteOrSkip = (variants.length > 0 && hasWriteEnv) ? describe : describe.skip
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  { maxAttempts = 3, delayMs = 2000, retryIf = (_e: unknown): boolean => true } = {},
+): Promise<T> {
+  let lastError: unknown
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    }
+    catch (error) {
+      lastError = error
+      if (attempt < maxAttempts && retryIf(error)) {
+        await new Promise(resolve => setTimeout(resolve, delayMs * attempt))
+        continue
+      }
+      break
+    }
+  }
+  throw lastError
+}
+
+suiteOrSkip('github write handlers (live)', () => {
+  for (const variant of variants) {
+    describe(`variant: ${variant.key}`, () => {
+      const ctx = {
+        owner: env._GITHUB_TEST_OWNER,
+        repo: env._GITHUB_TEST_REPO,
+      }
+      let toolbox: ReturnType<typeof createToolbox>
+
+      beforeAll(async () => {
+        const credentialStore = createCredentialStore(async () => ({ token: variant.token }))
+        const proxy = createProxy(credentialStore)
+        const node = createIntegrationNode('github', { credentialVariant: variant.key })
+        toolbox = createToolbox('github', proxy, node, variant.key)
+      }, 30000)
+
+      it('create_issue -> update_issue -> comment_on_issue -> list_issue_comments -> close_issue roundtrip', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+
+        const titleBase = `CmdTest Issue ${Date.now()}`
+
+        const create_issue = toolbox.write('create_issue')
+        const created = await create_issue({ owner: ctx.owner, repo: ctx.repo, title: titleBase, body: 'Initial body from test.' })
+        expect(created?.number).toBeTruthy()
+        const issue_number = created.number
+
+        const update_issue = toolbox.write('update_issue')
+        const updated = await update_issue({ owner: ctx.owner, repo: ctx.repo, issue_number, body: 'Updated body from test.' })
+        expect(updated?.number).toBe(issue_number)
+
+        const comment_on_issue = toolbox.write('comment_on_issue')
+        const comment = await comment_on_issue({ owner: ctx.owner, repo: ctx.repo, issue_number, body: 'A comment from test.' })
+        expect(comment?.id).toBeTruthy()
+
+        const list_issue_comments = toolbox.read('list_issue_comments')
+        const comments = await list_issue_comments({ owner: ctx.owner, repo: ctx.repo, issue_number })
+        expect(Array.isArray(comments)).toBe(true)
+        expect(comments.length).toBeGreaterThan(0)
+
+        const close_issue = toolbox.write('close_issue')
+        const closed = await close_issue({ owner: ctx.owner, repo: ctx.repo, issue_number })
+        expect(closed?.state).toBe('closed')
+      }, 90000)
+
+      it('fork_repo forks a public repo (best effort)', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+        const fork_repo = toolbox.write('fork_repo')
+        try {
+          const result = await fork_repo({ owner: ctx.owner, repo: ctx.repo })
+          // Fork returns the forked repo details
+          expect(result).toBeTruthy()
+        }
+        catch {
+          // May fail if repo is private or fork already exists -- that's ok
+          expect(true).toBe(true)
+        }
+      }, 30000)
+
+      it('create_release creates a draft release (classic_pat only)', async () => {
+        if (!toolbox.hasTool('write', 'create_repo'))
+          return expect(true).toBe(true)
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+        const create_release = toolbox.write('create_release')
+        const tagName = `v0.0.0-test-${Date.now()}`
+        try {
+          const result = await create_release({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            tag_name: tagName,
+            name: `Test Release ${tagName}`,
+            body: 'Draft release created by integration tests.',
+            draft: true,
+          })
+          expect(result?.tag_name).toBe(tagName)
+          expect(result?.draft).toBe(true)
+        }
+        catch {
+          // May fail if insufficient permissions -- that's ok
+          expect(true).toBe(true)
+        }
+      }, 30000)
+
+      it('create_repo -> delete_repo lifecycle (classic_pat only)', async () => {
+        if (!toolbox.hasTool('write', 'create_repo')) {
+          return expect(true).toBe(true)
+        }
+
+        const repoName = `cmdtest-repo-${Date.now()}`
+
+        const create_repo = toolbox.write('create_repo')
+        const created = await create_repo({
+          name: repoName,
+          description: 'Test repo created by integration tests',
+          private: true,
+          auto_init: true,
+        })
+        expect(created?.name).toBe(repoName)
+
+        const createdOwner = created?.owner?.login
+        expect(createdOwner).toBeTruthy()
+        expect(created?.full_name).toBe(`${createdOwner}/${repoName}`)
+
+        await new Promise(resolve => setTimeout(resolve, 3000))
+
+        const delete_repo = toolbox.write('delete_repo')
+        const deleted = await delete_repo({ owner: createdOwner, repo: repoName })
+        expect(deleted?.success).toBe(true)
+        expect(deleted?.status).toBe(204)
+      }, 90000)
+
+      it('create_file: create, overwrite, and verify', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+
+        const timestamp = Date.now()
+        const branchName = `test-create-file-${timestamp}`
+        const filePath = `test-create-${timestamp}.txt`
+
+        const create_branch = toolbox.write('create_branch')
+        const branch = await create_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+        expect(branch?.ref).toBe(`refs/heads/${branchName}`)
+
+        const create_file = toolbox.write('create_file')
+        const created = await create_file({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          branch: branchName,
+          path: filePath,
+          content: `Test content with UTF-8: Hello 世界 🌍\nCreated at ${timestamp}`,
+          message: `Add test file ${timestamp}`,
+        })
+        expect(created?.commit?.sha).toBeTruthy()
+        expect(created?.file?.path).toBe(filePath)
+        expect(created?.file?.action).toBe('created')
+
+        // Overwrite the same file
+        const overwritten = await withRetry(
+          () => create_file({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            branch: branchName,
+            path: filePath,
+            content: `Overwritten content at ${timestamp}`,
+            message: `Overwrite test file ${timestamp}`,
+          }),
+          { maxAttempts: 3, delayMs: 2000 },
+        )
+        expect(overwritten?.commit?.sha).toBeTruthy()
+        expect(overwritten?.file?.action).toBe('overwritten')
+
+        // Verify content -- retry until the Contents API reflects the overwrite
+        const get_file_contents = toolbox.read('get_file_contents')
+        const contents = await withRetry(
+          async () => {
+            const c = await get_file_contents({
+              owner: ctx.owner,
+              repo: ctx.repo,
+              path: filePath,
+              ref: branchName,
+            })
+            if (!c?.content?.includes('Overwritten content'))
+              throw new Error('stale content: overwrite not yet visible')
+            return c
+          },
+          { maxAttempts: 5, delayMs: 1500 },
+        )
+        expect(contents?.content).toContain('Overwritten content')
+
+        // delete_file without SHA (auto-fetches it)
+        const delete_file = toolbox.write('delete_file')
+        const deleted = await delete_file({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          path: filePath,
+          message: `Delete test file ${timestamp}`,
+          branch: branchName,
+        })
+        expect(deleted?.commit?.message).toBe(`Delete test file ${timestamp}`)
+
+        const delete_branch = toolbox.write('delete_branch')
+        await delete_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+      }, 120000)
+
+      it('edit_file: search/replace on a single file', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+
+        const timestamp = Date.now()
+        const branchName = `test-edit-file-${timestamp}`
+        const filePath = `test-edit-${timestamp}.txt`
+
+        const create_branch = toolbox.write('create_branch')
+        await create_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+
+        // Seed a file to edit
+        const create_file = toolbox.write('create_file')
+        await create_file({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          branch: branchName,
+          path: filePath,
+          content: 'line 1: hello world\nline 2: foo bar\nline 3: goodbye world\n',
+          message: `Seed file for edit test ${timestamp}`,
+        })
+
+        // Apply search/replace edits
+        const edit_file = toolbox.write('edit_file')
+        const edited = await withRetry(
+          () => edit_file({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            branch: branchName,
+            path: filePath,
+            edits: [
+              { old_text: 'hello world', new_text: 'hello universe' },
+              { old_text: 'foo bar', new_text: 'baz qux' },
+            ],
+            message: `Edit file ${timestamp}`,
+          }),
+          { maxAttempts: 3, delayMs: 2000 },
+        )
+        expect(edited?.commit?.sha).toBeTruthy()
+        expect(edited?.file?.path).toBe(filePath)
+
+        // Verify edits applied -- retry until the Contents API reflects the new commit
+        const get_file_contents = toolbox.read('get_file_contents')
+        const contents = await withRetry(
+          async () => {
+            const c = await get_file_contents({
+              owner: ctx.owner,
+              repo: ctx.repo,
+              path: filePath,
+              ref: branchName,
+            })
+            if (!c?.content?.includes('hello universe'))
+              throw new Error('stale content: edit not yet visible')
+            return c
+          },
+          { maxAttempts: 5, delayMs: 1500 },
+        )
+        expect(contents?.content).toContain('hello universe')
+        expect(contents?.content).toContain('baz qux')
+        expect(contents?.content).toContain('goodbye world')
+        expect(contents?.content).not.toContain('hello world')
+
+        const delete_branch = toolbox.write('delete_branch')
+        await delete_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+      }, 120000)
+
+      it('edit_files: mixed create, edit, delete in one atomic commit', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+
+        const timestamp = Date.now()
+        const branchName = `test-edit-files-${timestamp}`
+
+        const create_branch = toolbox.write('create_branch')
+        const branch = await create_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+        expect(branch?.ref).toBe(`refs/heads/${branchName}`)
+
+        // Seed initial files via edit_files (create action)
+        const edit_files = toolbox.write('edit_files')
+        const commit1 = await edit_files({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          branch: branchName,
+          message: `Add initial files ${timestamp}`,
+          files: [
+            { path: `multi-test/file1-${timestamp}.txt`, action: 'create', content: 'Content of file 1' },
+            { path: `multi-test/file2-${timestamp}.txt`, action: 'create', content: 'Content of file 2' },
+            { path: `multi-test/file3-${timestamp}.md`, action: 'create', content: '# Test File 3\n\nWith UTF-8: 你好 🚀' },
+          ],
+        })
+        expect(commit1?.commit?.sha).toBeTruthy()
+        expect(commit1?.commit?.message).toBe(`Add initial files ${timestamp}`)
+        expect(commit1?.files?.length).toBe(3)
+
+        // Mixed operations: edit file1, delete file2, create file4
+        const commit2 = await withRetry(
+          () => edit_files({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            branch: branchName,
+            message: `Mixed edit/delete/create ${timestamp}`,
+            files: [
+              {
+                path: `multi-test/file1-${timestamp}.txt`,
+                action: 'edit',
+                edits: [{ old_text: 'Content of file 1', new_text: 'Updated content of file 1' }],
+              },
+              { path: `multi-test/file2-${timestamp}.txt`, action: 'delete' },
+              { path: `multi-test/file4-${timestamp}.txt`, action: 'create', content: 'New file 4' },
+            ],
+          }),
+          {
+            maxAttempts: 3,
+            delayMs: 2000,
+            retryIf: (e: unknown) => String((e as { message?: string })?.message || '').includes('GitRPC::BadObjectState'),
+          },
+        )
+        expect(commit2?.commit?.sha).toBeTruthy()
+        expect(commit2?.files?.length).toBe(3)
+
+        // Verify the edit applied -- retry until the Contents API reflects the new commit
+        const get_file_contents = toolbox.read('get_file_contents')
+        const f1 = await withRetry(
+          async () => {
+            const c = await get_file_contents({
+              owner: ctx.owner,
+              repo: ctx.repo,
+              path: `multi-test/file1-${timestamp}.txt`,
+              ref: branchName,
+            })
+            if (!c?.content?.includes('Updated content of file 1'))
+              throw new Error('stale content: edit not yet visible')
+            return c
+          },
+          { maxAttempts: 5, delayMs: 1500 },
+        )
+        expect(f1?.content).toContain('Updated content of file 1')
+
+        // Verify the new file was created
+        const f4 = await get_file_contents({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          path: `multi-test/file4-${timestamp}.txt`,
+          ref: branchName,
+        })
+        expect(f4?.content).toContain('New file 4')
+
+        // get_commit verifies the commit details
+        const get_commit = toolbox.read('get_commit')
+        const commitDetails = await get_commit({ owner: ctx.owner, repo: ctx.repo, sha: commit2.commit.sha })
+        expect(commitDetails?.sha).toBe(commit2.commit.sha)
+      }, 150000)
+
+      it('full PR workflow: create_branch -> edit_files -> create_pull_request -> update_pull_request -> create_pull_request_review -> merge_pull_request -> delete_branch', async () => {
+        if (!ctx.owner || !ctx.repo)
+          return expect(true).toBe(true)
+
+        const timestamp = Date.now()
+        const branchName = `test-pr-workflow-${timestamp}`
+
+        const create_branch = toolbox.write('create_branch')
+        const branch = await create_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+        expect(branch?.ref).toBe(`refs/heads/${branchName}`)
+
+        const edit_files = toolbox.write('edit_files')
+        const commit = await edit_files({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          branch: branchName,
+          message: `Add feature files ${timestamp}`,
+          files: [
+            { path: `feature-${timestamp}/index.js`, action: 'create', content: 'export default function() { return "Hello"; }' },
+            { path: `feature-${timestamp}/README.md`, action: 'create', content: `# Feature ${timestamp}\n\nThis is a test feature.` },
+          ],
+        })
+        expect(commit?.commit?.sha).toBeTruthy()
+
+        const get_repo = toolbox.read('get_repo')
+        const repoDetails = await get_repo({ owner: ctx.owner, repo: ctx.repo })
+        const defaultBranch = repoDetails?.default_branch || 'main'
+
+        const create_pull_request = toolbox.write('create_pull_request')
+        const pr = await create_pull_request({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          title: `Test PR workflow ${timestamp}`,
+          body: 'This PR was created by integration tests to test the full workflow',
+          head: branchName,
+          base: defaultBranch,
+        })
+        expect(pr?.number).toBeTruthy()
+        const prNumber = pr.number
+
+        // update_pull_request
+        const update_pull_request = toolbox.write('update_pull_request')
+        const updated = await update_pull_request({
+          owner: ctx.owner,
+          repo: ctx.repo,
+          pull_number: prNumber,
+          body: 'Updated description by integration test.',
+        })
+        expect(updated?.number).toBe(prNumber)
+
+        // get_pull_request verifies state
+        const get_pull_request = toolbox.read('get_pull_request')
+        const prDetails = await get_pull_request({ owner: ctx.owner, repo: ctx.repo, pull_number: prNumber })
+        expect(prDetails?.number).toBe(prNumber)
+
+        // list_pull_request_files
+        const list_pull_request_files = toolbox.read('list_pull_request_files')
+        const files = await list_pull_request_files({ owner: ctx.owner, repo: ctx.repo, pull_number: prNumber })
+        expect(Array.isArray(files)).toBe(true)
+
+        // add_labels_to_issue (labels on PR)
+        const add_labels_to_issue = toolbox.write('add_labels_to_issue')
+        try {
+          await add_labels_to_issue({ owner: ctx.owner, repo: ctx.repo, issue_number: prNumber, labels: ['test'] })
+        }
+        catch {
+          // Label might not exist -- that's ok for this test
+        }
+
+        // request_pull_request_reviewers (may fail if requesting from self)
+        const request_pull_request_reviewers = toolbox.write('request_pull_request_reviewers')
+        try {
+          await request_pull_request_reviewers({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            pull_number: prNumber,
+            reviewers: [],
+          })
+        }
+        catch {
+          // May fail if requesting from self or insufficient permissions -- that's ok
+        }
+
+        // create_pull_request_review (comment only -- can't APPROVE own PRs typically)
+        const create_pull_request_review = toolbox.write('create_pull_request_review')
+        try {
+          await create_pull_request_review({
+            owner: ctx.owner,
+            repo: ctx.repo,
+            pull_number: prNumber,
+            event: 'COMMENT',
+            body: 'LGTM from integration test',
+          })
+        }
+        catch {
+          // May fail if author is same as reviewer in some repo configs -- that's ok
+        }
+
+        const merge_pull_request = toolbox.write('merge_pull_request')
+        const merged = await merge_pull_request({ owner: ctx.owner, repo: ctx.repo, pull_number: prNumber, merge_method: 'squash' })
+        expect(merged?.merged).toBe(true)
+
+        // delete_branch after merge
+        const delete_branch = toolbox.write('delete_branch')
+        const deletedBranch = await delete_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
+        expect(deletedBranch?.success).toBe(true)
+      }, 150000)
+    })
+  }
+})

package/integrations/github/credentials.json

@@ -0,0 +1,47 @@
+{
+  "variants": {
+    "classic_pat": {
+      "label": "Classic Personal Access Token",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "Classic PAT",
+            "description": "GitHub classic personal access token. Supports all GitHub API operations including creating and deleting repositories."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      },
+      "healthCheck": { "path": "/user" }
+    },
+    "fine_grained_pat": {
+      "label": "Fine-Grained Personal Access Token",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "token": {
+            "type": "string",
+            "title": "Fine-Grained PAT",
+            "description": "GitHub fine-grained personal access token scoped to specific repositories and permissions."
+          }
+        },
+        "required": ["token"],
+        "additionalProperties": false
+      },
+      "injection": {
+        "headers": {
+          "Authorization": "Bearer {{token}}"
+        }
+      },
+      "healthCheck": { "path": "/user" }
+    }
+  },
+  "default": "classic_pat"
+}

package/integrations/github/credentials_hint.md

@@ -0,0 +1,7 @@
+Create a GitHub personal access token and paste it here.
+
+- Fine-grained PAT: Settings → Developer settings → Personal access tokens → Fine-grained tokens
+- Classic PAT: Settings → Developer settings → Personal access tokens → Tokens (classic)
+
+Minimum scopes depend on the tools you use (repo read/write, issues, pull requests, etc.).
+

package/integrations/github/credentials_hint_classic_pat.md

@@ -0,0 +1,8 @@
+Create a GitHub Classic Personal Access Token:
+
+1. Go to `https://github.com/settings/tokens` → **Tokens (classic)**
+2. Click **Generate new token (classic)**
+3. Select the scopes you need: `repo` (full repo access), `delete_repo` (if you want to delete repos), `read:user` etc.
+4. Copy the token and paste it here.
+
+Classic PATs support all GitHub API operations including creating and deleting repositories.

package/integrations/github/credentials_hint_fine_grained_pat.md

@@ -0,0 +1,9 @@
+Create a GitHub Fine-Grained Personal Access Token:
+
+1. Go to `https://github.com/settings/tokens` → **Fine-grained tokens**
+2. Click **Generate new token**
+3. Set the resource owner and repository access (specific repos or all repos)
+4. Grant the permissions your use case requires (Contents, Issues, Pull Requests, etc.)
+5. Copy the token and paste it here.
+
+Note: Fine-grained PATs do not support user-level operations like creating or deleting repositories. Those tools will not be available with this token type.

package/integrations/github/handlers/add_labels_to_issue.js

@@ -0,0 +1,12 @@
+async (input) => {
+  const body = {
+    labels: input.labels,
+  }
+  
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/issues/${input.issue_number}/labels`, { 
+    method: 'POST', 
+    body 
+  })
+  return await res.json()
+}
+

package/integrations/github/handlers/close_issue.js

@@ -0,0 +1,5 @@
+async (input) => {
+  const body = { state: 'closed' }
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/issues/${input.issue_number}`, { method: 'PATCH', body })
+  return await res.json()
+}

package/integrations/github/handlers/comment_on_issue.js

@@ -0,0 +1,5 @@
+async (input) => {
+  const body = { body: input.body }
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/issues/${input.issue_number}/comments`, { method: 'POST', body })
+  return await res.json()
+}

package/integrations/github/handlers/create_branch.js

@@ -0,0 +1,33 @@
+async (input) => {
+  // First, get the SHA of the branch to create from
+  let fromRef = input.from_branch || 'main'
+  
+  // Try to get the ref, fallback to master if main doesn't exist
+  let refRes
+  try {
+    refRes = await integration.fetch(`/repos/${input.owner}/${input.repo}/git/refs/heads/${fromRef}`)
+  } catch (e) {
+    if (fromRef === 'main') {
+      fromRef = 'master'
+      refRes = await integration.fetch(`/repos/${input.owner}/${input.repo}/git/refs/heads/${fromRef}`)
+    } else {
+      throw e
+    }
+  }
+  
+  const refData = await refRes.json()
+  const sha = refData.object.sha
+  
+  // Create the new branch
+  const body = {
+    ref: `refs/heads/${input.branch}`,
+    sha: sha,
+  }
+  
+  const res = await integration.fetch(`/repos/${input.owner}/${input.repo}/git/refs`, { 
+    method: 'POST', 
+    body 
+  })
+  return await res.json()
+}
+