paperclip-github-plugin 0.7.3 → 0.7.4

package/README.md

@@ -35,7 +35,7 @@ The plugin adds a full in-host workflow instead of a one-off import script:
 - saved sync diagnostics that let operators inspect the latest per-issue failures, raw errors, and suggested next steps
 - a project sidebar item that opens a live project-scoped Pull Requests page for the mapped repository and can show the open PR count through a lightweight badge read
 - manual sync actions from global, project, and issue surfaces
-- a GitHub detail tab on synced Paperclip issues that stays hidden for Paperclip issues with no linked GitHub issue and includes GitHub-marked action buttons plus the GitHub issue creator with avatar
+- a GitHub detail tab on synced Paperclip issues that includes GitHub-marked action buttons plus the GitHub issue creator with avatar, and lets operators manually link an unlinked Paperclip issue to a GitHub issue or pull request
 - GitHub link annotations on sync-generated status transition comments when the host supports comment annotations
 
 ## How it works
@@ -68,7 +68,7 @@ The plugin does more than mirror issue text. It looks at linked pull requests, m
 
 GitHub Sync exposes a dedicated KPI dashboard widget alongside the operational sync widget. During full company syncs, the worker snapshots the current open GitHub backlog and records when already-imported GitHub issues move from open to closed. The KPI widget turns that worker-owned state into backlog, issue-closure, and Paperclip PR-creation cards with recent history and comparisons against older periods.
 
-Because GitHub alone cannot tell which pull requests came from a Paperclip company, the plugin uses explicit Paperclip attribution for delivery activity. `create_pull_request` automatically records a Paperclip-created PR event, and agents that use `gh` or another non-plugin GitHub client can post pull-request-created events to the plugin API route so the KPI history stays specific to Paperclip work.
+Because GitHub alone cannot tell which pull requests came from a Paperclip company, the plugin uses explicit Paperclip attribution for delivery activity. `create_pull_request` automatically records a Paperclip-created PR event, and agents that use `gh` or another non-plugin GitHub client can post pull-request-created events to the plugin API route so the KPI history stays specific to Paperclip work. When either path includes the Paperclip issue id, GitHub Sync also records the pull request link so later sync runs can move that issue based on PR CI, merge state, and review activity.
 
 That API route path matters on authenticated Paperclip deployments today because a current host bug blocks agents from calling plugin tools unless the instance runs in `local_trusted` mode. Those agents can still use `gh` with the propagated `GITHUB_TOKEN`, then call the agent-authenticated plugin API route from the shell after they create a PR. The Paperclip host authenticates `Authorization: Bearer <PAPERCLIP_API_KEY>`, scopes the request to the calling agent's company, and rejects anonymous or non-agent calls before dispatching to the worker.
 
@@ -78,10 +78,16 @@ Each mapped project can expose a **Pull Requests** entry in the sidebar that ope
 
 Paperclip issue linkage on the queue prefers the GitHub issue that the pull request closes, so imported GitHub issues and delivery work stay connected in the same project view. If a pull request has no closing-issue-backed link yet, the queue falls back to the Paperclip issue created directly from that pull request and updates the table immediately when that create action returns.
 
-Those pull-request-created Paperclip issues also stay in the scheduled/manual sync loop even when the pull request does not close a GitHub issue. GitHub Sync checks their CI, merge state, and review threads so new failures or unresolved feedback move the Paperclip issue back into active work.
+Those pull-request-created Paperclip issues also stay in the scheduled/manual sync loop even when the pull request does not close a GitHub issue. GitHub Sync checks their CI, merge state, and review threads so new failures or unresolved feedback move the Paperclip issue back into active work. The same durable PR link is written when an agent creates a PR through the plugin tool with `paperclipIssueId`, when an authenticated agent records a `gh`-created PR through the agent API route with `paperclipIssueId`, or when an operator manually links an unlinked issue from the issue page.
 
 The issue detail panel and sync-created comment annotations also preserve cross-repository linked pull requests, showing those PRs with their real repository path so operators land in the right place on GitHub.
 
+### Manual GitHub links
+
+If a Paperclip issue was created locally or by an agent workflow before GitHub Sync saw the matching GitHub item, the issue detail surface shows a **Link GitHub item** action. The modal accepts either a GitHub issue number or full issue URL, or a pull request number or full pull request URL. Number-only entries use the issue's mapped Paperclip project repository; full URLs can point at any repository mapped to that project.
+
+Manual GitHub issue links are added to the same import registry and issue-link entity used by normal sync, so future syncs update the Paperclip issue from the GitHub issue. Manual pull request links are added to the PR-link entity used by the project Pull Requests page, so future syncs monitor PR status even when there is no closing GitHub issue.
+
 ### Agent workflows built in
 
 Paperclip agents can search GitHub for duplicates, read and update issues, post comments, create pull requests, inspect changed files and CI, reply to review threads, resolve or unresolve threads, request reviewers, search org-level GitHub Projects, and associate pull requests with those projects without leaving the Paperclip plugin surface.
