paperclip-github-plugin 0.8.8 → 0.8.9

package/README.md

@@ -215,6 +215,12 @@ Notes:
 - The raw token is never persisted back into plugin state or plugin config.
 - A GitHub token secret saved through the settings UI takes precedence over the local file.
 
+### Worker-facing Paperclip API URL
+
+GitHub Sync uses direct worker-side Paperclip REST calls for host paths that are not fully covered by the plugin SDK, such as label reconciliation and some issue repair paths. By default, manual setup and sync actions use the current browser origin. If that origin is not reachable from the plugin worker, set **Worker Paperclip API URL** in GitHub Sync settings; the value is saved internally as plugin config `paperclipApiBaseUrl`.
+
+For private LAN, Docker, Kubernetes, custom DNS, or self-signed-certificate deployments, set that field to a local route the plugin worker can reach, such as `http://localhost:3100`, and port-forward or route that address to the Paperclip API when needed. Do not rely on exporting a process environment variable named `PAPERCLIP_API_URL` to Paperclip; Paperclip `2026.428.0` does not pass that value through to plugin worker runtime.
+
 ## GitHub agent tools
 
 The plugin exposes GitHub workflow tools to Paperclip agents, including:
@@ -296,9 +302,10 @@ curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/api/iss
 - If Paperclip says board access is required, open plugin settings inside the affected company and complete the Paperclip board access flow before retrying sync.
 - If GitHub Sync agent tools fail with `403 {"error":"Board access required"}` on `/api/plugins/tools` or `/api/plugins/tools/execute`, the current Paperclip host rejected the request before the plugin worker ran. Re-run from a board-authenticated session or agent run that has board access to the target company.
 - If a KPI API route call is rejected, make sure the request includes `Authorization: Bearer ${PAPERCLIP_API_KEY}`, that the token is still valid for the current run, and that any `companyId` in the payload matches the calling agent's company.
-- If the worker reaches an authenticated HTML page instead of the Paperclip API JSON responses it expects, connect Paperclip board access for that company or set `PAPERCLIP_API_URL` to a worker-accessible Paperclip API origin.
+- If the worker reaches an authenticated HTML page instead of the Paperclip API JSON responses it expects, connect Paperclip board access for that company or set **Worker Paperclip API URL** in GitHub Sync settings to a worker-accessible Paperclip API origin.
+- If a Paperclip API fetch fails before any HTTP response is returned, the saved diagnostics include the method, URL, primary error, nested cause, and cause code when Node exposes them.
 - If a sync run finishes with partial failures, open the saved troubleshooting panel in GitHub Sync to inspect the repository, issue number, raw error, and suggested fix for each recorded failure.
-- If sync says the Paperclip API URL is not trusted, reopen the plugin from the current Paperclip host so the settings UI can refresh the saved origin, or set `PAPERCLIP_API_URL` for the worker.
+- If sync says the Paperclip API URL is not trusted, set **Worker Paperclip API URL** in GitHub Sync settings to the worker-accessible Paperclip API origin and retry.
 - If a pull request comment or review action is rejected, read the full toast message. Fine-grained GitHub tokens need write access to that repository, and GitHub requires a review summary when requesting changes.
 - If a GitHub-linked project does not show the **Pull requests** sidebar entry, reopen the plugin settings and re-save the mapping. The project pull request surfaces also recover older mappings when saved ids are missing, and they can fall back to the active project's bound GitHub repository when the project already has a GitHub workspace configured.
 - If GitHub rate limiting is hit, the plugin pauses sync until the reported reset time instead of retrying pointlessly.

package/dist/manifest.js

@@ -587,7 +587,7 @@ var ISSUE_LINK_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.8.8"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.8.9"?.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

@@ -22694,6 +22694,9 @@ function normalizePluginConfig(value) {
   }
   return record;
 }
