paperclip-github-plugin 0.7.3 → 0.7.5

package/dist/worker.js

@@ -255,6 +255,10 @@ var GITHUB_AGENT_TOOLS = [
       required: ["head", "base", "title"],
       properties: {
         repository: repositoryProperty,
+        paperclipIssueId: {
+          type: "string",
+          description: "Optional Paperclip issue id to link with the created pull request so GitHub Sync can monitor PR status for that issue."
+        },
         head: {
           type: "string",
           description: "Head branch name or owner:branch."
@@ -2300,6 +2304,18 @@ async function resolvePaperclipIssueGitHubLink(ctx, issueId, companyId, options
   };
   return await hydrateRecoveredPaperclipIssueGitHubLink(ctx, issueId, fallbackLink) ?? fallbackLink;
 }
+async function resolvePaperclipIssueGitHubPullRequestLink(ctx, issueId, companyId) {
+  const links = await listGitHubPullRequestLinkRecords(ctx, {
+    paperclipIssueId: issueId
+  });
+  return links.filter((record) => !record.data.companyId || record.data.companyId === companyId).sort((left, right) => {
+    const rightTimestamp = Date.parse(right.updatedAt ?? right.createdAt ?? "");
+    const leftTimestamp = Date.parse(left.updatedAt ?? left.createdAt ?? "");
+    const safeRightTimestamp = Number.isFinite(rightTimestamp) ? rightTimestamp : 0;
+    const safeLeftTimestamp = Number.isFinite(leftTimestamp) ? leftTimestamp : 0;
+    return safeRightTimestamp - safeLeftTimestamp;
+  })[0] ?? null;
+}
 async function hydrateRecoveredPaperclipIssueGitHubLink(ctx, issueId, fallbackLink) {
   const repository = parseRepositoryReference(fallbackLink.repositoryUrl);
   if (!repository) {
@@ -2375,21 +2391,33 @@ async function resolveManualSyncTarget(ctx, settings, input) {
     }
     const link = await resolvePaperclipIssueGitHubLink(ctx, input.issueId, companyId2);
     if (!link) {
-      throw new Error("This Paperclip issue is not linked to a GitHub issue yet. Run a broader sync first.");
-    }
-    const candidateMappings = getSyncableMappingsForTarget(settings.mappings, {
-      kind: "issue",
-      companyId: companyId2,
-      projectId: link.paperclipProjectId,
-      repositoryUrl: link.repositoryUrl,
-      issueId: input.issueId,
-      githubIssueId: link.githubIssueId,
-      githubIssueNumber: link.githubIssueNumber,
-      githubIssueUrl: link.githubIssueUrl,
-      displayLabel: `issue #${link.githubIssueNumber}`
-    });
-    if (candidateMappings.length === 0) {
-      throw new Error("No saved GitHub repository mapping matches this Paperclip issue.");
+      const pullRequestLink = await resolvePaperclipIssueGitHubPullRequestLink(ctx, input.issueId, companyId2);
+      if (!pullRequestLink) {
+        throw new Error("This Paperclip issue is not linked to a GitHub issue or pull request yet. Run a broader sync first.");
+      }
+      const candidateMappings = getSyncableMappingsForTarget(settings.mappings, {
+        kind: "issue",
+        companyId: companyId2,
+        projectId: pullRequestLink.data.paperclipProjectId,
+        repositoryUrl: pullRequestLink.data.repositoryUrl,
+        issueId: input.issueId,
+        githubPullRequestNumber: pullRequestLink.data.githubPullRequestNumber,
+        githubPullRequestUrl: pullRequestLink.data.githubPullRequestUrl,
+        displayLabel: `pull request #${pullRequestLink.data.githubPullRequestNumber}`
+      });
+      if (candidateMappings.length === 0) {
+        throw new Error("No saved GitHub repository mapping matches this Paperclip issue.");
+      }
+      return {
+        kind: "issue",
+        companyId: companyId2,
+        projectId: pullRequestLink.data.paperclipProjectId,
+        issueId: input.issueId,
+        repositoryUrl: pullRequestLink.data.repositoryUrl,
+        githubPullRequestNumber: pullRequestLink.data.githubPullRequestNumber,
+        githubPullRequestUrl: pullRequestLink.data.githubPullRequestUrl,
+        displayLabel: `pull request #${pullRequestLink.data.githubPullRequestNumber}`
+      };
     }
     return {
       kind: "issue",
@@ -2513,23 +2541,46 @@ async function buildToolbarSyncState(ctx, input) {
   }
   if (entityType === "issue" && entityId && companyId) {
     const link = await resolvePaperclipIssueGitHubLink(ctx, entityId, companyId);
-    const mappings = link ? getSyncableMappingsForTarget(settings.mappings, {
+    if (link) {
+      const mappings2 = getSyncableMappingsForTarget(settings.mappings, {
+        kind: "issue",
+        companyId,
+        projectId: link.paperclipProjectId,
+        issueId: entityId,
+        repositoryUrl: link.repositoryUrl,
+        githubIssueId: link.githubIssueId,
+        githubIssueNumber: link.githubIssueNumber,
+        githubIssueUrl: link.githubIssueUrl,
+        displayLabel: `issue #${link.githubIssueNumber}`
+      });
+      return {
+        kind: "issue",
+        visible: false,
+        canRun: githubTokenConfigured && mappings2.length > 0,
+        label: `Sync #${link.githubIssueNumber}`,
+        message: `Sync ${link.repositoryUrl.replace(/^https:\/\/github\.com\//, "")} issue #${link.githubIssueNumber}.`,
+        syncState: settings.syncState,
+        githubTokenConfigured,
+        savedMappingCount
+      };
+    }
+    const pullRequestLink = await resolvePaperclipIssueGitHubPullRequestLink(ctx, entityId, companyId);
+    const mappings = pullRequestLink ? getSyncableMappingsForTarget(settings.mappings, {
       kind: "issue",
       companyId,
-      projectId: link.paperclipProjectId,
+      projectId: pullRequestLink.data.paperclipProjectId,
       issueId: entityId,
-      repositoryUrl: link.repositoryUrl,
-      githubIssueId: link.githubIssueId,
-      githubIssueNumber: link.githubIssueNumber,
-      githubIssueUrl: link.githubIssueUrl,
-      displayLabel: `issue #${link.githubIssueNumber}`
+      repositoryUrl: pullRequestLink.data.repositoryUrl,
+      githubPullRequestNumber: pullRequestLink.data.githubPullRequestNumber,
+      githubPullRequestUrl: pullRequestLink.data.githubPullRequestUrl,
+      displayLabel: `pull request #${pullRequestLink.data.githubPullRequestNumber}`
     }) : [];
     return {
       kind: "issue",
       visible: false,
       canRun: githubTokenConfigured && mappings.length > 0,
-      label: link?.githubIssueNumber ? `Sync #${link.githubIssueNumber}` : "Sync issue",
-      message: link ? `Sync ${link.repositoryUrl.replace(/^https:\/\/github\.com\//, "")} issue #${link.githubIssueNumber}.` : "This Paperclip issue is not linked to GitHub yet.",
+      label: pullRequestLink?.data.githubPullRequestNumber ? `Sync PR #${pullRequestLink.data.githubPullRequestNumber}` : "Sync issue",
+      message: pullRequestLink ? `Sync ${pullRequestLink.data.repositoryUrl.replace(/^https:\/\/github\.com\//, "")} pull request #${pullRequestLink.data.githubPullRequestNumber}.` : "This Paperclip issue is not linked to GitHub yet.",
       syncState: settings.syncState,
       githubTokenConfigured,
       savedMappingCount
@@ -2696,13 +2747,11 @@ async function buildIssueGitHubDetails(ctx, input) {
   const link = await resolvePaperclipIssueGitHubLink(ctx, issueId, companyId, {
     linkRecords
   });
-  if (!link) {
-    return null;
-  }
-  const entityMatch = link.entityRecord;
-  if (entityMatch) {
+  if (link?.entityRecord) {
+    const entityMatch = link.entityRecord;
     return {
       paperclipIssueId: issueId,
+      kind: "issue",
       source: "entity",
       githubIssueNumber: entityMatch.data.githubIssueNumber,
       githubIssueUrl: entityMatch.data.githubIssueUrl,
@@ -2723,14 +2772,48 @@ async function buildIssueGitHubDetails(ctx, input) {
       syncedAt: entityMatch.data.syncedAt
     };
   }
+  if (link) {
+    return {
+      paperclipIssueId: issueId,
+      kind: "issue",
+      source: link.source,
+      githubIssueNumber: link.githubIssueNumber,
+      githubIssueUrl: link.githubIssueUrl,
+      repositoryUrl: link.repositoryUrl,
+      linkedPullRequestNumbers: link.linkedPullRequestNumbers,
+      linkedPullRequests: link.linkedPullRequests
+    };
+  }
+  const pullRequestLinks = await listGitHubPullRequestLinkRecords(ctx, {
+    paperclipIssueId: issueId
+  });
+  const pullRequestLink = pullRequestLinks.filter((record) => !record.data.companyId || record.data.companyId === companyId).sort((left, right) => {
+    const rightTimestamp = Date.parse(right.updatedAt ?? right.createdAt ?? "");
+    const leftTimestamp = Date.parse(left.updatedAt ?? left.createdAt ?? "");
+    const safeRightTimestamp = Number.isFinite(rightTimestamp) ? rightTimestamp : 0;
+    const safeLeftTimestamp = Number.isFinite(leftTimestamp) ? leftTimestamp : 0;
+    return safeRightTimestamp - safeLeftTimestamp;
+  })[0];
+  if (!pullRequestLink) {
+    return null;
+  }
   return {
     paperclipIssueId: issueId,
-    source: link.source,
-    githubIssueNumber: link.githubIssueNumber,
-    githubIssueUrl: link.githubIssueUrl,
-    repositoryUrl: link.repositoryUrl,
-    linkedPullRequestNumbers: link.linkedPullRequestNumbers,
-    linkedPullRequests: link.linkedPullRequests
+    kind: "pull_request",
+    source: "pull_request_entity",
+    repositoryUrl: pullRequestLink.data.repositoryUrl,
+    githubPullRequestNumber: pullRequestLink.data.githubPullRequestNumber,
+    githubPullRequestUrl: pullRequestLink.data.githubPullRequestUrl,
+    githubPullRequestState: pullRequestLink.data.githubPullRequestState,
+    title: pullRequestLink.data.title,
+    linkedPullRequestNumbers: [pullRequestLink.data.githubPullRequestNumber],
+    linkedPullRequests: [
+      {
+        number: pullRequestLink.data.githubPullRequestNumber,
+        repositoryUrl: pullRequestLink.data.repositoryUrl
+      }
+    ],
+    syncedAt: pullRequestLink.data.syncedAt
   };
 }
 async function resolveIssueByIdentifier(ctx, input) {
@@ -6014,24 +6097,34 @@ function parseGitHubIssueHtmlUrl(value) {
 function normalizeGitHubIssueHtmlUrl(value) {
   return parseGitHubIssueHtmlUrl(value)?.issueUrl;
 }
-function normalizeGitHubPullRequestHtmlUrl(value) {
-  if (typeof value !== "string" || !value.trim()) {
-    return void 0;
-  }
+function parseGitHubPullRequestHtmlUrl(value) {
   try {
-    const parsed = new URL(value);
-    if (parsed.protocol !== "https:" || parsed.hostname !== "github.com") {
+    const url = new URL(value.trim());
+    const hostname = url.hostname.trim().toLowerCase();
+    if (hostname !== "github.com" && hostname !== "www.github.com") {
       return void 0;
     }
-    const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/i);
+    const match = url.pathname.match(/^\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/(\d+)\/?$/);
     if (!match) {
       return void 0;
     }
-    return `https://github.com/${match[1]}/${match[2]}/pull/${match[3]}`;
+    return {
+      owner: match[1],
+      repo: match[2],
+      repositoryUrl: `https://github.com/${match[1]}/${match[2]}`,
+      pullRequestNumber: Number(match[3]),
+      pullRequestUrl: `https://github.com/${match[1]}/${match[2]}/pull/${match[3]}`
+    };
   } catch {
     return void 0;
   }
 }
+function normalizeGitHubPullRequestHtmlUrl(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return void 0;
+  }
+  return parseGitHubPullRequestHtmlUrl(value)?.pullRequestUrl;
+}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -6705,6 +6798,257 @@ async function upsertGitHubPullRequestLinkRecord(ctx, params) {
     }
   });
 }
+function normalizeIssueGitHubLinkKind(value) {
+  if (value === "issue" || value === "github_issue") {
+    return "issue";
+  }
+  if (value === "pull_request" || value === "pr" || value === "github_pull_request") {
+    return "pull_request";
+  }
+  return null;
+}
+function getGitHubPullRequestStateForLink(value) {
+  return getPullRequestApiState(value) === "open" ? "open" : "closed";
+}
+async function assertPaperclipIssueHasNoManualGitHubLink(ctx, params) {
+  const existingIssueLink = await resolvePaperclipIssueGitHubLink(ctx, params.issueId, params.companyId);
+  if (existingIssueLink) {
+    throw new Error("This Paperclip issue is already linked to a GitHub issue.");
+  }
+  const existingPullRequestLinks = await listGitHubPullRequestLinkRecords(ctx, {
+    paperclipIssueId: params.issueId
+  });
+  const matchingPullRequestLink = existingPullRequestLinks.find(
+    (record) => !record.data.companyId || record.data.companyId === params.companyId
+  );
+  if (matchingPullRequestLink) {
+    throw new Error("This Paperclip issue is already linked to a GitHub pull request.");
+  }
+}
+async function resolveIssueGitHubLinkMapping(ctx, params) {
+  const issue = await ctx.issues.get(params.issueId, params.companyId);
+  if (!issue) {
+    throw new Error("Paperclip issue was not found.");
+  }
+  const projectId = typeof issue.projectId === "string" && issue.projectId.trim() ? issue.projectId.trim() : void 0;
+  if (!projectId) {
+    throw new Error("This Paperclip issue is not in a project that can be mapped to a GitHub repository.");
+  }
+  const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
+  const mappings = await resolveProjectScopedMappings(ctx, settings.mappings, {
+    companyId: params.companyId,
+    projectId
+  });
+  if (mappings.length === 0) {
+    throw new Error("This Paperclip issue project is not mapped to a GitHub repository.");
+  }
+  const requestedRepository = params.repositoryUrl ? parseRepositoryReference(params.repositoryUrl) : null;
+  if (params.repositoryUrl && !requestedRepository) {
+    throw new Error(`Invalid GitHub repository: ${params.repositoryUrl}. Use owner/repo or https://github.com/owner/repo.`);
+  }
+  const matchingMappings = requestedRepository ? mappings.filter(
+    (mapping2) => areRepositoriesEqual(requireRepositoryReference(mapping2.repositoryUrl), requestedRepository)
+  ) : mappings;
+  if (matchingMappings.length === 0 && requestedRepository) {
+    throw new Error("The current Paperclip issue project is not mapped to the selected GitHub repository.");
+  }
+  if (matchingMappings.length > 1 && !requestedRepository) {
+    throw new Error("This Paperclip issue project has multiple GitHub repositories. Enter the full GitHub URL.");
+  }
+  const mapping = matchingMappings[0];
+  if (!mapping) {
+    throw new Error("This Paperclip issue project is not mapped to a GitHub repository.");
+  }
+  return {
+    issue,
+    projectId,
+    mapping,
+    repository: requestedRepository ?? requireRepositoryReference(mapping.repositoryUrl)
+  };
+}
+function resolveGitHubIssueLinkReference(input) {
+  const reference = normalizeOptionalString2(input.reference);
+  if (reference) {
+    const parsedIssueUrl = parseGitHubIssueHtmlUrl(reference);
+    if (parsedIssueUrl) {
+      return {
+        repositoryUrl: parsedIssueUrl.repositoryUrl,
+        issueNumber: parsedIssueUrl.issueNumber,
+        issueUrl: parsedIssueUrl.issueUrl
+      };
+    }
+    if (parseGitHubPullRequestHtmlUrl(reference)) {
+      throw new Error("That reference is a GitHub pull request. Choose pull request instead.");
+    }
+    const referenceNumber = normalizePositiveIntegerReference(reference);
+    if (referenceNumber) {
+      return {
+        repositoryUrl: input.repositoryUrl,
+        issueNumber: referenceNumber
+      };
+    }
+  }
+  const explicitIssueNumber = normalizePositiveIntegerReference(input.issueNumber);
+  if (explicitIssueNumber) {
+    return {
+      repositoryUrl: input.repositoryUrl,
+      issueNumber: explicitIssueNumber
+    };
+  }
+  throw new Error("Enter a GitHub issue number or full GitHub issue URL.");
+}
+function resolveGitHubPullRequestLinkReference(input) {
+  const explicitPullRequestUrl = normalizeGitHubPullRequestHtmlUrl(normalizeOptionalString2(input.pullRequestUrl));
+  const parsedExplicitPullRequestUrl = explicitPullRequestUrl ? parseGitHubPullRequestHtmlUrl(explicitPullRequestUrl) : void 0;
+  const reference = normalizeOptionalString2(input.reference);
+  const parsedReferenceUrl = reference ? parseGitHubPullRequestHtmlUrl(reference) : void 0;
+  if (reference && parseGitHubIssueHtmlUrl(reference)) {
+    throw new Error("That reference is a GitHub issue. Choose issue instead.");
+  }
+  const parsedUrl = parsedReferenceUrl ?? parsedExplicitPullRequestUrl;
+  const explicitPullRequestNumber = normalizePositiveIntegerReference(input.pullRequestNumber);
+  const referenceNumber = reference && !parsedReferenceUrl ? normalizePositiveIntegerReference(reference) : void 0;
+  const pullRequestNumber = parsedUrl?.pullRequestNumber ?? explicitPullRequestNumber ?? referenceNumber;
+  const repositoryUrl = parsedUrl?.repositoryUrl ?? input.repositoryUrl;
+  if (!pullRequestNumber) {
+    throw new Error("Enter a GitHub pull request number or full GitHub pull request URL.");
+  }
+  if (parsedUrl && explicitPullRequestNumber && explicitPullRequestNumber !== parsedUrl.pullRequestNumber) {
+    throw new Error("pullRequestNumber must match the supplied GitHub pull request URL.");
+  }
+  if (parsedUrl && input.repositoryUrl) {
+    const requestedRepository = parseRepositoryReference(input.repositoryUrl);
+    const urlRepository = parseRepositoryReference(parsedUrl.repositoryUrl);
+    if (requestedRepository && urlRepository && !areRepositoriesEqual(requestedRepository, urlRepository)) {
+      throw new Error("repository must match the supplied GitHub pull request URL.");
+    }
+  }
+  return {
+    repositoryUrl,
+    pullRequestNumber,
+    ...parsedUrl?.pullRequestUrl ? { pullRequestUrl: parsedUrl.pullRequestUrl } : {}
+  };
+}
+async function linkPaperclipIssueToGitHubIssue(ctx, params) {
+  const companyId = normalizeCompanyId(params.companyId);
+  const issueId = normalizeOptionalString2(params.issueId);
+  if (!companyId || !issueId) {
+    throw new Error("companyId and issueId are required.");
+  }
+  if (params.requireUnlinked) {
+    await assertPaperclipIssueHasNoManualGitHubLink(ctx, {
+      companyId,
+      issueId
+    });
+  }
+  const reference = resolveGitHubIssueLinkReference({
+    kind: "issue",
+    reference: params.reference,
+    repositoryUrl: params.repositoryUrl,
+    issueNumber: params.issueNumber
+  });
+  const scope = await resolveIssueGitHubLinkMapping(ctx, {
+    companyId,
+    issueId,
+    repositoryUrl: reference.repositoryUrl
+  });
+  const octokit = await createGitHubToolOctokit(ctx, companyId);
+  const response = await octokit.rest.issues.get({
+    owner: scope.repository.owner,
+    repo: scope.repository.repo,
+    issue_number: reference.issueNumber,
+    headers: {
+      "X-GitHub-Api-Version": GITHUB_API_VERSION
+    }
+  });
+  const rawIssue = response.data;
+  if (rawIssue.pull_request) {
+    throw new Error("That GitHub number is a pull request. Choose pull request instead.");
+  }
+  const githubIssue = normalizeGitHubIssueRecord(rawIssue);
+  const linkedPullRequests = await listLinkedPullRequestsForIssue(octokit, scope.repository, githubIssue.number);
+  await upsertGitHubIssueLinkRecord(ctx, scope.mapping, issueId, githubIssue, linkedPullRequests);
+  const importRegistry = normalizeImportRegistry(await ctx.state.get(IMPORT_REGISTRY_SCOPE));
+  upsertImportedIssueRecord(
+    importRegistry,
+    buildImportedIssueRecord(scope.mapping, githubIssue, issueId, (/* @__PURE__ */ new Date()).toISOString())
+  );
+  await ctx.state.set(IMPORT_REGISTRY_SCOPE, importRegistry);
+  invalidateProjectPullRequestCaches({
+    companyId,
+    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
+    repository: scope.repository
+  });
+  return {
+    kind: "issue",
+    paperclipIssueId: issueId,
+    repositoryUrl: scope.repository.url,
+    githubIssueNumber: githubIssue.number,
+    githubIssueUrl: normalizeGitHubIssueHtmlUrl(githubIssue.htmlUrl) ?? githubIssue.htmlUrl,
+    linkedPullRequestNumbers: linkedPullRequests.map((pullRequest) => pullRequest.number)
+  };
+}
+async function linkPaperclipIssueToGitHubPullRequest(ctx, params) {
+  const companyId = normalizeCompanyId(params.companyId);
+  const issueId = normalizeOptionalString2(params.issueId);
+  if (!companyId || !issueId) {
+    throw new Error("companyId and issueId are required.");
+  }
+  if (params.requireUnlinked) {
+    await assertPaperclipIssueHasNoManualGitHubLink(ctx, {
+      companyId,
+      issueId
+    });
+  }
+  const reference = resolveGitHubPullRequestLinkReference({
+    reference: params.reference,
+    repositoryUrl: params.repositoryUrl,
+    pullRequestNumber: params.pullRequestNumber,
+    pullRequestUrl: params.pullRequestUrl
+  });
+  const scope = await resolveIssueGitHubLinkMapping(ctx, {
+    companyId,
+    issueId,
+    repositoryUrl: reference.repositoryUrl
+  });
+  const octokit = await createGitHubToolOctokit(ctx, companyId);
+  const response = await octokit.rest.pulls.get({
+    owner: scope.repository.owner,
+    repo: scope.repository.repo,
+    pull_number: reference.pullRequestNumber,
+    headers: {
+      "X-GitHub-Api-Version": GITHUB_API_VERSION
+    }
+  });
+  const pullRequestUrl = normalizeGitHubPullRequestHtmlUrl(response.data.html_url ?? reference.pullRequestUrl) ?? reference.pullRequestUrl ?? `${scope.repository.url}/pull/${reference.pullRequestNumber}`;
+  const pullRequestState = getGitHubPullRequestStateForLink({
+    state: response.data.state,
+    merged: response.data.merged
+  });
+  await upsertGitHubPullRequestLinkRecord(ctx, {
+    companyId,
+    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
+    issueId,
+    repositoryUrl: scope.repository.url,
+    pullRequestNumber: reference.pullRequestNumber,
+    pullRequestUrl,
+    pullRequestTitle: response.data.title || `Pull request #${reference.pullRequestNumber}`,
+    pullRequestState
+  });
+  invalidateProjectPullRequestCaches({
+    companyId,
+    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
+    repository: scope.repository
+  });
+  return {
+    kind: "pull_request",
+    paperclipIssueId: issueId,
+    repositoryUrl: scope.repository.url,
+    githubPullRequestNumber: reference.pullRequestNumber,
+    githubPullRequestUrl: pullRequestUrl,
+    githubPullRequestState: pullRequestState
+  };
+}
 async function upsertStatusTransitionCommentAnnotation(ctx, params) {
   const { issueId, commentId, annotation } = params;
   await ctx.entities.upsert({
@@ -7743,6 +8087,40 @@ async function listRepositoryIssues(octokit, repository, state = "open", options
   }
   return normalizedIssues;
 }
+async function listRepositoryIssuesForSyncTarget(octokit, repository, state, target, options = {}) {
+  if (target?.kind !== "issue") {
+    return listRepositoryIssues(octokit, repository, state, options);
+  }
+  if (target.githubIssueNumber === void 0) {
+    if (options.onProgress) {
+      await options.onProgress({
+        loadedIssueCount: 0
+      });
+    }
+    return [];
+  }
+  const response = await octokit.rest.issues.get({
+    owner: repository.owner,
+    repo: repository.repo,
+    issue_number: target.githubIssueNumber,
+    headers: {
+      accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": GITHUB_API_VERSION
+    }
+  });
+  const issue = response.data;
+  if ("pull_request" in issue) {
+    return [];
+  }
+  const normalizedIssue = normalizeGitHubIssueRecord(issue);
+  const issues = state === "open" && normalizedIssue.state !== "open" ? [] : [normalizedIssue];
+  if (options.onProgress) {
+    await options.onProgress({
+      loadedIssueCount: issues.length
+    });
+  }
+  return issues;
+}
 async function listRepositoryIssuesForImport(allIssues) {
   return sortIssuesForImport(allIssues.filter((issue) => issue.state === "open"));
 }
@@ -8565,6 +8943,20 @@ function normalizeOptionalToolString(value) {
 function normalizeToolPositiveInteger(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
 }
+function normalizePositiveIntegerReference(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const match = value.trim().match(/^#?(\d+)$/);
+  if (!match) {
+    return void 0;
+  }
+  const parsed = Number(match[1]);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
 function normalizeToolStringArray(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -8722,12 +9114,34 @@ async function handleCompanyMetricApiRoute(ctx, input) {
   const pullRequestNumber = normalizeToolPositiveInteger(payload.pullRequestNumber);
   const pullRequestUrl = normalizeGitHubPullRequestHtmlUrl(normalizeOptionalString2(payload.pullRequestUrl));
   const eventKey = normalizeOptionalString2(payload.eventKey);
+  const paperclipIssueId = normalizeOptionalString2(payload.paperclipIssueId);
+  let linkedPaperclipIssueId;
+  let linkedRepository = null;
+  let linkedPullRequestNumber;
+  let linkedPullRequestUrl;
+  if (paperclipIssueId) {
+    const linkResult = await linkPaperclipIssueToGitHubPullRequest(ctx, {
+      companyId,
+      issueId: paperclipIssueId,
+      repositoryUrl: repository?.url,
+      pullRequestNumber,
+      pullRequestUrl
+    });
+    linkedPaperclipIssueId = typeof linkResult.paperclipIssueId === "string" ? linkResult.paperclipIssueId : paperclipIssueId;
+    const resultRepositoryUrl = normalizeOptionalString2(linkResult.repositoryUrl);
+    linkedRepository = resultRepositoryUrl ? parseRepositoryReference(resultRepositoryUrl) : null;
+    linkedPullRequestNumber = normalizeToolPositiveInteger(linkResult.githubPullRequestNumber);
+    linkedPullRequestUrl = normalizeGitHubPullRequestHtmlUrl(normalizeOptionalString2(linkResult.githubPullRequestUrl));
+  }
+  const metricRepositoryUrl = repository?.url ?? linkedRepository?.url;
+  const metricPullRequestNumber = pullRequestNumber ?? linkedPullRequestNumber;
+  const metricPullRequestUrl = pullRequestUrl ?? linkedPullRequestUrl;
   const dedupeKey = buildCompanyMetricEventKey({
     metric,
     eventKey,
-    repositoryUrl: repository?.url,
-    pullRequestNumber,
-    pullRequestUrl
+    repositoryUrl: metricRepositoryUrl,
+    pullRequestNumber: metricPullRequestNumber,
+    pullRequestUrl: metricPullRequestUrl
   });
   if (!dedupeKey) {
     throw new Error(
@@ -8742,9 +9156,9 @@ async function handleCompanyMetricApiRoute(ctx, input) {
       count: normalizeToolPositiveInteger(payload.count),
       occurredAt: normalizeOptionalString2(payload.occurredAt),
       eventKey,
-      repositoryUrl: repository?.url,
-      pullRequestNumber,
-      pullRequestUrl
+      repositoryUrl: metricRepositoryUrl,
+      pullRequestNumber: metricPullRequestNumber,
+      pullRequestUrl: metricPullRequestUrl
     },
     {
       throwOnPersistFailure: true
@@ -8756,9 +9170,10 @@ async function handleCompanyMetricApiRoute(ctx, input) {
       routeKey: input.routeKey,
       companyId,
       metric,
-      repositoryUrl: repository?.url,
-      pullRequestNumber,
-      pullRequestUrl,
+      repositoryUrl: metricRepositoryUrl,
+      pullRequestNumber: metricPullRequestNumber,
+      pullRequestUrl: metricPullRequestUrl,
+      linkedPaperclipIssueId: linkedPaperclipIssueId ?? null,
       agentId: input.actor.agentId ?? null,
       runId: input.actor.runId ?? null
     }
@@ -8769,7 +9184,8 @@ async function handleCompanyMetricApiRoute(ctx, input) {
       status: recordedMetric.recorded ? "recorded" : "duplicate",
       recorded: recordedMetric.recorded,
       companyId,
-      metric: "pull_request_created"
+      metric: "pull_request_created",
+      ...linkedPaperclipIssueId ? { paperclipIssueId: linkedPaperclipIssueId } : {}
     }
   };
 }
@@ -11966,10 +12382,11 @@ async function performSync(ctx, trigger, options = {}) {
         updateSyncFailureContext(failureContext, {
           phase: "listing_github_issues"
         });
-        const allIssues = await listRepositoryIssues(
+        const allIssues = await listRepositoryIssuesForSyncTarget(
           octokit,
           repository,
           shouldLoadClosedIssues ? "all" : "open",
+          options.target,
           {
             onProgress: async (progress) => {
               currentProgress = {
@@ -12092,7 +12509,7 @@ async function performSync(ctx, trigger, options = {}) {
         };
         await persistRunningProgress(true);
         try {
-          const warmedLinkedPullRequests = await loadLinkedPullRequestsForOpenIssues(octokit, repository);
+          const warmedLinkedPullRequests = options.target?.kind === "issue" ? /* @__PURE__ */ new Map() : await loadLinkedPullRequestsForOpenIssues(octokit, repository);
           for (const [issueNumber, linkedPullRequests] of warmedLinkedPullRequests.entries()) {
             linkedPullRequestsByIssueNumber.set(issueNumber, linkedPullRequests);
           }
@@ -12727,7 +13144,13 @@ function registerGitHubAgentTools(ctx) {
     getGitHubAgentToolDeclaration("create_pull_request"),
     async (params, runCtx) => executeGitHubTool(async () => {
       const input = getToolInputRecord(params);
-      const repository = await resolveGitHubToolRepository(ctx, runCtx, input);
+      const paperclipIssueId = normalizeOptionalToolString(input.paperclipIssueId);
+      const explicitRepository = normalizeOptionalToolString(input.repository);
+      const issueLinkScope = paperclipIssueId && !explicitRepository ? await resolveIssueGitHubLinkMapping(ctx, {
+        companyId: runCtx.companyId,
+        issueId: paperclipIssueId
+      }) : null;
+      const repository = issueLinkScope?.repository ?? await resolveGitHubToolRepository(ctx, runCtx, input);
       const head = normalizeOptionalToolString(input.head);
       const base = normalizeOptionalToolString(input.base);
       const title = normalizeOptionalToolString(input.title);
@@ -12752,6 +13175,32 @@ function registerGitHubAgentTools(ctx) {
           "X-GitHub-Api-Version": GITHUB_API_VERSION
         }
       });
+      if (paperclipIssueId) {
+        const linkScope = issueLinkScope ?? await resolveIssueGitHubLinkMapping(ctx, {
+          companyId: runCtx.companyId,
+          issueId: paperclipIssueId,
+          repositoryUrl: repository.url
+        });
+        const pullRequestUrl = normalizeGitHubPullRequestHtmlUrl(response.data.html_url) ?? `${repository.url}/pull/${response.data.number}`;
+        await upsertGitHubPullRequestLinkRecord(ctx, {
+          companyId: runCtx.companyId,
+          projectId: linkScope.mapping.paperclipProjectId ?? linkScope.projectId,
+          issueId: paperclipIssueId,
+          repositoryUrl: repository.url,
+          pullRequestNumber: response.data.number,
+          pullRequestUrl,
+          pullRequestTitle: response.data.title || title,
+          pullRequestState: getGitHubPullRequestStateForLink({
+            state: response.data.state,
+            merged: false
+          })
+        });
+        invalidateProjectPullRequestCaches({
+          companyId: runCtx.companyId,
+          projectId: linkScope.mapping.paperclipProjectId ?? linkScope.projectId,
+          repository
+        });
+      }
       await persistCompanyActivityMetricEvent(
         ctx,
         {
@@ -13346,6 +13795,34 @@ var plugin = definePlugin({
       const record = input && typeof input === "object" ? input : {};
       return buildCommentAnnotationData(ctx, record);
     });
+    ctx.actions.register("issue.linkGitHubItem", async (input) => {
+      const record = input && typeof input === "object" ? input : {};
+      const kind = normalizeIssueGitHubLinkKind(record.kind);
+      if (!kind) {
+        throw new Error('kind must be "issue" or "pull_request".');
+      }
+      const companyId = normalizeCompanyId(record.companyId);
+      const issueId = normalizeOptionalString2(record.issueId);
+      if (!companyId || !issueId) {
+        throw new Error("companyId and issueId are required.");
+      }
+      return kind === "issue" ? linkPaperclipIssueToGitHubIssue(ctx, {
+        companyId,
+        issueId,
+        reference: record.reference,
+        repositoryUrl: normalizeOptionalString2(record.repository),
+        issueNumber: record.issueNumber,
+        requireUnlinked: true
+      }) : linkPaperclipIssueToGitHubPullRequest(ctx, {
+        companyId,
+        issueId,
+        reference: record.reference,
+        repositoryUrl: normalizeOptionalString2(record.repository),
+        pullRequestNumber: record.pullRequestNumber,
+        pullRequestUrl: record.pullRequestUrl,
+        requireUnlinked: true
+      });
+    });
     ctx.actions.register("settings.saveRegistration", async (input) => {
       const previous = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
       const config = await getResolvedConfig(ctx);