paperclip-github-plugin 0.2.1 → 0.2.3

package/dist/worker.js

@@ -515,6 +515,10 @@ var SYNC_STATE_SCOPE = {
   scopeKind: "instance",
   stateKey: "paperclip-github-plugin-last-sync"
 };
+var SYNC_CANCELLATION_SCOPE = {
+  scopeKind: "instance",
+  stateKey: "paperclip-github-plugin-sync-cancel-request"
+};
 var IMPORT_REGISTRY_SCOPE = {
   scopeKind: "instance",
   stateKey: "paperclip-github-plugin-import-registry"
@@ -527,7 +531,9 @@ var DEFAULT_PAPERCLIP_LABEL_COLOR = "#6366f1";
 var PAPERCLIP_LABEL_PAGE_SIZE = 100;
 var MANUAL_SYNC_RESPONSE_GRACE_PERIOD_MS = 500;
 var RUNNING_SYNC_MESSAGE = "GitHub sync is running in the background. This page will update when it finishes.";
+var CANCELLING_SYNC_MESSAGE = "Cancellation requested. GitHub sync will stop after the current step finishes.";
 var SYNC_PROGRESS_PERSIST_INTERVAL_MS = 250;
+var MAX_SYNC_FAILURE_LOG_ENTRIES = 25;
 var GITHUB_SECONDARY_RATE_LIMIT_FALLBACK_MS = 6e4;
 var MISSING_GITHUB_TOKEN_SYNC_MESSAGE = "Configure a GitHub token before running sync.";
 var MISSING_GITHUB_TOKEN_SYNC_ACTION = 'Open settings and save a GitHub token secret, or create ~/.paperclip/plugins/github-sync/config.json with a "githubToken" value, and then run sync again.';
@@ -577,6 +583,14 @@ var PaperclipLabelSyncError = class extends Error {
     this.labelNames = labelNames;
   }
 };
