sergeant 1.0.7 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c874d9cc43e11d9c891bf372f1324f188c7a1b5aebe5ee4ddcb71bb5db68c66
-  data.tar.gz: 2a47b52f0ae9fe27c7e02b13a74338b34c0db9a768bf36216048e838445843e3
+  metadata.gz: 36d4f8c54ef4d4f7168cb42c81abe472b8094bf67c648096e9513bdfcca9ad15
+  data.tar.gz: 820962c25da75cc167c88dfe3407fb1de3e294444bd5c737ec09779c46414aed
 SHA512:
-  metadata.gz: d9b9b02b04e41563f2a623f64228b07f2de2a551480d1547a731e4d09d577033c2bb29ceb1c8c5b0b56d22000d6c8bb51c267fc6e415f07190badcde85b631fc
-  data.tar.gz: 7a23e6671b4e1c77231060e3dde2cde017d859ce8cfacff23c449166cc7b62b1c3df0bcec53f3243ab5c193d6c82de7b5c73dfe684f671c3db1f3679aeed32b6
+  metadata.gz: 1838e264508e70d0c4012560764396c7772e9fb2a50ea1517c52ad584ced2f5d2cecdc7d19efab344ae25d80bb036964f8aa11d39667d5f79afedac05c4c75e4
+  data.tar.gz: 8e00de4e37bb7e3d971f39eb1dbce3932131941b80af2549c0e778d23a3c5a6a90b0d57e5aa956582467e112d3e052e0f496c71d602c61ccebbd06a453bff2cd

data/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.0.8] - 2026-08-19
+
+### Fixed
+- **Screen flicker on every keypress in fast terminals**
+  - `draw_screen` was calling curses' `clear`, forcing a full blank-then-redraw on each keystroke
+  - Barely visible on slower/buffered terminals but very noticeable on fast, immediate-mode terminals like Alacritty
+  - Switched to `erase`, which only rewrites the virtual buffer so `refresh` repaints just the changed cells
+
+### Added
+- **File-type colors** - files are now color-coded by category (archives, media, code, executables) in addition to the existing directory/file distinction, configurable via `~/.sgtrc`
+- **Live side preview panel** (`P` key) - shows the first lines of a text file or a directory's contents in a panel next to the list, without leaving the UI or shelling out to a pager. Appears automatically once the terminal is wide enough
+
 ## [1.0.7] - 2026-03-09
 
 ### Added

data/Gemfile

@@ -2,8 +2,6 @@
 
 source 'https://rubygems.org'
 
-ruby '>= 2.7.0'
-
 # Terminal UI library
 gem 'curses', '~> 1.4'
 

data/README.md

@@ -15,7 +15,8 @@ Simple, fast, and elegant.
 ### Navigation & Display
 - 🗂️  **Visual Directory Navigation** - See all directories and files at a glance
 - ⌨️  **Keyboard Driven** - Arrow keys, vim bindings (hjkl), and shortcuts
-- 🎨 **Color-Coded Display** - Directories in cyan, files grayed out
+- 🎨 **Color-Coded Display** - Directories in cyan; files colored by type (code, archives, media, executables)
+- 👀 **Live Preview Pane** - Text files and directory contents preview in a side panel as you move (press 'P' to toggle)
 - 📊 **Smart Scrolling** - Handles directories with hundreds of items
 - 🔍 **Git Branch Display** - Shows current git branch in header
 - 👤 **Ownership Toggle** - View file permissions and ownership (press 'o')
@@ -244,6 +245,7 @@ cd $(sgt --pwd /usr/local)
 | `/` | Search files (requires fzf) |
 | `:` | Execute terminal command in current directory |
 | `o` | Toggle ownership/permissions display |
+| `P` | Toggle side preview panel |
 | `b` | Go to bookmark |
 | `H` | Show recent directories history |
 | `R` | Force refresh and clear cache |
@@ -264,6 +266,10 @@ selected_fg=black
 header=yellow
 path=green
 git_branch=magenta
