sergeant 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b7c3b966daedbb73dc65a9ceb67bb5653791757713bc33dd838f3327d9c33b
-  data.tar.gz: 636ed748a5e8efbe0291ccacb65031c814524e85e731ce076c9918c8adcfddc0
+  metadata.gz: ac9c7c93fc3b942684b0f038cf0fa8658cc17c2a1fdc732a9bfef538bc4afa78
+  data.tar.gz: f4c839577ff9a2c23560e22332adf2641c2614118cc017b5e83cb7a0c3219878
 SHA512:
-  metadata.gz: d7e9b24e7f865efadec5dfe8729945bbf4c24bfa49df8c175e85d5de45c63457aba733fe09156950293e1ef3af4addd3831dd4e5a32f353e507b09667749eb23
-  data.tar.gz: 2b24694b491e148932545f6a727ca966a4803c489ca9d623098cd5e36ecc53cbcaf5761cf5fb1c6e259390555f6341551a1d55a1d765069a582275fc8d4c811a
+  metadata.gz: 24182721fbd0c5edb7900440b452a29ad2f7d98092e57c9701bad1bd19872faa38fa9d60985985785abb26734e5772604e4a90fa9862dab85d1646b880b98a45
+  data.tar.gz: 0e7d245c24cca22da30aba6c5fffd988f66ec82b93e34a83e0e543bf48657c1f1ada2985003e9157afc418b758e974ed86e400faf948570c4d5570a29aae65f4

data/CHANGELOG.md

@@ -5,7 +5,34 @@ 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.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 +61,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 +82,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 +93,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

@@ -73,7 +73,7 @@ sudo dnf install ncurses-devel ruby-devel
 
 ## 🚀 Installation
 
-### Install from RubyGems (Coming Soon)
+### Install from RubyGems
 
 Once published to RubyGems:
 
@@ -142,6 +142,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 +155,59 @@ 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]
+
+# 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 |

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,195 @@ 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
+      --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 --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
+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 '--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).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/file_operations.rb

@@ -23,6 +23,9 @@ module Sergeant
           if editor
             # Use user's preferred editor
             system("#{editor} \"#{file_path}\"")
+          elsif Gem.win_platform?
+            # Windows: use notepad (always available)
+            system("notepad \"#{file_path}\"")
           elsif nvim_available?
             # Second fallback: nvim (modern vim)
             system("nvim \"#{file_path}\"")
@@ -83,8 +86,11 @@ module Sergeant
         close_screen
 
         begin
+          if Gem.win_platform?
+            # Windows: use notepad for preview (simpler and always works)
+            system("notepad \"#{file_path}\"")
           # Use glow for markdown files if available, otherwise fall back to less
-          if file_ext == '.md' && glow_available?
+          elsif file_ext == '.md' && glow_available?
             system("glow -p \"#{file_path}\"")
           elsif file_ext == '.md'
             system("less -R -F -X \"#{file_path}\"")

data/lib/sergeant/rendering.rb

@@ -4,6 +4,13 @@
 
 module Sergeant
   module Rendering
+    # Use ASCII icons on Windows for better terminal compatibility
+    WINDOWS = Gem.win_platform?
+    ICON_DIR = WINDOWS ? '[D] ' : '📁 '
+    ICON_FILE = WINDOWS ? '[F] ' : '📄 '
+    ICON_MARK = WINDOWS ? '* ' : '✓ '
+    ICON_SELECT = WINDOWS ? '> ' : '▶ '
+
     def draw_screen
       clear
 
@@ -127,13 +134,13 @@ module Sergeant
     end
 
     def draw_item(item, max_x, is_selected)
-      icon = item[:type] == :directory ? '📁 ' : '📄 '
+      icon = item[:type] == :directory ? ICON_DIR : ICON_FILE
 
       # Check if item is marked
       is_marked = @marked_items.include?(item[:path])
-      mark_indicator = is_marked ? '✓ ' : '  '
+      mark_indicator = is_marked ? ICON_MARK : '  '
 
-      prefix = is_selected ? '▶ ' : '  '
+      prefix = is_selected ? ICON_SELECT : '  '
 
       size_str = format_size(item[:size])
       date_str = format_date(item[:mtime])

data/lib/sergeant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sergeant
-  VERSION = '1.0.3'
+  VERSION = '1.0.5'
 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)
+    @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 = []
@@ -41,8 +43,8 @@ class SergeantApp
   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

data/sergeant.gemspec

@@ -24,6 +24,8 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").reject do |f|
       f.match(%r{\A(?:test|spec|features)/}) ||
         f.match(%r{\A\.}) ||
+        f.match(%r{\.DS_Store$}) ||
+        f.match(%r{\.(gif|png|jpg|jpeg|mp4|webm)$}) ||  # Exclude media files
         f == 'build.rb' ||
         f == 'install.sh' ||
         f == 'sgt.rb'
@@ -34,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.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Mateusz Grotha
@@ -66,13 +66,9 @@ files:
 - LICENSE
 - README.md
 - bin/sgt
-- highlight.gif
-- lib/.DS_Store
 - lib/sergeant.rb
-- lib/sergeant/.DS_Store
 - lib/sergeant/config.rb
 - lib/sergeant/modals.rb
-- lib/sergeant/modals/.DS_Store
 - lib/sergeant/modals/dialogs.rb
 - lib/sergeant/modals/file_operations.rb
 - lib/sergeant/modals/help.rb
@@ -89,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