@@ -219,6 +225,7 @@ Supported payload fields:
 - `repository` optional: `owner/repo` or `https://github.com/owner/repo`
 - `pullRequestNumber` optional
 - `pullRequestUrl` optional
+- `paperclipIssueId` optional: the Paperclip issue id that should be linked to the pull request for future PR-status sync
 - `occurredAt` optional ISO timestamp
 - `eventKey` optional custom dedupe key
 - `count` optional positive integer
@@ -232,7 +239,7 @@ The Paperclip host validates that bearer token and passes the authenticated agen
 Example:
 
 ```bash
-payload='{"metric":"pull_request_created","repository":"paperclipai/example-repo","pullRequestNumber":21}'
+payload='{"metric":"pull_request_created","repository":"paperclipai/example-repo","pullRequestNumber":21,"paperclipIssueId":"iss_123"}'
 
 curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/api/company-metrics/events" \
   -H "content-type: application/json" \
@@ -240,7 +247,7 @@ curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/api/com
   -d "${payload}"
 ```
 
-The worker deduplicates repeated PR events by preferring the pull request URL, then `repository + pullRequestNumber`, before falling back to the explicit `eventKey`.
+The worker deduplicates repeated PR events by preferring the pull request URL, then `repository + pullRequestNumber`, before falling back to the explicit `eventKey`. When `paperclipIssueId` is present, the worker verifies the live pull request and persists the same PR-link metadata used by scheduled/manual status syncs.
 
 Current host caveat: on authenticated Paperclip deployments, the Paperclip host currently guards `GET /api/plugins/tools` and `POST /api/plugins/tools/execute` with board authentication before dispatching to any plugin worker. If an agent run does not have board access for the target company, GitHub Sync tool discovery and execution fail with `403 {"error":"Board access required"}` before this plugin's worker code runs.
 

package/dist/manifest.js

@@ -246,6 +246,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."
@@ -516,7 +520,7 @@ var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/a
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.7.3"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.7.4"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
   id: GITHUB_SYNC_PLUGIN_ID,
   apiVersion: 1,

package/dist/ui/index.js

