Add Emacs-native vterm copy workflows

Add an Emacs-first copy workflow for vterm and tmux. C-; V c enters vterm copy mode, C-; V C captures tmux pane scrollback into a temporary Emacs buffer, M-w copies and returns, and C-g/Escape cancel without copying. This also adds clickable URLs, removes the bad vtermf binding, unbinds C-c C-t, and tests the vterm/tmux keymap behavior.

2 files changed, 323 insertions, 5 deletions

diff --git a/modules/eshell-vterm-config.el b/modules/eshell-vterm-config.el
index 34738fa1..c305b5c8 100644
--- a/modules/eshell-vterm-config.el
+++ b/modules/eshell-vterm-config.el
@@ -19,10 +19,12 @@
 ;; just send them to the process that is currently running. So, C-a may be
 ;; beginning-of-the-line in a shell, or the prefix key in a screen session.
 
-;; If you enter vterm-copy-mode C-c C-t or <pause>, the buffer will become a normal
-;; Emacs buffer. You can then use your navigation keys, select rectangles, etc.
-;; When you press RET, the region will be copied and you'll be back in a working
-;; terminal session.
+;; If you enter vterm-copy-mode with C-; V c or <pause>, the buffer will become
+;; a normal Emacs buffer. You can then use your navigation keys, select
+;; rectangles, etc.  When you press RET or M-w, the region will be copied and
+;; you'll be back in a working terminal session.  C-; V C captures the current
+;; tmux pane history into a temporary Emacs buffer where M-w copies the selected
+;; region and returns to the vterm.
 
 ;; ANSI-TERM & TERM
 ;; I haven't yet found a need for term or ansi-term in my workflows, so I leave
