@paperclipai_dld/plugin-github 2026.319.0-canary.4

package/src/constants.ts

@@ -0,0 +1,48 @@
+export const PLUGIN_ID = "paperclip-github";
+export const PLUGIN_VERSION = "0.1.0";
+
+export const WEBHOOK_KEYS = {
+  github: "github-events",
+} as const;
+
+export const SUPPORTED_GITHUB_EVENTS = [
+  "workflow_run",
+  "check_run",
+  "issues",
+] as const;
+
+export type SupportedGitHubEvent = (typeof SUPPORTED_GITHUB_EVENTS)[number];
+
+export const TOOL_NAMES = {
+  searchIssues: "github_search_issues",
+  linkIssue: "github_link_issue",
+  unlinkIssue: "github_unlink_issue",
+} as const;
+
+export const JOB_KEYS = {
+  syncLinkedIssues: "sync-linked-issues",
+} as const;
+
+export const DEFAULT_CONFIG = {
+  webhookSecret: "",
+  companyId: "",
+  goalId: "",
+  defaultAssigneeAgentId: "",
+  defaultRepo: "",
+  githubTokenRef: "",
+  syncDirection: "bidirectional" as const,
+  syncComments: false,
+  skipSignatureVerification: false,
+} as const;
+
+export type PluginConfig = {
+  webhookSecret?: string;
+  companyId?: string;
+  goalId?: string;
+  defaultAssigneeAgentId?: string;
+  defaultRepo?: string;
+  githubTokenRef?: string;
+  syncDirection?: "bidirectional" | "github-to-paperclip" | "paperclip-to-github";
+  syncComments?: boolean;
+  skipSignatureVerification?: boolean;
+};

package/src/github-types.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal type definitions for the GitHub webhook payloads we care about.
+ * Only the fields we actually read are typed; the rest passes through as `unknown`.
+ */
+
+export interface GitHubWorkflowRunEvent {
+  action: "completed" | "requested" | "in_progress" | string;
+  workflow_run: {
+    id: number;
+    name: string;
+    head_branch: string;
+    head_sha: string;
+    status: string;
+    conclusion: "success" | "failure" | "cancelled" | "timed_out" | "action_required" | string | null;
+    html_url: string;
+    run_number: number;
+    run_attempt: number;
+    actor: { login: string } | null;
+    head_commit: {
+      id: string;
+      message: string;
+      author: { name: string; email: string } | null;
+    } | null;
+    pull_requests: Array<{
+      number: number;
+      head: { ref: string; sha: string };
+      base: { ref: string };
+    }>;
+    repository?: { full_name: string; html_url: string };
+  };
+  repository: { full_name: string; html_url: string };
+}
+
+export interface GitHubCheckRunEvent {
+  action: "completed" | "created" | "rerequested" | "requested_action" | string;
+  check_run: {
+    id: number;
+    name: string;
+    status: string;
+    conclusion: "success" | "failure" | "cancelled" | "timed_out" | "action_required" | "skipped" | string | null;
+    html_url: string;
+    head_sha: string;
+    output: {
+      title: string | null;
+      summary: string | null;
+    };
+    check_suite: {
+      id: number;
+      head_branch: string;
+      pull_requests: Array<{
+        number: number;
+        head: { ref: string; sha: string };
+        base: { ref: string };
+      }>;
+    } | null;
+    app: { slug: string; name: string } | null;
+  };
+  repository: { full_name: string; html_url: string };
+}
+
+export type GitHubWebhookPayload = GitHubWorkflowRunEvent | GitHubCheckRunEvent;

package/src/github.ts

