@bettsnation/paperclip-plugin-github 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @bettsnation/paperclip-plugin-github
+
+Paperclip plugin for bidirectional GitHub Issues sync.
+
+## Inbound (GitHub → Paperclip)
+- GitHub issue created/labeled with trigger label → plugin creates Paperclip issue
+- Verifies `X-Hub-Signature-256` natively (no signing incompatibility)
+- Routes to configured agent (Lead Engineer or Full Stack Developer)
+
+## Outbound (Paperclip → GitHub)
+- Paperclip issue completed → closes linked GitHub issue with comment
+
+## Install
+
+```
+npm install @bettsnation/paperclip-plugin-github
+```
+
+Or: Instance Settings → Plugins → Install Plugin → `@bettsnation/paperclip-plugin-github`
+
+## Configuration
+
+| Setting | Required | Description |
+|---------|----------|-------------|
+| `githubTokenRef` | Yes | Secret ref for GitHub API token |
+| `webhookSecretRef` | Yes | Secret ref for webhook signature verification |
+| `targetCompanyId` | Yes | Paperclip company for new issues |
+| `defaultAgentId` | Yes | Agent to assign new issues to |
+| `triggerLabel` | No | Only sync issues with this label (default: `paperclip`) |
+| `syncClosedBack` | No | Close GitHub issues on completion (default: true) |
+
+## GitHub Webhook Setup
+
+In each repo (or org-level): Settings → Webhooks → Add webhook
+- **Payload URL:** Plugin webhook endpoint from Paperclip
+- **Content type:** `application/json`
+- **Secret:** Same secret stored in Paperclip secret ref
+- **Events:** Select "Issues"
+
+## Label-Based Routing
+
+Only GitHub issues with the configured `triggerLabel` (default: `paperclip`) are synced. This prevents every GitHub issue from flooding Paperclip — only explicitly tagged issues get picked up.
+
+## License
+MIT

package/dist/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+declare const manifest: PaperclipPluginManifestV1;
+export default manifest;

package/dist/manifest.js

@@ -0,0 +1,70 @@
+const manifest = {
+    id: "bettsnation.github",
+    apiVersion: 1,
+    version: "0.1.0",
+    displayName: "GitHub Integration",
+    description: "Bidirectional GitHub Issues sync. Receives GitHub webhooks to create Paperclip issues, syncs status changes back to GitHub.",
+    author: "BettsNation",
+    categories: ["connector"],
+    capabilities: [
+        "events.subscribe",
+        "webhooks.receive",
+        "issues.create",
+        "issues.read",
+        "http.outbound",
+        "secrets.read-ref",
+    ],
+    entrypoints: {
+        worker: "./dist/worker.js",
+    },
+    webhooks: [
+        {
+            endpointKey: "github-events",
+            displayName: "GitHub Webhook",
+            description: "Receives issue and PR events from GitHub repositories",
+        },
+    ],
+    instanceConfigSchema: {
+        type: "object",
+        properties: {
+            githubTokenRef: {
+                type: "string",
+                title: "GitHub Token (Secret Ref)",
+                description: "Personal access token or GitHub App token for API calls",
+            },
+            webhookSecretRef: {
+                type: "string",
+                title: "Webhook Secret (Secret Ref)",
+                description: "Shared secret for verifying GitHub webhook signatures (X-Hub-Signature-256)",
+            },
+            targetCompanyId: {
+                type: "string",
+                title: "Target Company ID",
+                description: "Paperclip company to create issues in",
+            },
+            defaultAgentId: {
+                type: "string",
+                title: "Default Agent ID",
+                description: "Agent to assign new issues to (e.g. Lead Engineer or Full Stack Developer)",
+            },
+            triggerLabel: {
+                type: "string",
+                title: "Trigger Label",
+                description: "Only sync GitHub issues with this label (e.g. 'paperclip')",
+                default: "paperclip",
+            },
+            syncClosedBack: {
+                type: "boolean",
+                title: "Close GitHub issues when Paperclip issues complete",
+                default: true,
+            },
+        },
+        required: [
+            "githubTokenRef",
+            "webhookSecretRef",
+            "targetCompanyId",
+            "defaultAgentId",
+        ],
+    },
+};
+export default manifest;

package/dist/worker.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: import("@paperclipai/plugin-sdk").PaperclipPlugin;
+export default plugin;

package/dist/worker.js

