Confirm before destructive Re-convert action (#20) (#26)

Add a Services.prompt.confirmEx dialog before the Re-convert (replace)
menu action runs. Default opt-out via "Don't ask again" checkbox stored
in the new `confirmReconvert` pref.

Rationale: Re-convert silently deletes the existing markdown attachment
and starts fresh. An accidental click is cheap for users running the
standard pipeline locally (seconds of compute) but expensive for users
on long VLM batches or paired with a remote LLM API (hours of compute,
possibly substantial spend). The plugin's other destructive action
(Reset preferences) already prompts; this brings Re-convert in line.

Implementation notes:
- Confirm fires inside runBatch after the filter that drops PDFs with
  no matching .md, so the count in the dialog ("on N selected PDFs")
  reflects the actual destructive count.
- Confirm fires before setting `batchInFlight`, so cancelling is a
  clean no-op with no flag to clear.
- Button-flag constants fall back to literal values if the
  Components.interfaces.nsIPromptService constants are absent (Z9
  exposes them but defending against future runtime changes is cheap).
- "Don't ask again" persistence uses setPref; Reset to defaults already
  iterates ALL_PREF_KEYS so the new pref restores there.

Closes #20

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Mayank Vats <18255879+max3925vats@users.noreply.github.com>

Author: 3 people

addon/prefs.js

@@ -47,6 +47,10 @@ pref("exportFolderPath", "");
 // OS-level notification when a batch finishes, only if Zotero isn't focused.
 pref("notifyOnComplete", false);
 
+// Show a confirmation prompt before the destructive "Re-convert (replace)"
+// menu action. Users can opt out via a "Don't ask again" checkbox in the
+// dialog itself; Reset to defaults restores this.
+pref("confirmReconvert", true);
 // First-run onboarding nudge. Flipped to true after the first startup
 // toast fires OR after the first successful Test Connection. Reset to
 // defaults re-arms the nudge.

src/modules/menu.ts

@@ -33,7 +33,7 @@ import {
   removeMatchingMdChild,
   findMatchingMdChild,
 } from "../utils/zotero";
-import { getPref } from "../utils/prefs";
+import { getPref, setPref } from "../utils/prefs";
 import { notifyOnBatchComplete } from "../utils/notification";
 import { ConcurrencyLimiter } from "../utils/concurrencyLimiter";
 import { truncateMiddle } from "../utils/format";
@@ -116,6 +116,84 @@ function shouldShowReconvert(): boolean {
 //  Batch orchestration
 // ---------------------------------------------------------------------------
 
+/**
+ * Show a "Re-convert with Docling?" confirm dialog with a "Don't ask again"
+ * checkbox. Returns true if the user confirmed. The destructive Re-convert
+ * action deletes the existing .md attachment(s); confirming guards against
+ * an accidental click that would cost minutes-to-hours of compute (or API
+ * spend, when paired with a remote LLM API).
+ *
+ * Uses Services.prompt.confirmEx — cross-platform, supports a checkbox
+ * natively. If the user ticks "Don't ask again" and confirms, we flip the
+ * `confirmReconvert` pref off; the Reset-to-defaults button restores it.
+ */
+function confirmReconvertWithUser(count: number): boolean {
+  const Services = (globalThis as any).Services;
+  const prompt = Services?.prompt;
+  if (!prompt?.confirmEx) {
+    // No prompt service available (very unusual). Default to allowing the
+    // action — losing the confirm is preferable to silently blocking the
+    // user from re-converting at all.
+    return true;
+  }
+
+  const Ci = (globalThis as any).Components?.interfaces;
+  const STD =
+    prompt.BUTTON_TITLE_IS_STRING ??
+    Ci?.nsIPromptService?.BUTTON_TITLE_IS_STRING ??
+    127;
+  const CANCEL =
+    prompt.BUTTON_TITLE_CANCEL ??
+    Ci?.nsIPromptService?.BUTTON_TITLE_CANCEL ??
+    2;
+  const POS0 = prompt.BUTTON_POS_0 ?? Ci?.nsIPromptService?.BUTTON_POS_0 ?? 0;
+  const POS1 = prompt.BUTTON_POS_1 ?? Ci?.nsIPromptService?.BUTTON_POS_1 ?? 8;
+  const flags = STD * POS0 + CANCEL * POS1;
+
+  const win =
+    (Zotero as any).getMainWindow?.() ??
+    (Zotero as any).getActiveZoteroPane?.()?.document?.defaultView ??
+    null;
+
+  const title = "Re-convert with Docling?";
+  const body = `This will delete the existing markdown attachment${count === 1 ? "" : "s"} on ${count} selected PDF${count === 1 ? "" : "s"} and run conversion again. Any manual edits to the existing markdown will be lost.`;
+  const checkLabel = "Don't ask again";
+  const check = { value: false };
+
+  let pressed: number;
+  try {
+    pressed = prompt.confirmEx(
+      win,
+      title,
+      body,
+      flags,
+      "Re-convert", // button 0 (left)
+      null, // button 1 — title comes from CANCEL flag
+      null, // button 2 — unused
+      checkLabel,
+      check,
+    );
+  } catch (e) {
+    Zotero.debug(
+      `${LOG} confirmReconvert prompt threw, allowing action: ${(e as Error).message}`,
+    );
+    return true;
+  }
+
+  // Button index 0 is "Re-convert"; 1 is Cancel.
+  if (pressed !== 0) return false;
+  if (check.value) {
+    try {
+      setPref("confirmReconvert", false);
+    } catch (e) {
+      Zotero.debug(
+        `${LOG} confirmReconvert: failed to persist opt-out: ${(e as Error).message}`,
+      );
+    }
+  }
+  return true;
+}
+
 /**
  * Run convertAttachment over a resolved PDF list with parallel concurrency,
  * per-item progress, and aggregated status tags + toast.
@@ -148,6 +226,14 @@ async function runBatch(
     return;
   }
 
+  // Re-convert is destructive — it deletes existing .md attachments before
+  // running a fresh conversion. Confirm with the user unless they've opted
+  // out via the "Don't ask again" checkbox. Confirm BEFORE setting any
+  // in-flight state so cancelling is a clean no-op.
+  if (opts.force && ((getPref("confirmReconvert") ?? true) as boolean)) {
+    if (!confirmReconvertWithUser(pdfs.length)) return;
+  }
+
   // Only one batch at a time. A second click while a batch is running
   // would otherwise spawn a parallel orchestrator that fights over the
   // shared managed-progress window.

src/modules/preferenceScript.ts

@@ -38,6 +38,7 @@ const ALL_PREF_KEYS: ReadonlyArray<string> = [
   "attachToItem",
   "exportFolderPath",
   "notifyOnComplete",
+  "confirmReconvert",
   "firstRunCompleted",
   "lastHealthResult",
 ];

typings/prefs.d.ts

@@ -30,6 +30,7 @@ declare namespace _ZoteroTypes {
       "attachToItem": boolean;
       "exportFolderPath": string;
       "notifyOnComplete": boolean;
+      "confirmReconvert": boolean;
       "firstRunCompleted": boolean;
       "lastHealthResult": string;
     };