@paperclipai_dld/plugin-github 2026.319.0-canary.4

package/src/tools.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent tools for GitHub issue search, link, and unlink.
+ *
+ * SDK fix applied: ctx.tools.register requires 3 args (name, declaration, fn).
+ * The original mvanhorn plugin used 2-arg form which no longer matches the SDK.
+ */
+
+import type { PluginContext } from "@paperclipai_dld/plugin-sdk";
+import { TOOL_NAMES } from "./constants.js";
+import * as github from "./github.js";
+import * as sync from "./sync.js";
+
+export function registerTools(ctx: PluginContext): void {
+  // -----------------------------------------------------------------------
+  // github_search_issues
+  // -----------------------------------------------------------------------
+  ctx.tools.register(
+    TOOL_NAMES.searchIssues,
+    {
+      displayName: "Search GitHub Issues",
+      description: "Search GitHub issues in a repository. Returns matching issue titles, states, URLs, and labels.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query string" },
+          repo: { type: "string", description: "Repository in owner/repo format (optional, uses default if configured)" },
+        },
+        required: ["query"],
+      },
+    },
+    async (params, runCtx) => {
+      const p = params as Record<string, unknown>;
+      const config = (await ctx.config.get()) as Record<string, unknown>;
+      const tokenRef = config.githubTokenRef as string | undefined;
+      if (!tokenRef) return { error: "githubTokenRef not configured" };
+
+      const token = await ctx.secrets.resolve(tokenRef);
+      const defaultRepo = config.defaultRepo as string | undefined;
+      const repo = (p.repo as string | undefined) || defaultRepo || "";
+      if (!repo) {
+        return {
+          error: "No repository specified. Pass repo parameter or configure a default repository.",
+        };
+      }
+
+      try {
+        const results = await github.searchIssues(
+          ctx.http.fetch.bind(ctx.http),
+          token,
+          repo,
+          p.query as string,
+        );
+        return {
+          content: `Found ${results.total_count} issues`,
+          data: {
+            total_count: results.total_count,
+            issues: results.items.map((issue) => ({
+              number: issue.number,
+              title: issue.title,
+              state: issue.state,
+              url: issue.html_url,
+              labels: issue.labels.map((l) => l.name),
+              assignees: issue.assignees.map((a) => a.login),
+              updated_at: issue.updated_at,
+            })),
+          },
+        };
+      } catch (err) {
+        return { error: String(err) };
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // github_link_issue
+  // -----------------------------------------------------------------------
+  ctx.tools.register(
+    TOOL_NAMES.linkIssue,
+    {
+      displayName: "Link GitHub Issue",
+      description: "Link a GitHub issue to the current Paperclip issue for bidirectional sync.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          ghIssueUrl: {
+            type: "string",
+            description: "GitHub issue URL, owner/repo#number, or #number (with a configured default repo)",
+          },
+          syncDirection: {
+            type: "string",
+            enum: ["bidirectional", "github-to-paperclip", "paperclip-to-github"],
+            description: "Sync direction (defaults to bidirectional)",
+          },
+        },
+        required: ["ghIssueUrl"],
+      },
+    },
+    async (params, runCtx) => {
+      const p = params as Record<string, unknown>;
+      const config = (await ctx.config.get()) as Record<string, unknown>;
+      const tokenRef = config.githubTokenRef as string | undefined;
+      if (!tokenRef) return { error: "githubTokenRef not configured" };
+
+      const token = await ctx.secrets.resolve(tokenRef);
+      const defaultRepo = config.defaultRepo as string | undefined;
+
+      const ref = github.parseGitHubIssueRef(p.ghIssueUrl as string, defaultRepo);
+      if (!ref) return { error: "Could not parse GitHub issue reference." };
+
+      const issueId = runCtx.projectId; // using projectId as proxy; real impl uses context issue
+      const companyId = runCtx.companyId;
+      if (!issueId || !companyId) return { error: "No issue context available." };
+
+      try {
+        const ghIssue = await github.getIssue(
+          ctx.http.fetch.bind(ctx.http),
+          token,
+          ref.owner,
+          ref.repo,
+          ref.number,
+        );
+
+        const syncDirection =
+          (p.syncDirection as sync.IssueLink["syncDirection"] | undefined) ?? "bidirectional";
+
+        const link = await sync.createLink(ctx, {
+          paperclipIssueId: issueId,
+          paperclipCompanyId: companyId,
+          ghOwner: ref.owner,
+          ghRepo: ref.repo,
+          ghNumber: ref.number,
+          ghHtmlUrl: ghIssue.html_url,
+          ghState: ghIssue.state,
+          syncDirection,
+        });
+
+        return {
+          content: `Linked to GitHub issue #${ref.number} in ${ref.owner}/${ref.repo}`,
+          data: { link },
+        };
+      } catch (err) {
+        return { error: String(err) };
+      }
+    },
+  );
+
+  // -----------------------------------------------------------------------
+  // github_unlink_issue
+  // -----------------------------------------------------------------------
+  ctx.tools.register(
+    TOOL_NAMES.unlinkIssue,
+    {
+      displayName: "Unlink GitHub Issue",
+      description: "Remove the GitHub issue link from the current Paperclip issue.",
+      parametersSchema: {
+        type: "object",
+        properties: {},
+      },
+    },
+    async (_params, runCtx) => {
+      const issueId = runCtx.projectId;
+      const companyId = runCtx.companyId;
+      if (!issueId || !companyId) return { error: "No issue context available." };
+
+      const existing = await sync.getLink(ctx, issueId);
+      if (!existing) return { error: "No GitHub link found for this issue." };
+
+      await sync.deleteLink(ctx, issueId);
+      return { content: `Unlinked GitHub issue #${existing.ghNumber} from ${existing.ghOwner}/${existing.ghRepo}` };
+    },
+  );
+}

