paperclip-github-plugin 0.3.2 → 0.3.4

package/README.md

@@ -118,6 +118,8 @@ When a token is saved, the settings page audits the mapped repositories for the
 
 Imported issues keep the original GitHub title and use the normalized GitHub body as the Paperclip description. The worker also normalizes GitHub HTML that Paperclip descriptions do not render cleanly, including elements such as `<br>`, `<hr>`, `<details>`, `<summary>`, and inline images.
 
+To keep imported issues recognizable without cluttering the visible description, the plugin appends a hidden HTML comment footer with the source GitHub issue URL. Agents and repair flows use that marker when the plugin-owned link entity or import registry is missing.
+
 Repeated syncs keep existing imports current instead of creating duplicates again. If the plugin's import registry is stale, the worker can repair deduplication by reusing existing Paperclip issues when durable GitHub link metadata is already present.
 
 When the local Paperclip API is available, the plugin also syncs labels by name, prefers exact color matches when multiple Paperclip labels share the same name, and creates missing Paperclip labels when needed.
@@ -136,6 +138,7 @@ When the local Paperclip API is available, the plugin also syncs labels by name,
 Additional behavior:
 
 - Open imported issues that are already in `backlog` stay in `backlog` until someone changes them in Paperclip.
+- If an imported issue is `done` or `cancelled` and GitHub shows it open again with no linked pull request, sync moves it to `todo` so agents can pick it up again.
 - Trusted new GitHub comments from the original issue author or a verified maintainer/admin can move an open imported issue back to `todo`.
 - When the sync changes a Paperclip issue status, it adds a Paperclip comment explaining what changed and why.
 

package/dist/manifest.js

@@ -435,7 +435,7 @@ var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var DASHBOARD_WIDGET_CAPABILITY = "ui.dashboardWidget.register";
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.3.2"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.3.4"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
   id: "paperclip-github-plugin",
   apiVersion: 1,

package/dist/worker.js

@@ -560,6 +560,8 @@ var ISSUE_LINK_ENTITY_TYPE = "paperclip-github-plugin.issue-link";
 var PULL_REQUEST_LINK_ENTITY_TYPE = "paperclip-github-plugin.pull-request-link";
 var COMMENT_ANNOTATION_ENTITY_TYPE = "paperclip-github-plugin.comment-annotation";
 var AI_AUTHORED_COMMENT_FOOTER_PREFIX = "Created by a Paperclip AI agent using ";