+function resolvePaperclipApiBaseUrlForPluginAction(value, fallbackOrigin) {
+  return normalizePluginConfig(value).paperclipApiBaseUrl ?? normalizePaperclipApiBaseUrl(fallbackOrigin);
+}
 function mergePluginConfig(currentValue, patch5) {
   const current = normalizePluginConfig(currentValue);
   const currentGitHubTokenRefs = normalizePluginConfigGitHubTokenRefs(current.githubTokenRefs);
@@ -27577,7 +27580,7 @@ function shouldAutofillProjectName(mapping) {
   const previousSuggestedProjectName = formatProjectNameFromRepository(mapping.repositoryUrl);
   return previousSuggestedProjectName !== "" && currentProjectName === previousSuggestedProjectName;
 }
-function getPaperclipApiBaseUrl() {
+function getPaperclipApiBrowserOrigin() {
   if (typeof window === "undefined" || !window.location?.origin) {
     return void 0;
   }
@@ -27616,23 +27619,22 @@ async function fetchPluginDataResult(params) {
   return response.data;
 }
 async function syncTrustedPaperclipApiBaseUrl(pluginId) {
-  const paperclipApiBaseUrl = getPaperclipApiBaseUrl();
-  if (!paperclipApiBaseUrl) {
-    return void 0;
-  }
   const resolvedPluginId = await resolveCurrentPluginId(pluginId);
   if (!resolvedPluginId) {
     throw new Error(
       "Unable to sync the trusted Paperclip API origin because the plugin ID is missing. Reload the plugin and try again before saving or syncing."
     );
   }
+  const currentConfigResponse = await fetchJson(`/api/plugins/${resolvedPluginId}/config`);
+  const currentConfig = normalizePluginConfig(currentConfigResponse?.configJson);
+  const paperclipApiBaseUrl = resolvePaperclipApiBaseUrlForPluginAction(currentConfig, getPaperclipApiBrowserOrigin());
+  if (!paperclipApiBaseUrl) {
+    return void 0;
+  }
   const lastSyncedPaperclipApiBaseUrl = syncedPaperclipApiBaseUrlsByPluginId.get(resolvedPluginId);
   if (lastSyncedPaperclipApiBaseUrl === paperclipApiBaseUrl) {
     return paperclipApiBaseUrl;
   }
-  await patchPluginConfig(resolvedPluginId, {
-    paperclipApiBaseUrl
-  });
   syncedPaperclipApiBaseUrlsByPluginId.set(resolvedPluginId, paperclipApiBaseUrl);
   return paperclipApiBaseUrl;
 }
@@ -31964,6 +31966,7 @@ function GitHubSyncSettingsPage() {
   const [cancellingSync, setCancellingSync] = useState2(false);
   const [manualSyncRequestError, setManualSyncRequestError] = useState2(null);
   const [scheduleFrequencyDraft, setScheduleFrequencyDraft] = useState2(String(DEFAULT_SCHEDULE_FREQUENCY_MINUTES));
+  const [paperclipApiBaseUrlDraft, setPaperclipApiBaseUrlDraft] = useState2("");
   const [ignoredAuthorsDraft, setIgnoredAuthorsDraft] = useState2(DEFAULT_ADVANCED_SETTINGS.ignoredIssueAuthorUsernames.join(", "));
   const [tokenStatusOverride, setTokenStatusOverride] = useState2(null);
   const [validatedLogin, setValidatedLogin] = useState2(null);
@@ -32012,6 +32015,9 @@ function GitHubSyncSettingsPage() {
       updatedAt: settings.data.updatedAt
     });
     setScheduleFrequencyDraft(String(nextScheduleFrequencyMinutes));
+    setPaperclipApiBaseUrlDraft(
+      settings.data.paperclipApiBaseUrlConfigured ? settings.data.paperclipApiBaseUrl ?? "" : getPaperclipApiBrowserOrigin() ?? ""
+    );
     setIgnoredAuthorsDraft(normalizeAdvancedSettings(settings.data.advancedSettings).ignoredIssueAuthorUsernames.join(", "));
     setTokenDraft("");
     setValidatedLogin(tokenUiState.validatedLogin);
@@ -32283,12 +32289,21 @@ function GitHubSyncSettingsPage() {
   const scheduleFrequencyMinutes = parseScheduleFrequencyDraft(scheduleFrequencyDraft) ?? form.scheduleFrequencyMinutes;
   const savedScheduleFrequencyMinutes = normalizeScheduleFrequencyMinutes(currentSettings?.scheduleFrequencyMinutes);
   const scheduleDirty = scheduleFrequencyError === null && scheduleFrequencyMinutes !== savedScheduleFrequencyMinutes;
+  const browserPaperclipApiBaseUrl = getPaperclipApiBrowserOrigin();
+  const normalizedPaperclipApiBaseUrlDraft = normalizePaperclipApiBaseUrl(paperclipApiBaseUrlDraft);
+  const paperclipApiBaseUrlError = paperclipApiBaseUrlDraft.trim() && !normalizedPaperclipApiBaseUrlDraft ? "Enter a valid URL." : null;
+  const effectivePaperclipApiBaseUrl = normalizedPaperclipApiBaseUrlDraft ?? browserPaperclipApiBaseUrl;
+  const paperclipApiBaseUrlIsOverride = Boolean(
+    normalizedPaperclipApiBaseUrlDraft && browserPaperclipApiBaseUrl && normalizedPaperclipApiBaseUrlDraft !== browserPaperclipApiBaseUrl
+  );
+  const savedPaperclipApiBaseUrl = currentSettings?.paperclipApiBaseUrlConfigured ? currentSettings.paperclipApiBaseUrl ?? "" : browserPaperclipApiBaseUrl ?? "";
+  const paperclipApiBaseUrlDirty = paperclipApiBaseUrlError === null && (normalizedPaperclipApiBaseUrlDraft ?? "") !== savedPaperclipApiBaseUrl;
   const mappings = form.mappings.length > 0 ? form.mappings : [createEmptyMapping(0)];
   const settingsMutationsLocked = syncInFlight;
   const settingsMutationsLockReason = settingsMutationsLocked ? "Settings are temporarily locked while a sync is running to avoid overwriting local edits." : null;
   const syncStatus = getSyncStatus(displaySyncState, runningSync, syncUnlocked);
   const canSaveToken = hasCompanyContext && !settingsMutationsLocked && !submittingToken && !showInitialLoadingState && tokenDraft.trim().length > 0;
-  const canSaveSetup = hasCompanyContext && repositoriesUnlocked && !settingsMutationsLocked && !submittingSetup && !showInitialLoadingState && scheduleFrequencyError === null && (mappingsDirty || advancedSettingsDirty || scheduleDirty);
+  const canSaveSetup = hasCompanyContext && repositoriesUnlocked && !settingsMutationsLocked && !submittingSetup && !showInitialLoadingState && scheduleFrequencyError === null && paperclipApiBaseUrlError === null && (mappingsDirty || advancedSettingsDirty || scheduleDirty || paperclipApiBaseUrlDirty);
   const canConnectBoardAccess = hasCompanyContext && !settingsMutationsLocked && !connectingBoardAccess && !showInitialLoadingState;
   const boardAccessStatusLabel = !hasCompanyContext ? "Unavailable" : boardAccessBannerLabel;
   const boardAccessStatusTone = !hasCompanyContext ? boardAccessRequired ? "warning" : "neutral" : boardAccessTone;
@@ -32693,6 +32708,9 @@ function GitHubSyncSettingsPage() {
       if (scheduleFrequencyError) {
         throw new Error(scheduleFrequencyError);
       }
+      if (paperclipApiBaseUrlError) {
+        throw new Error(paperclipApiBaseUrlError);
+      }
       const resolvedMappings = [];
       for (const mapping of form.mappings) {
         const repositoryInput = mapping.repositoryUrl.trim();
@@ -32717,7 +32735,18 @@ function GitHubSyncSettingsPage() {
           companyId
         });
       }
-      const trustedPaperclipApiBaseUrl = await syncTrustedPaperclipApiBaseUrl(pluginIdFromLocation);
+      const pluginId = await resolveCurrentPluginId(pluginIdFromLocation);
+      if (!pluginId) {
+        throw new Error("Plugin id is required to save setup.");
+      }
+      const trustedPaperclipApiBaseUrl = effectivePaperclipApiBaseUrl;
+      if (!trustedPaperclipApiBaseUrl) {
+        throw new Error("Could not resolve the current browser origin for Paperclip API calls.");
+      }
+      const nextConfiguredPaperclipApiBaseUrl = paperclipApiBaseUrlIsOverride ? normalizedPaperclipApiBaseUrlDraft ?? "" : "";
+      await patchPluginConfig(pluginId, {
+        paperclipApiBaseUrl: nextConfiguredPaperclipApiBaseUrl
+      });
       const result = await saveRegistration({
         companyId,
         mappings: resolvedMappings,
@@ -32743,9 +32772,11 @@ function GitHubSyncSettingsPage() {
         advancedSettings: normalizeAdvancedSettings(result.advancedSettings),
         availableAssignees: result.availableAssignees ?? current.availableAssignees,
         paperclipApiBaseUrl: result.paperclipApiBaseUrl,
+        paperclipApiBaseUrlConfigured: paperclipApiBaseUrlIsOverride,
         updatedAt: result.updatedAt
       }));
       setScheduleFrequencyDraft(String(normalizeScheduleFrequencyMinutes(result.scheduleFrequencyMinutes)));
+      setPaperclipApiBaseUrlDraft(paperclipApiBaseUrlIsOverride ? nextConfiguredPaperclipApiBaseUrl : trustedPaperclipApiBaseUrl);
       toast({
         title: "GitHub sync setup saved",
         body: `Advanced defaults, mappings, and automatic sync are saved for ${currentCompanyName}.`,
@@ -33423,6 +33454,32 @@ function GitHubSyncSettingsPage() {
                 ] })
               ] })
             ] }),
