paperclip-github-plugin 0.8.9 → 0.8.11

package/dist/worker.js

@@ -1,4 +1,5 @@
 // src/worker.ts
+import { Buffer } from "node:buffer";
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -532,6 +533,58 @@ var GITHUB_AGENT_TOOLS = [
       }
     }
   },
+  {
+    name: "upload_pull_request_asset",
+    displayName: "Upload Pull Request Asset",
+    description: "Upload a PR-visible asset such as an image, PDF, log, archive, or report to a non-merge artifact branch and return durable markdown that can be embedded in the PR body.",
+    parametersSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["fileName"],
+      allOf: [pullRequestTargetSchema],
+      anyOf: [
+        { required: ["contentBase64"] },
+        { required: ["dataUrl"] }
+      ],
+      properties: {
+        repository: repositoryProperty,
+        pullRequestNumber: pullRequestNumberProperty,
+        paperclipIssueId: paperclipIssueIdProperty,
+        fileName: {
+          type: "string",
+          description: "Asset filename. The plugin sanitizes it and preserves a safe extension."
+        },
+        label: {
+          type: "string",
+          description: "Human-readable link text for the returned Markdown. Defaults to the sanitized filename."
+        },
+        alt: {
+          type: "string",
+          description: "Backward-compatible alias for label, useful as image alt text."
+        },
+        caption: {
+          type: "string",
+          description: "Optional human-facing caption returned with the uploaded asset metadata."
+        },
+        contentBase64: {
+          type: "string",
+          description: "Base64-encoded asset bytes. Assets are limited to 10 MiB."
+        },
+        dataUrl: {
+          type: "string",
+          description: "Alternative base64 data URL input such as data:application/pdf;base64,... or data:image/png;base64,... ."
+        },
+        mimeType: {
+          type: "string",
+          description: "Optional MIME type such as application/pdf or image/png. If omitted, the plugin infers common types from fileName and otherwise uses application/octet-stream."
+        },
+        artifactBranch: {
+          type: "string",
+          description: "Optional artifact branch name. Defaults to paperclip-artifacts-pr-<pullRequestNumber>."
+        }
+      }
+    }
+  },
   {
     name: "link_github_item",
     displayName: "Link GitHub Item",
@@ -637,6 +690,9 @@ var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/a
 var ISSUE_LINK_API_ROUTE_KEY = "link-github-item";
 var ISSUE_LINK_API_ROUTE_PATH = "/issue-link";
 var ISSUE_LINK_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${ISSUE_LINK_API_ROUTE_PATH}`;
+var PULL_REQUEST_ASSET_API_ROUTE_KEY = "upload-pull-request-asset";
+var PULL_REQUEST_ASSET_API_ROUTE_PATH = "/pull-request-assets";
+var PULL_REQUEST_ASSET_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${PULL_REQUEST_ASSET_API_ROUTE_PATH}`;
 
 // src/paperclip-health.ts
 function normalizeOptionalString(value) {
@@ -739,6 +795,40 @@ var AI_AUTHORED_MARKDOWN_FOOTER_PATTERN = /\n\n---\n###### ✨ This (?:comment|i
 var HIDDEN_GITHUB_IMPORT_MARKER_PREFIX = "<!-- paperclip-github-plugin-imported-from: ";
 var HIDDEN_GITHUB_IMPORT_MARKER_SUFFIX = " -->";
 var EMPTY_GITHUB_ISSUE_DESCRIPTION_PLACEHOLDER = "_No description provided on GitHub._";
+var MAX_PULL_REQUEST_ASSET_BYTES = 10 * 1024 * 1024;
+var DEFAULT_PULL_REQUEST_ASSET_MIME_TYPE = "application/octet-stream";
+var PULL_REQUEST_ASSET_MIME_TYPE_BY_EXTENSION = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  markdown: "text/markdown",
+  json: "application/json",
+  csv: "text/csv",
+  xml: "application/xml",
+  zip: "application/zip",
+  gz: "application/gzip",
+  tgz: "application/gzip"
+};
+var PULL_REQUEST_ASSET_EXTENSION_BY_MIME_TYPE = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "application/pdf": "pdf",
+  "text/plain": "txt",
+  "text/markdown": "md",
+  "application/json": "json",
+  "text/csv": "csv",
+  "application/xml": "xml",
+  "application/zip": "zip",
+  "application/gzip": "gz",
+  "application/octet-stream": "bin"
+};
 var pluginRuntimeContext = null;
 function normalizeCompanyId(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -5816,8 +5906,13 @@ function isGitHubPullRequestActionRequiredForSync(pullRequest) {
 function isGitHubPullRequestPendingExternalWaitForSync(pullRequest) {
   return pullRequest.ciState === "unfinished" && !pullRequest.hasUnresolvedReviewThreads && pullRequest.mergeability !== "conflicting" && (pullRequest.mergeStateStatus === "blocked" || pullRequest.mergeStateStatus === "unstable");
 }
+function isGitHubPullRequestBlockedMaintainerApprovalWaitForSync(pullRequest) {
+  return pullRequest.ciState === "green" && !pullRequest.hasUnresolvedReviewThreads && pullRequest.mergeability !== "conflicting" && pullRequest.mergeStateStatus === "blocked" && (pullRequest.reviewDecision === "unknown" || pullRequest.reviewDecision === "review_required");
+}
 function shouldPreserveBlockedExternalPullRequestWait(params) {
-  return params.currentStatus === "blocked" && params.linkedPullRequests.length > 0 && params.linkedPullRequests.every((pullRequest) => isGitHubPullRequestPendingExternalWaitForSync(pullRequest));
+  return params.currentStatus === "blocked" && params.linkedPullRequests.length > 0 && params.linkedPullRequests.every(
+    (pullRequest) => isGitHubPullRequestPendingExternalWaitForSync(pullRequest) || isGitHubPullRequestBlockedMaintainerApprovalWaitForSync(pullRequest)
+  );
 }
 function isGitHubPullRequestTransientUnknownMergeabilityWait(pullRequest) {
   return pullRequest.ciState === "green" && !pullRequest.hasUnresolvedReviewThreads && pullRequest.mergeability !== "conflicting" && pullRequest.mergeStateStatus === "unknown";
@@ -10003,6 +10098,187 @@ function buildToolSuccessResult(content, data) {
     data
   };
 }
+function normalizePullRequestAssetMimeType(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(?:;\s*[a-z0-9!#$&^_.+-]+=[a-z0-9!#$&^_.+-]+)*$/.test(normalized)) {
+    return void 0;
+  }
+  return normalized.split(";", 1)[0];
+}
+function getPullRequestAssetMimeTypeFromFileName(fileName) {
+  const extensionMatch = fileName.trim().toLowerCase().match(/\.([a-z0-9]+)$/);
+  if (!extensionMatch) {
+    return void 0;
+  }
+  return PULL_REQUEST_ASSET_MIME_TYPE_BY_EXTENSION[extensionMatch[1]];
+}
+function getPullRequestAssetExtension(fileName) {
+  const extensionMatch = fileName.trim().toLowerCase().match(/\.([a-z0-9]+)$/);
+  return extensionMatch?.[1];
+}
+function sanitizePullRequestAssetFileName(fileNameInput, mimeType) {
+  const inferredExtension = PULL_REQUEST_ASSET_EXTENSION_BY_MIME_TYPE[mimeType] ?? "bin";
+  const fallbackBaseName = `asset.${inferredExtension}`;
+  const rawFileName = normalizeOptionalString2(fileNameInput) ?? fallbackBaseName;
+  const lastSegment = rawFileName.split(/[\\/]+/).filter(Boolean).at(-1) ?? fallbackBaseName;
+  const extension = getPullRequestAssetExtension(lastSegment) ?? inferredExtension;
+  const withoutExtension = lastSegment.replace(/\.[A-Za-z0-9]+$/, "");
+  const sanitizedBaseName = withoutExtension.normalize("NFKD").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/[-_.]+$/g, "").replace(/^[-_.]+/g, "").slice(0, 80) || "asset";
+  return `${sanitizedBaseName}.${extension}`;
+}
+function sanitizePullRequestAssetLabel(value, fallbackFileName) {
+  const normalized = normalizeOptionalString2(value);
+  return (normalized ?? fallbackFileName.replace(/[-_.]+/g, " ")).slice(0, 200);
+}
+function sanitizePullRequestAssetArtifactBranch(value, pullRequestNumber) {
+  const normalized = normalizeOptionalString2(value);
+  const candidate = normalized ?? `paperclip-artifacts-pr-${pullRequestNumber}`;
+  const sanitized = candidate.replace(/[^A-Za-z0-9._/-]+/g, "-").replace(/\.\.+/g, ".").replace(/\/{2,}/g, "/").replace(/^[-/.]+|[-/.]+$/g, "");
+  if (!sanitized || sanitized.includes("..") || sanitized.startsWith("/") || sanitized.endsWith(".lock")) {
+    throw new Error("artifactBranch must be a safe Git branch name.");
+  }
+  return sanitized;
+}
+function decodePullRequestAssetContent(payload) {
+  const dataUrl = normalizeOptionalString2(payload.dataUrl);
+  let contentBase64 = normalizeOptionalString2(payload.contentBase64);
+  let mimeType = normalizePullRequestAssetMimeType(payload.mimeType);
+  if (dataUrl) {
+    const match = dataUrl.match(/^data:([^;,]+(?:;[^,]+)?);base64,(.+)$/is);
+    if (!match) {
+      throw new Error("dataUrl must be a base64 data URL.");
+    }
+    const dataUrlMimeType = normalizePullRequestAssetMimeType(match[1]);
+    if (!dataUrlMimeType) {
+      throw new Error("dataUrl MIME type must be a valid MIME type such as image/png or application/pdf.");
+    }
+    mimeType = dataUrlMimeType;
+    contentBase64 = match[2].replace(/\s+/g, "");
+  }
+  if (!contentBase64) {
+    throw new Error("contentBase64 or dataUrl is required.");
+  }
+  mimeType = mimeType ?? getPullRequestAssetMimeTypeFromFileName(normalizeOptionalString2(payload.fileName) ?? "") ?? DEFAULT_PULL_REQUEST_ASSET_MIME_TYPE;
+  const normalizedBase64 = contentBase64.replace(/\s+/g, "");
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(normalizedBase64) || normalizedBase64.length % 4 === 1) {
+    throw new Error("Asset content must be valid base64.");
+  }
+  const bytes = Buffer.from(normalizedBase64, "base64");
+  if (bytes.length === 0) {
+    throw new Error("Asset content must not be empty.");
+  }
+  if (bytes.length > MAX_PULL_REQUEST_ASSET_BYTES) {
+    throw new Error(`Asset content exceeds the ${MAX_PULL_REQUEST_ASSET_BYTES} byte limit.`);
+  }
+  return {
+    bytes,
+    mimeType
+  };
+}
+function buildPullRequestAssetMarkdown(label, rawUrl, mimeType) {
+  const normalizedLabel = label.replace(/[\]\n\r]/g, " ").trim();
+  if (mimeType.startsWith("image/")) {
+    return `![${normalizedLabel}](${rawUrl})`;
+  }
+  return `[${normalizedLabel}](${rawUrl})`;
+}
+async function uploadPullRequestAssetArtifact(params) {
+  const { bytes, mimeType } = decodePullRequestAssetContent(params.payload);
+  const fileName = sanitizePullRequestAssetFileName(params.payload.fileName, mimeType);
+  const label = sanitizePullRequestAssetLabel(params.payload.label ?? params.payload.alt, fileName);
+  const caption = normalizeOptionalString2(params.payload.caption);
+  const artifactBranch = sanitizePullRequestAssetArtifactBranch(params.payload.artifactBranch, params.pullRequestNumber);
+  const pullRequestResponse = await params.octokit.rest.pulls.get({
+    owner: params.repository.owner,
+    repo: params.repository.repo,
+    pull_number: params.pullRequestNumber,
+    headers: {
+      "X-GitHub-Api-Version": GITHUB_API_VERSION
+    }
+  });
+  const headSha = pullRequestResponse.data.head.sha;
+  const shortHeadSha = headSha.slice(0, 12);
+  const contentPath = `assets/pr-${params.pullRequestNumber}/${shortHeadSha}/${fileName}`;
+  let branchSha;
+  try {
+    const branchRefResponse = await params.octokit.rest.git.getRef({
+      owner: params.repository.owner,
+      repo: params.repository.repo,
+      ref: `heads/${artifactBranch}`,
+      headers: {
+        "X-GitHub-Api-Version": GITHUB_API_VERSION
+      }
+    });
+    branchSha = branchRefResponse.data.object.sha;
+  } catch (error) {
+    if (getErrorStatus(error) !== 404) {
+      throw error;
+    }
+  }
+  if (!branchSha) {
+    await params.octokit.rest.git.createRef({
+      owner: params.repository.owner,
+      repo: params.repository.repo,
+      ref: `refs/heads/${artifactBranch}`,
+      sha: pullRequestResponse.data.base.sha,
+      headers: {
+        "X-GitHub-Api-Version": GITHUB_API_VERSION
+      }
+    });
+  }
+  let existingFileSha;
+  try {
+    const existingContentResponse = await params.octokit.rest.repos.getContent({
+      owner: params.repository.owner,
+      repo: params.repository.repo,
+      path: contentPath,
+      ref: artifactBranch,
+      headers: {
+        "X-GitHub-Api-Version": GITHUB_API_VERSION
+      }
+    });
+    if (!Array.isArray(existingContentResponse.data) && existingContentResponse.data.type === "file") {
+      existingFileSha = existingContentResponse.data.sha;
+    }
+  } catch (error) {
+    if (getErrorStatus(error) !== 404) {
+      throw error;
+    }
+  }
+  const updateResponse = await params.octokit.rest.repos.createOrUpdateFileContents({
+    owner: params.repository.owner,
+    repo: params.repository.repo,
+    path: contentPath,
+    message: `Add asset for PR #${params.pullRequestNumber}`,
+    content: bytes.toString("base64"),
+    branch: artifactBranch,
+    ...existingFileSha ? { sha: existingFileSha } : {},
+    headers: {
+      "X-GitHub-Api-Version": GITHUB_API_VERSION
+    }
+  });
+  const commitSha = updateResponse.data.commit.sha;
+  const rawUrl = `https://raw.githubusercontent.com/${params.repository.owner}/${params.repository.repo}/${commitSha}/${contentPath}`;
+  const markdown = buildPullRequestAssetMarkdown(label, rawUrl, mimeType);
+  return {
+    repository: params.repository.url,
+    pullRequestNumber: params.pullRequestNumber,
+    artifactBranch,
+    path: contentPath,
+    fileName,
+    mimeType,
+    sizeBytes: bytes.length,
+    commitSha,
+    rawUrl,
+    markdown,
+    label,
+    ...mimeType.startsWith("image/") ? { alt: label } : {},
+    ...caption ? { caption } : {}
+  };
+}
 function buildToolErrorResult(error) {
   const rateLimitPause = getGitHubRateLimitPauseDetails(error);
   if (rateLimitPause) {
@@ -10183,12 +10459,15 @@ async function handleCompanyMetricApiRoute(ctx, input) {
     }
   };
 }
