sergeant 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80f83fe4916418417a546134baeff0c43e0daf5e383b39cdd49c77bdea88e3a3
+  data.tar.gz: 6105effe9798842cf02bdb5b56e32b1b58e5838da3c66004b24da31365982758
+SHA512:
+  metadata.gz: a90c6c72ab39338aa0d27a603051a2fea99b97b9f9c0764f2cc3f59bde980c3310b0aa97015028543453e03b11d4fff62f162fc2ae716fa991a91090628bb680
+  data.tar.gz: 845f119f78cfb9d08d4afa1abd6816195b630a16e2276cc59a7caab318a34e7fa15cb1984e6aa9a82c5f43e758894238740ba99a8490a8d676c9577b0560e78f

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+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.0] - 2024-12-23
+
+### Added
+- **Interactive TUI navigation** - Navigate directories with arrow keys or vim bindings (hjkl)
+- **File operations**
+  - Mark/unmark files with Space
+  - Copy (c), cut (x), paste (p) with smart conflict resolution
+  - Delete with confirmation (d)
+  - Rename files/directories (r)
+  - Create new files/directories (n)
+- **File viewing and editing**
+  - Edit files with $EDITOR support (e) - respects POSIX conventions
+  - Preview files read-only (v) - markdown with glow, code with nvim/vim
+  - Fallback chain: $EDITOR → nano → nvim → vim → vi
+- **Terminal integration**
+  - Execute shell commands without leaving sgt (:)
+  - Commands run in current directory context
+- **Search and navigation**
+  - Fuzzy file search with fzf integration (/)
+  - Bookmarks system (b)
+  - Git branch display in header
+  - Parent directory navigation (h/←)
+- **UI features**
+  - Color-coded display (directories, files, selected items)
+  - Adaptive interface for narrow terminals and tiling window managers
+  - Smart scrolling for large directories
+  - Ownership/permissions toggle (o)
+  - Help modal with all key mappings (m)
+  - Status indicators for marked/copied items
+- **Configuration**
+  - Customizable colors via ~/.sgtrc
+  - Bookmark management in config file
+  - Theme support
+
+### Technical
+- Built as Ruby gem for easy installation
+- POSIX-compliant, respects environment variables ($EDITOR, $VISUAL)
+- Ncurses-based TUI
+- Comprehensive test suite with RSpec
+- No GUI dependencies - works in pure terminal
+
+[1.0.0]: https://github.com/biscoitinho/Sergeant/releases/tag/v1.0.0

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+ruby '>= 2.7.0'
+
+# Terminal UI library
+gem 'curses', '~> 1.4'
+
+group :development do
+  # Code linting and style checking
+  gem 'rubocop', '~> 1.81', require: false
+end
+
+group :test do
+  # Testing framework
+  gem 'rspec', '~> 3.13'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mateusz 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# 🎖️ Sergeant (sgt)
+
+![Sergeant Logo](./logo.svg)
+
+**Interactive TUI Directory Navigator for Terminal - "Leave it to the Sarge!"**
+
+Sergeant is a interactive terminal user interface (TUI) for navigating directories and managing files.
+Instead of typing `cd` and file manipulation commands, just run `sgt`,
+use arrow keys and keyboard shortcuts to navigate, preview, copy, move, and organize your files.
+Simple, fast, and elegant.
+
+## ✨ Features
+
+### 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
+- 📊 **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')
+- 📑 **Bookmarks** - Save and quickly navigate to favorite directories
+
+### File Operations
+- 📋 **Copy/Cut/Paste** - Mark files with spacebar, copy (c), cut (x), and paste (p)
+- ✂️  **Multi-file Selection** - Mark multiple files/folders for batch operations
+- 🗑️  **Delete with Confirmation** - Safe deletion with confirmation dialog
+- ✏️  **Rename** - Rename files and folders with pre-filled input
+- 🔄 **Conflict Resolution** - Smart handling of file conflicts (skip/overwrite/rename)
+- 📄 **File Preview** - View markdown files with glow, code files with vim/nano
+
+### Search & Productivity
+- 🔎 **Fuzzy Search** - Integrate with fzf for fast file finding
+- ❓ **Help Modal** - Press 'm' for comprehensive key mapping reference
+- 🚀 **Instant CD** - Select and change directory in one smooth motion
+
+## 📋 Requirements
+
+- **Ruby** 2.7 or higher (Ruby 3.x recommended)
+
+### System Dependencies
+
+The `curses` gem (installed automatically) requires native libraries:
+
+**macOS:**
+```bash
+# Usually works out of the box
+# If you get errors, install Xcode Command Line Tools:
+xcode-select --install
+
+# Recommended: Use Homebrew Ruby instead of system Ruby
+brew install ruby
+# Add to ~/.zshrc: export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
+```
+
+**Linux (Debian/Ubuntu):**
+```bash
+sudo apt-get install libncurses-dev ruby-dev
+```
+
+**Linux (Fedora/RHEL):**
+```bash
+sudo dnf install ncurses-devel ruby-devel
+```
+
+### Optional Tools
+- **glow** - For beautiful markdown preview (`brew install glow` or `go install github.com/charmbracelet/glow@latest`)
+- **fzf** - For fuzzy file search (`brew install fzf` or `sudo apt-get install fzf`)
+
+## 🚀 Installation
+
+### Install from RubyGems (Coming Soon)
+
+Once published to RubyGems:
+
+```bash
+gem install sergeant
+```
+
+### Install from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/biscoitinho/Sergeant.git
+cd Sergeant
+
+# Build and install the gem locally
+gem build sergeant.gemspec
+gem install ./sergeant-1.0.0.gem
+```
+
+That's it! The `sgt` command will automatically be added to your PATH.
+
+### Development Installation
+
+If you want to work on the gem:
+
+```bash
+# Clone and setup
+git clone https://github.com/biscoitinho/Sergeant.git
+cd Sergeant
+
+# Install dependencies
+bundle install
+
+# Run directly without installing
+bundle exec bin/sgt
+```
+
+## 🎮 Usage
+
+### Basic Navigation
+
+```bash
+# Start sergeant in current directory
+sgt
+
+# Navigate and select
+# Arrow keys or j/k to move up/down
+# Enter or l to enter directory
+# h to go back
+# q to quit and cd to selected directory
+```
+
+### File Operations
+
+| Key | Action |
+|-----|--------|
+| `Space` | Mark/unmark item for operations |
+| `c` | Copy marked items |
+| `x` | Cut marked items |
+| `p` | Paste copied/cut items |
+| `d` | Delete marked items (with confirmation) |
+| `r` | Rename current item |
+| `u` | Unmark all items |
+| `v` | Preview file (markdown/code) |
+
+### Other Commands
+
+| Key | Action |
+|-----|--------|
+| `↑/k` | Move up |
+| `↓/j` | Move down |
+| `Enter/→/l` | Open directory or preview file |
+| `←/h` | Go to parent directory |
+| `o` | Toggle ownership/permissions display |
+| `b` | Go to bookmark |
+| `/` | Search files (requires fzf) |
+| `m` | Show help modal with all key mappings |
+| `q/ESC` | Quit and cd to current directory |
+
+## ⚙️ Configuration
+
+Create a `~/.sgtrc` file to customize colors and bookmarks:
+
+```ini
+# Color theme (available: black, red, green, yellow, blue, magenta, cyan, white)
+[colors]
+directories=cyan
+files=white
+selected_bg=blue
+selected_fg=black
+header=yellow
+path=green
+git_branch=magenta
+
+# Bookmarks
+[bookmarks]
+home=/home/user
+projects=~/projects
+documents=~/Documents
+```
+
+## 🧪 Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/utils_spec.rb
+
+# Run with documentation format
+bundle exec rspec --format documentation
+```
+
+### Code Quality
+
+```bash
+# Run rubocop linter
+bundle exec rubocop
+
+# Auto-correct issues
+bundle exec rubocop -A
+```
+
+### Project Structure
+
+```
+sergeant/
+├── bin/
+│   └── sgt                   # Executable command
+├── lib/
+│   ├── sergeant.rb           # Main application class
+│   └── sergeant/
+│       ├── version.rb        # Gem version
+│       ├── config.rb         # Configuration and bookmark management
+│       ├── utils.rb          # Utility functions (formatting, file detection)
+│       ├── rendering.rb      # UI rendering and display logic
+│       ├── modals.rb         # Modal modules loader
+│       └── modals/           # Modal dialog modules
+│           ├── navigation.rb       # Bookmark navigation
+│           ├── dialogs.rb          # Info/error/confirmation dialogs
+│           ├── file_operations.rb  # File preview, copy, paste, delete, rename
+│           └── help.rb             # Help modal with key mappings
+├── spec/                     # RSpec test suite
+├── sergeant.gemspec          # Gem specification
+├── Gemfile                   # Bundler configuration
+└── README.md                 # This file
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+Be warn, that I reserve my personal judgement to new features
+as I'm very focused on not to bloat it with too many functionalities
+
+## 📝 License
+
+MIT License
+
+## 🙏 Acknowledgments
+
+- Built with Ruby and ncurses
+- Inspired by [Omarchy linux](https://omarchy.org) and terminal file managers like ranger and nnn
+- Uses [glow](https://github.com/charmbracelet/glow) for markdown rendering
+- Integrates with [fzf](https://github.com/junegunn/fzf) for fuzzy finding
+
+---
+
+**"Leave it to the Sarge!"** 🎖️

data/bin/sgt

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Sergeant (sgt) - Interactive TUI directory navigator
+# Version: 1.0.0
+
+# Add lib directory to load path for development
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'sergeant'
+
+# Run the navigator
+SergeantApp.new.run

data/lib/sergeant/config.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# Configuration and bookmark management
+
+module Sergeant
+  module Config
+    COLOR_MAP = {
+      'black' => Curses::COLOR_BLACK,
+      'red' => Curses::COLOR_RED,
+      'green' => Curses::COLOR_GREEN,
+      'yellow' => Curses::COLOR_YELLOW,
+      'blue' => Curses::COLOR_BLUE,
+      'magenta' => Curses::COLOR_MAGENTA,
+      'cyan' => Curses::COLOR_CYAN,
+      'white' => Curses::COLOR_WHITE
+    }.freeze
+
+    DEFAULT_CONFIG = {
+      'directories' => 'cyan',
+      'files' => 'white',
+      'selected_bg' => 'cyan',
+      'selected_fg' => 'black',
+      'header' => 'yellow',
+      'path' => 'green',
+      'git_branch' => 'magenta'
+    }.freeze
+
+    MINIMAL_CONFIG_TEMPLATE = <<~CONFIG.freeze
+      # Sergeant Configuration File
+      # Color theme (available: black, red, green, yellow, blue, magenta, cyan, white)
+      directories=cyan
+      files=white
+      selected_bg=cyan
+      selected_fg=black
+      header=yellow
+      path=green
+      git_branch=magenta
+
+      # Bookmarks
+      [bookmarks]
+      # Add your bookmarks here
+      # Example:
+      # home=#{Dir.home}
+      # projects=~/projects
+    CONFIG
+
+    def self.load_config
+      config_file = File.join(Dir.home, '.sgtrc')
+      ensure_config_exists(config_file)
+
+      config = DEFAULT_CONFIG.dup
+
+      return config unless File.exist?(config_file)
+
+      File.readlines(config_file).each do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?('#')
+        next if line.include?('=') && line.split('=')[0].strip.start_with?('[bookmark')
+
+        key, value = line.split('=', 2)
+        next unless key && value
+
+        config[key.strip] = value.strip
+      end
+
+      config
+    rescue StandardError
+      DEFAULT_CONFIG.dup
+    end
+
+    def self.load_bookmarks
+      config_file = File.join(Dir.home, '.sgtrc')
+      bookmarks = {}
+
+      return bookmarks unless File.exist?(config_file)
+
+      in_bookmark_section = false
+
+      File.readlines(config_file).each do |line|
+        line = line.strip
+
+        if line.downcase.include?('[bookmarks]')
+          in_bookmark_section = true
+          next
+        end
+
+        if line.start_with?('[') && line.end_with?(']')
+          in_bookmark_section = false
+          next
+        end
+
+        next if line.empty? || line.start_with?('#')
+
+        next unless in_bookmark_section && line.include?('=')
+
+        key, value = line.split('=', 2)
+        next unless key && value
+
+        key = key.strip
+        value = value.strip.gsub('~', Dir.home)
+
+        bookmarks[key] = File.expand_path(value) if value.start_with?('/') || value.start_with?('~') || value.include?('/')
+      end
+
+      bookmarks
+    rescue StandardError
+      {}
+    end
+
+    def self.ensure_config_exists(config_file)
+      return if File.exist?(config_file)
+
+      File.write(config_file, MINIMAL_CONFIG_TEMPLATE)
+    end
+
+    def self.get_color(name)
+      COLOR_MAP[name.downcase] || Curses::COLOR_WHITE
+    end
+  end
+end