+var SyncCancellationError = class extends Error {
+  name = "SyncCancellationError";
+  requestedAt;
+  constructor(requestedAt) {
+    super(CANCELLING_SYNC_MESSAGE);
+    this.requestedAt = requestedAt;
+  }
+};
 var SUCCESSFUL_CHECK_RUN_CONCLUSIONS = /* @__PURE__ */ new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
 var FAILED_CHECK_RUN_CONCLUSIONS = /* @__PURE__ */ new Set([
   "ACTION_REQUIRED",
@@ -884,6 +898,20 @@ function createIdleSyncState() {
     status: "idle"
   };
 }
+function createCancelledSyncState(params) {
+  const { message, trigger, syncedIssuesCount, createdIssuesCount, skippedIssuesCount, erroredIssuesCount, progress } = params;
+  return {
+    status: "cancelled",
+    message,
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    syncedIssuesCount,
+    createdIssuesCount,
+    skippedIssuesCount,
+    erroredIssuesCount,
+    lastRunTrigger: trigger,
+    ...progress ? { progress: normalizeSyncProgress(progress) } : {}
+  };
+}
 function formatGitHubIssueCountLabel(count) {
   const normalizedCount = Math.max(0, Math.floor(count));
   return `${normalizedCount} GitHub ${normalizedCount === 1 ? "issue" : "issues"}`;
@@ -1047,6 +1075,7 @@ function normalizeSyncConfigurationIssue(value) {
   switch (value) {
     case "missing_token":
     case "missing_mapping":
+    case "missing_board_access":
       return value;
     default:
       return void 0;
@@ -1120,6 +1149,30 @@ function normalizeSyncErrorDetails(value) {
     ...rateLimitResource ? { rateLimitResource } : {}
   };
 }
+function normalizeSyncFailureLogEntry(value) {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const record = value;
+  const details = normalizeSyncErrorDetails(record);
+  const message = typeof record.message === "string" && record.message.trim() ? record.message.trim() : void 0;
+  const occurredAt = typeof record.occurredAt === "string" && record.occurredAt.trim() ? record.occurredAt.trim() : void 0;
+  if (!message || !occurredAt) {
+    return void 0;
+  }
+  return {
+    message,
+    occurredAt,
+    ...details ?? {}
+  };
+}
+function normalizeSyncFailureLogEntries(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const entries = value.map((entry) => normalizeSyncFailureLogEntry(entry)).filter((entry) => entry !== void 0).slice(-MAX_SYNC_FAILURE_LOG_ENTRIES);
+  return entries.length > 0 ? entries : void 0;
+}
 function formatSyncFailurePhase(phase) {
   switch (phase) {
     case "configuration":
@@ -1274,8 +1327,49 @@ function buildSyncErrorDetails(error, context) {
     ...rateLimitPause?.resource ? { rateLimitResource: rateLimitPause.resource } : {}
   };
 }
+function createSyncFailureLogEntry(params) {
+  const message = params.message.trim();
+  const occurredAt = typeof params.occurredAt === "string" && params.occurredAt.trim() ? params.occurredAt.trim() : (/* @__PURE__ */ new Date()).toISOString();
+  const errorDetails = normalizeSyncErrorDetails(params.errorDetails);
+  if (!message) {
+    return void 0;
+  }
+  return {
+    message,
+    occurredAt,
+    ...errorDetails ?? {}
+  };
+}
+function buildSyncFailureLogEntry(error, context, occurredAt) {
+  return createSyncFailureLogEntry({
+    message: buildSyncFailureMessage(error, context),
+    occurredAt,
+    errorDetails: buildSyncErrorDetails(error, context)
+  });
+}
+function buildRecentSyncFailureLogEntries(failures) {
+  const entries = failures.slice(-MAX_SYNC_FAILURE_LOG_ENTRIES).map((failure) => buildSyncFailureLogEntry(failure.error, failure.context, failure.occurredAt)).filter((entry) => entry !== void 0);
+  return entries.length > 0 ? entries : void 0;
+}
+function appendRecentSyncFailureLogEntry(entries, entry) {
+  if (!entry) {
+    return entries;
+  }
+  return [...entries ?? [], entry].slice(-MAX_SYNC_FAILURE_LOG_ENTRIES);
+}
 function createErrorSyncState(params) {
-  const { message, trigger, syncedIssuesCount, createdIssuesCount, skippedIssuesCount, erroredIssuesCount, progress, errorDetails } = params;
+  const {
+    message,
+    trigger,
+    syncedIssuesCount,
+    createdIssuesCount,
+    skippedIssuesCount,
+    erroredIssuesCount,
+    progress,
+    errorDetails,
+    recentFailures
+  } = params;
+  const normalizedRecentFailures = normalizeSyncFailureLogEntries(recentFailures);
   return {
     status: "error",
     message,
@@ -1286,20 +1380,27 @@ function createErrorSyncState(params) {
     erroredIssuesCount,
     lastRunTrigger: trigger,
     ...progress ? { progress: normalizeSyncProgress(progress) } : {},
-    ...errorDetails ? { errorDetails } : {}
+    ...errorDetails ? { errorDetails } : {},
+    ...normalizedRecentFailures ? { recentFailures: normalizedRecentFailures } : {}
   };
 }
 function createRunningSyncState(previous, trigger, options = {}) {
+  const previousRunningState = previous.status === "running" ? previous : void 0;
+  const nextMessage = options.message ?? previousRunningState?.message ?? RUNNING_SYNC_MESSAGE;
+  const nextCancelRequestedAt = options.cancelRequestedAt ?? previousRunningState?.cancelRequestedAt;
+  const normalizedRecentFailures = normalizeSyncFailureLogEntries(options.recentFailures);
   return {
     status: "running",
-    message: options.message ?? RUNNING_SYNC_MESSAGE,
+    message: nextMessage,
     checkedAt: previous.checkedAt,
     syncedIssuesCount: options.syncedIssuesCount ?? 0,
     createdIssuesCount: options.createdIssuesCount ?? 0,
     skippedIssuesCount: options.skippedIssuesCount ?? 0,
     erroredIssuesCount: options.erroredIssuesCount ?? 0,
     lastRunTrigger: trigger,
-    ...options.progress ? { progress: normalizeSyncProgress(options.progress) } : {}
+    ...nextCancelRequestedAt ? { cancelRequestedAt: nextCancelRequestedAt } : {},
+    ...options.progress ? { progress: normalizeSyncProgress(options.progress) } : {},
+    ...normalizedRecentFailures ? { recentFailures: normalizedRecentFailures } : {}
   };
 }
 function getSyncableMappings(mappings) {
@@ -1785,7 +1886,16 @@ function createSetupConfigurationErrorSyncState(issue, trigger) {
           phase: "configuration",
           configurationIssue: "missing_token",
           suggestedAction: MISSING_GITHUB_TOKEN_SYNC_ACTION
-        }
+        },
+        recentFailures: [
+          {
+            message: MISSING_GITHUB_TOKEN_SYNC_MESSAGE,
+            occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+            phase: "configuration",
+            configurationIssue: "missing_token",
+            suggestedAction: MISSING_GITHUB_TOKEN_SYNC_ACTION
+          }
+        ]
       });
     case "missing_mapping":
       return createErrorSyncState({
@@ -1799,7 +1909,16 @@ function createSetupConfigurationErrorSyncState(issue, trigger) {
           phase: "configuration",
           configurationIssue: "missing_mapping",
           suggestedAction: MISSING_MAPPING_SYNC_ACTION
-        }
+        },
+        recentFailures: [
+          {
+            message: MISSING_MAPPING_SYNC_MESSAGE,
+            occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+            phase: "configuration",
+            configurationIssue: "missing_mapping",
+            suggestedAction: MISSING_MAPPING_SYNC_ACTION
+          }
+        ]
       });
     case "missing_board_access":
       return createErrorSyncState({
@@ -1813,7 +1932,16 @@ function createSetupConfigurationErrorSyncState(issue, trigger) {
           phase: "configuration",
           configurationIssue: "missing_board_access",
           suggestedAction: MISSING_BOARD_ACCESS_SYNC_ACTION
-        }
+        },
+        recentFailures: [
+          {
+            message: MISSING_BOARD_ACCESS_SYNC_MESSAGE,
+            occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+            phase: "configuration",
+            configurationIssue: "missing_board_access",
+            suggestedAction: MISSING_BOARD_ACCESS_SYNC_ACTION
+          }
+        ]
       });
   }
 }