+archives=red
+media=magenta
+code=blue
+executables=green
 
 # Bookmarks
 [bookmarks]

data/lib/sergeant/config.rb

@@ -22,7 +22,11 @@ module Sergeant
       'selected_fg' => 'black',
       'header' => 'yellow',
       'path' => 'green',
-      'git_branch' => 'magenta'
+      'git_branch' => 'magenta',
+      'archives' => 'red',
+      'media' => 'magenta',
+      'code' => 'blue',
+      'executables' => 'green'
     }.freeze
 
     MINIMAL_CONFIG_TEMPLATE = <<~CONFIG.freeze
@@ -35,6 +39,10 @@ module Sergeant
       header=yellow
       path=green
       git_branch=magenta
+      archives=red
+      media=magenta
+      code=blue
+      executables=green
 
       # Bookmarks
       [bookmarks]

data/lib/sergeant/modals/help.rb

@@ -68,6 +68,7 @@ module Sergeant
           'Other:',
           '  :                 - Execute terminal command',
           '  o                 - Toggle ownership display',
+          '  P                 - Toggle side preview panel',
           '  b                 - Go to bookmark',
           '  H                 - Show recent directories history',
           '  R                 - Force refresh and clear cache',

data/lib/sergeant/rendering.rb

@@ -11,12 +11,40 @@ module Sergeant
     ICON_MARK = WINDOWS ? '* ' : '✓ '
     ICON_SELECT = WINDOWS ? '> ' : '▶ '
 
+    # Side preview panel only kicks in once the terminal is wide enough that
+    # both panes stay readable; below that it just doesn't fit.
+    MIN_PREVIEW_TOTAL_WIDTH = 100
+    MIN_PREVIEW_WIDTH = 24
+    PREVIEW_WIDTH_RATIO = 0.35
+
+    # Maps file_category (Sergeant::Utils) to the color pair set up in
+    # Sergeant#apply_color_theme (pairs 7-10).
+    FILE_CATEGORY_COLOR_PAIRS = {
+      archive: 7,
+      media: 8,
+      code: 9,
+      executable: 10
+    }.freeze
+
     def draw_screen
-      clear
+      # `erase` only rewrites the virtual buffer; `refresh` then diffs it
+      # against the physical screen and repaints just the changed cells.
+      # `clear` forces a full physical blank-then-redraw on every call,
+      # which flickers visibly on fast terminals like Alacritty.
+      erase
 
       max_y = lines - 1
       max_x = cols
 
+      preview_enabled = @show_preview && max_x >= MIN_PREVIEW_TOTAL_WIDTH
+      if preview_enabled
+        preview_width = [(max_x * PREVIEW_WIDTH_RATIO).to_i, MIN_PREVIEW_WIDTH].max
+        list_width = max_x - preview_width - 1
+      else
+        preview_width = 0
+        list_width = max_x
+      end
+
       setpos(0, 0)
       attron(color_pair(4) | Curses::A_BOLD) do
         addstr("┌─ Sergeant - 'Leave it to the Sarge!' ".ljust(max_x, '─'))
@@ -42,9 +70,11 @@ module Sergeant
       end
       status_text = status_parts.empty? ? '' : " | #{status_parts.join(' | ')}"
 
+      status_width = list_width
+
       if branch
         branch_text = " [#{branch}]"
-        path_max_length = max_x - 4 - branch_text.length - status_text.length
+        path_max_length = status_width - 4 - branch_text.length - status_text.length
         path_display = @current_dir.length > path_max_length ? "...#{@current_dir[(-path_max_length + 3)..]}" : @current_dir
 
         attron(color_pair(5)) do
@@ -58,9 +88,9 @@ module Sergeant
             addstr(status_text)
           end
         end
-        remaining = max_x - 2 - path_display.length - branch_text.length - status_text.length
+        remaining = status_width - 2 - path_display.length - branch_text.length - status_text.length
       else
-        path_max_length = max_x - 4 - status_text.length
+        path_max_length = status_width - 4 - status_text.length
         path_display = @current_dir.length > path_max_length ? "...#{@current_dir[(-path_max_length + 3)..]}" : @current_dir
 
         attron(color_pair(5)) do