@@ -0,0 +1,145 @@
+import { definePlugin, runWorker, } from "@paperclipai/plugin-sdk";
+import { createHmac, timingSafeEqual } from "crypto";
+async function githubRequest(ctx, config, method, path, body) {
+    const token = await ctx.secrets.resolve(config.githubTokenRef);
+    return ctx.http.fetch(`https://api.github.com${path}`, {
+        method,
+        headers: {
+            Accept: "application/vnd.github.v3+json",
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "User-Agent": "paperclip-plugin-github",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+}
+function verifyGitHubSignature(secret, rawBody, signatureHeader) {
+    const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+    try {
+        return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
+    }
+    catch {
+        return false;
+    }
+}
+let _config = null;
+let _ctx = null;
+const plugin = definePlugin({
+    async setup(ctx) {
+        const config = (await ctx.config.get());
+        _config = config;
+        _ctx = ctx;
+        const triggerLabel = config.triggerLabel ?? "paperclip";
+        // =========================================================
+        // OUTBOUND: Paperclip issue done → close GitHub issue
+        // =========================================================
+        if (config.syncClosedBack !== false) {
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                const changes = payload?.changes;
+                const statusChange = changes?.status;
+                const newStatus = statusChange?.to ?? payload?.status;
+                if (newStatus !== "done")
+                    return;
+                // Check if this issue originated from GitHub (originId format: "github:<owner>/<repo>#<number>")
+                const originId = payload?.originId;
+                if (!originId?.startsWith("github:"))
+                    return;
+                const match = originId.match(/^github:(.+)#(\d+)$/);
+                if (!match)
+                    return;
+                const [, repoFullName, issueNumber] = match;
+                // Close the GitHub issue
+                const response = await githubRequest(ctx, config, "PATCH", `/repos/${repoFullName}/issues/${issueNumber}`, {
+                    state: "closed",
+                    state_reason: "completed",
+                });
+                if (response.ok) {
+                    // Add a comment
+                    await githubRequest(ctx, config, "POST", `/repos/${repoFullName}/issues/${issueNumber}/comments`, {
+                        body: `Resolved by Paperclip agent. Issue: ${payload?.issueTag ?? event.entityId}`,
+                    });
+                    ctx.logger.info(`Closed GitHub issue ${repoFullName}#${issueNumber}`);
+                }
+                else {
+                    ctx.logger.error(`Failed to close GitHub issue: ${response.status}`);
+                }
+            });
+        }
+        ctx.logger.info("GitHub plugin initialized", { triggerLabel });
+    },
+    // =========================================================
+    // INBOUND: GitHub webhook → create Paperclip issue
+    // =========================================================
+    async onWebhook(input) {
+        if (input.endpointKey !== "github-events")
+            return;
+        const ctx = _ctx;
+        const config = _config;
+        // Verify GitHub signature (X-Hub-Signature-256)
+        const signatureHeader = Array.isArray(input.headers["x-hub-signature-256"])
+            ? input.headers["x-hub-signature-256"][0]
+            : input.headers["x-hub-signature-256"];
+        if (!signatureHeader) {
+            ctx.logger.warn("GitHub webhook missing signature header");
+            return;
+        }
+        const secret = await ctx.secrets.resolve(config.webhookSecretRef);
+        if (!verifyGitHubSignature(secret, input.rawBody, signatureHeader)) {
+            ctx.logger.warn("GitHub webhook signature verification failed");
+            return;
+        }
+        // Check event type
+        const eventType = Array.isArray(input.headers["x-github-event"])
+            ? input.headers["x-github-event"][0]
+            : input.headers["x-github-event"];
+        if (eventType !== "issues") {
+            ctx.logger.info(`Ignoring GitHub event type: ${eventType}`);
+            return;
+        }
+        const event = input.parsedBody;
+        // Only process opened/labeled events
+        if (event.action !== "opened" && event.action !== "labeled")
+            return;
+        // Check for trigger label
+        const triggerLabel = config.triggerLabel ?? "paperclip";
+        const hasLabel = event.issue.labels.some((l) => l.name === triggerLabel);
+        if (!hasLabel)
+            return;
+        const repo = event.repository.full_name;
+        const num = event.issue.number;
+        const originId = `github:${repo}#${num}`;
+        // Create Paperclip issue
+        const description = [
+            `## GitHub Issue`,
+            ``,
+            `**Repo:** [${repo}](${event.repository.html_url})`,
+            `**Issue:** [#${num}](${event.issue.html_url})`,
+            `**Author:** ${event.issue.user.login}`,
+            `**Labels:** ${event.issue.labels.map((l) => l.name).join(", ")}`,
+            ``,
+            `### Description`,
+            event.issue.body || "_No description_",
+        ].join("\n");
+        await ctx.issues.create({
+            companyId: config.targetCompanyId,
+            title: `[${repo}#${num}] ${event.issue.title}`,
+            description,
+            status: "todo",
+            priority: "medium",
+            assigneeAgentId: config.defaultAgentId,
+            originKind: "routine_execution",
+            originId,
+        });
+        ctx.logger.info(`Created Paperclip issue for ${repo}#${num}`);
+    },
+    async onHealth() {
+        return { status: "ok" };
+    },
+    async onShutdown() {
+        _config = null;
+        _ctx = null;
+    },
+});
+export default plugin;
+runWorker(plugin, import.meta.url);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bettsnation/paperclip-plugin-github",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Paperclip plugin for bidirectional GitHub Issues sync — webhook intake and status sync",
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@paperclipai/plugin-sdk": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@paperclipai/plugin-sdk": "^2026.403.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "BettsNation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bettsnation/paperclip-plugin-github.git"
+  }
+}