Server(feat[buffers]): add save_buffer, load_buffer, list_buffers for buffer I/O

why: Buffer file I/O and listing are needed for exporting pane content,
importing data, and querying available buffers programmatically.
what:
- Add Server.save_buffer() wrapping save-buffer with append (-a),
  buffer_name (-b), and file path
- Add Server.load_buffer() wrapping load-buffer with buffer_name (-b)
  and file path
- Add Server.list_buffers() wrapping list-buffers returning raw output
- Add tests for save/load cycle, append mode, and buffer listing

Author: tony

src/libtmux/server.py

@@ -622,6 +622,102 @@ def delete_buffer(self, *, buffer_name: str | None = None) -> None:
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+    def save_buffer(
+        self,
+        path: StrPath,
+        *,
+        buffer_name: str | None = None,
+        append: bool | None = None,
+    ) -> None:
+        """Save a paste buffer to a file via ``$ tmux save-buffer``.
+
+        Parameters
+        ----------
+        path : str or PathLike
+            File path to save the buffer to.
+        buffer_name : str, optional
+            Name of the buffer (``-b`` flag). Defaults to the most recent.
+        append : bool, optional
+            Append to the file instead of overwriting (``-a`` flag).
+
+        Examples
+        --------
+        >>> import pathlib
+        >>> server.set_buffer('save_me')
+        >>> path = pathlib.Path(request.config.rootdir) / '..' / 'tmp_save.txt'
+        >>> server.save_buffer(str(path))
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if append:
+            tmux_args += ("-a",)
+
+        if buffer_name is not None:
+            tmux_args += ("-b", buffer_name)
+
+        tmux_args += (str(pathlib.Path(path).expanduser()),)
+
+        proc = self.cmd("save-buffer", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def load_buffer(
+        self,
+        path: StrPath,
+        *,
+        buffer_name: str | None = None,
+    ) -> None:
+        """Load a file into a paste buffer via ``$ tmux load-buffer``.
+
+        Parameters
+        ----------
+        path : str or PathLike
+            File path to load into the buffer.
+        buffer_name : str, optional
+            Name of the buffer (``-b`` flag).
+
+        Examples
+        --------
+        >>> import pathlib
+        >>> path = pathlib.Path(request.config.rootdir) / '..' / 'tmp_load.txt'
+        >>> _ = path.write_text('loaded')
+        >>> server.load_buffer(str(path), buffer_name='loaded_buf')
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if buffer_name is not None:
+            tmux_args += ("-b", buffer_name)
+
+        tmux_args += (str(pathlib.Path(path).expanduser()),)
+
+        proc = self.cmd("load-buffer", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def list_buffers(self) -> list[str]:
+        """List paste buffers via ``$ tmux list-buffers``.
+
+        Returns
+        -------
+        list[str]
+            Raw output lines from list-buffers.
+
+        Examples
+        --------
+        >>> server.set_buffer('buf_data')
+        >>> result = server.list_buffers()
+        >>> len(result) >= 1
+        True
+        """
+        proc = self.cmd("list-buffers")
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        return proc.stdout
+
     def switch_client(self, target_session: str) -> None:
         """Switch tmux client.
 

tests/test_server.py

@@ -561,6 +561,50 @@ def test_buffer_delete(server: Server) -> None:
         server.show_buffer(buffer_name="del_buf")
 
 
+def test_buffer_save_load(server: Server, tmp_path: pathlib.Path) -> None:
+    """Test Server.save_buffer() and load_buffer() cycle."""
+    server.new_session(session_name="buf_saveload")
+
+    # Set and save
+    server.set_buffer("save_test_data")
+    buf_file = tmp_path / "saved_buf.txt"
+    server.save_buffer(buf_file)
+
+    # Verify file content
+    assert buf_file.read_text() == "save_test_data"
+
+    # Load into a named buffer
+    server.load_buffer(buf_file, buffer_name="loaded_buf")
+    assert server.show_buffer(buffer_name="loaded_buf") == "save_test_data"
+
+
+def test_buffer_save_append(server: Server, tmp_path: pathlib.Path) -> None:
+    """Test Server.save_buffer() with append flag."""
+    server.new_session(session_name="buf_saveappend")
+
+    buf_file = tmp_path / "append_buf.txt"
+
+    server.set_buffer("first_line", buffer_name="app1")
+    server.save_buffer(buf_file, buffer_name="app1")
+
+    server.set_buffer("second_line", buffer_name="app2")
+    server.save_buffer(buf_file, buffer_name="app2", append=True)
+
+    content = buf_file.read_text()
+    assert "first_line" in content
+    assert "second_line" in content
+
+
+def test_list_buffers(server: Server) -> None:
+    """Test Server.list_buffers()."""
+    server.new_session(session_name="buf_list")
+    server.set_buffer("buf_a", buffer_name="list_a")
+    server.set_buffer("buf_b", buffer_name="list_b")
+
+    result = server.list_buffers()
+    assert len(result) >= 2
+
+
 def test_new_session_config_file(
     server: Server,
     tmp_path: pathlib.Path,