@@ -71,7 +101,7 @@ module Sergeant
             addstr(status_text)
           end
         end
-        remaining = max_x - 2 - path_display.length - status_text.length
+        remaining = status_width - 2 - path_display.length - status_text.length
       end
       addstr(''.ljust(remaining)) if remaining.positive?
 
@@ -103,18 +133,8 @@ module Sergeant
 
         is_selected = actual_index == @selected_index
 
-        if is_selected
-          attron(color_pair(3) | Curses::A_BOLD) do
-            draw_item(item, max_x, true)
-          end
-        elsif item[:type] == :directory
-          attron(color_pair(1)) do
-            draw_item(item, max_x, false)
-          end
-        else
-          attron(color_pair(2) | Curses::A_DIM) do
-            draw_item(item, max_x, false)
-          end
+        attron(item_attributes(item, is_selected)) do
+          draw_item(item, list_width, is_selected)
         end
       end
 
@@ -124,15 +144,28 @@ module Sergeant
         scroll_pos = (@scroll_offset.to_f / (total - visible)) * (visible - 1)
         scroll_pos = scroll_pos.round.clamp(0, visible - 1)
 
-        setpos(3 + scroll_pos, max_x - 1)
+        setpos(3 + scroll_pos, list_width - 1)
         attron(color_pair(4) | Curses::A_BOLD) do
           addstr('█')
         end
       end
 
+      draw_preview_panel(list_width, preview_width, max_y, visible_lines) if preview_enabled
+
       refresh
     end
 
+    # Which curses attributes to draw a list row with: selection highlight
+    # wins, then directories, then a file's type-based color (falling back
+    # to the plain dimmed file color when its category has none).
+    def item_attributes(item, is_selected)
+      return color_pair(3) | Curses::A_BOLD if is_selected
+      return color_pair(1) if item[:type] == :directory
+
+      pair = FILE_CATEGORY_COLOR_PAIRS[file_category(item)]
+      pair ? color_pair(pair) : (color_pair(2) | Curses::A_DIM)
+    end
+
     def draw_item(item, max_x, is_selected)
       icon = item[:type] == :directory ? ICON_DIR : ICON_FILE
 
@@ -171,5 +204,99 @@ module Sergeant
 
       addstr(display)
     end
+
+    # Draws the divider, title row and content of the side preview panel.
+    # Content itself is precomputed by Sergeant#update_preview_if_needed -
+    # this method only ever paints what's already in @preview_lines, so it
+    # stays cheap even though draw_screen runs on every keystroke.
+    def draw_preview_panel(list_width, preview_width, max_y, visible_lines)
+      col = list_width + 1
+      width = preview_width - 1
+      return if width <= 1
+
+      draw_preview_divider(list_width, max_y)
+      draw_preview_title(col, width)
+
+      case @preview_kind
+      when :text
+        if @preview_lines.empty?
+          draw_preview_message(col, width, '(empty file)')
+        else
+          draw_preview_lines(col, width, visible_lines, @preview_lines, color_pair(2))
+        end
+      when :directory
+        if @preview_lines.empty?
+          draw_preview_message(col, width, '(empty directory)')
+        else
+          names = @preview_lines.map { |name| "  #{name}" }
+          draw_preview_lines(col, width, visible_lines, names, color_pair(1))
+        end
+      else
+        draw_preview_message(col, width, preview_placeholder_message)
+      end
+    end
+
+    def draw_preview_divider(list_width, max_y)
+      setpos(0, list_width)
+      attron(color_pair(4) | Curses::A_BOLD) { addstr('┬') }
+
+      (1...max_y).each do |row|
+        next if row == 2
+
+        setpos(row, list_width)
+        attron(color_pair(4)) { addstr('│') }
+      end
+
+      setpos(2, list_width)
+      attron(color_pair(4)) { addstr('┼') }
+    end
+
+    def draw_preview_title(col, width)
+      label = case @preview_kind
+              when :directory then "#{ICON_DIR}#{@preview_item[:name]}"
+              when :text, :binary then "#{ICON_FILE}#{@preview_item[:name]}"
+              else ''
+              end
+
+      setpos(1, col)
+      attron(color_pair(5) | Curses::A_BOLD) do
+        addstr(truncate_for_preview(label, width).ljust(width))
+      end
+    end
+
+    def draw_preview_lines(col, width, visible_lines, source_lines, pair)
+      visible_lines.times do |idx|
+        setpos(idx + 3, col)
+        line = source_lines[idx]
+        attron(pair) do
+          addstr((line ? truncate_for_preview(line, width) : '').ljust(width))
+        end
+      end
+    end
+
+    def draw_preview_message(col, width, message)
+      setpos(3, col)
+      attron(color_pair(2) | Curses::A_DIM) do
+        addstr(truncate_for_preview(message, width).ljust(width))
+      end
+    end
+
+    def truncate_for_preview(text, width)
+      return text if text.length <= width
+      return text[0, width].to_s if width <= 1
+
+      "#{text[0, width - 1]}…"
+    end
+
+    def preview_placeholder_message
+      case @preview_kind
+      when :empty then '(empty directory)'
+      when :binary
+        size = @preview_item && @preview_item[:size]
+        size ? "(no preview - #{format_size(size).strip})" : '(no preview available)'
+      else
+        ''
+      end
+    end
   end
 end

