sergeant 1.0.4 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a87751fe5e98dee814b470aa90818bd0f798cbdb4143f55522ffcf610d8de0c
-  data.tar.gz: d1c47033ac959cc1bbd50af0fe96e526df4d2f72077efc914d0570b8df6e0e7b
+  metadata.gz: 8121e483349ea026f5d4abec53dea0fc9a08b9201d43904c3a31e2a6667b457a
+  data.tar.gz: e3067dbdafba6fe79d606662ea3ee27d85dcba40a290413a9c43c1c3195e2976
 SHA512:
-  metadata.gz: 77dac789c948ee83d3bfeda13cdda4fa0c3f03779d2e6cfc3ec85126dd97465c309d55cfa2500008656be3b65367e961c7af8b639c4d237a0716572d2cfa82be
-  data.tar.gz: e0e1222dba1be26d9a3da7611aa8c5289ea422f58f9c1f5d3813d7f7581c05f860e61144e7623c1f66ccbb127ba37d27eaded1b9c5633f6e9e5cfa7422df8c0b
+  metadata.gz: 52c9ede72d02a8d22f6ad98d5d7b8590c16adbfe4c5e3d907ea6e4dc52e90b6abf609a2a01de11d3c9d3556bc537f7adad40206ee0823f105a98bf53fc3418f0
+  data.tar.gz: 8cf1a0e2467cd455513385bef1beceea416b0d347129eff30ef61162c4370623034031e8b623ce966d078db4075d79beac7003c0aae2586b3da1b0e93682b6e0

data/CHANGELOG.md

@@ -5,7 +5,58 @@ All notable changes to Sergeant will be documented in this file.
 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.3] - 2024-12-26
