@commandable/integration-data 0.0.6 → 0.0.7

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

@@ -3,19 +3,19 @@ import { createCredentialStore, createIntegrationNode, createProxy, createToolbo
 
 // LIVE GitHub read tests -- runs once per available credential variant.
 // Required env vars (at least one):
-// - GITHUB_CLASSIC_PAT
-// - GITHUB_FINE_GRAINED_PAT
+// - _GITHUB_CLASSIC_PAT
+// - _GITHUB_FINE_GRAINED_PAT
 
 const env = process.env as Record<string, string | undefined>
 
 interface VariantConfig {
-  key: string
+  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 || '' },
+  { 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 suiteOrSkip = variants.length > 0 ? describe : describe.skip

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

@@ -3,11 +3,11 @@ import { createCredentialStore, createIntegrationNode, createProxy, createToolbo
 
 // 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)
+// - _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
+// - _GITHUB_TEST_OWNER
+// - _GITHUB_TEST_REPO
 
 const env = process.env as Record<string, string | undefined>
 
@@ -17,11 +17,11 @@ interface VariantConfig {
 }
 
 const variants: VariantConfig[] = [
-  { key: 'classic_pat', token: env.GITHUB_CLASSIC_PAT || '' },
-  { key: 'fine_grained_pat', token: env.GITHUB_FINE_GRAINED_PAT || '' },
+  { 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 hasWriteEnv = hasEnv('_GITHUB_TEST_OWNER', '_GITHUB_TEST_REPO')
 const suiteOrSkip = (variants.length > 0 && hasWriteEnv) ? describe : describe.skip
 
 async function withRetry<T>(
@@ -49,8 +49,8 @@ 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,
+        owner: env._GITHUB_TEST_OWNER,
+        repo: env._GITHUB_TEST_REPO,
       }
       let toolbox: ReturnType<typeof createToolbox>
 
@@ -158,97 +158,188 @@ suiteOrSkip('github write handlers (live)', () => {
         expect(deleted?.status).toBe(204)
       }, 90000)
 
-      it('create_or_update_file: single file commit', async () => {
+      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-single-file-${timestamp}`
+        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_or_update_file = toolbox.write('create_or_update_file')
-        const file = await create_or_update_file({
+        const create_file = toolbox.write('create_file')
+        const created = await create_file({
           owner: ctx.owner,
           repo: ctx.repo,
-          path: `test-single-${timestamp}.txt`,
-          message: `Add single test file ${timestamp}`,
-          content: `Test content with UTF-8: Hello 世界 🌍\nCreated at ${timestamp}`,
           branch: branchName,
+          path: filePath,
+          content: `Test content with UTF-8: Hello 世界 🌍\nCreated at ${timestamp}`,
+          message: `Add test file ${timestamp}`,
         })
-        expect(file?.commit?.message).toBe(`Add single test file ${timestamp}`)
-        expect(file?.content?.path).toBe(`test-single-${timestamp}.txt`)
+        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')
 
-        // get_file_contents and delete_file roundtrip
+        // Verify content -- retry until the Contents API reflects the overwrite
         const get_file_contents = toolbox.read('get_file_contents')
-        const contents = await get_file_contents({
-          owner: ctx.owner,
-          repo: ctx.repo,
-          path: `test-single-${timestamp}.txt`,
-          ref: branchName,
-        })
-        expect(contents?.encoding).toBe('utf-8')
-        expect(contents?.content).toContain('Hello')
-        const fileSha = contents?.sha
+        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: `test-single-${timestamp}.txt`,
+          path: filePath,
           message: `Delete test file ${timestamp}`,
-          sha: fileSha,
           branch: branchName,
         })
         expect(deleted?.commit?.message).toBe(`Delete test file ${timestamp}`)
 
-        // delete_branch cleanup
         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)
+        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('create_commit: multiple files in one commit', async () => {
+      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-multi-file-${timestamp}`
+        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}`)
 
-        const create_commit = toolbox.write('create_commit')
-        const commit = await create_commit({
+        // 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 multiple files ${timestamp}`,
+          message: `Add initial files ${timestamp}`,
           files: [
-            { path: `multi-test/file1-${timestamp}.txt`, content: 'Content of file 1' },
-            { path: `multi-test/file2-${timestamp}.txt`, content: 'Content of file 2' },
-            { path: `multi-test/file3-${timestamp}.md`, content: '# Test File 3\n\nWith UTF-8: 你好 🚀' },
+            { 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(commit?.commit?.sha).toBeTruthy()
-        expect(commit?.commit?.message).toBe(`Add multiple files ${timestamp}`)
-        expect(commit?.files?.length).toBe(3)
+        expect(commit1?.commit?.sha).toBeTruthy()
+        expect(commit1?.commit?.message).toBe(`Add initial files ${timestamp}`)
+        expect(commit1?.files?.length).toBe(3)
 
-        // Retry second commit: GitHub's backend sometimes needs a moment to settle
-        // after the first commit before accepting a follow-up on the same branch.
+        // Mixed operations: edit file1, delete file2, create file4
         const commit2 = await withRetry(
-          () => create_commit({
+          () => edit_files({
             owner: ctx.owner,
             repo: ctx.repo,
             branch: branchName,
-            message: `Update and delete files ${timestamp}`,
+            message: `Mixed edit/delete/create ${timestamp}`,
             files: [
-              { path: `multi-test/file1-${timestamp}.txt`, content: 'Updated content of file 1' },
-              { path: `multi-test/file2-${timestamp}.txt` },
-              { path: `multi-test/file4-${timestamp}.txt`, content: 'New file 4' },
+              {
+                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' },
             ],
           }),
           {
@@ -258,15 +349,42 @@ suiteOrSkip('github write handlers (live)', () => {
           },
         )
         expect(commit2?.commit?.sha).toBeTruthy()
-        expect(commit2?.commit?.message).toBe(`Update and delete files ${timestamp}`)
+        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)
-      }, 120000)
+      }, 150000)
 
-      it('full PR workflow: create_branch -> create_commit -> create_pull_request -> update_pull_request -> create_pull_request_review -> merge_pull_request -> delete_branch', async () => {
+      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)
 
@@ -277,15 +395,15 @@ suiteOrSkip('github write handlers (live)', () => {
         const branch = await create_branch({ owner: ctx.owner, repo: ctx.repo, branch: branchName })
         expect(branch?.ref).toBe(`refs/heads/${branchName}`)
 
-        const create_commit = toolbox.write('create_commit')
-        const commit = await create_commit({
+        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`, content: 'export default function() { return "Hello"; }' },
-            { path: `feature-${timestamp}/README.md`, content: `# Feature ${timestamp}\n\nThis is a test feature.` },
+            { 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()

package/integrations/github/handlers/create_file.js

@@ -0,0 +1,46 @@
+async (input) => {
+  const { owner, repo, branch, path, content, message } = input
+
+  // Check if the file already exists to get its SHA for overwrite
+  let existingSha
+  try {
+    const params = new URLSearchParams()
+    params.set('ref', branch)
+    const checkRes = await integration.fetch(`/repos/${owner}/${repo}/contents/${path}?${params.toString()}`)
+    const checkData = await checkRes.json()
+    if (checkData && checkData.sha) {
+      existingSha = checkData.sha
+    }
+  } catch (e) {
+    // 404 means file doesn't exist yet -- that's fine
+  }
+
+  const contentBase64 = btoa(unescape(encodeURIComponent(content)))
+
+  const body = {
+    message: message,
+    content: contentBase64,
+    branch: branch,
+  }
+  if (existingSha) {
+    body.sha = existingSha
+  }
+
+  const res = await integration.fetch(`/repos/${owner}/${repo}/contents/${path}`, {
+    method: 'PUT',
+    body: body,
+  })
+  const result = await res.json()
+
+  return {
+    commit: {
+      sha: result.commit?.sha,
+      message: result.commit?.message,
+      url: result.commit?.html_url,
+    },
+    file: {
+      path: path,
+      action: existingSha ? 'overwritten' : 'created',
+    },
+  }
+}

package/integrations/github/handlers/delete_file.js

@@ -1,5 +1,18 @@
 async (input) => {
-  const body = { message: input.message, sha: input.sha }
+  let sha = input.sha
+  if (!sha) {
+    const params = new URLSearchParams()
+    if (input.branch) params.set('ref', input.branch)
+    const query = params.toString() ? `?${params.toString()}` : ''
+    const fileRes = await integration.fetch(`/repos/${input.owner}/${input.repo}/contents/${input.path}${query}`)
+    const fileData = await fileRes.json()
+    if (!fileData || !fileData.sha) {
+      throw new Error(`File not found: ${input.path}. Cannot delete a file that does not exist.`)
+    }
+    sha = fileData.sha
+  }
+
+  const body = { message: input.message, sha: sha }
   if (input.branch) body.branch = input.branch
   const res = await integration.fetch(
     `/repos/${input.owner}/${input.repo}/contents/${input.path}`,

package/integrations/github/handlers/edit_file.js

@@ -0,0 +1,52 @@
+async (input) => {
+  const { owner, repo, branch, path, edits, message } = input
+
+  const params = new URLSearchParams()
+  params.set('ref', branch)
+  const fileRes = await integration.fetch(`/repos/${owner}/${repo}/contents/${path}?${params.toString()}`)
+  const fileData = await fileRes.json()
+
+  if (!fileData || !fileData.content || !fileData.sha) {
+    throw new Error(`File not found: ${path}. Use get_repo_tree to discover file paths.`)
+  }
+
+  const b64 = fileData.content.replace(/\n/g, '')
+  let content = decodeURIComponent(
+    atob(b64).split('').map(c => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)).join('')
+  )
+
+  for (let i = 0; i < edits.length; i++) {
+    const { old_text, new_text } = edits[i]
+    const idx = content.indexOf(old_text)
+    if (idx === -1) {
+      throw new Error(
+        `Edit ${i + 1}/${edits.length} failed: old_text not found in ${path}. `
+        + 'Ensure the search text matches the file exactly, including whitespace and indentation. '
+        + 'Use get_file_contents to verify the current content.'
+      )
+    }
+    content = content.substring(0, idx) + new_text + content.substring(idx + old_text.length)
+  }
+
+  const contentBase64 = btoa(unescape(encodeURIComponent(content)))
+
+  const res = await integration.fetch(`/repos/${owner}/${repo}/contents/${path}`, {
+    method: 'PUT',
+    body: {
+      message: message,
+      content: contentBase64,
+      sha: fileData.sha,
+      branch: branch,
+    },
+  })
+  const result = await res.json()
+
+  return {
+    commit: {
+      sha: result.commit?.sha,
+      message: result.commit?.message,
+      url: result.commit?.html_url,
+    },
+    file: { path: path },
+  }
+}

package/integrations/github/handlers/edit_files.js

@@ -0,0 +1,107 @@
+async (input) => {
+  const { owner, repo, branch, message, files } = input
+
+  // Helper: decode base64 GitHub content to UTF-8
+  function decodeContent(b64Raw) {
+    const b64 = b64Raw.replace(/\n/g, '')
+    return decodeURIComponent(
+      atob(b64).split('').map(c => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2)).join('')
+    )
+  }
+
+  // Helper: apply search/replace edits to text
+  function applyEdits(text, edits, filePath) {
+    let result = text
+    for (let i = 0; i < edits.length; i++) {
+      const { old_text, new_text } = edits[i]
+      const idx = result.indexOf(old_text)
+      if (idx === -1) {
+        throw new Error(
+          `Edit ${i + 1}/${edits.length} failed on ${filePath}: old_text not found. `
+          + 'Ensure the search text matches exactly, including whitespace and indentation. '
+          + 'Use get_file_contents to verify the current content.'
+        )
+      }
+      result = result.substring(0, idx) + new_text + result.substring(idx + old_text.length)
+    }
+    return result
+  }
+
+  // 1. Get the current commit SHA for the branch
+  const refRes = await integration.fetch(`/repos/${owner}/${repo}/git/refs/heads/${branch}`)
+  const refData = await refRes.json()
+  const currentCommitSha = refData.object.sha
+
+  // 2. Get the current commit to find its tree
+  const commitRes = await integration.fetch(`/repos/${owner}/${repo}/git/commits/${currentCommitSha}`)
+  const commitData = await commitRes.json()
+  const currentTreeSha = commitData.tree.sha
+
+  // 3. Resolve final content for each file
+  const tree = []
+  for (const file of files) {
+    if (file.action === 'delete') {
+      tree.push({ path: file.path, mode: '100644', type: 'blob', sha: null })
+      continue
+    }
+
+    let finalContent
+    if (file.action === 'edit') {
+      if (!file.edits || file.edits.length === 0) {
+        throw new Error(`File ${file.path} has action 'edit' but no edits provided.`)
+      }
+      const params = new URLSearchParams()
+      params.set('ref', branch)
+      const fileRes = await integration.fetch(`/repos/${owner}/${repo}/contents/${file.path}?${params.toString()}`)
+      const fileData = await fileRes.json()
+      if (!fileData || !fileData.content) {
+        throw new Error(`File not found: ${file.path}. Use get_repo_tree to discover file paths.`)
+      }
+      const currentContent = decodeContent(fileData.content)
+      finalContent = applyEdits(currentContent, file.edits, file.path)
+    } else {
+      // action === 'create'
+      if (file.content === undefined || file.content === null) {
+        throw new Error(`File ${file.path} has action 'create' but no content provided.`)
+      }
+      finalContent = file.content
+    }
+
+    // Create blob
+    const blobRes = await integration.fetch(`/repos/${owner}/${repo}/git/blobs`, {
+      method: 'POST',
+      body: { content: finalContent, encoding: 'utf-8' },
+    })
+    const blobData = await blobRes.json()
+    tree.push({ path: file.path, mode: '100644', type: 'blob', sha: blobData.sha })
+  }
+
+  // 4. Create a new tree
+  const treeRes = await integration.fetch(`/repos/${owner}/${repo}/git/trees`, {
+    method: 'POST',
+    body: { base_tree: currentTreeSha, tree: tree },
+  })
+  const treeData = await treeRes.json()
+
+  // 5. Create the commit
+  const newCommitRes = await integration.fetch(`/repos/${owner}/${repo}/git/commits`, {
+    method: 'POST',
+    body: { message: message, tree: treeData.sha, parents: [currentCommitSha] },
+  })
+  const newCommitData = await newCommitRes.json()
+
+  // 6. Update the branch reference
+  await integration.fetch(`/repos/${owner}/${repo}/git/refs/heads/${branch}`, {
+    method: 'PATCH',
+    body: { sha: newCommitData.sha },
+  })
+
+  return {
+    commit: {
+      sha: newCommitData.sha,
+      message: newCommitData.message,
+      url: newCommitData.html_url,
+    },
+    files: files.map(f => ({ path: f.path, action: f.action })),
+  }
+}