@@ -1826,6 +1954,25 @@ async function saveSettingsSyncState(ctx, settings, syncState) {
   await ctx.state.set(SYNC_STATE_SCOPE, next.syncState);
   return next;
 }
+async function setSyncCancellationRequest(ctx, request) {
+  await ctx.state.set(SYNC_CANCELLATION_SCOPE, request);
+}
+async function getSyncCancellationRequest(ctx) {
+  const activeRequestedAt = activeRunningSyncState?.syncState.cancelRequestedAt?.trim();
+  if (activeRunningSyncState?.syncState.status === "running" && activeRequestedAt) {
+    return {
+      requestedAt: activeRequestedAt
+    };
+  }
+  return normalizeSyncCancellationRequest(await ctx.state.get(SYNC_CANCELLATION_SCOPE));
+}
+function buildCancelledSyncMessage(target, progress) {
+  const completedIssueCount = typeof progress?.completedIssueCount === "number" ? Math.max(0, progress.completedIssueCount) : void 0;
+  const totalIssueCount = typeof progress?.totalIssueCount === "number" ? Math.max(0, progress.totalIssueCount) : void 0;
+  const scopeLabel = target ? `GitHub sync for ${target.displayLabel}` : "GitHub sync";
+  const completionSummary = completedIssueCount !== void 0 && totalIssueCount !== void 0 ? ` Completed ${Math.min(completedIssueCount, totalIssueCount)} of ${totalIssueCount} issues before stopping.` : "";
+  return `${scopeLabel} was cancelled before it finished.${completionSummary}`;
+}
 async function createUnexpectedSyncErrorResult(ctx, trigger, error) {
   const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
   const errorDetails = buildSyncErrorDetails(error, {
@@ -1844,7 +1991,14 @@ async function createUnexpectedSyncErrorResult(ctx, trigger, error) {
       createdIssuesCount: settings.syncState.createdIssuesCount ?? 0,
       skippedIssuesCount: settings.syncState.skippedIssuesCount ?? 0,
       erroredIssuesCount: 0,
-      errorDetails
+      errorDetails,
+      recentFailures: appendRecentSyncFailureLogEntry(
+        void 0,
+        createSyncFailureLogEntry({
+          message,
+          errorDetails
+        })
+      )
     })
   );
 }