package/src/verify-signature.ts

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify GitHub webhook HMAC-SHA256 signature.
+ *
+ * @param rawBody  The raw request body string (must match what GitHub signed).
+ * @param signature  The value of the `x-hub-signature-256` header (`sha256=<hex>`).
+ * @param secret  The shared webhook secret.
+ * @returns `true` if the signature is valid.
+ */
+export function verifyGitHubSignature(
+  rawBody: string,
+  signature: string | undefined,
+  secret: string,
+): boolean {
+  if (!signature || !secret) return false;
+
+  const [algo, hex] = signature.split("=", 2);
+  if (algo !== "sha256" || !hex) return false;
+
+  const expected = createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
+
+  if (expected.length !== hex.length) return false;
+
+  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(hex, "hex"));
+}

package/src/worker.ts

@@ -0,0 +1,488 @@
+import {
+  definePlugin,
+  runWorker,
+  type PluginContext,
+  type PluginWebhookInput,
+} from "@paperclipai_dld/plugin-sdk";
+import type { Agent } from "@paperclipai_dld/shared";
+import {
+  DEFAULT_CONFIG,
+  SUPPORTED_GITHUB_EVENTS,
+  WEBHOOK_KEYS,
+  type PluginConfig,
+  type SupportedGitHubEvent,
+} from "./constants.js";
+import type {
+  GitHubCheckRunEvent,
+  GitHubWorkflowRunEvent,
+} from "./github-types.js";
+import * as sync from "./sync.js";
+import { registerTools } from "./tools.js";
+import { verifyGitHubSignature } from "./verify-signature.js";
+
+interface GitHubIssueEvent {
+  action: "opened" | "closed" | "reopened" | "edited" | "assigned" | string;
+  issue: {
+    number: number;
+    title: string;
+    body: string | null;
+    state: "open" | "closed";
+    html_url: string;
+    labels: Array<{ name: string }>;
+  };
+  repository: { full_name: string; html_url: string };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let ctx: PluginContext | null = null;
+
+async function getConfig(): Promise<Required<PluginConfig>> {
+  if (!ctx) throw new Error("Plugin not initialized");
+  const raw = (await ctx.config.get()) as PluginConfig;
+  return { ...DEFAULT_CONFIG, ...raw } as Required<PluginConfig>;
+}
+
+/** Normalise header access — GitHub sends lowercase, SDK may preserve casing. */
+function getHeader(
+  headers: Record<string, string | string[]>,
+  key: string,
+): string | undefined {
+  const lower = key.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower) return Array.isArray(v) ? v[0] : v;
+  }
+  return undefined;
+}
+
+/**
+ * Try to resolve a Paperclip agent from the Git committer email or login.
+ * This is a best-effort lookup — the agent list is searched for a name match.
+ */
+async function resolveAgent(
+  companyId: string,
+  login: string | undefined,
+  email: string | undefined,
+): Promise<Agent | null> {
+  if (!ctx || (!login && !email)) return null;
+  try {
+    const agents = await ctx.agents.list({ companyId });
+    const needle = (login ?? email ?? "").toLowerCase();
+    return (
+      agents.find(
+        (a) =>
+          a.name.toLowerCase() === needle ||
+          a.urlKey?.toLowerCase() === needle,
+      ) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store the last processed delivery ID to avoid duplicate processing
+ * on retries from GitHub.
+ */
+async function isDuplicate(deliveryId: string): Promise<boolean> {
+  if (!ctx) return false;
+  try {
+    const last = (await ctx.state.get({
+      scopeKind: "instance",
+      stateKey: `last-delivery-${deliveryId}`,
+    })) as string | null;
+    return last != null;
+  } catch {
+    return false;
+  }
+}
+
+async function markDelivery(deliveryId: string): Promise<void> {
+  if (!ctx) return;
+  try {
+    await ctx.state.set(
+      { scopeKind: "instance", stateKey: `last-delivery-${deliveryId}` },
+      new Date().toISOString(),
+    );
+  } catch {
+    // best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Event handlers
+// ---------------------------------------------------------------------------
+
+async function handleWorkflowRun(payload: GitHubWorkflowRunEvent): Promise<void> {
+  const run = payload.workflow_run;
+
+  if (payload.action !== "completed") return;
+  if (run.conclusion !== "failure" && run.conclusion !== "timed_out") return;
+
+  const config = await getConfig();
+  if (!config.companyId) {
+    ctx?.logger.warn("No companyId configured — skipping issue creation");
+    return;
+  }
+
+  const repo = payload.repository.full_name;
+  const commitAuthor = run.head_commit?.author;
+  const prNumbers = run.pull_requests.map((pr) => pr.number);
+
+  const agent = await resolveAgent(
+    config.companyId,
+    run.actor?.login,
+    commitAuthor?.email,
+  );
+
+  const assigneeAgentId = agent?.id ?? (config.defaultAssigneeAgentId || undefined);
+
+  if (prNumbers.length > 0) {
+    const commented = await commentOnLinkedIssues(config.companyId, repo, prNumbers, run);
+    if (commented) return;
+  }
+
+  const title = `CI failure: ${run.name} #${run.run_number} on ${repo}`;
+  const description = buildWorkflowRunDescription(payload);
+
+  ctx?.logger.info(`Creating issue: ${title}`);
+
+  await ctx!.issues.create({
+    companyId: config.companyId,
+    goalId: config.goalId || undefined,
+    title,
+    description,
+    priority: "high",
+    assigneeAgentId,
+  });
+
+  if (assigneeAgentId) {
+    try {
+      await ctx!.agents.invoke(assigneeAgentId, config.companyId, {
+        prompt: `CI failure on ${repo}: workflow "${run.name}" #${run.run_number} failed (${run.conclusion}). Details: ${run.html_url}`,
+        reason: "github-ci-failure",
+      });
+    } catch {
+      ctx?.logger.warn(`Could not invoke agent ${assigneeAgentId}`);
+    }
+  }
+}
+
+async function handleCheckRun(payload: GitHubCheckRunEvent): Promise<void> {
+  const check = payload.check_run;
+
+  if (payload.action !== "completed") return;
+  if (check.conclusion !== "failure" && check.conclusion !== "timed_out") return;
+
+  const config = await getConfig();
+  if (!config.companyId) {
+    ctx?.logger.warn("No companyId configured — skipping");
+    return;
+  }
+
+  const repo = payload.repository.full_name;
+  const prNumbers = check.check_suite?.pull_requests.map((pr) => pr.number) ?? [];
+
+  if (prNumbers.length > 0) {
+    const commented = await commentOnLinkedIssues(config.companyId, repo, prNumbers, check);
+    if (commented) return;
+  }
+
+  const title = `PR gate failure: ${check.name} on ${repo}`;
+  const description = buildCheckRunDescription(payload);
+
+  ctx?.logger.info(`Creating issue: ${title}`);
+
+  const assigneeAgentId = config.defaultAssigneeAgentId || undefined;
+
+  await ctx!.issues.create({
+    companyId: config.companyId,
+    goalId: config.goalId || undefined,
+    title,
+    description,
+    priority: "high",
+    assigneeAgentId,
+  });
+
+  if (assigneeAgentId) {
+    try {
+      await ctx!.agents.invoke(assigneeAgentId, config.companyId, {
+        prompt: `PR gate failure on ${repo}: check "${check.name}" failed (${check.conclusion}). Details: ${check.html_url}`,
+        reason: "github-pr-gate-failure",
+      });
+    } catch {
+      ctx?.logger.warn(`Could not invoke agent ${assigneeAgentId}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PR-linked issue comment logic
+// ---------------------------------------------------------------------------
+
+async function commentOnLinkedIssues(
+  companyId: string,
+  repo: string,
+  prNumbers: number[],
+  failureContext: GitHubWorkflowRunEvent["workflow_run"] | GitHubCheckRunEvent["check_run"],
+): Promise<boolean> {
+  if (!ctx) return false;
+
+  const issues = await ctx.issues.list({
+    companyId,
+    status: "in_progress",
+    limit: 50,
+  });
+
+  let commented = false;
+
+  for (const issue of issues) {
+    const haystack = `${issue.title} ${issue.description ?? ""}`.toLowerCase();
+    const repoLower = repo.toLowerCase();
+
+    const matchesPR = prNumbers.some(
+      (n) =>
+        haystack.includes(`#${n}`) ||
+        haystack.includes(`pr ${n}`) ||
+        haystack.includes(`pull/${n}`),
+    );
+    const matchesRepo = haystack.includes(repoLower);
+
+    if (matchesPR || matchesRepo) {
+      const commentBody = buildFailureComment(repo, failureContext);
+      await ctx.issues.createComment(issue.id, commentBody, companyId);
+      commented = true;
+
+      ctx.logger.info(`Commented on issue ${issue.identifier ?? issue.id} about CI failure`);
+
+      if (issue.assigneeAgentId) {
+        try {
+          const name = "name" in failureContext ? failureContext.name : "CI check";
+          await ctx.agents.invoke(issue.assigneeAgentId, companyId, {
+            prompt: `CI/PR gate failure on ${repo}: "${name}" failed. See issue ${issue.identifier ?? issue.id} for details.`,
+            reason: "github-ci-failure-on-linked-issue",
+          });
+        } catch {
+          ctx.logger.warn(`Could not invoke agent ${issue.assigneeAgentId}`);
+        }
+      }
+    }
+  }
+
+  return commented;
+}
+
+// ---------------------------------------------------------------------------
+// Description builders
+// ---------------------------------------------------------------------------
+
+function buildWorkflowRunDescription(event: GitHubWorkflowRunEvent): string {
+  const run = event.workflow_run;
+  const repo = event.repository;
+  const commit = run.head_commit;
+
+  const lines: string[] = [
+    `## CI Failure: ${run.name}`,
+    "",
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| Repository | [${repo.full_name}](${repo.html_url}) |`,
+    `| Workflow | ${run.name} |`,
+    `| Run | [#${run.run_number}](${run.html_url}) (attempt ${run.run_attempt}) |`,
+    `| Branch | \`${run.head_branch}\` |`,
+    `| Conclusion | \`${run.conclusion}\` |`,
+    `| Commit | \`${run.head_sha.slice(0, 8)}\` |`,
+  ];
+
+  if (commit?.author) {
+    lines.push(`| Author | ${commit.author.name} (${commit.author.email}) |`);
+  }
+  if (run.actor) {
+    lines.push(`| Actor | ${run.actor.login} |`);
+  }
+
+  if (run.pull_requests.length > 0) {
+    const prLinks = run.pull_requests
+      .map((pr) => `[#${pr.number}](${repo.html_url}/pull/${pr.number})`)
+      .join(", ");
+    lines.push(`| Pull Requests | ${prLinks} |`);
+  }
+
+  if (commit?.message) {
+    lines.push("", "### Commit Message", "", `> ${commit.message.split("\n")[0]}`);
+  }
+
+  lines.push("", "---", `*Created by GitHub plugin*`);
+
+  return lines.join("\n");
+}
+
+function buildCheckRunDescription(event: GitHubCheckRunEvent): string {
+  const check = event.check_run;
+  const repo = event.repository;
+
+  const lines: string[] = [
+    `## PR Gate Failure: ${check.name}`,
+    "",
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| Repository | [${repo.full_name}](${repo.html_url}) |`,
+    `| Check | [${check.name}](${check.html_url}) |`,
+    `| Conclusion | \`${check.conclusion}\` |`,
+    `| Commit | \`${check.head_sha.slice(0, 8)}\` |`,
+  ];
+
+  if (check.app) {
+    lines.push(`| App | ${check.app.name} (\`${check.app.slug}\`) |`);
+  }
+
+  if (check.check_suite?.head_branch) {
+    lines.push(`| Branch | \`${check.check_suite.head_branch}\` |`);
+  }
+
+  const prNumbers = check.check_suite?.pull_requests ?? [];
+  if (prNumbers.length > 0) {
+    const prLinks = prNumbers
+      .map((pr) => `[#${pr.number}](${repo.html_url}/pull/${pr.number})`)
+      .join(", ");
+    lines.push(`| Pull Requests | ${prLinks} |`);
+  }
+
+  if (check.output.summary) {
+    lines.push("", "### Summary", "", check.output.summary);
+  }
+
+  lines.push("", "---", `*Created by GitHub plugin*`);
+
+  return lines.join("\n");
+}
+
+function buildFailureComment(
+  repo: string,
+  failureContext: GitHubWorkflowRunEvent["workflow_run"] | GitHubCheckRunEvent["check_run"],
+): string {
+  const name = failureContext.name;
+  const conclusion = failureContext.conclusion;
+  const url = failureContext.html_url;
+  const sha = failureContext.head_sha.slice(0, 8);
+
+  return [
+    `## CI Failure Detected`,
+    "",
+    `**${name}** failed on \`${repo}\` at commit \`${sha}\`.`,
+    "",
+    `- Conclusion: \`${conclusion}\``,
+    `- Details: [View on GitHub](${url})`,
+    "",
+    `*Reported by GitHub plugin*`,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// GitHub issues event handler (Phase 2 — bidirectional sync)
+// ---------------------------------------------------------------------------
+
+async function handleIssueEvent(payload: GitHubIssueEvent): Promise<void> {
+  if (!ctx) return;
+  if (payload.action !== "closed" && payload.action !== "reopened") return;
+
+  const [owner, repo] = payload.repository.full_name.split("/");
+  if (!owner || !repo) return;
+
+  const link = await sync.getLinkByGitHub(ctx, owner, repo, payload.issue.number);
+  if (!link) {
+    ctx.logger.info(
+      `No linked Paperclip issue for ${payload.repository.full_name}#${payload.issue.number}`,
+    );
+    return;
+  }
+
+  const ghState = payload.issue.state;
+  ctx.logger.info(
+    `Syncing GitHub issue state (${ghState}) to Paperclip issue ${link.paperclipIssueId}`,
+  );
+
+  await sync.syncGitHubStateToPaperclip(ctx, link, ghState);
+}
+
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+
+const plugin = definePlugin({
+  async setup(pluginCtx) {
+    ctx = pluginCtx;
+    registerTools(ctx);
+    ctx.logger.info("GitHub plugin initialized");
+  },
+
+  async onHealth() {
+    return { status: "ok", message: "GitHub plugin ready" };
+  },
+
+  async onWebhook(input: PluginWebhookInput) {
+    if (!ctx) throw new Error("Plugin not initialized");
+
+    if (input.endpointKey !== WEBHOOK_KEYS.github) {
+      throw new Error(`Unsupported webhook endpoint "${input.endpointKey}"`);
+    }
+
+    const config = await getConfig();
+
+    const deliveryId = getHeader(input.headers, "x-github-delivery");
+    if (deliveryId && (await isDuplicate(deliveryId))) {
+      ctx.logger.info(`Skipping duplicate delivery ${deliveryId}`);
+      return;
+    }
+
+    if (!config.skipSignatureVerification) {
+      const signature = getHeader(input.headers, "x-hub-signature-256");
+      if (!config.webhookSecret) {
+        throw new Error(
+          "webhookSecret not configured — cannot verify GitHub signature. " +
+            "Set the webhook secret in plugin config or enable skipSignatureVerification for development.",
+        );
+      }
+      if (!verifyGitHubSignature(input.rawBody, signature, config.webhookSecret)) {
+        throw new Error("Invalid GitHub webhook signature");
+      }
+    }
+
+    const eventType = getHeader(input.headers, "x-github-event");
+    if (!eventType || !SUPPORTED_GITHUB_EVENTS.includes(eventType as SupportedGitHubEvent)) {
+      ctx.logger.info(`Ignoring unsupported event type: ${eventType}`);
+      return;
+    }
+
+    const payload =
+      typeof input.parsedBody === "object" && input.parsedBody !== null
+        ? input.parsedBody
+        : JSON.parse(input.rawBody);
+
+    if (deliveryId) await markDelivery(deliveryId);
+
+    switch (eventType as SupportedGitHubEvent) {
+      case "workflow_run":
+        await handleWorkflowRun(payload as GitHubWorkflowRunEvent);
+        break;
+      case "check_run":
+        await handleCheckRun(payload as GitHubCheckRunEvent);
+        break;
+      case "issues":
+        await handleIssueEvent(payload as GitHubIssueEvent);
+        break;
+    }
+
+    ctx.logger.info(`Processed ${eventType} event`);
+  },
+
+  async onShutdown() {
+    ctx?.logger.info("GitHub plugin shutting down");
+    ctx = null;
+  },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2023"]
+  },
+  "include": ["src"]
+}