@2en/clawly-plugins 1.34.0-beta.1 → 1.34.0-beta.3

package/github.ts

@@ -0,0 +1,212 @@
+/**
+ * GitHub integration via Clawly backend.
+ *
+ * Gateway methods (external RPC):
+ * - github.listRepos     — list accessible repositories
+ * - github.authToken     — get a short-lived installation access token for git operations
+ * - github.getConnectUrl — get OAuth URL to connect a GitHub account
+ *
+ * Agent tools (LLM-callable):
+ * - github_list_repos    — list accessible repositories
+ * - github_auth_token    — get a short-lived token for git clone/pull/fetch
+ * - github_connect       — get OAuth URL to connect a GitHub account
+ */
+
+import type {PluginApi} from './index'
+import type {GatewayCfg, HandlerResult} from './gateway-fetch'
+import {gatewayFetch, toToolResult} from './gateway-fetch'
+
+// ── Handlers ──
+
+async function handleListRepos(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const qs = new URLSearchParams()
+  if (typeof params.page === 'number') qs.set('page', String(params.page))
+  if (typeof params.perPage === 'number') qs.set('per_page', String(params.perPage))
+
+  const query = qs.toString()
+  const res = await gatewayFetch(cfg, `/github/repos${query ? `?${query}` : ''}`)
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleAuthToken(cfg: GatewayCfg): Promise<HandlerResult> {
+  const res = await gatewayFetch(cfg, '/github/clone-token')
+  const data = (await res.json()) as {
+    token?: string
+    expiresAt?: string
+    error?: string
+    message?: string
+  }
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  if (!data.token) return {ok: false, error: {code: 'error', message: 'No token returned'}}
+  return {
+    ok: true,
+    data: {
+      token: data.token,
+      expiresAt: data.expiresAt,
+      usage: `git clone https://x-access-token:<token>@github.com/{owner}/{repo}.git`,
+    },
+  }
+}
+
+async function handleGetConnectUrl(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const res = await gatewayFetch(cfg, '/connections/start', {
+    method: 'POST',
+    body: JSON.stringify({provider: 'github'}),
+  })
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+// ── Registration ──
+
+export function registerGitHub(api: PluginApi, cfg: GatewayCfg) {
+  // Gateway methods (external RPC)
+
+  api.registerGatewayMethod('github.listRepos', async ({params, respond}) => {
+    try {
+      const r = await handleListRepos(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('github.authToken', async ({respond}) => {
+    try {
+      const r = await handleAuthToken(cfg)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('github.getConnectUrl', async ({params, respond}) => {
+    try {
+      const r = await handleGetConnectUrl(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  // Agent tools (LLM-callable)
+
+  api.registerTool({
+    name: 'github_list_repos',
+    description:
+      'List GitHub repositories accessible via the connected GitHub App installation. ' +
+      'Returns repo names, descriptions, languages, and default branches. ' +
+      'If no GitHub account is connected, the result will contain a CONNECTION_REQUIRED error — ' +
+      'use github_connect to get an OAuth URL.',
+    parameters: {
+      type: 'object',
+      properties: {
+        page: {type: 'number', description: 'Page number (default 1)'},
+        perPage: {type: 'number', description: 'Results per page (default 30, max 100)'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleListRepos(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'github_auth_token',
+    description:
+      'Get a short-lived GitHub installation access token (~1 hour) for git operations. ' +
+      'Use the returned token to authenticate git commands, e.g.: ' +
+      'git clone https://x-access-token:<token>@github.com/{owner}/{repo}.git ' +
+      'If no GitHub account is connected, the result will contain a CONNECTION_REQUIRED error — ' +
+      'use github_connect to get an OAuth URL.',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+    async execute() {
+      try {
+        return toToolResult(await handleAuthToken(cfg))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'github_connect',
+    description:
+      'Get an OAuth URL to connect a GitHub account. ' +
+      'Returns an authorizeUrl that the user should open in a browser to authorize access. ' +
+      'Use this when GitHub operations return CONNECTION_REQUIRED.',
+    parameters: {
+      type: 'object',
+      properties: {},
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleGetConnectUrl(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.logger.info(
+    'github: registered gateway methods (github.listRepos, github.authToken, github.getConnectUrl) ' +
+      'and agent tools (github_list_repos, github_auth_token, github_connect)',
+  )
+}

package/index.ts

@@ -51,6 +51,7 @@ import {setupConfig} from './config-setup'
 import {registerCronHistory} from './cron-history'
 import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
+import {registerGitHub} from './github'
 import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
 import {
@@ -99,6 +100,7 @@ export default {
     if (gw.baseUrl && gw.token) {
       registerEmail(api, gw)
       registerCalendar(api, gw)
+      registerGitHub(api, gw)
     }
 
     api.logger.info(`Loaded ${api.id} plugin. (debug-instrumented build)`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.34.0-beta.1",
+  "version": "1.34.0-beta.3",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -33,6 +33,7 @@
     "cron-history.ts",
     "cron-hook.ts",
     "email.ts",
+    "github.ts",
     "gateway-fetch.ts",
     "http",
     "media-understanding.ts",