+            /* @__PURE__ */ jsxs2("div", { className: "ghsync__schedule-card", children: [
+              /* @__PURE__ */ jsxs2("div", { className: "ghsync__field", children: [
+                /* @__PURE__ */ jsx2("label", { htmlFor: "paperclip-api-base-url", children: "Worker Paperclip API URL" }),
+                /* @__PURE__ */ jsx2(
+                  "input",
+                  {
+                    id: "paperclip-api-base-url",
+                    className: "ghsync__input",
+                    type: "url",
+                    value: paperclipApiBaseUrlDraft,
+                    disabled: settingsMutationsLocked || !hasCompanyContext,
+                    onChange: (event) => {
+                      setPaperclipApiBaseUrlDraft(event.currentTarget.value);
+                    },
+                    placeholder: browserPaperclipApiBaseUrl ?? "https://paperclip.example.com",
+                    autoComplete: "off"
+                  }
+                ),
+                /* @__PURE__ */ jsx2("p", { className: `ghsync__hint${paperclipApiBaseUrlError ? " ghsync__hint--error" : ""}`, children: paperclipApiBaseUrlError ?? "Edit this only when the plugin worker needs a different Paperclip API origin." })
+              ] }),
+              /* @__PURE__ */ jsxs2("div", { className: "ghsync__schedule-meta", children: [
+                /* @__PURE__ */ jsx2("span", { className: "ghsync__scope-pill ghsync__scope-pill--global", children: "Worker" }),
+                /* @__PURE__ */ jsx2("strong", { children: effectivePaperclipApiBaseUrl ?? "Browser origin unavailable" }),
+                /* @__PURE__ */ jsx2("span", { children: paperclipApiBaseUrlIsOverride ? "Configured override." : "Using browser origin." })
+              ] })
+            ] }),
             !syncUnlocked ? /* @__PURE__ */ jsxs2("div", { className: "ghsync__locked", children: [
               /* @__PURE__ */ jsxs2("div", { children: [
                 /* @__PURE__ */ jsx2("strong", { children: syncSetupIssue === "missing_board_access" ? "Paperclip board access is required" : "Manual sync is locked" }),
@@ -33544,6 +33601,10 @@ function GitHubSyncSettingsPage() {
               /* @__PURE__ */ jsx2("span", { className: "ghsync__detail-label", children: "Auto-sync" }),
               /* @__PURE__ */ jsx2("strong", { className: "ghsync__detail-value", children: scheduleDescription })
             ] }),
+            /* @__PURE__ */ jsxs2("div", { className: "ghsync__detail", children: [
+              /* @__PURE__ */ jsx2("span", { className: "ghsync__detail-label", children: "Worker API" }),
+              /* @__PURE__ */ jsx2("strong", { className: "ghsync__detail-value", children: effectivePaperclipApiBaseUrl })
+            ] }),
             /* @__PURE__ */ jsxs2("div", { className: "ghsync__detail", children: [
               /* @__PURE__ */ jsx2("span", { className: "ghsync__detail-label", children: "Last sync" }),
               /* @__PURE__ */ jsx2("strong", { className: "ghsync__detail-value", children: lastSync })