@@ -26778,6 +26778,113 @@ var EXTENSION_SURFACE_STYLES = `
     margin: 0;
   }
 
+  .ghsync__field {
+    display: grid;
+    gap: 8px;
+  }
+
+  .ghsync__field label {
+    color: var(--ghsync-title);
+    font-size: 12px;
+    font-weight: 600;
+  }
+
+  .ghsync__input {
+    width: 100%;
+    min-height: 40px;
+    border-radius: 8px;
+    border: 1px solid var(--ghsync-input-border);
+    background: var(--ghsync-input-bg);
+    color: var(--ghsync-input-text);
+    padding: 0 12px;
+    outline: none;
+  }
+
+  .ghsync__input::placeholder {
+    color: var(--ghsync-muted);
+  }
+
+  .ghsync__input:focus {
+    border-color: var(--ghsync-border);
+  }
+
+  .ghsync-link-modal-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 50;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+    background: rgba(10, 10, 12, 0.48);
+    backdrop-filter: blur(10px);
+  }
+
+  .ghsync-link-modal {
+    width: min(520px, 100%);
+    display: grid;
+    gap: 16px;
+    padding: 18px;
+    border-radius: 8px;
+    border: 1px solid var(--ghsync-border);
+    background: var(--ghsync-surface);
+    color: var(--ghsync-text);
+    box-shadow: 0 28px 80px rgba(2, 6, 23, 0.34);
+  }
+
+  .ghsync-prs-modal__header {
+    display: grid;
+    gap: 6px;
+  }
+
+  .ghsync-prs-modal__header h3 {
+    margin: 0;
+    color: var(--ghsync-title);
+    font-size: 18px;
+  }
+
+  .ghsync-prs-modal__header p {
+    margin: 0;
+    color: var(--ghsync-muted);
+    font-size: 12px;
+    line-height: 1.5;
+  }
+
+  .ghsync-prs-modal__actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+    flex-wrap: wrap;
+  }
+
+  .ghsync-link-kind {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 6px;
+    padding: 4px;
+    border-radius: 8px;
+    border: 1px solid var(--ghsync-border-soft);
+    background: var(--ghsync-surfaceAlt);
+  }
+
+  .ghsync-link-kind__button {
+    min-height: 34px;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--ghsync-muted);
+    font: inherit;
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+
+  .ghsync-link-kind__button--active {
+    background: var(--ghsync-surface);
+    color: var(--ghsync-title);
+    box-shadow: inset 0 0 0 1px var(--ghsync-border);
+  }
+
   ${SHARED_LOADING_STYLES}
 `;
 function createEmptyMapping(index2) {
@@ -34523,7 +34630,8 @@ function GitHubSyncIssueDetailTabContent(props) {
     loadingIssueId: props.loadingIssueId,
     detailsLoading: details.loading,
     detailsError: Boolean(details.error),
-    issueDetails
+    issueDetails,
+    canLinkManually: Boolean(props.companyId && props.issueId)
   });
   const issueSyncButton = useGitHubSyncButtonController({
     companyId: props.companyId,
@@ -34532,6 +34640,12 @@ function GitHubSyncIssueDetailTabContent(props) {
     resolvedIssueId: props.issueId,
     forceVisible: true
   });
+  const linkGitHubItem = usePluginAction("issue.linkGitHubItem");
+  const toast = usePluginToast();
+  const [manualLinkOpen, setManualLinkOpen] = useState2(false);
+  const [manualLinkKind, setManualLinkKind] = useState2("issue");
+  const [manualLinkReference, setManualLinkReference] = useState2("");
+  const [manualLinkPending, setManualLinkPending] = useState2(false);
   useEffect2(() => {
     if (!props.companyId || !props.issueId) {
       return;
@@ -34546,18 +34660,77 @@ function GitHubSyncIssueDetailTabContent(props) {
     return null;
   }
   const linkedPullRequests = issueDetails ? getLinkedPullRequestsForIssueDetails(issueDetails) : [];
+  const issueDetailsKind = issueDetails?.kind ?? "issue";
+  const githubUrl = issueDetailsKind === "pull_request" ? issueDetails?.githubPullRequestUrl : issueDetails?.githubIssueUrl;
+  const githubStateLabel = issueDetailsKind === "pull_request" ? issueDetails?.githubPullRequestState === "closed" ? "Closed" : "Open" : formatGitHubIssueState(issueDetails?.githubIssueState, issueDetails?.githubIssueStateReason);
+  function closeManualLinkModal() {
+    if (manualLinkPending) {
+      return;
+    }
+    setManualLinkOpen(false);
+    setManualLinkReference("");
+    setManualLinkKind("issue");
+  }
+  async function handleManualLinkSubmit() {
+    if (!props.companyId || !props.issueId || !manualLinkReference.trim()) {
+      return;
+    }
+    setManualLinkPending(true);
+    try {
+      const result = await linkGitHubItem({
+        companyId: props.companyId,
+        issueId: props.issueId,
+        kind: manualLinkKind,
+        reference: manualLinkReference.trim()
+      });
+      setManualLinkOpen(false);
+      setManualLinkReference("");
+      await details.refresh();
+      notifyGitHubSyncPullRequestsChanged();
+      toast({
+        title: "GitHub link saved",
+        body: result.kind === "pull_request" ? `Linked pull request #${result.githubPullRequestNumber ?? manualLinkReference.trim()}.` : `Linked issue #${result.githubIssueNumber ?? manualLinkReference.trim()}.`,
+        tone: "success"
+      });
+    } catch (error) {
+      toast({
+        title: "Unable to link GitHub item",
+        body: getActionErrorMessage(error, "GitHub Sync could not save this link."),
+        tone: "error"
+      });
+    } finally {
+      setManualLinkPending(false);
+    }
+  }
   return /* @__PURE__ */ jsxs2("section", { className: "ghsync-issue-detail", style: props.themeVars, children: [
     /* @__PURE__ */ jsx2("style", { children: EXTENSION_SURFACE_STYLES }),
     detailTabState === "loading" ? /* @__PURE__ */ jsx2("p", { className: "ghsync-extension-empty", children: "Loading GitHub sync details\u2026" }) : null,
     detailTabState === "error" && details.error ? /* @__PURE__ */ jsx2("p", { className: "ghsync-extension-empty", children: details.error.message }) : null,
+    detailTabState === "unlinked" ? /* @__PURE__ */ jsx2("div", { className: "ghsync-issue-detail__intro", children: /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-heading", children: [
+      /* @__PURE__ */ jsxs2("div", { className: "ghsync-issue-detail__headline", children: [
+        /* @__PURE__ */ jsx2("h4", { children: "GitHub link" }),
+        /* @__PURE__ */ jsx2("p", { children: "No GitHub issue or pull request is linked to this Paperclip issue yet." })
+      ] }),
+      /* @__PURE__ */ jsx2("div", { className: "ghsync-issue-detail__actions", children: /* @__PURE__ */ jsx2(
+        "button",
+        {
+          type: "button",
+          className: getPluginActionClassName({
+            variant: "secondary",
+            size: "sm",
+            extraClassName: "ghsync-extension-link"
+          }),
+          onClick: () => setManualLinkOpen(true),
+          children: /* @__PURE__ */ jsx2(GitHubButtonLabel, { label: "Link GitHub item" })
+        }
+      ) })
+    ] }) }) : null,
     detailTabState === "ready" && issueDetails ? /* @__PURE__ */ jsxs2(Fragment2, { children: [
       /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-heading", children: [
         /* @__PURE__ */ jsxs2("div", { className: "ghsync-issue-detail__headline", children: [
-          /* @__PURE__ */ jsxs2("h4", { children: [
-            "Issue #",
-            issueDetails.githubIssueNumber
-          ] }),
+          /* @__PURE__ */ jsx2("h4", { children: issueDetailsKind === "pull_request" ? `Pull request #${issueDetails.githubPullRequestNumber ?? ""}` : `Issue #${issueDetails.githubIssueNumber ?? ""}` }),
           /* @__PURE__ */ jsx2("p", { children: formatGitHubRepositoryLabel(issueDetails.repositoryUrl) }),
+          issueDetailsKind === "pull_request" && issueDetails.title ? /* @__PURE__ */ jsx2("p", { children: issueDetails.title }) : null,
           issueDetails.creator ? /* @__PURE__ */ jsxs2("div", { className: "ghsync-issue-detail__creator-row", children: [
             /* @__PURE__ */ jsx2("span", { className: "ghsync-issue-detail__creator-label", children: "Creator" }),
             /* @__PURE__ */ jsxs2(
@@ -34599,10 +34772,10 @@ function GitHubSyncIssueDetailTabContent(props) {
               )
             }
           ) : null,
-          /* @__PURE__ */ jsx2(
+          githubUrl ? /* @__PURE__ */ jsx2(
             "a",
             {
-              href: issueDetails.githubIssueUrl,
+              href: githubUrl,
               target: "_blank",
               rel: "noreferrer",
               className: getPluginActionClassName({
@@ -34612,17 +34785,17 @@ function GitHubSyncIssueDetailTabContent(props) {
               }),
               children: /* @__PURE__ */ jsx2(GitHubButtonLabel, { label: "Open on GitHub" })
             }
-          )
+          ) : null
         ] })
       ] }),
       /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-grid", children: [
         /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-metric", children: [
           /* @__PURE__ */ jsx2("span", { children: "State" }),
-          /* @__PURE__ */ jsx2("strong", { children: formatGitHubIssueState(issueDetails.githubIssueState, issueDetails.githubIssueStateReason) })
+          /* @__PURE__ */ jsx2("strong", { children: githubStateLabel })
         ] }),
         /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-metric", children: [
-          /* @__PURE__ */ jsx2("span", { children: "Comments" }),
-          /* @__PURE__ */ jsx2("strong", { children: issueDetails.commentsCount ?? "Unknown" })
+          /* @__PURE__ */ jsx2("span", { children: "Type" }),
+          /* @__PURE__ */ jsx2("strong", { children: issueDetailsKind === "pull_request" ? "Pull request" : "Issue" })
         ] }),
         /* @__PURE__ */ jsxs2("div", { className: "ghsync-extension-metric", children: [
           /* @__PURE__ */ jsx2("span", { children: "Linked PRs" }),
@@ -34656,7 +34829,7 @@ function GitHubSyncIssueDetailTabContent(props) {
           `${pullRequest.repositoryUrl}:${pullRequest.number}`
         )) })
       ] }) : null,