@@ -1892,7 +2046,8 @@ function recordRecoverableSyncFailure(ctx, failures, error, context) {
   const snapshot = cloneSyncFailureContext(context);
   failures.push({
     error,
-    context: snapshot
+    context: snapshot,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   ctx.logger.warn("GitHub sync skipped a failed item and continued.", {
     phase: snapshot.phase,
@@ -1998,6 +2153,13 @@ function normalizePaperclipBoardApiTokenRefs(value) {
   }
   return Object.fromEntries(entries);
 }
+function normalizeSyncCancellationRequest(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const requestedAt = typeof value.requestedAt === "string" ? value.requestedAt.trim() : "";
+  return requestedAt ? { requestedAt } : null;
+}
 function normalizeSyncState(value) {
   if (!value || typeof value !== "object") {
     return DEFAULT_SETTINGS.syncState;
@@ -2007,8 +2169,9 @@ function normalizeSyncState(value) {
   const lastRunTrigger = record.lastRunTrigger;
   const progress = normalizeSyncProgress(record.progress);
   const errorDetails = normalizeSyncErrorDetails(record.errorDetails);
+  const recentFailures = normalizeSyncFailureLogEntries(record.recentFailures);
   return {
-    status: status === "running" || status === "success" || status === "error" ? status : "idle",
+    status: status === "running" || status === "success" || status === "error" || status === "cancelled" ? status : "idle",
     message: typeof record.message === "string" ? record.message : void 0,
     checkedAt: typeof record.checkedAt === "string" ? record.checkedAt : void 0,
     syncedIssuesCount: typeof record.syncedIssuesCount === "number" ? record.syncedIssuesCount : void 0,
@@ -2016,8 +2179,10 @@ function normalizeSyncState(value) {
     skippedIssuesCount: typeof record.skippedIssuesCount === "number" ? record.skippedIssuesCount : void 0,
     erroredIssuesCount: typeof record.erroredIssuesCount === "number" ? record.erroredIssuesCount : void 0,
     lastRunTrigger: lastRunTrigger === "manual" || lastRunTrigger === "schedule" || lastRunTrigger === "retry" ? lastRunTrigger : void 0,
+    cancelRequestedAt: typeof record.cancelRequestedAt === "string" ? record.cancelRequestedAt : void 0,
     ...progress ? { progress } : {},
-    ...errorDetails ? { errorDetails } : {}
+    ...errorDetails ? { errorDetails } : {},
+    ...recentFailures ? { recentFailures } : {}
   };
 }
 function normalizeMappings(value) {
@@ -4318,25 +4483,30 @@ async function createPaperclipIssue(ctx, mapping, advancedSettings, issue, avail
     createdIssueDescription = createdIssue.description;
     createPath = "sdk";
   }
+  const ensuredCreatedIssueId = createdIssueId;
+  if (!ensuredCreatedIssueId) {
+    throw new Error("GitHub sync could not resolve the created Paperclip issue id.");
+  }
+  const normalizedCreatedIssueDescription = createdIssueDescription ?? void 0;
   if (createPath !== "sdk") {
     await applyDefaultAssigneeToPaperclipIssue(ctx, {
       companyId: mapping.companyId,
-      issueId: createdIssueId,
+      issueId: ensuredCreatedIssueId,
       defaultAssigneeAgentId: advancedSettings.defaultAssigneeAgentId
     });
   }
-  if (normalizeIssueDescriptionValue(createdIssueDescription) !== description) {
+  if (normalizeIssueDescriptionValue(normalizedCreatedIssueDescription) !== description) {
     logIssueDescriptionDiagnostic(
       ctx,
       "warn",
       "GitHub sync detected a missing or mismatched Paperclip issue description immediately after issue creation.",
       {
         companyId: mapping.companyId,
-        issueId: createdIssueId,
+        issueId: ensuredCreatedIssueId,
         paperclipApiBaseUrl,
         githubIssue: issue,
         linkedPullRequestNumbers: [],
-        currentDescription: createdIssueDescription,
+        currentDescription: normalizedCreatedIssueDescription,
         nextDescription: description,
         reason: "create_response_mismatch",
         createPath
@@ -4346,8 +4516,8 @@ async function createPaperclipIssue(ctx, mapping, advancedSettings, issue, avail
       ctx,
       {
         companyId: mapping.companyId,
-        issueId: createdIssueId,
-        currentDescription: createdIssueDescription,
+        issueId: ensuredCreatedIssueId,
+        currentDescription: normalizedCreatedIssueDescription,
         githubIssue: issue,
         linkedPullRequestNumbers: [],
         paperclipApiBaseUrl,
@@ -4355,7 +4525,7 @@ async function createPaperclipIssue(ctx, mapping, advancedSettings, issue, avail
       }
     );
   }
-  await upsertGitHubIssueLinkRecord(ctx, mapping, createdIssueId, issue, []);
+  await upsertGitHubIssueLinkRecord(ctx, mapping, ensuredCreatedIssueId, issue, []);
   if (syncFailureContext) {
     updateSyncFailureContext(syncFailureContext, {
       phase: "syncing_labels",
@@ -4373,11 +4543,11 @@ async function createPaperclipIssue(ctx, mapping, advancedSettings, issue, avail
   await applyPaperclipLabelsToIssue(
     ctx,
     mapping.companyId,
-    createdIssueId,
+    ensuredCreatedIssueId,
     labelResolution.labels
   );
   return {
-    id: createdIssueId,
+    id: ensuredCreatedIssueId,
     unresolvedGitHubLabels: labelResolution.unresolvedGitHubLabels,
     ...labelResolution.failure ? { labelResolutionFailure: labelResolution.failure } : {}
   };
@@ -4449,7 +4619,7 @@ async function ensurePaperclipIssueImported(ctx, mapping, advancedSettings, issu
   }
   return createdIssue.id;
 }
-async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mapping, advancedSettings, allIssuesById, importedIssues, createdIssueIds, availableLabels, paperclipApiBaseUrl, linkedPullRequestsByIssueNumber, issueStatusSnapshotCache, pullRequestStatusCache, repositoryMaintainerCache, syncFailureContext, failures, onProgress) {
+async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mapping, advancedSettings, allIssuesById, importedIssues, createdIssueIds, availableLabels, paperclipApiBaseUrl, linkedPullRequestsByIssueNumber, issueStatusSnapshotCache, pullRequestStatusCache, repositoryMaintainerCache, syncFailureContext, failures, assertNotCancelled, onProgress) {
   if (!mapping.companyId || !ctx.issues || typeof ctx.issues.get !== "function" || typeof ctx.issues.update !== "function") {
     return {
       updatedStatusesCount: 0,
@@ -4463,6 +4633,9 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
   let completedIssueCount = 0;
   const totalIssueCount = importedIssues.length;
   for (const importedIssue of importedIssues) {
+    if (assertNotCancelled) {
+      await assertNotCancelled();
+    }
     const githubIssue = allIssuesById.get(importedIssue.githubIssueId);
     try {
       if (!githubIssue) {
@@ -5128,6 +5301,7 @@ async function performSync(ctx, trigger, options = {}) {
   const config = await getResolvedConfig(ctx);
   const importRegistry = normalizeImportRegistry(await ctx.state.get(IMPORT_REGISTRY_SCOPE));
   const token = typeof options.resolvedToken === "string" ? options.resolvedToken : await resolveGithubToken(ctx);
+  const paperclipApiBaseUrl = getConfiguredPaperclipApiBaseUrl(settings, config);
   const mappings = getSyncableMappingsForTarget(settings.mappings, options.target);
   activePaperclipApiAuthTokensByCompanyId = null;
   const failureContext = {
@@ -5152,7 +5326,7 @@ async function performSync(ctx, trigger, options = {}) {
     return next;
   }
   const mappingsMissingBoardAccess = getMappingsMissingPaperclipBoardAccess(settings, config, mappings);
-  if (mappingsMissingBoardAccess.length > 0 && await detectPaperclipBoardAccessRequirement(settings.paperclipApiBaseUrl)) {
+  if (mappingsMissingBoardAccess.length > 0 && await detectPaperclipBoardAccessRequirement(paperclipApiBaseUrl)) {
     const next = {
       ...settings,
       syncState: createSetupConfigurationErrorSyncState("missing_board_access", trigger)
@@ -5162,6 +5336,10 @@ async function performSync(ctx, trigger, options = {}) {
     return next;
   }
   if (!ctx.issues || typeof ctx.issues.create !== "function") {
+    const errorDetails = {
+      phase: "configuration",
+      suggestedAction: "Update Paperclip to a runtime that supports plugin issue creation, then retry sync."
+    };
     const next = {
       ...settings,
       syncState: createErrorSyncState({
@@ -5171,10 +5349,14 @@ async function performSync(ctx, trigger, options = {}) {
         createdIssuesCount: 0,
         skippedIssuesCount: 0,
         erroredIssuesCount: 0,
-        errorDetails: {
-          phase: "configuration",
-          suggestedAction: "Update Paperclip to a runtime that supports plugin issue creation, then retry sync."
-        }
+        errorDetails,
+        recentFailures: appendRecentSyncFailureLogEntry(
+          void 0,
+          createSyncFailureLogEntry({
+            message: "This Paperclip runtime does not expose plugin issue creation yet.",
+            errorDetails
+          })
+        )
       })
     };
     await ctx.state.set(SETTINGS_SCOPE, next);
@@ -5210,14 +5392,23 @@ async function performSync(ctx, trigger, options = {}) {
     erroredIssuesCount: recoverableFailures.length,
     progress: currentProgress
   });
+  async function throwIfSyncCancelled() {
+    const cancellationRequest = await getSyncCancellationRequest(ctx);
+    if (!cancellationRequest) {
+      return;
+    }
+    throw new SyncCancellationError(cancellationRequest.requestedAt);
+  }
   async function persistRunningProgress(force = false) {
     const progress = normalizeSyncProgress(currentProgress);
+    const recentFailures = buildRecentSyncFailureLogEntries(recoverableFailures);
     const signature = JSON.stringify({
       syncedIssuesCount,
       createdIssuesCount,
       skippedIssuesCount,
       erroredIssuesCount: recoverableFailures.length,
-      progress
+      progress,
+      recentFailures
     });
     const now = Date.now();
     if (!force) {
@@ -5236,7 +5427,8 @@ async function performSync(ctx, trigger, options = {}) {
         createdIssuesCount,
         skippedIssuesCount,
         erroredIssuesCount: recoverableFailures.length,
-        progress
+        progress,
+        recentFailures
       })
     );
     activeRunningSyncState = currentSettings;
@@ -5253,7 +5445,9 @@ async function performSync(ctx, trigger, options = {}) {
   }
   const repositoryPlans = [];
   try {
+    await throwIfSyncCancelled();
     for (const [mappingIndex, mapping] of mappings.entries()) {
+      await throwIfSyncCancelled();
       try {
         const repository = requireRepositoryReference(mapping.repositoryUrl);
         const importedIssueRecords = nextRegistry.filter((entry) => doesImportedIssueRecordMatchMapping(entry, mapping)).filter((entry) => doesImportedIssueMatchTarget(entry, options.target));
@@ -5276,7 +5470,7 @@ async function performSync(ctx, trigger, options = {}) {
           updateSyncFailureContext(failureContext, {
             phase: "loading_paperclip_labels"
           });
-          availableLabels = supportsPaperclipLabelMapping && companyId ? await buildPaperclipLabelDirectory(ctx, companyId, settings.paperclipApiBaseUrl) : /* @__PURE__ */ new Map();
+          availableLabels = supportsPaperclipLabelMapping && companyId ? await buildPaperclipLabelDirectory(ctx, companyId, paperclipApiBaseUrl) : /* @__PURE__ */ new Map();
           if (companyId) {
             companyLabelDirectoryCache.set(companyId, availableLabels);
           }
@@ -5341,7 +5535,7 @@ async function performSync(ctx, trigger, options = {}) {
           trackedIssueCount
         });
       } catch (error) {
-        if (isGitHubRateLimitError(error)) {
+        if (error instanceof SyncCancellationError || isGitHubRateLimitError(error)) {
           throw error;
         }
         recordRecoverableSyncFailure(ctx, recoverableFailures, error, failureContext);
@@ -5370,6 +5564,7 @@ async function performSync(ctx, trigger, options = {}) {
     }
     await persistRunningProgress(true);
     for (const plan of repositoryPlans) {
+      await throwIfSyncCancelled();
       try {
         const { mapping, advancedSettings, repository, repositoryIndex, allIssuesById, issues } = plan;
         const companyId = mapping.companyId;
@@ -5380,7 +5575,7 @@ async function performSync(ctx, trigger, options = {}) {
             repositoryUrl: repository.url,
             githubIssueNumber: void 0
           });
-          availableLabels = supportsPaperclipLabelMapping && companyId ? await buildPaperclipLabelDirectory(ctx, companyId, settings.paperclipApiBaseUrl) : /* @__PURE__ */ new Map();
+          availableLabels = supportsPaperclipLabelMapping && companyId ? await buildPaperclipLabelDirectory(ctx, companyId, paperclipApiBaseUrl) : /* @__PURE__ */ new Map();
           if (companyId) {
             companyLabelDirectoryCache.set(companyId, availableLabels);
           }
@@ -5424,8 +5619,9 @@ async function performSync(ctx, trigger, options = {}) {
             openLinkedPullRequestNumbers,
             pullRequestStatusCache
           );
+          await throwIfSyncCancelled();
         } catch (error) {
-          if (isGitHubRateLimitError(error)) {
+          if (error instanceof SyncCancellationError || isGitHubRateLimitError(error)) {
             throw error;
           }
         }
@@ -5440,6 +5636,7 @@ async function performSync(ctx, trigger, options = {}) {
         };
         await persistRunningProgress(true);
         for (const [issueIndex, issue] of issues.entries()) {
+          await throwIfSyncCancelled();
           const createdIssueCountBefore = createdIssueIds.size;
           const skippedIssueCountBefore = skippedIssueIds.size;
           try {
@@ -5449,7 +5646,7 @@ async function performSync(ctx, trigger, options = {}) {
               advancedSettings,
               issue,
               availableLabels,
-              settings.paperclipApiBaseUrl,
+              paperclipApiBaseUrl,
               importRegistryByIssueId,
               existingImportedPaperclipIssuesByUrl,
               nextRegistry,
@@ -5488,6 +5685,7 @@ async function performSync(ctx, trigger, options = {}) {
           totalIssueCount: totalTrackedIssueCount
         };
         await persistRunningProgress(true);
+        await throwIfSyncCancelled();
         const synchronizationResult = await synchronizePaperclipIssueStatuses(
           ctx,
           octokit,
@@ -5498,13 +5696,14 @@ async function performSync(ctx, trigger, options = {}) {
           importedIssuesForSynchronization,
           createdIssueIds,
           availableLabels,
-          settings.paperclipApiBaseUrl,
+          paperclipApiBaseUrl,
           linkedPullRequestsByIssueNumber,
           issueStatusSnapshotCache,
           pullRequestStatusCache,
           repositoryMaintainerCache,
           failureContext,
           recoverableFailures,
+          throwIfSyncCancelled,
           async (progress) => {
             markTrackedIssueProcessed(mapping, progress.githubIssueId);
             currentProgress = {
@@ -5523,7 +5722,7 @@ async function performSync(ctx, trigger, options = {}) {
         updatedLabelsCount += synchronizationResult.updatedLabelsCount;
         updatedDescriptionsCount += synchronizationResult.updatedDescriptionsCount;
       } catch (error) {
-        if (isGitHubRateLimitError(error)) {
+        if (error instanceof SyncCancellationError || isGitHubRateLimitError(error)) {
           throw error;
         }
         recordRecoverableSyncFailure(ctx, recoverableFailures, error, failureContext);
@@ -5547,7 +5746,8 @@ async function performSync(ctx, trigger, options = {}) {
           skippedIssuesCount,
           erroredIssuesCount: recoverableFailures.length,
           progress: currentProgress,
-          errorDetails
+          errorDetails,
+          recentFailures: buildRecentSyncFailureLogEntries(recoverableFailures)
         })
       };
       await ctx.state.set(SETTINGS_SCOPE, next2);
@@ -5573,6 +5773,24 @@ async function performSync(ctx, trigger, options = {}) {
     await ctx.state.set(IMPORT_REGISTRY_SCOPE, nextRegistry);
     return next;
   } catch (error) {
+    if (error instanceof SyncCancellationError) {
+      const next2 = {
+        ...currentSettings,
+        syncState: createCancelledSyncState({
+          message: buildCancelledSyncMessage(options.target, currentProgress),
+          trigger,
+          syncedIssuesCount,
+          createdIssuesCount,
+          skippedIssuesCount,
+          erroredIssuesCount: recoverableFailures.length,
+          progress: currentProgress
+        })
+      };
+      await ctx.state.set(SETTINGS_SCOPE, next2);
+      await ctx.state.set(SYNC_STATE_SCOPE, next2.syncState);
+      await ctx.state.set(IMPORT_REGISTRY_SCOPE, nextRegistry);
+      return next2;
+    }
     const errorDetails = buildSyncErrorDetails(error, failureContext);
     const next = {
       ...currentSettings,
@@ -5584,7 +5802,11 @@ async function performSync(ctx, trigger, options = {}) {
         skippedIssuesCount,
         erroredIssuesCount: recoverableFailures.length,
         progress: currentProgress,
-        errorDetails
+        errorDetails,
+        recentFailures: appendRecentSyncFailureLogEntry(
+          buildRecentSyncFailureLogEntries(recoverableFailures),
+          buildSyncFailureLogEntry(error, failureContext)
+        )
       })
     };
     await ctx.state.set(SETTINGS_SCOPE, next);
@@ -5638,6 +5860,7 @@ async function startSync(ctx, trigger, options = {}) {
   if (trigger !== "manual" && !token.trim()) {
     return currentSettings;
   }
+  await setSyncCancellationRequest(ctx, null);
   const runningStatePromise = (async () => {
     const syncableMappings = getSyncableMappingsForTarget(currentSettings.mappings, options.target);
     const syncState = createRunningSyncState(currentSettings.syncState, trigger, {
@@ -5667,6 +5890,7 @@ async function startSync(ctx, trigger, options = {}) {
     } catch (error) {
       return await createUnexpectedSyncErrorResult(ctx, trigger, error);
     } finally {
+      await setSyncCancellationRequest(ctx, null);
       activePaperclipApiAuthTokensByCompanyId = null;
       activeRunningSyncState = null;
       activeSyncPromise = null;
@@ -6527,6 +6751,32 @@ var plugin = definePlugin({
         ...target ? { target } : {}
       });
     });
+    ctx.actions.register("sync.cancel", async () => {
+      const currentSettings = await getActiveOrCurrentSyncState(ctx);
+      if (currentSettings.syncState.status !== "running") {
+        return currentSettings;
+      }
+      const existingRequest = currentSettings.syncState.cancelRequestedAt?.trim() ? { requestedAt: currentSettings.syncState.cancelRequestedAt.trim() } : await getSyncCancellationRequest(ctx);
+      const cancellationRequest = existingRequest ?? {
+        requestedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await setSyncCancellationRequest(ctx, cancellationRequest);
+      const next = await saveSettingsSyncState(
+        ctx,
+        currentSettings,
+        createRunningSyncState(currentSettings.syncState, currentSettings.syncState.lastRunTrigger ?? "manual", {
+          syncedIssuesCount: currentSettings.syncState.syncedIssuesCount ?? 0,
+          createdIssuesCount: currentSettings.syncState.createdIssuesCount ?? 0,
+          skippedIssuesCount: currentSettings.syncState.skippedIssuesCount ?? 0,
+          erroredIssuesCount: currentSettings.syncState.erroredIssuesCount ?? 0,
+          progress: currentSettings.syncState.progress,
+          message: CANCELLING_SYNC_MESSAGE,
+          cancelRequestedAt: cancellationRequest.requestedAt
+        })
+      );
+      activeRunningSyncState = next;
+      return next;
+    });
     registerGitHubAgentTools(ctx);
     ctx.jobs.register("sync.github-issues", async (job) => {
       const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",