From 899c55f230d96649bdd3a3f4a8a0302ecf2df994 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Tue, 26 May 2026 19:28:05 -0500
Subject: feat(refresh): prompt instead of silently deferring a dirty refresh

Running pearl-list-issues on a buffer with unsaved edits used to print a passive "refresh deferred" message and do nothing visible, so it read as a no-op. Now it prompts: (d)iscard and rebuild, (m)erge by LINEAR-ID keeping the edits, or (q) cancel. Branch C of pearl--update-org-from-issues dispatches on the choice: discard rebuilds in place, merge hands off to the same by-id merge that pearl-refresh-current-view uses, and cancel leaves the buffer untouched.
---
 pearl.el | 58 ++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 48 insertions(+), 10 deletions(-)

(limited to 'pearl.el')

diff --git a/pearl.el b/pearl.el
index 79c2ebd..f988668 100644
--- a/pearl.el
+++ b/pearl.el
@@ -2838,6 +2838,16 @@ yields the hardcoded default.  Pure function, no side effects."
 
       (buffer-string))))
 
+(defun pearl--dirty-refresh-choice (path)
+  "Ask how to refresh PATH when its buffer has unsaved changes.
+Returns one of ?d (discard the edits and rebuild), ?m (merge by LINEAR-ID,
+keeping unpushed edits), or ?q (cancel and leave the buffer untouched)."
+  (read-char-choice
+   (format (concat "%s has unsaved changes — "
+                   "(d)iscard & refresh, (m)erge keeping edits, (q) cancel? ")
+           (file-name-nondirectory path))
+   '(?d ?m ?q)))
+
 (defun pearl--update-org-from-issues (issues &optional source truncated)
   "Update `pearl-org-file-path' with rendered ISSUES, buffer-aware.
 SOURCE and TRUNCATED are threaded into the header (see
@@ -2849,8 +2859,9 @@ Behavior depends on whether the file is currently visited in a buffer:
   then visit it so there is a buffer to show.
 - Buffer exists and is unmodified: replace its contents in place and save,
   preserving point and avoiding a modtime mismatch warning.
-- Buffer exists and has unsaved edits: do not overwrite.  Log and emit a
-  message asking the user to save or revert before re-running.
+- Buffer exists and has unsaved edits: a full rebuild would discard them, so
+  prompt (see `pearl--dirty-refresh-choice') to discard and rebuild, merge by
+  LINEAR-ID keeping the edits, or cancel.
 
 In every case the resulting buffer is surfaced (see `pearl--surface-buffer'),
 so a fetch run from a menu or dashboard actually shows the issues instead of
@@ -2892,15 +2903,42 @@ just writing the file and leaving it off-screen."
                org-file-path (length issues))
       (pearl--surface-buffer existing-buf))
 
-     ;; Branch C: buffer is dirty -- defer, do not overwrite, but show it.
+     ;; Branch C: buffer is dirty -- a full rebuild would discard unsaved work,
+     ;; so ask before clobbering rather than silently deferring.
      (t
-      (pearl--log
-       "Linear refresh deferred: %s has unsaved changes (%d issues not written)"
-       org-file-path (length issues))
-      (message
-       "Linear refresh deferred: %s has unsaved changes. Save or revert, then re-run M-x pearl-list-issues."
-       (file-name-nondirectory org-file-path))
-      (pearl--surface-buffer existing-buf)))))
+      (pcase (pearl--dirty-refresh-choice org-file-path)
+        (?d                             ; discard the edits, rebuild in place
+         (with-current-buffer existing-buf
+           (let ((inhibit-read-only t))
+             (set-buffer-modified-p nil)
+             (erase-buffer)
+             (insert new-content)
+             (save-buffer)
+             (goto-char (point-min))
+             (pearl--restore-page-visibility)
+             (pearl-highlight-comments)))
+         (message "Updated Linear issues in %s with %d active issues"
+                  org-file-path (length issues))
+         (pearl--surface-buffer existing-buf))
+        (?m                             ; merge by LINEAR-ID, keeping edits
+         (with-current-buffer existing-buf
+           (let ((counts (pearl--merge-issues-into-buffer issues)))
+             (pearl--update-source-header (length issues) truncated)
+             (pearl--update-derived-todo-header (pearl--gather-header-states issues))
+             (pearl-highlight-comments)
+             (pearl--restore-page-visibility)
+             (message "Merged into %s: %d updated, %d added, %d dropped%s"
+                      (file-name-nondirectory org-file-path)
+                      (plist-get counts :updated)
+                      (plist-get counts :added)
+                      (plist-get counts :dropped)
+                      (let ((s (plist-get counts :skipped)))
+                        (if (> s 0) (format ", %d kept (unpushed edits)" s) "")))))
+         (pearl--surface-buffer existing-buf))
+        (_                              ; cancel
+         (message "Linear refresh cancelled; %s left unchanged"
+                  (file-name-nondirectory org-file-path))
+         (pearl--surface-buffer existing-buf)))))))
 
 (defcustom pearl-saved-queries nil
   "Named local issue queries, run with `pearl-run-saved-query'.
-- 
cgit v1.2.3