@@ -31,6 +33,9 @@
 ;;; Code:
 
 (require 'system-utils)
+(require 'keybindings)
+(require 'seq)
+(require 'subr-x)
 
 ;; ------------------------------ Eshell -----------------------------
 ;; the Emacs shell.
@@ -191,10 +196,141 @@
 ;; ------------------------------ Vterm ------------------------------
 ;; faster and highly dependable, but not extensible
 
+(defvar-keymap cj/vterm-map
+  :doc "Personal vterm command map.")
+;; Uppercase V is intentional: lowercase C-; v is the version-control menu.
+(keymap-set cj/custom-keymap "V" cj/vterm-map)
+
+(defvar-local cj/vterm-tmux-history--origin-buffer nil
+  "Buffer active before opening the tmux history buffer.")
+
+(defvar-local cj/vterm-tmux-history--origin-window nil
+  "Window active before opening the tmux history buffer.")
+
+(defvar-local cj/vterm-tmux-history--origin-point nil
+  "Point in the origin buffer before opening the tmux history buffer.")
+
+(defun cj/vterm--tmux-output (&rest args)
+  "Run tmux with ARGS and return its stdout.
+Signal `user-error' when tmux exits with a non-zero status."
+  (with-temp-buffer
+    (let ((exit-code (apply #'process-file "tmux" nil t nil args)))
+      (unless (zerop exit-code)
+        (user-error "tmux failed: %s" (string-trim (buffer-string))))
+      (buffer-string))))
+
+(defun cj/vterm--tmux-pane-id-for-tty (tty)
+  "Return the tmux pane id for client TTY."
+  (let* ((output (cj/vterm--tmux-output
+                  "list-clients" "-F" "#{client_tty}\t#{pane_id}"))
+         (lines (split-string output "\n" t))
+         (match (seq-find
+                 (lambda (line)
+                   (let ((fields (split-string line "\t")))
+                     (equal (car fields) tty)))
+                 lines)))
+    (unless match
+      (user-error "No tmux client found for vterm tty %s" tty))
+    (cadr (split-string match "\t"))))
+
+(defun cj/vterm--tmux-capture-pane (pane-id)
+  "Return full joined tmux history for PANE-ID."
+  (cj/vterm--tmux-output
+   "capture-pane" "-p" "-J" "-S" "-" "-E" "-" "-t" pane-id))
+
+(defun cj/vterm--current-tmux-pane-id ()
+  "Return the tmux pane id for the current vterm buffer."
+  (unless (eq major-mode 'vterm-mode)
+    (user-error "Current buffer is not a vterm buffer"))
+  (let* ((proc (get-buffer-process (current-buffer)))
+         (tty (and proc (process-tty-name proc))))
+    (unless (and tty (not (string-empty-p tty)))
+      (user-error "Could not determine vterm tty"))
+    (cj/vterm--tmux-pane-id-for-tty tty)))
+
+(defvar-keymap cj/vterm-tmux-history-mode-map
+  :doc "Keymap for `cj/vterm-tmux-history-mode'."
+  "M-w" #'cj/vterm-tmux-history-copy-and-quit
+  "q" #'cj/vterm-tmux-history-quit)
+
+(define-derived-mode cj/vterm-tmux-history-mode special-mode "Tmux History"
+  "Mode for copying captured tmux pane history with normal Emacs keys."
+  (setq-local truncate-lines t)
+  (goto-address-mode 1))
+
+(defun cj/vterm-tmux-history-quit ()
+  "Quit tmux history and return to its origin buffer."
+  (interactive)
+  (let ((history-buffer (current-buffer))
+        (origin-buffer cj/vterm-tmux-history--origin-buffer)
+        (origin-window cj/vterm-tmux-history--origin-window)
+        (origin-point cj/vterm-tmux-history--origin-point))
+    (when (buffer-live-p origin-buffer)
+      (if (window-live-p origin-window)
+          (progn
+            (set-window-buffer origin-window origin-buffer)
+            (select-window origin-window))
+        (pop-to-buffer origin-buffer))
+      (with-current-buffer origin-buffer
+        (when (integer-or-marker-p origin-point)
+          (goto-char origin-point))))
+    (when (buffer-live-p history-buffer)
+      (kill-buffer history-buffer))))
+
+(defun cj/vterm-tmux-history-copy-and-quit ()
+  "Copy active region from tmux history, then quit back to the origin."
+  (interactive)
+  (unless (use-region-p)
+    (user-error "No active region"))
+  (let ((text (buffer-substring-no-properties
+               (region-beginning)
+               (region-end))))
+    (kill-new text)
+    (deactivate-mark)
+    (cj/vterm-tmux-history-quit)))
+
+(defun cj/vterm-tmux-history ()
+  "Open full tmux pane history in a temporary Emacs buffer.
+
+The history buffer uses normal Emacs navigation and selection.  `M-w'
+copies the active region, closes the history buffer, and returns point
+to the vterm buffer that launched it."
+  (interactive)
+  (let* ((origin-buffer (current-buffer))
+         (origin-window (selected-window))
+         (origin-point (point))
+         (pane-id (cj/vterm--current-tmux-pane-id))
+         (history (cj/vterm--tmux-capture-pane pane-id))
+         (buffer (get-buffer-create
+                  (format "*vterm tmux history: %s*" (buffer-name origin-buffer)))))
+    (with-current-buffer buffer
+      (let ((inhibit-read-only t))
+        (erase-buffer)
+        (insert history))
+      (cj/vterm-tmux-history-mode)
+      (setq-local cj/vterm-tmux-history--origin-buffer origin-buffer)
+      (setq-local cj/vterm-tmux-history--origin-window origin-window)
+      (setq-local cj/vterm-tmux-history--origin-point origin-point)
+      (goto-char (point-max)))
+    (pop-to-buffer buffer)))
+
+(defalias 'cj/vterm-history #'cj/vterm-tmux-history)
+
+(defun cj/vterm-copy-mode-cancel ()
+  "Exit `vterm-copy-mode' without copying."
+  (interactive)
+  (unless (bound-and-true-p vterm-copy-mode)
+    (user-error "This command is effective only in vterm-copy-mode"))
+  (vterm-copy-mode -1))
+
 (use-package vterm
   :defer .5
   :commands (vterm vterm-other-window)
   :init
+  (defvar vterm-keymap-exceptions
+    '("C-c" "C-x" "C-u" "C-g" "C-h" "C-l" "M-x" "M-o" "C-y" "M-y")
+    "Exceptions for `vterm-keymap'.")
+  (add-to-list 'vterm-keymap-exceptions "C-;")
   (setq vterm-always-compile-module t)
 
   (defun cj/turn-off-chrome-for-vterm ()
@@ -222,8 +358,8 @@ ai-vterm.el is loaded."
 		("<f9>"    . nil)
 		("<f10>"   . nil)
 		("<f12>"   . nil)
+		("C-c C-t" . nil)
 		("C-y"     . vterm-yank)
-		("C-p"     . vtermf-copy-mode)
 		("<pause>" . vterm-copy-mode))
   :custom
   (vterm-kill-buffer-on-exit t)
@@ -420,5 +556,46 @@ C-F9 / M-F9 dispatch via `cj/ai-vterm'."
 
 (keymap-global-set "<f12>" #'cj/vterm-toggle)
 
+(keymap-set cj/vterm-map "C" #'cj/vterm-tmux-history)
+(keymap-set cj/vterm-map "c" #'vterm-copy-mode)
+(keymap-set cj/vterm-map "l" #'vterm-clear-scrollback)
+(keymap-set cj/vterm-map "n" #'vterm)
+(keymap-set cj/vterm-map "o" #'vterm-other-window)
+(keymap-set cj/vterm-map "q" #'vterm-send-next-key)
+(keymap-set cj/vterm-map "r" #'vterm-reset-cursor-point)
+(keymap-set cj/vterm-map "t" #'cj/vterm-toggle)
+
+(defun cj/vterm-install-prefix-key ()
+  "Make `C-;' resolve as the personal keymap inside vterm buffers."
+  (when (boundp 'vterm-mode-map)
+    (keymap-set vterm-mode-map "C-;" cj/custom-keymap)))
+
+(defun cj/vterm-install-copy-mode-cancel-keys ()
+  "Install copy and cancel keys in `vterm-copy-mode-map'."
+  (when (boundp 'vterm-copy-mode-map)
+    (keymap-set vterm-copy-mode-map "C-g" #'cj/vterm-copy-mode-cancel)
+    (keymap-set vterm-copy-mode-map "<escape>" #'cj/vterm-copy-mode-cancel)
+    (keymap-set vterm-copy-mode-map "M-w" #'vterm-copy-mode-done)))
+
+(cj/vterm-install-prefix-key)
+(cj/vterm-install-copy-mode-cancel-keys)
+(with-eval-after-load 'vterm
+  (cj/vterm-install-prefix-key)
+  (cj/vterm-install-copy-mode-cancel-keys))
+
+(add-hook 'vterm-mode-hook #'goto-address-mode)
+
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; V" "vterm menu"
+    "C-; V C" "tmux scrollback copy"
+    "C-; V c" "vterm copy mode"
+    "C-; V l" "clear vterm scrollback"
+    "C-; V n" "new vterm"
+    "C-; V o" "vterm other window"
+    "C-; V q" "send next key to vterm"
+    "C-; V r" "reset vterm cursor point"
+    "C-; V t" "toggle vterm"))
+
 (provide 'eshell-vterm-config)
 ;;; eshell-vterm-config.el ends here.
diff --git a/tests/test-vterm-tmux-history.el b/tests/test-vterm-tmux-history.el
new file mode 100644
index 00000000..33fa1330
--- /dev/null
+++ b/tests/test-vterm-tmux-history.el
@@ -0,0 +1,141 @@
+;;; test-vterm-tmux-history.el --- Tests for tmux history capture UX -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Exercises the Emacs-owned history buffer used to copy text from the
+;; current tmux pane without entering tmux copy-mode.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+(setq load-prefer-newer t)
+(defvar vterm-mode-map (make-sparse-keymap))
+(defvar vterm-copy-mode-map (make-sparse-keymap))
+(keymap-set vterm-mode-map "C-c C-t" #'ignore)
+(require 'eshell-vterm-config)
+(require 'testutil-vterm-buffers)
+
+(defmacro test-vterm-tmux-history--with-tmux-mock (responses &rest body)
+  "Run BODY with `process-file' mocked for tmux RESPONSES.
+
+RESPONSES is an alist of (ARGS EXIT-CODE OUTPUT)."
+  (declare (indent 1))
+  `(let ((calls nil))
+     (cl-letf (((symbol-function 'process-file)
+                (lambda (program _infile destination _display &rest args)
+                  (push (cons program args) calls)
+                  (let* ((entry (seq-find
+                                 (lambda (candidate)
+                                   (equal (car candidate) args))
+                                 ,responses))
+                         (exit-code (or (cadr entry) 1))
+                         (output (or (caddr entry) "")))
+                    (when destination
+                      (let ((buffer (cond
+                                     ((eq destination t) (current-buffer))
+                                     ((bufferp destination) destination)
+                                     ((consp destination) (car destination)))))
+                        (when (bufferp buffer)
+                          (with-current-buffer buffer
+                            (insert output)))))
+                    exit-code))))
+       ,@body)))
+
+(ert-deftest test-vterm-tmux-history--pane-id-for-tty-matches-client ()
+  "Normal: current vterm pty maps to the active pane for that tmux client."
+  (test-vterm-tmux-history--with-tmux-mock
+      '((("list-clients" "-F" "#{client_tty}\t#{pane_id}") 0
+         "/dev/pts/1\t%1\n/dev/pts/8\t%8\n"))
+    (should (equal (cj/vterm--tmux-pane-id-for-tty "/dev/pts/8") "%8"))))
+
+(ert-deftest test-vterm-tmux-history--capture-pane-uses-full-history ()
+  "Normal: capture asks tmux for joined full pane history."
+  (test-vterm-tmux-history--with-tmux-mock
+      '((("capture-pane" "-p" "-J" "-S" "-" "-E" "-" "-t" "%8") 0
+         "first line\nsecond line\n"))
+    (should (equal (cj/vterm--tmux-capture-pane "%8")
+                   "first line\nsecond line\n"))))
+
+(ert-deftest test-vterm-tmux-history-open-renders-read-only-history-buffer ()
+  "Normal: command renders tmux history in a normal Emacs buffer."
+  (let ((origin (cj/test--make-fake-vterm-buffer "*test-vterm-history-origin*")))
+    (unwind-protect
+        (with-current-buffer origin
+          (cl-letf (((symbol-function 'get-buffer-process)
+                     (lambda (_buffer) 'fake-process))
+                    ((symbol-function 'process-tty-name)
+                     (lambda (_process) "/dev/pts/8"))
+                    ((symbol-function 'pop-to-buffer)
+                     (lambda (buffer &rest _)
+                       (set-buffer buffer)
+                       buffer)))
+            (test-vterm-tmux-history--with-tmux-mock
+                '((("list-clients" "-F" "#{client_tty}\t#{pane_id}") 0
+                   "/dev/pts/8\t%8\n")
+                  (("capture-pane" "-p" "-J" "-S" "-" "-E" "-" "-t" "%8") 0
+                   "history http://example.com\n"))
+              (cj/vterm-tmux-history)
+              (should (eq major-mode 'cj/vterm-tmux-history-mode))
+              (should buffer-read-only)
+              (should (string-match-p "history http://example.com"
+                                      (buffer-string)))))))
+      (cj/test--kill-buffers-matching-prefix "*vterm tmux history")
+      (when (buffer-live-p origin)
+        (kill-buffer origin))))
+
+(ert-deftest test-vterm-tmux-history-copy-copies-region-and-returns ()
+  "Normal: M-w copies the region, kills history buffer, and restores origin."
+  (let ((origin (get-buffer-create "*test-vterm-history-return*"))
+        (kill-ring nil))
+    (unwind-protect
+        (let ((history (get-buffer-create "*vterm tmux history: test*")))
+          (with-current-buffer origin
+            (erase-buffer)
+            (insert "origin")
+            (goto-char (point-min)))
+          (switch-to-buffer origin)
+          (let ((origin-window (selected-window)))
+            (with-current-buffer history
+              (cj/vterm-tmux-history-mode)
+              (let ((inhibit-read-only t))
+                (insert "alpha\nbeta\ngamma\n"))
+              (setq-local cj/vterm-tmux-history--origin-buffer origin)
+              (setq-local cj/vterm-tmux-history--origin-window origin-window)
+              (setq-local cj/vterm-tmux-history--origin-point (point-min))
+              (goto-char (point-min))
+              (set-mark (point))
+              (goto-char (point-at-eol 2))
+              (activate-mark)
+              (cj/vterm-tmux-history-copy-and-quit))
+            (should (equal (car kill-ring) "alpha\nbeta"))
+            (should-not (buffer-live-p history))
+            (should (eq (current-buffer) origin))
+            (should (= (point) (point-min)))))
+      (when (buffer-live-p origin)
+        (kill-buffer origin)))))
+
+(ert-deftest test-vterm-keymap-includes-history-and-copy-bindings ()
+  "Normal: personal vterm map owns the high-level vterm UX commands."
+  (should (member "C-;" vterm-keymap-exceptions))
+  (should-not (eq (keymap-lookup cj/custom-keymap "v c") #'vterm-copy-mode))
+  (should (eq (keymap-lookup cj/custom-keymap "V C") #'cj/vterm-tmux-history))
+  (should (eq (keymap-lookup cj/custom-keymap "V c") #'vterm-copy-mode))
+  (should (equal (keymap-lookup vterm-mode-map "C-;") cj/custom-keymap))
+  (should (eq (keymap-lookup vterm-mode-map "C-; V C") #'cj/vterm-tmux-history))
+  (should (eq (keymap-lookup vterm-mode-map "C-; V c") #'vterm-copy-mode))
+  (should-not (keymap-lookup vterm-mode-map "C-c C-t")))
+
+(ert-deftest test-vterm-copy-mode-cancel-keys ()
+  "Normal: copy mode has explicit copy and no-copy exits."
+  (should (eq (keymap-lookup vterm-copy-mode-map "C-g")
+              #'cj/vterm-copy-mode-cancel))
+  (should (eq (keymap-lookup vterm-copy-mode-map "<escape>")
+              #'cj/vterm-copy-mode-cancel))
+  (should (eq (keymap-lookup vterm-copy-mode-map "M-w")
+              #'vterm-copy-mode-done)))
+
+(provide 'test-vterm-tmux-history)
+;;; test-vterm-tmux-history.el ends here