data/lib/sergeant/utils.rb

@@ -4,6 +4,28 @@
 
 module Sergeant
   module Utils
+    ARCHIVE_EXTENSIONS = %w[.zip .tar .gz .tgz .bz2 .tbz2 .xz .txz .7z .rar .zst .lz .lzma .cab .iso .deb .rpm .apk
+                            .jar .war].freeze
+    MEDIA_EXTENSIONS = %w[.png .jpg .jpeg .gif .bmp .svg .webp .ico .tiff .tif .heic .avif
+                          .mp4 .mkv .avi .mov .wmv .flv .webm .m4v .mpg .mpeg
+                          .mp3 .wav .flac .ogg .aac .m4a .wma .opus].freeze
+    CODE_EXTENSIONS = %w[.rb .py .js .jsx .mjs .cjs .ts .tsx .go .rs .c .cpp .cc .h .hpp .java .kt .kts .swift .php
+                         .sh .bash .zsh .fish .lua .pl .pm .r .scala .clj .cljs .ex .exs .erl .hs .ml .mli .sql
+                         .html .htm .css .scss .sass .less .json .yaml .yml .toml .xml .vue .svelte].freeze
+
+    # Which color pair (see Sergeant#apply_color_theme) to use for a file,
+    # based on its extension, falling back to the executable bit. Directories
+    # are colored separately by draw_screen and never reach this method.
+    def file_category(item)
+      ext = File.extname(item[:name]).downcase
+      return :archive if ARCHIVE_EXTENSIONS.include?(ext)
+      return :media if MEDIA_EXTENSIONS.include?(ext)
+      return :code if CODE_EXTENSIONS.include?(ext)
+      return :executable if item[:mode] && (item[:mode] & 0o111).nonzero? && ext.empty?
+
+      :file
+    end
+
     def get_git_branch
       return nil unless Dir.exist?(File.join(@current_dir, '.git'))
 

data/lib/sergeant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sergeant
-  VERSION = '1.0.7'
+  VERSION = '1.0.8'
 end

data/lib/sergeant.rb

@@ -21,6 +21,10 @@ class SergeantApp
   include Sergeant::Modals
   include Sergeant::Rendering
 
+  # Side preview panel content limits
+  PREVIEW_LINE_LIMIT = 500
+  PREVIEW_LINE_MAX_BYTES = 2000
+
   def initialize(start_dir: nil, no_color: false, pwd_mode: false, restore_session: false)
     @current_dir = start_dir || Dir.pwd
     @selected_index = 0
@@ -39,6 +43,13 @@ class SergeantApp
     @filter_text = ''
     @all_items = []
 