-      issueDetails.labels && issueDetails.labels.length > 0 ? /* @__PURE__ */ jsxs2("div", { className: "ghsync-issue-detail__section", children: [
+      issueDetails.kind !== "pull_request" && issueDetails.labels && issueDetails.labels.length > 0 ? /* @__PURE__ */ jsxs2("div", { className: "ghsync-issue-detail__section", children: [
         /* @__PURE__ */ jsx2("div", { className: "ghsync-issue-detail__section-heading", children: "Labels" }),
         /* @__PURE__ */ jsx2("div", { className: "ghsync-extension-labels", children: issueDetails.labels.map((label) => /* @__PURE__ */ jsx2(
           "span",
@@ -34668,8 +34841,84 @@ function GitHubSyncIssueDetailTabContent(props) {
           `${label.name}:${label.color ?? "none"}`
         )) })
       ] }) : null,
-      issueDetails.source !== "entity" ? /* @__PURE__ */ jsx2("div", { className: "ghsync-extension-note", children: "GitHub Sync recovered this link from older sync metadata. Run sync once to refresh the creator, GitHub state, labels, and linked PRs in this panel." }) : null
-    ] }) : null
+      issueDetails.kind !== "pull_request" && issueDetails.source !== "entity" ? /* @__PURE__ */ jsx2("div", { className: "ghsync-extension-note", children: "GitHub Sync recovered this link from older sync metadata. Run sync once to refresh the creator, GitHub state, labels, and linked PRs in this panel." }) : null
+    ] }) : null,
+    manualLinkOpen ? /* @__PURE__ */ jsx2("div", { className: "ghsync-link-modal-backdrop", onClick: closeManualLinkModal, children: /* @__PURE__ */ jsxs2(
+      "div",
+      {
+        className: "ghsync-link-modal",
+        role: "dialog",
+        "aria-modal": "true",
+        "aria-labelledby": "ghsync-link-modal-title",
+        onClick: (event) => event.stopPropagation(),
+        children: [
+          /* @__PURE__ */ jsxs2("div", { className: "ghsync-prs-modal__header", children: [
+            /* @__PURE__ */ jsx2("h3", { id: "ghsync-link-modal-title", children: "Link GitHub item" }),
+            /* @__PURE__ */ jsx2("p", { children: "Enter a GitHub issue or pull request number from the mapped repository, or paste the full GitHub URL." })
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { className: "ghsync-link-kind", role: "group", "aria-label": "GitHub item type", children: [
+            /* @__PURE__ */ jsx2(
+              "button",
+              {
+                type: "button",
+                className: manualLinkKind === "issue" ? "ghsync-link-kind__button ghsync-link-kind__button--active" : "ghsync-link-kind__button",
+                onClick: () => setManualLinkKind("issue"),
+                disabled: manualLinkPending,
+                children: "Issue"
+              }
+            ),
+            /* @__PURE__ */ jsx2(
+              "button",
+              {
+                type: "button",
+                className: manualLinkKind === "pull_request" ? "ghsync-link-kind__button ghsync-link-kind__button--active" : "ghsync-link-kind__button",
+                onClick: () => setManualLinkKind("pull_request"),
+                disabled: manualLinkPending,
+                children: "Pull request"
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { className: "ghsync__field", children: [
+            /* @__PURE__ */ jsx2("label", { htmlFor: "ghsync-link-reference", children: manualLinkKind === "pull_request" ? "Pull request number or URL" : "Issue number or URL" }),
+            /* @__PURE__ */ jsx2(
+              "input",
+              {
+                id: "ghsync-link-reference",
+                className: "ghsync__input",
+                value: manualLinkReference,
+                onChange: (event) => setManualLinkReference(event.currentTarget.value),
+                placeholder: manualLinkKind === "pull_request" ? "89 or https://github.com/owner/repo/pull/89" : "88 or https://github.com/owner/repo/issues/88",
+                disabled: manualLinkPending
+              }
+            )
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { className: "ghsync-prs-modal__actions", children: [
+            /* @__PURE__ */ jsx2(
+              "button",
+              {
+                type: "button",
+                className: getPluginActionClassName({ variant: "secondary", size: "sm" }),
+                onClick: closeManualLinkModal,
+                disabled: manualLinkPending,
+                children: "Cancel"
+              }
+            ),
+            /* @__PURE__ */ jsx2(
+              "button",
+              {
+                type: "button",
+                className: getPluginActionClassName({ variant: "primary", size: "sm" }),
+                onClick: () => {
+                  void handleManualLinkSubmit();
+                },
+                disabled: !manualLinkReference.trim() || manualLinkPending,
+                children: /* @__PURE__ */ jsx2(LoadingButtonContent, { busy: manualLinkPending, label: "Link", busyLabel: "Linking" })
+              }
+            )
+          ] })
+        ]
+      }
+    ) }) : null
   ] });
 }
 function resolveGitHubIssueDetailTabState(params) {
@@ -34682,6 +34931,9 @@ function resolveGitHubIssueDetailTabState(params) {
   if (params.detailsError) {
     return "error";
   }
+  if (params.canLinkManually) {
+    return "unlinked";
+  }
   return "hidden";
 }
 function GitHubSyncIssueTaskDetailView() {