feat(ui): Enhanced flag display with color coordination and clean separation

Display Enhancements: • Added color-coordinated flag lines (bold yellow flags, dim separator) • Enhanced bottom preview panel (3 lines → 8 lines) • Implemented bordered box design with flag 🏴 and description 📝 emojis • Added clean flag/description separation using AWK-based parsing • Flag section shows ONLY bash input (e.g., -s sig) • Description section shows ONLY explanation text • Cyan bold for flags, green for descriptions in preview • Handles missing descriptions with dimmed "(No description available)" Technical Improvements: • Modified extract_all_flags() to add ANSI color codes to output • Enhanced browse_flags_fuzzy() preview with intelligent parsing • Uses AWK field separator on em dash (—) for robust splitting • Replaced xargs with sed for trimming to avoid flag interpretation • Added fallback handling for flags without descriptions Project Organization: • Moved documentation files to docs/ directory for better structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-01 13:22:46 -07:00
parent f8e31d49e0
commit 3ce1d2ec1f
16 changed files with 2242 additions and 9 deletions
@@ -0,0 +1,452 @@
+# Bash Buddy Enhancement Proposal
+
+## 🎯 Goal
+Transform bash-helper into an intelligent CLI assistant that can:
+- Accept natural language questions
+- Return relevant bash commands with examples
+- Explain flags in context
+- Remain fast and local
+- Work offline
+
+## 🏗️ Multi-Tiered Architecture
+
+### Tier 1: Fast Keyword Matching (Instant - <10ms)
+**Use Case:** Simple, common tasks
+
+```bash
+bash-helper "list files by size"
+# Returns: ls -lhS
+
+bash-helper "find large files"
+# Returns: find . -type f -size +100M -exec ls -lh {} \;
+
+bash-helper "search in files"
+# Returns: grep -r "pattern" .
+```
+
+**Implementation:**
+- JSON database of common tasks → commands
+- Simple keyword matching
+- Pre-indexed for speed
+
+### Tier 2: Pattern Database (Fast - <100ms)
+**Use Case:** More complex tasks with variations
+
+```bash
+bash-helper "compress all logs older than 30 days"
+# Returns: find /var/log -name "*.log" -mtime +30 -exec gzip {} \;
+# Explanation: Finds logs older than 30 days and compresses them
+
+bash-helper "monitor cpu usage every 2 seconds"
+# Returns: watch -n 2 'top -b -n 1 | head -20'
+```
+
+**Implementation:**
+- Template-based matching
+- Parameter extraction
+- Context-aware suggestions
+
+### Tier 3: Local LLM (Optional - ~1-5s)
+**Use Case:** Complex, unique queries
+
+```bash
+bash-helper --ai "extract all email addresses from files and save to csv"
+# Uses local Ollama/llama.cpp for understanding
+# Generates: grep -roh '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' . | sort -u > emails.csv
+```
+
+**Implementation:**
+- Optional Ollama integration
+- Cached responses
+- Fallback to pattern matching
+
+## 📊 Proposed Features
+
+### 1. Natural Language Query Mode
+
+```bash
+# Ask a question
+bash-helper ask "how do I find files modified today"
+
+# Get command + explanation
+bash-helper explain "what does find . -name '*.log' do"
+
+# Get examples for a task
+bash-helper examples "working with archives"
+```
+
+### 2. Task-Based Categories
+
+```bash
+# Browse by category
+bash-helper category files      # File operations
+bash-helper category network    # Network commands
+bash-helper category system     # System monitoring
+bash-helper category text       # Text processing
+```
+
+### 3. Interactive Examples
+
+```bash
+bash-helper demo "find and replace in files"
+# Shows:
+# 1. Basic: sed -i 's/old/new/g' file.txt
+# 2. Recursive: find . -type f -exec sed -i 's/old/new/g' {} +
+# 3. With backup: find . -type f -exec sed -i.bak 's/old/new/g' {} +
+```
+
+### 4. Command Builder
+
+```bash
+bash-helper build
+# Interactive wizard:
+# What do you want to do?
+# > Find files
+# What type of files?
+# > Text files (*.txt)
+# Any conditions?
+# > Larger than 1MB
+#
+# Generated: find . -name "*.txt" -size +1M
+```
+
+## 🗄️ Data Structure
+
+### commands.json
+```json
+{
+  "tasks": [
+    {
+      "id": "list-files-by-size",
+      "keywords": ["list", "files", "size", "largest", "biggest"],
+      "category": "files",
+      "command": "ls -lhS",
+      "description": "List files sorted by size (largest first)",
+      "examples": [
+        {
+          "desc": "List all files by size",
+          "cmd": "ls -lhS"
+        },
+        {
+          "desc": "List only in current dir (no subdirs)",
+          "cmd": "ls -lhS | grep -v '^d'"
+        },
+        {
+          "desc": "Show top 10 largest",
+          "cmd": "ls -lhS | head -11"
+        }
+      ],
+      "related": ["find-large-files", "disk-usage"],
+      "flags_explained": {
+        "-l": "Long format (detailed info)",
+        "-h": "Human readable sizes (KB, MB, GB)",
+        "-S": "Sort by size (largest first)"
+      }
+    },
+    {
+      "id": "find-large-files",
+      "keywords": ["find", "large", "big", "files", "disk", "space"],
+      "category": "files",
+      "command": "find . -type f -size +100M -exec ls -lh {} \\;",
+      "description": "Find files larger than 100MB",
+      "templates": [
+        {
+          "pattern": "find {files} larger than {size}",
+          "cmd": "find . -type f -size +{size} -exec ls -lh {} \\;"
+        }
+      ],
+      "examples": [
+        {
+          "desc": "Find files larger than 100MB",
+          "cmd": "find . -type f -size +100M -exec ls -lh {} \\;"
+        },
+        {
+          "desc": "Find and sort by size",
+          "cmd": "find . -type f -size +100M -exec ls -lh {} \\; | sort -k5 -hr"
+        }
+      ]
+    }
+  ],
+  "categories": {
+    "files": ["File Operations", "list-files-by-size", "find-large-files"],
+    "text": ["Text Processing", "search-in-files", "find-and-replace"],
+    "network": ["Network Operations", "check-ports", "download-file"],
+    "system": ["System Monitoring", "cpu-usage", "memory-usage"]
+  }
+}
+```
+
+## 🚀 Implementation Phases
+
+### Phase 1: Enhanced Command Database (Week 1)
+- Create comprehensive JSON database
+- 100+ common tasks with examples
+- Keyword-based search
+- Category browsing
+
+**Files to create:**
+- `commands-db.json` - Task database
+- `bash-helper-search.sh` - Search functionality
+- `bash-helper-ask.sh` - Natural language queries
+
+### Phase 2: Pattern Matching (Week 2)
+- Template-based command generation
+- Parameter extraction from queries
+- Context-aware suggestions
+
+**Features:**
+- "find files modified in last {N} days"
+- "compress all {extension} files"
+- "search for {pattern} in {location}"
+
+### Phase 3: LLM Integration (Optional)
+- Ollama integration for complex queries
+- Caching layer for speed
+- Graceful fallback
+
+**Integration points:**
+- `bash-helper --ai "complex query"`
+- Local llama3 or codellama
+- Response caching in ~/.cache/bash-helper/
+
+## 🎨 Enhanced CLI Interface
+
+```bash
+# Current
+bash-helper ls size              # Show ls flags with 'size'
+
+# Enhanced
+bash-helper ask "show largest files"
+bash-helper task "compress old logs"
+bash-helper explain "tar -czf archive.tar.gz folder/"
+bash-helper category files
+bash-helper search "find duplicate"
+bash-helper build                # Interactive builder
+bash-helper recent              # Recently used commands
+bash-helper bookmark "useful-find-command"
+bash-helper --ai "complex natural language query"
+```
+
+## 📦 Database Content Areas
+
+### File Operations (30+ tasks)
+- List, find, search, copy, move, delete
+- Permissions, ownership
+- Archives (tar, zip, gzip)
+- Disk usage, large files
+
+### Text Processing (25+ tasks)
+- grep, sed, awk patterns
+- Find and replace
+- Text manipulation
+- Format conversion
+
+### Network (20+ tasks)
+- Download files (wget, curl)
+- Check connections (ping, netstat)
+- Port scanning (nc, nmap)
+- SSH operations
+
+### System Monitoring (20+ tasks)
+- CPU, memory, disk usage
+- Process management
+- Logs analysis
+- System info
+
+### Git Operations (15+ tasks)
+- Common workflows
+- Branch management
+- Undoing changes
+- Collaboration
+
+## 🔧 Technical Architecture
+
+```
+bash-helper (main script)
+    │
+    ├─> Mode Detection
+    │   ├─> --help, --list (existing)
+    │   ├─> COMMAND [FILTER] (existing)
+    │   ├─> ask "query"
+    │   ├─> task "description"
+    │   ├─> explain "command"
+    │   └─> category NAME
+    │
+    ├─> Fast Keyword Search
+    │   └─> commands-db.json lookup
+    │       └─> Return top 3 matches
+    │
+    ├─> Pattern Matching
+    │   └─> Template expansion
+    │       └─> Parameter substitution
+    │
+    └─> Optional LLM (--ai flag)
+        └─> Ollama API call
+            └─> Cache response
+```
+
+## 💾 Storage & Performance
+
+### Fast Lookup Strategy
+```bash
+# Pre-indexed keyword→command mapping
+KEYWORD_INDEX=~/.local/share/bash-helper/keywords.idx
+
+# On first run: build index
+# Subsequent runs: instant lookup
+
+# Expected performance:
+# - Keyword search: <10ms
+# - Pattern match: <100ms
+# - LLM query: 1-5s (cached: <10ms)
+```
+
+### Caching
+```bash
+~/.cache/bash-helper/
+    ├── ai-responses/       # Cached LLM responses
+    ├── recent-commands     # History
+    └── bookmarks.json      # User bookmarks
+```
+
+## 🎯 Example Usage Scenarios
+
+### Scenario 1: New User Learning
+```bash
+$ bash-helper ask "how to find text in files"
+
+📖 Task: Search for text in files
+
+Command:
+  grep -r "pattern" directory/
+
+Explanation:
+  -r  : Recursive search
+  "pattern" : Text to find
+  directory/ : Where to search
+
+Examples:
+  1. Search in current directory:
+     grep -r "error" .
+
+  2. Case-insensitive search:
+     grep -ri "error" .
+
+  3. Show line numbers:
+     grep -rn "error" .
+
+Related tasks:
+  • find-and-replace
+  • search-specific-files
+  • count-occurrences
+```
+
+### Scenario 2: Quick Lookup
+```bash
+$ bash-helper task "compress folder"
+
+💡 Quick answer:
+
+  tar -czf archive.tar.gz folder/
+
+Flags explained:
+  -c : Create archive
+  -z : Compress with gzip
+  -f : File name follows
+
+Try also:
+  bash-helper explain "tar -czf archive.tar.gz folder/"
+  bash-helper category files
+```
+
+### Scenario 3: Complex Query (with AI)
+```bash
+$ bash-helper --ai "find all python files modified in last week, exclude virtual environments, and count lines of code"
+
+🤖 AI Assistant (using local LLM)
+
+Generated command:
+  find . -name "*.py" -not -path "*/venv/*" -not -path "*/.env/*" \
+    -mtime -7 -exec wc -l {} + | awk '{sum+=$1} END {print sum}'
+
+Breakdown:
+  1. find . -name "*.py"           # Find Python files
+  2. -not -path "*/venv/*"         # Exclude venv directories
+  3. -mtime -7                     # Modified in last 7 days
+  4. -exec wc -l {} +              # Count lines
+  5. awk '{sum+=$1} END {print sum}' # Sum total
+
+Cached for future use.
+```
+
+## 🔌 Ollama Integration (Optional)
+
+### Setup
+```bash
+# Install Ollama
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Pull a code-focused model
+ollama pull codellama:7b
+
+# Configure bash-helper
+bash-helper config set llm.enable true
+bash-helper config set llm.model codellama:7b
+```
+
+### Usage
+```bash
+# First time (generates command)
+bash-helper --ai "complex query"  # ~3s
+
+# Second time (cached)
+bash-helper --ai "complex query"  # <10ms
+
+# Clear cache
+bash-helper cache clear
+```
+
+## 📈 Success Metrics
+
+After implementation, users should be able to:
+- ✅ Ask questions in natural language
+- ✅ Get relevant commands instantly (<100ms)
+- ✅ See examples for any task
+- ✅ Understand what commands do
+- ✅ Build complex commands interactively
+- ✅ Work completely offline
+- ✅ Learn bash progressively
+
+## 🎓 Educational Value
+
+The enhanced tool becomes a learning platform:
+1. **Discovery**: Browse categories to learn what's possible
+2. **Examples**: See real-world usage patterns
+3. **Explanation**: Understand each flag's purpose
+4. **Practice**: Build commands interactively
+5. **History**: Review and reuse previous solutions
+
+## 🚀 Next Steps
+
+Ready to implement? Here's the order:
+
+1. **Create command database** (commands-db.json)
+   - Start with 20-30 common tasks
+   - Expand over time
+
+2. **Add search functionality**
+   - Keyword matching
+   - Category browsing
+
+3. **Implement query modes**
+   - ask, task, explain, category
+
+4. **Optional: Add LLM integration**
+   - Ollama setup
+   - Caching layer
+
+5. **Test and iterate**
+   - Real-world usage
+   - Expand database
+
+Would you like me to start implementing this? We can begin with Phase 1!