+    # Side preview panel
+    @show_preview = true
+    @last_preview_path = :unset
+    @preview_kind = :empty
+    @preview_item = nil
+    @preview_lines = []
+
     # Stat caching for performance
     @stat_cache = {}
     @cache_ttl = 5  # seconds
@@ -74,6 +85,7 @@ class SergeantApp
       loop do
         # Only refresh items when directory changes, not on every keystroke
         refresh_items_if_needed
+        update_preview_if_needed
         draw_screen
 
         key = getch
@@ -95,6 +107,9 @@ class SergeantApp
           goto_bookmark
         when 'o'
           @show_ownership = !@show_ownership
+        when 'P'
+          @show_preview = !@show_preview
+          @last_preview_path = :unset
         when 'e'
           edit_file
         when 'v'
@@ -165,6 +180,10 @@ class SergeantApp
     init_pair(4, Sergeant::Config.get_color(@config['header']), Curses::COLOR_BLACK)
     init_pair(5, Sergeant::Config.get_color(@config['path']), Curses::COLOR_BLACK)
     init_pair(6, Sergeant::Config.get_color(@config['git_branch']), Curses::COLOR_BLACK)
+    init_pair(7, Sergeant::Config.get_color(@config['archives']), Curses::COLOR_BLACK)
+    init_pair(8, Sergeant::Config.get_color(@config['media']), Curses::COLOR_BLACK)
+    init_pair(9, Sergeant::Config.get_color(@config['code']), Curses::COLOR_BLACK)
+    init_pair(10, Sergeant::Config.get_color(@config['executables']), Curses::COLOR_BLACK)
   end
 
   def search_files
@@ -335,6 +354,69 @@ class SergeantApp
 
     # Also clear cache for current directory
     clear_cache_for_directory(@current_dir)
+
+    # The selected item's content may have changed too
+    @last_preview_path = :unset
+  end
+
+  # Side preview panel
+
+  def update_preview_if_needed
+    return unless @show_preview
+
+    item = @items[@selected_index]
+    path = item && item[:path]
+
+    # Only rebuild the preview when the selection actually points at a new
+    # path - never on every keystroke/redraw, to keep this cheap even in
+    # directories with many files.
+    return if path == @last_preview_path
+
+    @last_preview_path = path
+    @preview_item = item
+    @preview_kind, @preview_lines = build_preview(item)
+  end
+
+  def build_preview(item)
+    return [:empty, []] unless item
+    return [:parent, []] if item[:name] == '..'
+
+    if item[:type] == :directory
+      [:directory, build_directory_preview(item[:path])]
+    elsif text_file?(item[:path])
+      [:text, build_text_preview(item[:path])]
+    else
+      [:binary, []]
+    end
+  end
+
+  def build_directory_preview(path)
+    names = []
+
+    # each_child is lazy, so even a directory with huge numbers of entries
+    # only costs us PREVIEW_LINE_LIMIT reads, not a full scan.
+    Dir.each_child(path) do |name|
+      names << name
+      break if names.length >= PREVIEW_LINE_LIMIT
+    end
+
+    names.sort_by(&:downcase)
+  rescue Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR
+    []
+  end
+
+  def build_text_preview(path)
+    lines = []
+
+    File.foreach(path, mode: 'rb') do |line|
+      text = line.byteslice(0, PREVIEW_LINE_MAX_BYTES).to_s.chomp
+      lines << text.force_encoding('UTF-8').scrub('?').gsub("\t", '    ')
+      break if lines.length >= PREVIEW_LINE_LIMIT
+    end
+
+    lines
+  rescue StandardError
+    []
   end
 
   def refresh_items
@@ -384,7 +466,8 @@ class SergeantApp
             size: stat.size,
             mtime: stat.mtime,
             owner: owner_info,
-            perms: perms
+            perms: perms,
+            mode: stat.mode
           }
         end
       rescue Errno::EACCES, Errno::ENOENT

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sergeant
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.0.8
 platform: ruby
 authors:
 - Mateusz Grotha