@@ -0,0 +1,152 @@
+/**
+ * GitHub REST API client. Uses the plugin SDK's http.fetch for outbound calls
+ * so all requests go through the capability-gated host proxy.
+ */
+
+const GITHUB_API = "https://api.github.com";
+
+interface GitHubFetch {
+  (url: string, init?: RequestInit): Promise<Response>;
+}
+
+export interface GitHubIssue {
+  number: number;
+  title: string;
+  body: string | null;
+  state: "open" | "closed";
+  html_url: string;
+  labels: Array<{ name: string; color: string }>;
+  assignees: Array<{ login: string }>;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+}
+
+export interface GitHubComment {
+  id: number;
+  body: string;
+  user: { login: string };
+  created_at: string;
+  html_url: string;
+}
+
+export interface GitHubSearchResult {
+  total_count: number;
+  items: GitHubIssue[];
+}
+
+function headers(token: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+}
+
+export async function searchIssues(
+  fetch: GitHubFetch,
+  token: string,
+  repo: string,
+  query: string,
+): Promise<GitHubSearchResult> {
+  const q = encodeURIComponent(`repo:${repo} is:issue ${query}`);
+  const res = await fetch(`${GITHUB_API}/search/issues?q=${q}&per_page=10`, {
+    headers: headers(token),
+  });
+  if (!res.ok) throw new Error(`GitHub search failed: ${res.status} ${res.statusText}`);
+  return res.json() as Promise<GitHubSearchResult>;
+}
+
+export async function getIssue(
+  fetch: GitHubFetch,
+  token: string,
+  owner: string,
+  repo: string,
+  number: number,
+): Promise<GitHubIssue> {
+  const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+    headers: headers(token),
+  });
+  if (!res.ok) throw new Error(`GitHub get issue failed: ${res.status} ${res.statusText}`);
+  return res.json() as Promise<GitHubIssue>;
+}
+
+export async function updateIssueState(
+  fetch: GitHubFetch,
+  token: string,
+  owner: string,
+  repo: string,
+  number: number,
+  state: "open" | "closed",
+): Promise<GitHubIssue> {
+  const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+    method: "PATCH",
+    headers: { ...headers(token), "Content-Type": "application/json" },
+    body: JSON.stringify({ state }),
+  });
+  if (!res.ok) throw new Error(`GitHub update issue failed: ${res.status} ${res.statusText}`);
+  return res.json() as Promise<GitHubIssue>;
+}
+
+export async function listComments(
+  fetch: GitHubFetch,
+  token: string,
+  owner: string,
+  repo: string,
+  number: number,
+  since?: string,
+): Promise<GitHubComment[]> {
+  const params = since ? `?since=${encodeURIComponent(since)}` : "";
+  const res = await fetch(
+    `${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/comments${params}`,
+    { headers: headers(token) },
+  );
+  if (!res.ok) throw new Error(`GitHub list comments failed: ${res.status} ${res.statusText}`);
+  return res.json() as Promise<GitHubComment[]>;
+}
+
+export async function createComment(
+  fetch: GitHubFetch,
+  token: string,
+  owner: string,
+  repo: string,
+  number: number,
+  body: string,
+): Promise<GitHubComment> {
+  const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/comments`, {
+    method: "POST",
+    headers: { ...headers(token), "Content-Type": "application/json" },
+    body: JSON.stringify({ body }),
+  });
+  if (!res.ok) throw new Error(`GitHub create comment failed: ${res.status} ${res.statusText}`);
+  return res.json() as Promise<GitHubComment>;
+}
+
+/**
+ * Parse a GitHub issue reference from various formats:
+ * - https://github.com/owner/repo/issues/123
+ * - owner/repo#123
+ * - #123 (requires default repo)
+ */
+export function parseGitHubIssueRef(
+  ref: string,
+  defaultRepo?: string,
+): { owner: string; repo: string; number: number } | null {
+  const urlMatch = ref.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+  if (urlMatch) {
+    return { owner: urlMatch[1], repo: urlMatch[2], number: parseInt(urlMatch[3], 10) };
+  }
+
+  const refMatch = ref.match(/^([^/]+)\/([^#]+)#(\d+)$/);
+  if (refMatch) {
+    return { owner: refMatch[1], repo: refMatch[2], number: parseInt(refMatch[3], 10) };
+  }
+
+  const numMatch = ref.match(/^#?(\d+)$/);
+  if (numMatch && defaultRepo) {
+    const [owner, repo] = defaultRepo.split("/");
+    if (owner && repo) return { owner, repo, number: parseInt(numMatch[1], 10) };
+  }
+
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { default as manifest } from "./manifest.js";
+export * from "./constants.js";
+export * from "./verify-signature.js";
+export type * from "./github-types.js";
+export * as sync from "./sync.js";
+export * as githubApi from "./github.js";

package/src/manifest.ts

@@ -0,0 +1,105 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai_dld/plugin-sdk";
+import { DEFAULT_CONFIG, PLUGIN_ID, PLUGIN_VERSION, WEBHOOK_KEYS } from "./constants.js";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "GitHub",
+  description:
+    "GitHub integration for Paperclip. Phase 1: receives GitHub Actions webhook events (workflow_run, check_run) and creates Paperclip issues on CI failures. Phase 2: bidirectional issue sync, status bridging, and agent tools for searching and linking GitHub issues.",
+  author: "Paperclip",
+  categories: ["connector", "automation"],
+  capabilities: [
+    "webhooks.receive",
+    "issues.read",
+    "issues.create",
+    "issues.update",
+    "issue.comments.read",
+    "issue.comments.create",
+    "agents.read",
+    "agents.invoke",
+    "plugin.state.read",
+    "plugin.state.write",
+    "http.outbound",
+    "secrets.read-ref",
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+  },
+  instanceConfigSchema: {
+    type: "object",
+    properties: {
+      webhookSecret: {
+        type: "string",
+        title: "GitHub Webhook Secret",
+        description:
+          "Shared secret for HMAC-SHA256 signature verification of incoming GitHub webhooks.",
+        default: DEFAULT_CONFIG.webhookSecret,
+      },
+      companyId: {
+        type: "string",
+        title: "Company ID",
+        description: "Paperclip company ID where failure issues are created.",
+        default: DEFAULT_CONFIG.companyId,
+      },
+      goalId: {
+        type: "string",
+        title: "Goal ID",
+        description: "Goal to associate CI failure issues with.",
+        default: DEFAULT_CONFIG.goalId,
+      },
+      defaultAssigneeAgentId: {
+        type: "string",
+        title: "Default Assignee Agent ID",
+        description:
+          "Agent to assign CI failure issues to when the committing agent cannot be determined.",
+        default: DEFAULT_CONFIG.defaultAssigneeAgentId,
+      },
+      defaultRepo: {
+        type: "string",
+        title: "Default Repository",
+        description:
+          "Default GitHub repository in owner/repo format for agent tools and issue references.",
+        default: DEFAULT_CONFIG.defaultRepo,
+      },
+      githubTokenRef: {
+        type: "string",
+        title: "GitHub Token Secret Ref",
+        description:
+          "Paperclip secret reference name (or ID) for a GitHub Personal Access Token with repo scope. Required for GitHub API calls (search, sync, agent tools).",
+        default: DEFAULT_CONFIG.githubTokenRef,
+      },
+      syncDirection: {
+        type: "string",
+        title: "Sync Direction",
+        enum: ["bidirectional", "github-to-paperclip", "paperclip-to-github"],
+        description:
+          "Direction of issue state synchronisation when a GitHub link is active.",
+        default: DEFAULT_CONFIG.syncDirection,
+      },
+      syncComments: {
+        type: "boolean",
+        title: "Sync Comments",
+        description: "When enabled, new GitHub comments are mirrored to linked Paperclip issues.",
+        default: DEFAULT_CONFIG.syncComments,
+      },
+      skipSignatureVerification: {
+        type: "boolean",
+        title: "Skip Signature Verification",
+        description: "Development only — skip GitHub webhook HMAC verification.",
+        default: DEFAULT_CONFIG.skipSignatureVerification,
+      },
+    },
+  },
+  webhooks: [
+    {
+      endpointKey: WEBHOOK_KEYS.github,
+      displayName: "GitHub Events",
+      description:
+        "Receives workflow_run and check_run events from GitHub. Configure your GitHub repo webhook to POST to this endpoint.",
+    },
+  ],
+};
+
+export default manifest;

package/src/sync.ts

@@ -0,0 +1,193 @@
+/**
+ * Sync logic between GitHub Issues and Paperclip issues.
+ * Manages link state in plugin state storage and handles
+ * bidirectional status + comment syncing.
+ *
+ * SDK fix applied: removed `scopeId: "default"` from all `{ scopeKind: "instance" }` state
+ * calls — `scopeId` must be omitted for instance-scoped keys per current SDK contract.
+ */
+
+import type { PluginContext } from "@paperclipai_dld/plugin-sdk";
+import * as github from "./github.js";
+
+const LINK_PREFIX = "link:";
+const GH_PREFIX = "gh:";
+
+export interface IssueLink {
+  paperclipIssueId: string;
+  paperclipCompanyId: string;
+  ghOwner: string;
+  ghRepo: string;
+  ghNumber: number;
+  ghHtmlUrl: string;
+  syncDirection: "bidirectional" | "github-to-paperclip" | "paperclip-to-github";
+  lastSyncAt: string;
+  lastGhState: "open" | "closed";
+  lastCommentSyncAt: string | null;
+}
+
+function linkStateKey(paperclipIssueId: string): string {
+  return `${LINK_PREFIX}${paperclipIssueId}`;
+}
+
+function ghStateKey(owner: string, repo: string, number: number): string {
+  return `${GH_PREFIX}${owner}/${repo}#${number}`;
+}
+
+export async function getLink(
+  ctx: PluginContext,
+  paperclipIssueId: string,
+): Promise<IssueLink | null> {
+  const raw = await ctx.state.get({
+    scopeKind: "instance",
+    stateKey: linkStateKey(paperclipIssueId),
+  });
+  if (!raw) return null;
+  return JSON.parse(String(raw)) as IssueLink;
+}
+
+export async function getLinkByGitHub(
+  ctx: PluginContext,
+  owner: string,
+  repo: string,
+  number: number,
+): Promise<IssueLink | null> {
+  const raw = await ctx.state.get({
+    scopeKind: "instance",
+    stateKey: ghStateKey(owner, repo, number),
+  });
+  if (!raw) return null;
+  const paperclipIssueId = String(raw);
+  return getLink(ctx, paperclipIssueId);
+}
+
+export async function createLink(
+  ctx: PluginContext,
+  params: {
+    paperclipIssueId: string;
+    paperclipCompanyId: string;
+    ghOwner: string;
+    ghRepo: string;
+    ghNumber: number;
+    ghHtmlUrl: string;
+    ghState: "open" | "closed";
+    syncDirection: IssueLink["syncDirection"];
+  },
+): Promise<IssueLink> {
+  const link: IssueLink = {
+    paperclipIssueId: params.paperclipIssueId,
+    paperclipCompanyId: params.paperclipCompanyId,
+    ghOwner: params.ghOwner,
+    ghRepo: params.ghRepo,
+    ghNumber: params.ghNumber,
+    ghHtmlUrl: params.ghHtmlUrl,
+    syncDirection: params.syncDirection,
+    lastSyncAt: new Date().toISOString(),
+    lastGhState: params.ghState,
+    lastCommentSyncAt: null,
+  };
+
+  await ctx.state.set(
+    { scopeKind: "instance", stateKey: linkStateKey(params.paperclipIssueId) },
+    JSON.stringify(link),
+  );
+
+  await ctx.state.set(
+    { scopeKind: "instance", stateKey: ghStateKey(params.ghOwner, params.ghRepo, params.ghNumber) },
+    params.paperclipIssueId,
+  );
+
+  return link;
+}
+
+export async function updateLink(
+  ctx: PluginContext,
+  paperclipIssueId: string,
+  patch: Partial<Pick<IssueLink, "lastSyncAt" | "lastGhState" | "lastCommentSyncAt" | "syncDirection">>,
+): Promise<IssueLink | null> {
+  const existing = await getLink(ctx, paperclipIssueId);
+  if (!existing) return null;
+
+  const updated: IssueLink = { ...existing, ...patch };
+
+  await ctx.state.set(
+    { scopeKind: "instance", stateKey: linkStateKey(paperclipIssueId) },
+    JSON.stringify(updated),
+  );
+
+  return updated;
+}
+
+export async function deleteLink(
+  ctx: PluginContext,
+  paperclipIssueId: string,
+): Promise<void> {
+  const existing = await getLink(ctx, paperclipIssueId);
+  if (!existing) return;
+
+  await ctx.state.delete({
+    scopeKind: "instance",
+    stateKey: linkStateKey(paperclipIssueId),
+  });
+
+  await ctx.state.delete({
+    scopeKind: "instance",
+    stateKey: ghStateKey(existing.ghOwner, existing.ghRepo, existing.ghNumber),
+  });
+}
+
+/**
+ * Sync a GitHub issue state change to the linked Paperclip issue.
+ */
+export async function syncGitHubStateToPaperclip(
+  ctx: PluginContext,
+  link: IssueLink,
+  ghState: "open" | "closed",
+): Promise<void> {
+  if (link.syncDirection === "paperclip-to-github") return;
+  if (link.lastGhState === ghState) return;
+
+  const paperclipStatus = ghState === "closed" ? "done" : "in_progress";
+  await ctx.issues.update(
+    link.paperclipIssueId,
+    { status: paperclipStatus },
+    link.paperclipCompanyId,
+  );
+
+  await updateLink(ctx, link.paperclipIssueId, {
+    lastSyncAt: new Date().toISOString(),
+    lastGhState: ghState,
+  });
+}
+
+/**
+ * Sync new GitHub comments to the linked Paperclip issue.
+ */
+export async function syncGitHubCommentsToPaperclip(
+  ctx: PluginContext,
+  link: IssueLink,
+  fetch: PluginContext["http"]["fetch"],
+  token: string,
+): Promise<void> {
+  if (link.syncDirection === "paperclip-to-github") return;
+
+  const comments = await github.listComments(
+    fetch,
+    token,
+    link.ghOwner,
+    link.ghRepo,
+    link.ghNumber,
+    link.lastCommentSyncAt ?? undefined,
+  );
+
+  for (const comment of comments) {
+    const body = `**[${comment.user.login} on GitHub](${comment.html_url}):**\n\n${comment.body}`;
+    await ctx.issues.createComment(link.paperclipIssueId, body, link.paperclipCompanyId);
+  }
+
+  if (comments.length > 0) {
+    await updateLink(ctx, link.paperclipIssueId, {
+      lastCommentSyncAt: new Date().toISOString(),
+    });
+  }
+}