feat: improve visual selection handling in file tree buffers (#132)

# Improved Visual Selection Support for Tree Buffers

This PR enhances the file selection mechanism in tree-based file explorers (neo-tree, nvim-tree, mini.files) when using visual mode. The changes:

- Add dedicated visual selection handling for tree buffers that accurately captures files in visual selections
- Implement a fallback mechanism that tries visual selection first, then falls back to regular selection methods
- Add detailed logging for neo-tree integration to help diagnose selection issues
- Support directory nodes in visual selections for neo-tree
- Add unit tests to verify visual selection handling in tree buffers

These improvements make it more intuitive to select multiple files in file explorers using visual mode (V), similar to how neo-tree's built-in commands work with visual selections.

Author: ThomasK33

lua/claudecode/init.lua

@@ -691,22 +691,27 @@ function M._create_commands()
 
     if is_tree_buffer then
       local integrations = require("claudecode.integrations")
+      local visual_cmd_module = require("claudecode.visual_commands")
       local files, error
 
-      -- For mini.files, try to get the range from visual marks
+      -- For mini.files, try to get the range from visual marks for accuracy
       if current_ft == "minifiles" or string.match(current_bufname, "minifiles://") then
         local start_line = vim.fn.line("'<")
         local end_line = vim.fn.line("'>")
 
         if start_line > 0 and end_line > 0 and start_line <= end_line then
-          -- Use range-based selection for mini.files
           files, error = integrations._get_mini_files_selection_with_range(start_line, end_line)
         else
-          -- Fall back to regular method
-          files, error = integrations.get_selected_files_from_tree()
+          -- If range invalid, try visual selection fallback (uses pre-captured visual_data)
+          files, error = visual_cmd_module.get_files_from_visual_selection(visual_data)
         end
       else
-        files, error = integrations.get_selected_files_from_tree()
+        -- Use visual selection-aware extraction for tree buffers (neo-tree, nvim-tree, oil)
+        files, error = visual_cmd_module.get_files_from_visual_selection(visual_data)
+        if (not files or #files == 0) and not error then
+          -- Fallback: try generic selection if visual data was unavailable
+          files, error = integrations.get_selected_files_from_tree()
+        end
       end
 
       if error then

lua/claudecode/integrations.lua

@@ -2,6 +2,7 @@
 --- Handles detection and selection of files from nvim-tree, neo-tree, mini.files, and oil.nvim
 ---@module 'claudecode.integrations'
 local M = {}
+local logger = require("claudecode.logger")
 
 ---Get selected files from the current tree explorer
 ---@return table|nil files List of file paths, or nil if error
@@ -75,22 +76,33 @@ end
 function M._get_neotree_selection()
   local success, manager = pcall(require, "neo-tree.sources.manager")
   if not success then
+    logger.debug("integrations/neotree", "neo-tree not available (require failed)")
     return {}, "neo-tree not available"
   end
 
   local state = manager.get_state("filesystem")
   if not state then
+    logger.debug("integrations/neotree", "filesystem state not available from manager")
     return {}, "neo-tree filesystem state not available"
   end
 
   local files = {}
 
   -- Use neo-tree's own visual selection method (like their copy/paste feature)
   local mode = vim.fn.mode()
+  local current_win = vim.api.nvim_get_current_win()
+  logger.debug(
+    "integrations/neotree",
+    "begin selection",
+    "mode=",
+    mode,
+    "current_win=",
+    current_win,
+    "state.winid=",
+    tostring(state.winid)
+  )
 
   if mode == "V" or mode == "v" or mode == "\22" then
-    local current_win = vim.api.nvim_get_current_win()
-
     if state.winid and state.winid == current_win then
       -- Use neo-tree's exact method to get visual range (from their get_selected_nodes implementation)
       local start_pos = vim.fn.getpos("'<")[2]
@@ -113,6 +125,8 @@ function M._get_neotree_selection()
         start_pos, end_pos = end_pos, start_pos
       end
 
+      logger.debug("integrations/neotree", "visual selection range", start_pos, "to", end_pos)
+
       local selected_nodes = {}
 
       for line = start_pos, end_pos do
@@ -121,22 +135,59 @@ function M._get_neotree_selection()
           -- Add validation for node types before adding to selection
           if node.type and node.type ~= "message" then
             table.insert(selected_nodes, node)
+            local depth = (node.get_depth and node:get_depth()) and node:get_depth() or 0
+            logger.debug(
+              "integrations/neotree",
+              "line",
+              line,
+              "node type=",
+              tostring(node.type),
+              "depth=",
+              depth,
+              "path=",
+              tostring(node.path)
+            )
+          else
+            logger.debug("integrations/neotree", "line", line, "node rejected (type)", tostring(node and node.type))
           end
+        else
+          logger.debug("integrations/neotree", "line", line, "no node returned from state.tree:get_node")
         end
       end
 
+      logger.debug("integrations/neotree", "selected_nodes count=", #selected_nodes)
+
       for _, node in ipairs(selected_nodes) do
         -- Enhanced validation: check for file type and valid path
         if node.type == "file" and node.path and node.path ~= "" then
           -- Additional check: ensure it's not a root node (depth protection)
           local depth = (node.get_depth and node:get_depth()) and node:get_depth() or 0
           if depth > 1 then
             table.insert(files, node.path)
+            logger.debug("integrations/neotree", "accepted file", node.path)
+          else
+            logger.debug("integrations/neotree", "rejected file (depth<=1)", node.path)
           end
+        elseif node.type == "directory" and node.path and node.path ~= "" then
+          local depth = (node.get_depth and node:get_depth()) and node:get_depth() or 0
+          if depth > 1 then
+            table.insert(files, node.path)
+            logger.debug("integrations/neotree", "accepted directory", node.path)
+          else
+            logger.debug("integrations/neotree", "rejected directory (depth<=1)", node.path)
+          end
+        else
+          logger.debug(
+            "integrations/neotree",
+            "rejected node (missing path or unsupported type)",
+            tostring(node and node.type),
+            tostring(node and node.path)
+          )
         end
       end
 
       if #files > 0 then
+        logger.debug("integrations/neotree", "files from visual selection:", files)
         return files, nil
       end
     end
@@ -154,13 +205,23 @@ function M._get_neotree_selection()
     end
 
     if selection and #selection > 0 then
+      logger.debug("integrations/neotree", "using state selection count=", #selection)
       for _, node in ipairs(selection) do
         if node.type == "file" and node.path then
           table.insert(files, node.path)
+          logger.debug("integrations/neotree", "accepted file from state selection", node.path)
+        else
+          logger.debug(
+            "integrations/neotree",
+            "ignored non-file in state selection",
+            tostring(node and node.type),
+            tostring(node and node.path)
+          )
         end
       end
 
       if #files > 0 then
+        logger.debug("integrations/neotree", "files from state selection:", files)
         return files, nil
       end
     end
@@ -170,6 +231,14 @@ function M._get_neotree_selection()
     local node = state.tree:get_node()
 
     if node then
+      logger.debug(
+        "integrations/neotree",
+        "fallback single node",
+        "type=",
+        tostring(node.type),
+        "path=",
+        tostring(node.path)
+      )
       if node.type == "file" and node.path then
         return { node.path }, nil
       elseif node.type == "directory" and node.path then
@@ -178,6 +247,7 @@ function M._get_neotree_selection()
     end
   end
 
+  logger.debug("integrations/neotree", "no file found under cursor/selection")
   return {}, "No file found under cursor"
 end
 

lua/claudecode/visual_commands.lua

@@ -2,6 +2,7 @@
 ---Implements neo-tree-style visual mode exit and command processing
 ---@module 'claudecode.visual_commands'
 local M = {}
+local logger = require("claudecode.logger")
 
 ---Get current vim mode with fallback for test environments
 ---@param full_mode? boolean Whether to get full mode info (passed to vim.fn.mode)
@@ -38,6 +39,17 @@ function M.exit_visual_and_schedule(callback, ...)
   -- Capture visual selection data BEFORE exiting visual mode
   local visual_data = M.capture_visual_selection_data()
 
+  if visual_data and visual_data.tree_type == "neo-tree" then
+    logger.debug(
+      "visual_commands/neotree",
+      "captured visual before exit",
+      "range=",
+      visual_data.start_pos,
+      "to",
+      visual_data.end_pos
+    )
+  end
+
   pcall(function()
     vim.api.nvim_feedkeys(ESC_KEY, "i", true)
   end)
@@ -162,8 +174,17 @@ function M.get_tree_state()
 
     -- Validate we're in the correct neo-tree window
     if state.winid and state.winid == current_win then
+      logger.debug("visual_commands/neotree", "tree state detected for current window", "win=", current_win)
       return state, "neo-tree"
     else
+      logger.debug(
+        "visual_commands/neotree",
+        "tree state win mismatch",
+        "current_win=",
+        current_win,
+        "state.winid=",
+        tostring(state.winid)
+      )
       return nil, nil
     end
   elseif current_ft == "NvimTree" then
@@ -264,30 +285,61 @@ function M.get_files_from_visual_selection(visual_data)
   local files = {}
 
   if tree_type == "neo-tree" then
+    logger.debug("visual_commands/neotree", "processing visual selection", "range=", start_pos, "to", end_pos)
     local selected_nodes = {}
     for line = start_pos, end_pos do
       -- Neo-tree's tree:get_node() uses the line number directly (1-based)
       local node = tree_state.tree:get_node(line)
       if node then
         if node.type and node.type ~= "message" then
           table.insert(selected_nodes, node)
+          local depth = (node.get_depth and node:get_depth()) or 0
+          logger.debug(
+            "visual_commands/neotree",
+            "line",
+            line,
+            "node type=",
+            tostring(node.type),
+            "depth=",
+            depth,
+            "path=",
+            tostring(node.path)
+          )
+        else
+          logger.debug("visual_commands/neotree", "line", line, "node rejected (type)", tostring(node and node.type))
         end
+      else
+        logger.debug("visual_commands/neotree", "line", line, "no node returned from tree:get_node")
       end
     end
 
+    logger.debug("visual_commands/neotree", "selected_nodes count=", #selected_nodes)
+
     for _, node in ipairs(selected_nodes) do
       if node.type == "file" and node.path and node.path ~= "" then
         local depth = (node.get_depth and node:get_depth()) or 0
         if depth > 1 then
           table.insert(files, node.path)
+        else
+          logger.debug("visual_commands/neotree", "rejected file (depth<=1)", node.path)
         end
       elseif node.type == "directory" and node.path and node.path ~= "" then
         local depth = (node.get_depth and node:get_depth()) or 0
         if depth > 1 then
           table.insert(files, node.path)
+        else
+          logger.debug("visual_commands/neotree", "rejected directory (depth<=1)", node.path)
         end
+      else
+        logger.debug(
+          "visual_commands/neotree",
+          "rejected node (missing path or unsupported type)",
+          tostring(node and node.type),
+          tostring(node and node.path)
+        )
       end
     end
+    logger.debug("visual_commands/neotree", "files from visual selection:", files)
   elseif tree_type == "nvim-tree" then
     -- For nvim-tree, we need to manually map visual lines to tree nodes
     -- since nvim-tree doesn't have direct line-to-node mapping like neo-tree