-function parseIssueLinkApiRouteBody(input) {
+function parsePluginApiRouteJsonObjectBody(input, routeLabel) {
   if (!input.body || typeof input.body !== "object" || Array.isArray(input.body)) {
-    throw new Error("Issue link route body must be a JSON object.");
+    throw new Error(`${routeLabel} body must be a JSON object.`);
   }
   return input.body;
 }
+function parseIssueLinkApiRouteBody(input) {
+  return parsePluginApiRouteJsonObjectBody(input, "Issue link route");
+}
 function normalizeIssueLinkApiRouteKind(payload) {
   const explicitKind = normalizeIssueGitHubLinkKind(payload.kind);
   if (explicitKind) {
@@ -10203,6 +10482,47 @@ function normalizeIssueLinkApiRouteKind(payload) {
   }
   return null;
 }
+async function handlePullRequestAssetApiRoute(ctx, input) {
+  if (input.actor.actorType !== "agent") {
+    throw new Error("Pull request assets must be uploaded by an authenticated Paperclip agent.");
+  }
+  const payload = parsePluginApiRouteJsonObjectBody(input, "Pull request asset route");
+  const rawPullRequestUrl = normalizeOptionalString2(payload.pullRequestUrl);
+  const pullRequestUrl = normalizeGitHubPullRequestHtmlUrl(rawPullRequestUrl);
+  if (rawPullRequestUrl && !pullRequestUrl) {
+    throw new Error("pullRequestUrl must be a valid GitHub pull request URL.");
+  }
+  const parsedPullRequestUrl = pullRequestUrl ? parseGitHubPullRequestHtmlUrl(pullRequestUrl) : void 0;
+  const repositoryInput = normalizeOptionalString2(payload.repository) ?? parsedPullRequestUrl?.repositoryUrl;
+  if (!repositoryInput) {
+    throw new Error("repository is required unless pullRequestUrl is provided.");
+  }
+  const repository = requireRepositoryReference(repositoryInput);
+  const pullRequestNumber = normalizeToolPositiveInteger(payload.pullRequestNumber) ?? parsedPullRequestUrl?.pullRequestNumber;
+  if (!pullRequestNumber) {
+    throw new Error("pullRequestNumber is required unless pullRequestUrl is provided.");
+  }
+  if (parsedPullRequestUrl && !areRepositoriesEqual(repository, requireRepositoryReference(parsedPullRequestUrl.repositoryUrl))) {
+    throw new Error("repository must match pullRequestUrl.");
+  }
+  const octokit = await createGitHubToolOctokit(ctx, input.companyId, {
+    toolName: PULL_REQUEST_ASSET_API_ROUTE_KEY,
+    repositoryUrl: repository.url
+  });
+  const asset = await uploadPullRequestAssetArtifact({
+    octokit,
+    repository,
+    pullRequestNumber,
+    payload
+  });
+  return {
+    status: 201,
+    body: {
+      status: "uploaded",
+      asset
+    }
+  };
+}
 async function handleIssueLinkApiRoute(ctx, input) {
   if (input.actor.actorType !== "agent") {
     throw new Error("GitHub issue links must be recorded by an authenticated Paperclip agent.");
@@ -15085,6 +15405,27 @@ function registerGitHubAgentTools(ctx) {
       );
     })
   );
+  ctx.tools.register(
+    "upload_pull_request_asset",
+    getGitHubAgentToolDeclaration("upload_pull_request_asset"),
+    async (params, runCtx) => executeGitHubTool(async () => {
+      const input = getToolInputRecord(params);
+      const target = await resolveGitHubPullRequestToolTarget(ctx, runCtx, input);
+      const octokit = await createAgentToolOctokit(runCtx, "upload_pull_request_asset", target.repository);
+      const asset = await uploadPullRequestAssetArtifact({
+        octokit,
+        repository: target.repository,
+        pullRequestNumber: target.pullRequestNumber,
+        payload: input
+      });
+      return buildToolSuccessResult(
+        `Uploaded asset ${asset.fileName} for pull request #${target.pullRequestNumber}.`,
+        {
+          asset
+        }
+      );
+    })
+  );
   ctx.tools.register(
     "link_github_item",
     getGitHubAgentToolDeclaration("link_github_item"),
@@ -15139,6 +15480,7 @@ var __testing = {
   formatPaperclipApiFetchErrorMessage,
   hasUnresolvedPaperclipIssueBlocker,
   isHealthyMaintainerWaitTransition,
+  resolvePaperclipPullRequestIssueStatus,
   resolveSyncTransitionAssignee
 };
 var plugin = definePlugin({
@@ -15559,6 +15901,9 @@ var plugin = definePlugin({
     if (input.routeKey === ISSUE_LINK_API_ROUTE_KEY) {
       return handleIssueLinkApiRoute(pluginRuntimeContext, input);
     }
+    if (input.routeKey === PULL_REQUEST_ASSET_API_ROUTE_KEY) {
+      return handlePullRequestAssetApiRoute(pluginRuntimeContext, input);
+    }
     return {
       status: 404,
       body: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",
@@ -42,14 +42,14 @@
   "dependencies": {
     "@octokit/rest": "^22.0.1",
     "@paperclipai/plugin-sdk": "^2026.428.0",
-    "react": "^19.2.5",
+    "react": "^19.2.6",
     "react-markdown": "^10.1.0",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
-    "@types/node": "24.12.2",
+    "@types/node": "24.12.3",
     "@types/react": "19.2.14",
     "esbuild": "0.28.0",
     "playwright": "1.59.1",