+var HIDDEN_GITHUB_IMPORT_MARKER_PREFIX = "<!-- paperclip-github-plugin-imported-from: ";
+var HIDDEN_GITHUB_IMPORT_MARKER_SUFFIX = " -->";
 function normalizeCompanyId(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
@@ -1157,6 +1159,9 @@ function createMappingId(index) {
 function normalizeOptionalString2(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+function stripNullBytes(value) {
+  return value.replace(/\u0000/g, "");
+}
 function getErrorStatus(error) {
   if (!error || typeof error !== "object" || !("status" in error)) {
     return void 0;
@@ -1419,7 +1424,11 @@ function normalizeSecretRef(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 function normalizeGitHubUserLogin(value) {
-  return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : void 0;
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = stripNullBytes(value).trim();
+  return trimmed ? trimmed.toLowerCase() : void 0;
 }
 function normalizeGitHubTokenRef(value) {
   return normalizeSecretRef(value);
@@ -1983,8 +1992,8 @@ function doesImportedIssueMatchTarget(issue, target) {
   }
   return target.issueId !== void 0 && issue.paperclipIssueId === target.issueId || target.githubIssueId !== void 0 && issue.githubIssueId === target.githubIssueId || target.githubIssueNumber !== void 0 && issue.githubIssueNumber === target.githubIssueNumber;
 }
-async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId) {
-  const linkRecords = await listGitHubIssueLinkRecords(ctx, {
+async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId, options = {}) {
+  const linkRecords = options.linkRecords ?? await listGitHubIssueLinkRecords(ctx, {
     paperclipIssueId: issueId
   });
   const entityMatch = linkRecords.find((record) => !record.data.companyId || record.data.companyId === companyId);
@@ -1997,7 +2006,8 @@ async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId) {
       githubIssueId: entityMatch.data.githubIssueId,
       githubIssueNumber: entityMatch.data.githubIssueNumber,
       githubIssueUrl: entityMatch.data.githubIssueUrl,
-      linkedPullRequestNumbers: entityMatch.data.linkedPullRequestNumbers
+      linkedPullRequestNumbers: entityMatch.data.linkedPullRequestNumbers,
+      entityRecord: entityMatch
     };
   }
   const importRegistry = normalizeImportRegistry(await ctx.state.get(IMPORT_REGISTRY_SCOPE));
@@ -2010,7 +2020,7 @@ async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId) {
       registryMatch.githubIssueNumber
     );
     if (githubIssueUrl2) {
-      return {
+      const fallbackLink2 = {
         source: "import_registry",
         companyId: registryMatch.companyId,
         paperclipProjectId: registryMatch.paperclipProjectId,
@@ -2020,15 +2030,16 @@ async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId) {
         githubIssueUrl: githubIssueUrl2,
         linkedPullRequestNumbers: []
       };
+      return await hydrateRecoveredPaperclipIssueGitHubLink(ctx, issueId, fallbackLink2) ?? fallbackLink2;
     }
   }
-  const issue = await ctx.issues.get(issueId, companyId);
+  const issue = options.paperclipIssue ?? await ctx.issues.get(issueId, companyId);
   const githubIssueUrl = extractImportedGitHubIssueUrlFromDescription(issue?.description);
   const githubIssueReference = githubIssueUrl ? parseGitHubIssueHtmlUrl(githubIssueUrl) : null;
   if (!githubIssueReference) {
     return null;
   }
-  return {
+  const fallbackLink = {
     source: "description",
     companyId,
     paperclipProjectId: issue?.projectId ?? void 0,
@@ -2037,6 +2048,73 @@ async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId) {
     githubIssueUrl: githubIssueReference.issueUrl,
     linkedPullRequestNumbers: []
   };
+  return await hydrateRecoveredPaperclipIssueGitHubLink(ctx, issueId, fallbackLink) ?? fallbackLink;
+}
+async function hydrateRecoveredPaperclipIssueGitHubLink(ctx, issueId, fallbackLink) {
+  const repository = parseRepositoryReference(fallbackLink.repositoryUrl);
+  if (!repository) {
+    return null;
+  }
+  let octokit;
+  try {
+    octokit = await createGitHubToolOctokit(ctx);
+  } catch {
+    return null;
+  }
+  try {
+    const response = await octokit.rest.issues.get({
+      owner: repository.owner,
+      repo: repository.repo,
+      issue_number: fallbackLink.githubIssueNumber,
+      headers: {
+        "X-GitHub-Api-Version": GITHUB_API_VERSION
+      }
+    });
+    const githubIssue = normalizeGitHubIssueRecord(response.data);
+    const linkedPullRequests = await listLinkedPullRequestsForIssue(octokit, repository, githubIssue.number);
+    const linkedPullRequestNumbers = linkedPullRequests.map((pullRequest) => pullRequest.number);
+    const entityRecord = buildGitHubIssueLinkRecord(
+      {
+        companyId: fallbackLink.companyId,
+        paperclipProjectId: fallbackLink.paperclipProjectId,
+        repositoryUrl: fallbackLink.repositoryUrl
+      },
+      issueId,
+      githubIssue,
+      linkedPullRequestNumbers
+    );
+    await upsertGitHubIssueLinkRecord(
+      ctx,
+      {
+        companyId: fallbackLink.companyId,
+        paperclipProjectId: fallbackLink.paperclipProjectId,
+        repositoryUrl: fallbackLink.repositoryUrl
+      },
+      issueId,
+      githubIssue,
+      linkedPullRequestNumbers
+    );
+    return {
+      source: "entity",
+      companyId: fallbackLink.companyId,
+      paperclipProjectId: fallbackLink.paperclipProjectId,
+      repositoryUrl: fallbackLink.repositoryUrl,
+      githubIssueId: githubIssue.id,
+      githubIssueNumber: githubIssue.number,
+      githubIssueUrl: normalizeGitHubIssueHtmlUrl(githubIssue.htmlUrl) ?? githubIssue.htmlUrl,
+      linkedPullRequestNumbers,
+      entityRecord
+    };
+  } catch (error) {
+    ctx.logger.warn("Unable to hydrate recovered GitHub issue metadata for a Paperclip issue fallback link.", {
+      issueId,
+      companyId: fallbackLink.companyId,
+      repositoryUrl: fallbackLink.repositoryUrl,
+      githubIssueNumber: fallbackLink.githubIssueNumber,
+      error: getErrorMessage(error)
+    });
+    return null;
+  }
 }
 async function resolveManualSyncTarget(ctx, settings, input) {
   if (input.issueId) {
@@ -2225,7 +2303,13 @@ async function buildIssueGitHubDetails(ctx, input) {
   const linkRecords = await listGitHubIssueLinkRecords(ctx, {
     paperclipIssueId: issueId
   });
-  const entityMatch = linkRecords.find((record) => !record.data.companyId || record.data.companyId === companyId);
+  const link = await resolvePaperclipIssueGitHubLink(ctx, issueId, companyId, {
+    linkRecords
+  });
+  if (!link) {
+    return null;
+  }
+  const entityMatch = link.entityRecord;
   if (entityMatch) {
     return {
       paperclipIssueId: issueId,
@@ -2241,17 +2325,13 @@ async function buildIssueGitHubDetails(ctx, input) {
       syncedAt: entityMatch.data.syncedAt
     };
   }
-  const fallbackLink = await resolvePaperclipIssueGitHubLink(ctx, issueId, companyId);
-  if (!fallbackLink) {
-    return null;
-  }
   return {
     paperclipIssueId: issueId,
-    source: fallbackLink.source,
-    githubIssueNumber: fallbackLink.githubIssueNumber,
-    githubIssueUrl: fallbackLink.githubIssueUrl,
-    repositoryUrl: fallbackLink.repositoryUrl,
-    linkedPullRequestNumbers: fallbackLink.linkedPullRequestNumbers
+    source: link.source,
+    githubIssueNumber: link.githubIssueNumber,
+    githubIssueUrl: link.githubIssueUrl,
+    repositoryUrl: link.repositoryUrl,
+    linkedPullRequestNumbers: link.linkedPullRequestNumbers
   };
 }
 async function resolveIssueByIdentifier(ctx, input) {
@@ -2839,7 +2919,7 @@ function normalizeGitHubUsername(value) {
   if (typeof value !== "string") {
     return void 0;
   }
-  const trimmed = value.trim().replace(/^@+/, "");
+  const trimmed = stripNullBytes(value).trim().replace(/^@+/, "");
   return trimmed ? trimmed.toLowerCase() : void 0;
 }
 function buildGitHubUsernameAliases(value) {
@@ -3126,7 +3206,7 @@ function normalizeGitHubIssueLabels(value) {
   const seen = /* @__PURE__ */ new Set();
   const labels = [];
   for (const entry of value) {
-    const name = typeof entry === "string" ? entry.trim() : entry && typeof entry === "object" && typeof entry.name === "string" ? entry.name.trim() : "";
+    const name = typeof entry === "string" ? stripNullBytes(entry).trim() : entry && typeof entry === "object" && typeof entry.name === "string" ? stripNullBytes(entry.name).trim() : "";
     if (!name) {
       continue;
     }
@@ -3146,8 +3226,8 @@ function normalizeGitHubIssueRecord(issue) {
   return {
     id: issue.id,
     number: issue.number,
-    title: issue.title,
-    body: issue.body ?? null,
+    title: stripNullBytes(issue.title),
+    body: typeof issue.body === "string" ? stripNullBytes(issue.body) : null,
     htmlUrl: issue.html_url,
     ...normalizeGitHubUsername(issue.user?.login) ? { authorLogin: normalizeGitHubUsername(issue.user?.login) } : {},
     labels: normalizeGitHubIssueLabels(issue.labels),
@@ -3632,7 +3712,7 @@ function resolvePaperclipIssueStatus(params) {
     return defaultImportedStatus;
   }
   if (currentStatus === "done" || currentStatus === "cancelled") {
-    return "backlog";
+    return "todo";
   }
   return currentStatus;
 }
@@ -3978,7 +4058,7 @@ async function listNewGitHubIssueCommentsSinceCount(octokit, repository, issueNu
     for (const comment of response.data.slice(remainingOffset)) {
       comments.push({
         id: comment.id,
-        body: comment.body ?? "",
+        body: typeof comment.body === "string" ? stripNullBytes(comment.body) : "",
         url: comment.html_url ?? void 0,
         authorLogin: normalizeGitHubUserLogin(comment.user?.login),
         createdAt: comment.created_at ?? void 0,
@@ -4061,6 +4141,15 @@ function parseGitHubIssueHtmlUrl(value) {
 function normalizeGitHubIssueHtmlUrl(value) {
   return parseGitHubIssueHtmlUrl(value)?.issueUrl;
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getHiddenGitHubImportMarkerPattern() {
+  return new RegExp(
+    `${escapeRegExp(HIDDEN_GITHUB_IMPORT_MARKER_PREFIX)}(\\S+?)${escapeRegExp(HIDDEN_GITHUB_IMPORT_MARKER_SUFFIX)}`,
+    "i"
+  );
+}
 function normalizeLinkedPullRequestNumbers(values) {
   return [...new Set(
     values.filter((pullRequestNumber) => Number.isInteger(pullRequestNumber) && pullRequestNumber > 0)
@@ -4070,6 +4159,10 @@ function extractImportedGitHubIssueUrlFromDescription(description) {
   if (typeof description !== "string") {
     return void 0;
   }
+  const hiddenMarkerMatch = description.match(getHiddenGitHubImportMarkerPattern());
+  if (hiddenMarkerMatch) {
+    return normalizeGitHubIssueHtmlUrl(hiddenMarkerMatch[1]);
+  }
   const markdownMetadataMatch = description.match(/^\*\s+GitHub issue:\s+\[[^\]]+\]\(([^)]+)\)/m);
   if (markdownMetadataMatch) {
     return normalizeGitHubIssueHtmlUrl(markdownMetadataMatch[1]);
@@ -4179,7 +4272,7 @@ function normalizeGitHubIssueBodyForPaperclip(body) {
   if (typeof body !== "string") {
     return void 0;
   }
-  const trimmed = body.trim();
+  const trimmed = stripNullBytes(body).trim();
   if (!trimmed) {
     return void 0;
   }
@@ -4212,8 +4305,27 @@ ${markdownImage}
 }
 function buildPaperclipIssueDescription(issue, linkedPullRequestNumbers = []) {
   const normalizedBody = normalizeGitHubIssueBodyForPaperclip(issue.body);
+  const hiddenImportMarker = buildHiddenGitHubImportMarker(issue.htmlUrl);
   void linkedPullRequestNumbers;
-  return normalizedBody ?? "";
+  if (!hiddenImportMarker) {
+    return normalizedBody ?? "";
+  }
+  if (!normalizedBody) {
+    return hiddenImportMarker;
+  }
+  return `${normalizedBody}
+
+${hiddenImportMarker}`;
+}
+function buildHiddenGitHubImportMarker(githubIssueUrl) {
+  if (typeof githubIssueUrl !== "string") {
+    return void 0;
+  }
+  const normalizedIssueUrl = normalizeGitHubIssueHtmlUrl(githubIssueUrl);
+  if (!normalizedIssueUrl) {
+    return void 0;
+  }
+  return `${HIDDEN_GITHUB_IMPORT_MARKER_PREFIX}${normalizedIssueUrl}${HIDDEN_GITHUB_IMPORT_MARKER_SUFFIX}`;
 }
 function normalizeIssueDescriptionValue(value) {
   return typeof value === "string" ? value : "";
@@ -4460,19 +4572,17 @@ async function findStoredStatusTransitionCommentAnnotation(ctx, params) {
   }
   return null;
 }
-async function upsertGitHubIssueLinkRecord(ctx, mapping, issueId, githubIssue, linkedPullRequestNumbers) {
+function buildGitHubIssueLinkRecord(target, issueId, githubIssue, linkedPullRequestNumbers) {
   const githubIssueUrl = normalizeGitHubIssueHtmlUrl(githubIssue.htmlUrl) ?? githubIssue.htmlUrl;
-  await ctx.entities.upsert({
-    entityType: ISSUE_LINK_ENTITY_TYPE,
-    scopeKind: "issue",
-    scopeId: issueId,
-    externalId: githubIssueUrl,
+  const repositoryUrl = parseRepositoryReference(target.repositoryUrl)?.url ?? target.repositoryUrl.trim();
+  return {
+    paperclipIssueId: issueId,
     title: `GitHub issue #${githubIssue.number}`,
     status: githubIssue.state,
     data: {
-      ...mapping.companyId ? { companyId: mapping.companyId } : {},
-      ...mapping.paperclipProjectId ? { paperclipProjectId: mapping.paperclipProjectId } : {},
-      repositoryUrl: getNormalizedMappingRepositoryUrl(mapping),
+      ...target.companyId ? { companyId: target.companyId } : {},
+      ...target.paperclipProjectId ? { paperclipProjectId: target.paperclipProjectId } : {},
+      repositoryUrl,
       githubIssueId: githubIssue.id,
       githubIssueNumber: githubIssue.number,
       githubIssueUrl,
@@ -4483,6 +4593,18 @@ async function upsertGitHubIssueLinkRecord(ctx, mapping, issueId, githubIssue, l
       labels: githubIssue.labels,
       syncedAt: (/* @__PURE__ */ new Date()).toISOString()
     }
+  };
+}
+async function upsertGitHubIssueLinkRecord(ctx, target, issueId, githubIssue, linkedPullRequestNumbers) {
+  const record = buildGitHubIssueLinkRecord(target, issueId, githubIssue, linkedPullRequestNumbers);
+  await ctx.entities.upsert({
+    entityType: ISSUE_LINK_ENTITY_TYPE,
+    scopeKind: "issue",
+    scopeId: issueId,
+    externalId: record.data.githubIssueUrl,
+    ...record.title ? { title: record.title } : {},
+    ...record.status ? { status: record.status } : {},
+    data: record.data
   });
 }
 async function upsertGitHubPullRequestLinkRecord(ctx, params) {
@@ -6405,7 +6527,7 @@ async function listAllGitHubIssueComments(octokit, repository, issueNumber) {
     for (const comment of response.data) {
       comments.push({
         id: comment.id,
-        body: comment.body ?? "",
+        body: typeof comment.body === "string" ? stripNullBytes(comment.body) : "",
         url: comment.html_url ?? void 0,
         authorLogin: normalizeGitHubUserLogin(comment.user?.login),
         authorUrl: comment.user?.html_url ?? void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@octokit/rest": "^22.0.1",
-    "@paperclipai/plugin-sdk": "^2026.403.0",
+    "@paperclipai/plugin-sdk": "^2026.416.0",
     "react": "^19.2.5",
     "react-markdown": "^10.1.0",
     "rehype-raw": "^7.0.0",