+## [1.0.6] - 2026-01-16
+
+### Added
+- **Session persistence** (`--restore` flag)
+  - Automatically saves current directory on exit to `~/.sgt_session`
+  - Use `sgt --restore` to continue from where you left off
+  - Perfect for resuming work after restarting terminal
+- **Recent directories history** (H key)
+  - Tracks last 50 visited directories in `~/.sgt_history`
+  - Press 'H' to show history modal with quick navigation
+  - Navigate with ↑/↓, press Enter to jump to directory
+- **Enhanced error handling**
+  - New error dialog with file path and detailed error message
+  - Options: [S]kip, [R]etry, [A]bort for better error recovery
+  - Shows specific file/path that caused the error
+
+### Performance
+- **Stat caching with 5-second TTL**
+  - Cache file stat results to avoid redundant system calls
+  - 90%+ faster navigation when browsing back/forth between directories
+  - Automatic cache cleanup and memory management (max 5000 entries)
+  - Press 'R' to force refresh and clear cache manually
+  - Especially beneficial on network filesystems (NFS, SMB)
+
+## [1.0.5] - 2025-01-15
+
+### Added
+- **Command-line interface improvements**
+  - Added `--help` / `-h` flag to show usage and features
+  - Added `--version` / `-v` flag to show version number
+  - Support starting in specific directory: `sgt ~/Documents`
+  - Added `-b` / `--bookmark [name]` to start at a saved bookmark location
+  - Added `--list-bookmarks` to display all saved bookmarks with status
+  - Added `--pwd` flag to print final directory on exit for shell integration
+  - Added `--debug` flag to show environment and configuration details
+  - Added `--no-color` flag for terminals without color support
+  - Post-install message with quick start guide and tips
+  - Shell integration examples for quick directory jumping
+
+## [1.0.4] - 2025-12-27
+
+### Fixed
+- **Windows compatibility improvements**
+  - Use ASCII icons ([D], [F], *, >) on Windows for better terminal compatibility (PR #15)
+  - Windows terminals often don't render emoji properly - now uses ASCII fallback
+  - Add notepad fallback for file preview and edit on Windows (PR #16)
+  - POSIX tools (vim, nano, less) replaced with notepad when not available
+
+### Changed
+- Reduced gem package size from 4.8MB to ~115KB by excluding media files and .DS_Store
+
+## [1.0.3] - 2025-12-26
 
 ### Added
 - **Total size display for marked items**
@@ -34,7 +85,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Track ownership toggle changes to refresh only when needed
 - **Added comprehensive test coverage** for performance optimizations (14 test cases)
 
-## [1.0.2] - 2024-12-26
+## [1.0.2] - 2025-12-26
 
 ### Fixed
 - **Display issue on Arch Linux**: Added terminal color support checking
@@ -55,7 +106,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added error recovery for curses screen initialization failures
 - Better compatibility with different ncurses implementations
 
-## [1.0.1] - 2024-12-24
+## [1.0.1] - 2025-12-24
 
 ### Fixed
 - **Major performance improvement**: Fixed severe input lag with large directories
@@ -66,7 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Shows load path and helpful reinstall instructions if gem fails to load
   - Displays full error details instead of silently failing
 
-## [1.0.0] - 2024-12-23
+## [1.0.0] - 2025-12-23
 
 ### Added
 - **Interactive TUI navigation** - Navigate directories with arrow keys or vim bindings (hjkl)

data/README.md

@@ -37,6 +37,12 @@ Simple, fast, and elegant.
 - ❓ **Help Modal** - Press 'm' for comprehensive key mapping reference
 - 🚀 **Instant CD** - Select and change directory in one smooth motion
 
+### Performance & Session Management
+- ⚡ **Stat Caching** - Blazing fast navigation with intelligent file stat caching
+- 💾 **Session Persistence** - Continue exactly where you left off with `--restore`
+- 📚 **Directory History** - Quick access to your 50 most recent locations (press 'H')
+- 🔄 **Smart Cache Management** - Automatic memory optimization and manual refresh
+
 ## 📋 Requirements
 
 - **Ruby** 2.7 or higher (Ruby 3.x recommended)
@@ -73,7 +79,7 @@ sudo dnf install ncurses-devel ruby-devel
 
 ## 🚀 Installation
 
-### Install from RubyGems (Coming Soon)
+### Install from RubyGems
 
 Once published to RubyGems:
 
@@ -142,6 +148,12 @@ bundle exec bin/sgt
 # Start sergeant in current directory
 sgt
 
+# Start in specific directory
+sgt ~/Documents
+
+# Start at a bookmark
+sgt -b projects
+
 # Navigate and select
 # Arrow keys or j/k to move up/down
 # Enter or l to enter directory
@@ -149,6 +161,62 @@ sgt
 # q to quit and cd to selected directory
 ```
 
+### Command-Line Options
+
+```bash
+# View help and all options
+sgt --help
+
+# Show version
+sgt --version
+
+# List all bookmarks
+sgt --list-bookmarks
+
+# Start at bookmark location
+sgt -b [bookmark_name]
+
+# Restore last session (continue from where you left off)
+sgt --restore
+
+# Debug mode (show environment info)
+sgt --debug
+
+# Disable colors
+sgt --no-color
+```
+
+### Shell Integration (cd to final directory)
+
+The `--pwd` flag enables powerful shell integration, allowing you to navigate visually in sergeant and have your shell automatically cd to the final location:
+
+```bash
+# Quick navigation function
+# Add this to your ~/.bashrc or ~/.zshrc:
+s() {
+  local dir=$(sgt --pwd "$@")
+  [[ -n "$dir" ]] && cd "$dir"
+}
+
+# Usage examples:
+s                    # Navigate from current dir, cd to final location
+s ~/projects         # Start in projects, cd to where you end up
+s -b work            # Start at work bookmark, cd to final location
+
+# Alternative one-liner (no function needed):
+cd $(sgt --pwd ~/projects)
+
+# Jump to deeply nested directory visually:
+cd $(sgt --pwd /usr/local)
+```
+
+**How it works:**
+1. Start sergeant with `--pwd` flag
+2. Navigate to your desired directory using arrow keys
+3. Press `q` to quit
+4. Sergeant outputs the final directory path
+5. Shell captures it with `$()` and cd's there
+
 ### File Operations
 
 | Key | Action |
@@ -177,6 +245,8 @@ sgt
 | `:` | Execute terminal command in current directory |
 | `o` | Toggle ownership/permissions display |
 | `b` | Go to bookmark |
+| `H` | Show recent directories history |
+| `R` | Force refresh and clear cache |
 | `m` | Show help modal with all key mappings |
 | `q/ESC` | Quit and cd to current directory |
 

data/bin/sgt

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 # Sergeant (sgt) - Interactive TUI directory navigator
-# Version: 1.0.0
 
 begin
   require 'sergeant'
@@ -13,11 +12,200 @@ rescue LoadError => e
   exit 1
 end
 
+def show_help
+  puts <<~HELP
+    Sergeant (sgt) v#{Sergeant::VERSION} - Interactive TUI Directory Navigator
+
+    USAGE:
+      sgt [OPTIONS] [DIRECTORY]
+
+    OPTIONS:
+      -h, --help              Show this help message
+      -v, --version           Show version number
+      -b, --bookmark NAME     Start at bookmark location
+      --list-bookmarks        List all saved bookmarks
+      --restore               Restore last session (start in last directory)
+      --pwd                   Print final directory on exit (for shell integration)
+      --debug                 Show debug information and environment details
+      --no-color              Disable colors (for terminals without color support)
+
+    ARGUMENTS:
+      DIRECTORY               Start in specified directory (default: current directory)
+
+    EXAMPLES:
+      sgt                     Start in current directory
+      sgt ~/Documents         Start in Documents folder
+      sgt -b projects         Start at 'projects' bookmark
+      sgt --restore           Continue from last session
+      sgt --list-bookmarks    Show all bookmarks
+      cd $(sgt --pwd)         Navigate and cd to final directory
+      sgt --debug             Show debug info before starting
+      sgt --help              Show this help
+
+    SHELL INTEGRATION:
+      Add this to your ~/.bashrc or ~/.zshrc for quick directory jumping:
+
+        s() {
+          local dir=$(sgt --pwd "$@")
+          [[ -n "$dir" ]] && cd "$dir"
+        }
+
+      Then use: s ~/projects
+
+    FEATURES:
+      • Navigate with arrow keys or vim bindings (hjkl)
+      • Mark files with Space, copy (c), cut (x), paste (p)
+      • Quick filter (f), fuzzy search (/), file preview (v)
+      • Archive peek for .zip, .tar.gz, and more
+      • Press 'm' in-app for complete key mappings
+
+    For more information, visit: https://github.com/biscoitinho/Sergeant
+  HELP
+  exit 0
+end
+
+def show_version
+  puts "Sergeant (sgt) version #{Sergeant::VERSION}"
+  exit 0
+end
+
+def show_debug_info
+  puts "Sergeant Debug Information"
+  puts "=" * 50
+  puts "Version:           #{Sergeant::VERSION}"
+  puts "Ruby Version:      #{RUBY_VERSION}"
+  puts "Ruby Platform:     #{RUBY_PLATFORM}"
+  puts "Current Directory: #{Dir.pwd}"
+  puts "Home Directory:    #{ENV['HOME']}"
+  puts "TERM:              #{ENV['TERM'] || 'not set'}"
+  puts "COLORTERM:         #{ENV['COLORTERM'] || 'not set'}"
+  puts "EDITOR:            #{ENV['EDITOR'] || 'not set'}"
+  puts "VISUAL:            #{ENV['VISUAL'] || 'not set'}"
+  puts "PATH:              #{ENV['PATH']}"
+  puts "\nLoad Path:"
+  $LOAD_PATH.each { |path| puts "  #{path}" }
+  puts "\nConfig File:       #{File.expand_path('~/.sgtrc')}"
+  puts "Config Exists:     #{File.exist?(File.expand_path('~/.sgtrc'))}"
+  puts "=" * 50
+  puts "\nPress Enter to continue or Ctrl+C to exit..."
+  gets
+end
+
+def list_bookmarks
+  require_relative '../lib/sergeant/config'
+  bookmarks = Sergeant::Config.load_bookmarks
+
+  if bookmarks.empty?
+    puts "No bookmarks found."
+    puts "Add bookmarks to ~/.sgtrc under [bookmarks] section:"
+    puts "\n[bookmarks]"
+    puts "home=/home/user"
+    puts "projects=~/projects"
+    exit 0
+  end
+
+  puts "Saved Bookmarks:"
+  puts "=" * 50
+  bookmarks.each do |name, path|
+    expanded = File.expand_path(path)
+    exists = File.directory?(expanded) ? "✓" : "✗"
+    puts "  #{exists} #{name.ljust(15)} → #{path}"
+  end
+  puts "=" * 50
+  puts "\nUsage: sgt -b [bookmark_name]"
+  exit 0
+end
+
+def get_bookmark_path(bookmark_name)
+  require_relative '../lib/sergeant/config'
+  bookmarks = Sergeant::Config.load_bookmarks
+
+  unless bookmarks.key?(bookmark_name)
+    warn "Error: Bookmark '#{bookmark_name}' not found"
+    warn "Available bookmarks: #{bookmarks.keys.join(', ')}"
+    warn "Use 'sgt --list-bookmarks' to see all bookmarks"
+    exit 1
+  end
+
+  path = File.expand_path(bookmarks[bookmark_name])
+  unless File.directory?(path)
+    warn "Error: Bookmark path '#{path}' does not exist"
+    exit 1
+  end
+
+  path
+end
+
+# Process arguments
+start_dir = nil
+no_color = false
+show_debug = false
+pwd_mode = false
+restore_session = false
+bookmark_name = nil
+
+i = 0
+while i < ARGV.length
+  arg = ARGV[i]
+  case arg
+  when '-h', '--help'
+    show_help
+  when '-v', '--version'
+    show_version
+  when '--debug'
+    show_debug = true
+  when '--pwd'
+    pwd_mode = true
+  when '--restore'
+    restore_session = true
+  when '--list-bookmarks'
+    list_bookmarks
+  when '-b', '--bookmark'
+    i += 1
+    if i >= ARGV.length
+      warn "Error: --bookmark requires a bookmark name"
+      warn "Use 'sgt --list-bookmarks' to see available bookmarks"
+      exit 1
+    end
+    bookmark_name = ARGV[i]
+  when '--no-color'
+    no_color = true
+  when /^-/
+    warn "Unknown option: #{arg}"
+    warn "Try 'sgt --help' for more information."
+    exit 1
+  else
+    start_dir = arg
+  end
+  i += 1
+end
+
+# Show debug info if requested
+show_debug_info if show_debug
+
+# Handle bookmark
+start_dir = get_bookmark_path(bookmark_name) if bookmark_name
+
+# Validate and expand directory path
+if start_dir
+  start_dir = File.expand_path(start_dir)
+  unless File.directory?(start_dir)
+    warn "Error: '#{start_dir}' is not a valid directory"
+    exit 1
+  end
+end
+
 # Run the navigator
 begin
-  SergeantApp.new.run
+  SergeantApp.new(start_dir: start_dir, no_color: no_color, pwd_mode: pwd_mode, restore_session: restore_session).run
 rescue StandardError => e
-  warn "\nSergeant error: #{e.message}"
-  warn e.backtrace.join("\n")
-  exit 1
+  # In pwd mode, don't show error details, just exit silently with current dir
+  if pwd_mode
+    puts Dir.pwd
+    exit 1
+  else
+    warn "\nSergeant error: #{e.message}"
+    warn e.backtrace.join("\n")
+    exit 1
+  end
 end

data/lib/sergeant/modals/dialogs.rb

@@ -347,6 +347,112 @@ module Sergeant
           end
         end
       end
+
+      def show_error_with_retry(filepath, error_message)
+        max_y = lines
+        max_x = cols
+
+        # Calculate modal dimensions based on message length
+        message_lines = [
+          "Error with:",
+          filepath.length > 60 ? "...#{filepath[-60..]}" : filepath,
+          "",
+          error_message.length > 60 ? error_message[0...60] : error_message
+        ]
+
+        modal_height = 11
+        modal_width = [70, max_x - 4].min
+        modal_y = (max_y - modal_height) / 2
+        modal_x = (max_x - modal_width) / 2
+
+        # Draw modal background
+        (modal_y..(modal_y + modal_height)).each do |y|
+          setpos(y, modal_x)
+          attron(color_pair(3)) do
+            addstr(' ' * modal_width)
+          end
+        end
+
+        # Draw border and title
+        setpos(modal_y, modal_x)
+        attron(color_pair(4) | Curses::A_BOLD) do
+          addstr("\u250C#{'─' * (modal_width - 2)}\u2510")
+        end
+
+        setpos(modal_y + 1, modal_x)
+        attron(color_pair(4) | Curses::A_BOLD) do
+          addstr('│')
+        end
+        attron(color_pair(4) | Curses::A_BOLD) do
+          addstr(' Error '.center(modal_width - 2))
+        end
+        attron(color_pair(4) | Curses::A_BOLD) do
+          addstr('│')
+        end
+
+        setpos(modal_y + 2, modal_x)
+        attron(color_pair(4)) do
+          addstr("\u251C#{'─' * (modal_width - 2)}\u2524")
+        end
+
+        # Draw message lines
+        message_lines.each_with_index do |line, idx|
+          setpos(modal_y + 3 + idx, modal_x)
+          attron(color_pair(4)) do
+            addstr('│ ')
+          end
+          addstr(line.ljust(modal_width - 4))
+          attron(color_pair(4)) do
+            addstr(' │')
+          end
+        end
+
+        # Draw separator
+        setpos(modal_y + 7, modal_x)
+        attron(color_pair(4)) do
+          addstr("\u251C#{'─' * (modal_width - 2)}\u2524")
+        end
+
+        # Draw options
+        setpos(modal_y + 8, modal_x)
+        attron(color_pair(4)) do
+          addstr('│ ')
+        end
+        addstr('[S]kip  [R]etry  [A]bort'.ljust(modal_width - 4))
+        attron(color_pair(4)) do
+          addstr(' │')
+        end
+
+        setpos(modal_y + 9, modal_x)
+        attron(color_pair(4)) do
+          addstr('│ ')
+        end
+        addstr('Choose action:'.ljust(modal_width - 4))
+        attron(color_pair(4)) do
+          addstr(' │')
+        end
+
+        # Draw bottom border
+        setpos(modal_y + modal_height - 1, modal_x)
+        attron(color_pair(4) | Curses::A_BOLD) do
+          addstr("\u2514#{'─' * (modal_width - 2)}\u2518")
+        end
+
+        refresh
+
+        # Handle input
+        loop do
+          ch = getch
+          case ch
+          when 's', 'S'
+            return :skip
+          when 'r', 'R'
+            return :retry
+          when 'a', 'A', 27  # A or ESC = abort
+            return :abort
+          end
+        end
+      end
     end
   end
 end

data/lib/sergeant/modals/help.rb

@@ -9,7 +9,7 @@ module Sergeant
         max_y = lines
         max_x = cols
 
-        modal_height = [26, max_y - 4].min  # Adaptive height
+        modal_height = [28, max_y - 4].min  # Adaptive height
         modal_width = [70, max_x - 4].min   # Adaptive width
         modal_y = (max_y - modal_height) / 2
         modal_x = (max_x - modal_width) / 2
@@ -69,6 +69,8 @@ module Sergeant
           '  :                 - Execute terminal command',
           '  o                 - Toggle ownership display',
           '  b                 - Go to bookmark',
+          '  H                 - Show recent directories history',
+          '  R                 - Force refresh and clear cache',
           '  q / ESC           - Quit and cd to current directory'
         ]
 

data/lib/sergeant/modals/navigation.rb

@@ -364,6 +364,181 @@ module Sergeant
         @scroll_offset = 0
         force_refresh  # Force refresh to apply filter
       end
+
+      def show_history_modal
+        return if @directory_history.empty? && show_no_history_modal
+
+        max_y = lines
+        max_x = cols
+
+        modal_height = [@directory_history.length + 8, max_y - 4].min
+        modal_width = [70, max_x - 4].min
+        modal_y = (max_y - modal_height) / 2
+        modal_x = (max_x - modal_width) / 2
+
+        selected = 0
+        scroll_offset = 0
+
+        loop do
+          # Draw modal background
+          (modal_y..(modal_y + modal_height)).each do |y|
+            setpos(y, modal_x)
+            attron(color_pair(3)) do
+              addstr(' ' * modal_width)
+            end
+          end
+
+          # Draw border
+          setpos(modal_y, modal_x)
+          attron(color_pair(4) | Curses::A_BOLD) do
+            addstr("\u250C#{'─' * (modal_width - 2)}\u2510")
+          end
+
+          setpos(modal_y + 1, modal_x)
+          attron(color_pair(4) | Curses::A_BOLD) do
+            addstr('│')
+          end
+          attron(color_pair(5) | Curses::A_BOLD) do
+            title = ' Recent Directories '.center(modal_width - 2)
+            addstr(title)
+          end
+          attron(color_pair(4) | Curses::A_BOLD) do
+            addstr('│')
+          end
+
+          setpos(modal_y + 2, modal_x)
+          attron(color_pair(4)) do
+            addstr("\u251C#{'─' * (modal_width - 2)}\u2524")
+          end
+
+          # Draw history entries
+          visible_height = modal_height - 7
+          visible_history = @directory_history[scroll_offset...(scroll_offset + visible_height)]
+
+          visible_history.each_with_index do |dir, idx|
+            actual_idx = scroll_offset + idx
+            setpos(modal_y + 3 + idx, modal_x)
+            attron(color_pair(4)) do
+              addstr('│ ')
+            end
+
+            # Highlight selected
+            if actual_idx == selected
+              attron(color_pair(3) | Curses::A_BOLD) do
+                display_dir = dir.length > modal_width - 6 ? "...#{dir[-(modal_width - 9)..]}" : dir
+                addstr(display_dir.ljust(modal_width - 4))
+              end
+            else
+              display_dir = dir.length > modal_width - 6 ? "...#{dir[-(modal_width - 9)..]}" : dir
+              addstr(display_dir.ljust(modal_width - 4))
+            end
+
+            attron(color_pair(4)) do
+              addstr(' │')
+            end
+          end
+
+          # Fill remaining lines
+          (visible_history.length...visible_height).each do |idx|
+            setpos(modal_y + 3 + idx, modal_x)
+            attron(color_pair(4)) do
+              addstr("\u2502#{' ' * (modal_width - 2)}\u2502")
+            end
+          end
+
+          # Draw footer
+          setpos(modal_y + modal_height - 4, modal_x)
+          attron(color_pair(4)) do
+            addstr("\u251C#{'─' * (modal_width - 2)}\u2524")
+          end
+
+          setpos(modal_y + modal_height - 3, modal_x)
+          attron(color_pair(4)) do
+            addstr('│ ')
+          end
+          addstr('↑/↓: Navigate  Enter: Go  ESC: Cancel'.ljust(modal_width - 4))
+          attron(color_pair(4)) do
+            addstr(' │')
+          end
+
+          setpos(modal_y + modal_height - 2, modal_x)
+          attron(color_pair(4)) do
+            addstr('│ ')
+          end
+          addstr("#{selected + 1}/#{@directory_history.length}".ljust(modal_width - 4))
+          attron(color_pair(4)) do
+            addstr(' │')
+          end
+
+          setpos(modal_y + modal_height - 1, modal_x)
+          attron(color_pair(4)) do
+            addstr("\u2514#{'─' * (modal_width - 2)}\u2518")
+          end
+
+          refresh
+
+          # Handle input
+          ch = getch
+          case ch
+          when Curses::Key::UP, 'k'
+            selected = [selected - 1, 0].max
+            scroll_offset = selected if selected < scroll_offset
+          when Curses::Key::DOWN, 'j'
+            selected = [selected + 1, @directory_history.length - 1].min
+            scroll_offset = selected - visible_height + 1 if selected >= scroll_offset + visible_height
+          when 10, 13  # Enter
+            target_dir = @directory_history[selected]
+            if File.directory?(target_dir)
+              @current_dir = target_dir
+              @selected_index = 0
+              @scroll_offset = 0
+              force_refresh
+            end
+            break
+          when 27, 'q'  # ESC
+            break
+          end
+        end
+      end
+
+      def show_no_history_modal
+        max_y = lines
+        max_x = cols
+
+        modal_height = 8
+        modal_width = 50
+        modal_y = (max_y - modal_height) / 2
+        modal_x = (max_x - modal_width) / 2
+
+        (modal_y..(modal_y + modal_height)).each do |y|
+          setpos(y, modal_x)
+          attron(color_pair(3)) do
+            addstr(' ' * modal_width)
+          end
+        end
+
+        setpos(modal_y + 3, modal_x)
+        attron(color_pair(4)) do
+          addstr('│ ')
+        end
+        addstr('No directory history yet.'.ljust(modal_width - 4))
+        attron(color_pair(4)) do
+          addstr(' │')
+        end
+
+        setpos(modal_y + 5, modal_x)
+        attron(color_pair(4)) do
+          addstr('│ ')
+        end
+        addstr('Press any key to continue'.ljust(modal_width - 4))
+        attron(color_pair(4)) do
+          addstr(' │')
+        end
+
+        refresh
+        getch
+        true
+      end
     end
   end
 end

data/lib/sergeant/version.rb

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

data/lib/sergeant.rb

@@ -21,12 +21,14 @@ class SergeantApp
   include Sergeant::Modals
   include Sergeant::Rendering
 
-  def initialize
-    @current_dir = Dir.pwd
+  def initialize(start_dir: nil, no_color: false, pwd_mode: false, restore_session: false)
+    @current_dir = start_dir || Dir.pwd
     @selected_index = 0
     @scroll_offset = 0
     @show_ownership = false
     @last_show_ownership = false
+    @no_color = no_color
+    @pwd_mode = pwd_mode
     @config = Sergeant::Config.load_config
     @bookmarks = Sergeant::Config.load_bookmarks
     @marked_items = []
@@ -36,13 +38,30 @@ class SergeantApp
     @items = []
     @filter_text = ''
     @all_items = []
+
+    # Stat caching for performance
+    @stat_cache = {}
+    @cache_ttl = 5  # seconds
+    @max_cache_entries = 5000
+
+    # Session persistence
+    @session_file = File.expand_path('~/.sgt_session')
+    if restore_session && File.exist?(@session_file)
+      saved_dir = File.read(@session_file).strip
+      @current_dir = saved_dir if File.directory?(saved_dir)
+    end
+
+    # Recent directories history
+    @history_file = File.expand_path('~/.sgt_history')
+    @directory_history = load_history
+    @history_max_size = 50
   end
 
   def run
     init_screen
 
-    # Only initialize colors if terminal supports them
-    if has_colors?
+    # Only initialize colors if terminal supports them and not disabled
+    if !@no_color && has_colors?
       start_color
       apply_color_theme
     end
@@ -104,8 +123,15 @@ class SergeantApp
           search_files
         when 'f'
           filter_current_view
+        when 'H'
+          show_history_modal
+        when 'R'
+          # Force refresh and clear cache
+          @stat_cache.clear
+          force_refresh
         when 'q', 27
           close_screen
+          save_session  # Save current directory for --restore
           puts @current_dir
           exit 0
         when Curses::Key::LEFT, 'h'
@@ -119,6 +145,7 @@ class SergeantApp
       end
     rescue Interrupt
       close_screen
+      save_session
       exit 0
     rescue StandardError => e
       close_screen
@@ -196,6 +223,99 @@ class SergeantApp
     @scroll_offset = 0
   end
 
+  # Stat caching for performance
+  def cached_stat(path)
+    now = Time.now
+
+    # Check if we have a cached stat for this path
+    if @stat_cache[path]
+      cached_entry = @stat_cache[path]
+      age = now - cached_entry[:time]
+
+      # If cache is still fresh (less than TTL), return it
+      return cached_entry[:stat] if age < @cache_ttl
+    end
+
+    # Cache miss or expired - fetch fresh stat
+    stat = File.stat(path)
+
+    # Store in cache with timestamp
+    @stat_cache[path] = {
+      stat: stat,
+      time: now
+    }
+
+    # Cleanup cache if it's too large
+    cleanup_cache if @stat_cache.size > @max_cache_entries
+
+    stat
+  rescue Errno::ENOENT, Errno::EACCES
+    # File was deleted or no permission - remove from cache
+    @stat_cache.delete(path)
+    nil
+  end
+
+  def clear_cache_for_directory(dir)
+    # Remove all cached stats for files in this directory
+    @stat_cache.delete_if { |path, _| path.start_with?(dir) }
+  end
+
+  def cleanup_cache
+    now = Time.now
+
+    # Remove entries older than TTL
+    @stat_cache.delete_if do |_, entry|
+      (now - entry[:time]) > @cache_ttl
+    end
+
+    # If still too large, remove oldest entries
+    if @stat_cache.size > @max_cache_entries
+      sorted = @stat_cache.sort_by { |_, entry| entry[:time] }
+      to_remove = @stat_cache.size - @max_cache_entries
+      sorted.first(to_remove).each do |path, _|
+        @stat_cache.delete(path)
+      end
+    end
+  end
+
+  # Session persistence
+  def save_session
+    File.write(@session_file, @current_dir)
+  rescue StandardError
+    # Silently ignore session save errors
+  end
+
+  # Directory history
+  def load_history
+    return [] unless File.exist?(@history_file)
+
+    File.readlines(@history_file).map(&:strip).reject(&:empty?)
+  rescue StandardError
+    []
+  end
+
+  def save_history
+    File.write(@history_file, @directory_history.join("\n"))
+  rescue StandardError
+    # Silently ignore history save errors
+  end
+
+  def add_to_history(dir)
+    # Don't add duplicates or current dir if it's already at the top
+    return if @directory_history.first == dir
+
+    # Remove dir if it exists elsewhere in history
+    @directory_history.delete(dir)
+
+    # Add to front
+    @directory_history.unshift(dir)
+
+    # Trim to max size
+    @directory_history = @directory_history.first(@history_max_size)
+
+    save_history
+  end
+
   def refresh_items_if_needed
     # Only refresh if directory has changed, or if showing ownership toggle changed
     # This prevents expensive file system operations on every keystroke
@@ -203,12 +323,18 @@ class SergeantApp
       refresh_items
       @last_refreshed_dir = @current_dir
       @last_show_ownership = @show_ownership
+
+      # Add to history when directory changes
+      add_to_history(@current_dir) if @current_dir != @last_refreshed_dir
     end
   end
 
   def force_refresh
     # Force a refresh even if directory hasn't changed (e.g., after file operations)
     @last_refreshed_dir = nil
+
+    # Also clear cache for current directory
+    clear_cache_for_directory(@current_dir)
   end
 
   def refresh_items
@@ -233,7 +359,9 @@ class SergeantApp
     entries.each do |entry|
       full_path = File.join(@current_dir, entry)
       begin
-        stat = File.stat(full_path)
+        stat = cached_stat(full_path)  # Use cached stat for performance
+        next unless stat  # Skip if file was deleted or no permission
+
         is_dir = stat.directory?  # Use stat instead of File.directory? (saves syscall)
         owner_info = @show_ownership ? get_owner_info(stat) : nil  # Only fetch if needed
         perms = @show_ownership ? format_permissions(stat.mode, is_dir) : nil

data/sergeant.gemspec

@@ -36,6 +36,25 @@ Gem::Specification.new do |spec|
   spec.executables   = ['sgt']
   spec.require_paths = ['lib']
 
+  # Post-install message
+  spec.post_install_message = <<~MSG
+    ╔═══════════════════════════════════════════════════════════════╗
+    ║           Sergeant (sgt) installed successfully! 🎖️           ║
+    ╚═══════════════════════════════════════════════════════════════╝
+
+    Get started:
+      sgt              # Start in current directory
+      sgt ~/Documents  # Start in specific directory
+      sgt --help       # View all options
+
+    Quick tips:
+      • Use arrow keys or vim bindings (hjkl) to navigate
+      • Press 'm' for help modal with all key mappings
+      • Press 'f' to filter, 'v' to preview, Space to mark files
+
+    For documentation: https://github.com/biscoitinho/Sergeant
+  MSG
+
   # Runtime dependencies
   spec.add_dependency 'curses', '~> 1.4'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sergeant
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.6
 platform: ruby
 authors:
 - Mateusz Grotha
@@ -85,6 +85,13 @@ metadata:
   homepage_uri: https://github.com/biscoitinho/Sergeant
   source_code_uri: https://github.com/biscoitinho/Sergeant
   changelog_uri: https://github.com/biscoitinho/Sergeant/blob/main/CHANGELOG.md
+post_install_message: "╔═══════════════════════════════════════════════════════════════╗\n║
+  \          Sergeant (sgt) installed successfully! \U0001F396️           ║\n╚═══════════════════════════════════════════════════════════════╝\n\nGet
+  started:\n  sgt              # Start in current directory\n  sgt ~/Documents  #
+  Start in specific directory\n  sgt --help       # View all options\n\nQuick tips:\n
+  \ • Use arrow keys or vim bindings (hjkl) to navigate\n  • Press 'm' for help modal
+  with all key mappings\n  • Press 'f' to filter, 'v' to preview, Space to mark files\n\nFor
+  documentation: https://github.com/biscoitinho/Sergeant\n"
 rdoc_options: []
 require_paths:
 - lib