gims 0.5.3 → 0.6.1

package/README.md

@@ -1,4 +1,4 @@
-# 🚀 GIMS - Git Made Simple
+# 🚀 GIMS - Git Made Simple (Enhanced)
 
 <div align="center">
   
@@ -9,7 +9,7 @@
 
   **The AI-powered Git CLI that writes your commit messages for you**
   
-  *Because life's too short for "fix stuff" commits* 🎯
+  *Now with enhanced UX, smart insights, and interactive workflows* ✨
 
 </div>
 
@@ -17,7 +17,7 @@
 
 ## ✨ What is GIMS?
 
-GIMS is a revolutionary Git CLI tool that uses AI to automatically generate meaningful commit messages from your code changes. Say goodbye to generic "update code" commits and hello to descriptive, professional commit messages that actually tell a story.
+GIMS is a revolutionary Git CLI tool that uses AI to automatically generate meaningful commit messages from your code changes. The enhanced version adds intelligent insights, interactive workflows, and a modular architecture for better performance and user experience.
 
 ### 🎬 See It In Action
 
@@ -31,91 +31,152 @@ git push
 g o  # AI analyzes changes, commits with perfect message, and pushes!
 ```
 
-## 🌟 Features
+## 🌟 Enhanced Features
 
 ### 🤖 **AI-Powered Commit Messages**
 - OpenAI, Google Gemini, and Groq support with automatic provider selection
-- Smart diff analysis that understands your code changes
+- Smart diff analysis with caching for improved performance
+- Multiple suggestion generation for better options
 - Handles large codebases with intelligent summarization and safe truncation
-- Optional Conventional Commits formatting and optional commit body generation (`--conventional`, `--body`)
+- Optional Conventional Commits formatting and optional commit body generation
 
 ### ⚡ **Lightning Fast Workflow**
+- **Interactive Mode**: `g int` - guided commit wizard with multiple suggestions
+- **Smart Status**: `g status` - enhanced git status with AI insights
+- **Preview Mode**: `g preview` - see what would be committed with AI message
 - One command commits: `g o` - analyze, commit, and push
-- Smart suggestions: `g s` - get AI-generated messages copied to clipboard
-- Local commits: `g l` - commit locally with AI messages
-- Staged-only by default for suggestions for precise control (use `--all` to stage everything)
-
-### 🧠 **Intelligent Code Analysis**
-- Analyzes actual code changes, not just file names
-- Understands context from function changes, imports, and logic
-- Graceful fallbacks for extremely large changesets and offline use
-
-### 🛠️ **Developer-Friendly**
-- Numbered commit history with `g ls` / `g ll` and index-aware commands
-- Smart branching: `g b 5` creates branch from commit #5
-- Safe operations with confirmations and dry-run support
-- JSON output for editor integrations
-- Quality-of-life: `--amend`, `undo` command, and automatic upstream setup on push
-- Manual commit command for custom messages: `g m "your message"`
+- Smart suggestions: `g s` - get AI-generated messages (use `--multiple` for options)
+
+### 🧠 **Intelligent Analysis & Insights**
+- **Project Detection**: Automatically detects project type (React, Node, Python, etc.)
+- **Smart Insights**: AI analyzes changes and provides contextual tips
+- **Change Complexity**: Understands and reports on the scope of changes
+- **Commit History Analysis**: Tracks patterns and suggests improvements
+
+### 🛠️ **Enhanced Developer Experience**
+- **Setup Wizard**: `g setup` - interactive configuration for first-time users
+- **Progress Indicators**: Visual feedback for AI operations
+- **Better Error Messages**: Actionable guidance when things go wrong
+- **Smart Sync**: `g sync` - intelligent pull with rebase/merge options
+- **Enhanced Stash**: `g stash` - AI-generated stash descriptions
+
+### 🔧 **Advanced Configuration**
+- **Config Management**: `g config` - set preferences globally or per-project
+- **Caching System**: Speeds up repeated operations
+- **Modular Architecture**: Better performance and maintainability
 
 ## 🚀 Quick Start
 
+### Prerequisites
+
+- Node.js >= 18.18.0 (Node 20+ recommended)
+- npm >= 9
+
+Tip: Use nvm to manage Node versions per-user without sudo:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh"
+nvm install 20 && nvm alias default 20
+```
+
 ### Installation
 
 ```bash
 npm install -g gims
 ```
 
-### Setup AI (Choose One)
+If you get EACCES permission errors on Linux when installing globally, set a user prefix:
 
-**Option 1: OpenAI**
 ```bash
-export OPENAI_API_KEY="your-api-key-here"
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+npm install -g gims
 ```
 
-**Option 2: Google Gemini**
+### Setup AI (Choose One - Quick & Easy!)
+
+**🚀 Quick Setup (Recommended)**
 ```bash
-export GEMINI_API_KEY="your-api-key-here"
+# Gemini (Free, fast, recommended)
+g setup --api-key gemini
+
+# OpenAI (High quality)  
+g setup --api-key openai
+
+# Groq (Ultra fast)
+g setup --api-key groq
 ```
 
-**Option 3: Groq**
+**🔧 Manual Setup (Advanced)**
 ```bash
-export GROQ_API_KEY="your-api-key-here"
-# Optional, if self-hosting/proxying
-export GROQ_BASE_URL="https://api.groq.com/openai/v1"
+# Set environment variables
+export GEMINI_API_KEY="your-api-key-here"     # Uses gemini-2.0-flash-exp
+export OPENAI_API_KEY="your-api-key-here"     # Uses gpt-4o-mini  
+export GROQ_API_KEY="your-api-key-here"       # Uses llama-3.1-8b-instant
 ```
 
-GIMS auto-detects configured providers. If none are configured, it uses a local heuristic to generate sensible messages.
+GIMS auto-detects configured providers and uses smart defaults. If no AI is configured, it uses local heuristics to generate sensible messages.
 
-### Your First AI Commit
+### Your First Enhanced Experience
 
 ```bash
+# Quick AI setup (choose one - Gemini recommended)
+g setup --api-key gemini    # Fast & free
+g setup --api-key openai    # High quality  
+g setup --api-key groq      # Ultra fast
+
 # Make some changes to your code
-echo "console.log('Hello GIMS!');" > hello.js
+echo "console.log('Hello Enhanced GIMS!');" > hello.js
+
+# Check enhanced status with AI insights
+g s
+# Shows: Git status + AI insights about your changes
+
+# Use interactive mode for guided commits
+g i
+# Walks you through: staging → AI suggestions → commit → push
 
-# Let AI commit it for you
+# Or use the classic one-command workflow
 g o
-# Output: Committed & pushed: "Add hello world console log"
+# Output: ✓ Committed & pushed: "Add hello world console log"
 ```
 
-## 📖 Commands Reference
+## 📖 Enhanced Commands Reference
 
+### 🚀 **Main Workflow (Single Letters)**
 | Command | Alias | Description | Example |
 |---------|-------|-------------|---------|
-| `gims init` | `g i` | Initialize new Git repo | `g i` |
-| `gims clone <repo>` | `g c` | Clone repository | `g c https://github.com/user/repo` |
-| `gims suggest` | `g s` | Generate & copy commit message from staged changes (use `--all` to stage) | `g s --all` |
+| `gims status` | `g s` | Enhanced git status with AI insights | `g s` |
+| `gims interactive` | `g i` | Interactive commit wizard | `g i` |
+| `gims preview` | `g p` | Preview commit with AI message | `g p` |
 | `gims local` | `g l` | AI commit locally | `g l` |
-| `gims online` | `g o` | AI commit + push (use `--set-upstream` on first push) | `g o --set-upstream` |
-| `gims commit <message...>` | `g m` | Commit with a custom message (no AI) | `g m "fix: handle empty input"` |
-| `gims pull` | `g p` | Pull latest changes | `g p` |
-| `gims amend` | `g a` | Stage all changes and amend the last commit (reuse message) | `g a` |
-| `gims list` | `g ls` | Show numbered commit history | `g ls` |
-| `gims largelist` | `g ll` | Detailed commit history | `g ll` |
+| `gims online` | `g o` | AI commit + push | `g o` |
+| `gims list` | `g h` | Numbered commit history | `g h` |
+| `gims amend` | `g a` | Smart amend with AI | `g a` |
+| `gims undo` | `g u` | Undo last commit | `g u --yes` |
+
+### � **Se tup & Config**
+| Command | Alias | Description | Example |
+|---------|-------|-------------|---------|
+| `gims setup` | - | Setup wizard or quick API key setup | `g setup --api-key gemini` |
+| `gims config` | - | Manage configuration | `g config --set provider=gemini` |
+
+### 📝 **Additional Commands**
+| Command | Alias | Description | Example |
+|---------|-------|-------------|---------|
+| `gims suggest` | `g sg` | AI suggestions with clipboard | `g sg --multiple` |
+| `gims commit <msg>` | `g m` | Custom message commit | `g m "fix: handle edge case"` |
+| `gims sync` | - | Smart sync: pull + rebase/merge | `g sync --rebase` |
+| `gims stash` | - | Enhanced stash with AI descriptions | `g stash` |
+| `gims init` | - | Initialize repo | `g init` |
+| `gims clone <repo>` | `g c` | Clone repository | `g c https://github.com/user/repo` |
+| `gims pull` | - | Pull changes | `g pull` |
 | `gims branch <n>` | `g b` | Branch from commit #n | `g b 3 feature-x` |
-| `gims reset <n>` | `g r` | Reset to commit #n (`--hard` needs `--yes`) | `g r 5 --hard --yes` |
-| `gims revert <n>` | `g rv` | Safely revert commit #n (requires `--yes`) | `g rv 2 --yes` |
-| `gims undo` | `g u` | Undo last commit (soft reset by default) | `g u` or `g u --hard --yes` |
+| `gims reset <n>` | `g r` | Reset to commit | `g r 5 --hard --yes` |
+| `gims revert <n>` | `g rv` | Revert commit | `g rv 2 --yes` |
 
 ### Global Options
 
@@ -127,97 +188,190 @@ g o
 - `--body`: Generate a commit body in addition to subject
 - `--conventional`: Format subject using Conventional Commits
 - `--dry-run`: Print what would happen without committing/pushing
-- `--verbose`: Verbose logging
+- `--verbose`: Verbose logging with AI provider details
 - `--json`: Machine-readable output for `g s`
-- `--yes`: Confirm destructive actions without prompting (e.g., reset/revert/undo)
+- `--yes`: Confirm destructive actions without prompting
 - `--amend`: Amend the last commit instead of creating a new one
 - `--set-upstream`: On push, set upstream if the current branch has none
 
-## 💡 Real-World Examples
+### Command-Specific Options
+
+- `g s --multiple`: Generate multiple commit message suggestions
+- `g ls --detailed`: Show detailed commit information with dates and authors
+- `g ls --limit <n>`: Limit number of commits shown (default: 20)
+- `g sync --rebase`: Use rebase instead of merge for sync
+- `g stash --list`: List all stashes
+- `g stash --pop`: Pop the latest stash
+- `g stash --apply <n>`: Apply stash by index
+- `g a --no-edit`: Amend without changing the commit message
+- `g config --global`: Use global configuration instead of project-local
+
+## 💡 Enhanced Real-World Examples
 
-### 🔧 Bug Fix
+### 🎯 **Interactive Workflow**
 ```bash
-# You fix a null pointer exception
-g o
-# AI generates: "Fix null pointer exception in user authentication"
+# Complex feature development
+g status                    # See AI insights about your changes
+# Output: "📦 Dependencies changed - consider updating package-lock.json"
+
+g int                       # Interactive commit wizard
+# Guides you through: staging → multiple AI suggestions → commit
+
+g sync --rebase            # Smart sync with rebase
+# Output: "✓ Rebased successfully"
 ```
 
-### ✨ New Feature
+### 🔧 **Bug Fix with Preview**
 ```bash
-# You add a search function
-g o  
-# AI generates: "Add search functionality with pagination support"
+# You fix a critical bug
+g preview                   # Preview what would be committed
+# Shows: complexity analysis + AI suggestion + diff summary
+
+g o                        # Commit with confidence
+# AI generates: "Fix null pointer exception in user authentication"
 ```
 
-### 📚 Documentation
+### ✨ **Feature Development**
 ```bash
-# You update README and add comments
-g o
-# AI generates: "Update documentation and add inline code comments"
+# Multiple related changes
+g s --multiple             # Get several commit message options
+# Shows: 3 different AI-generated suggestions
+
+g stash                    # Stash with AI description
+# Output: "✓ Stashed changes: 'Add search functionality components'"
+
+g l                        # Commit locally first
+g sync                     # Smart sync before pushing
+g o                        # Push with upstream setup
 ```
 
-### 🎨 Refactoring
+### 📊 **Project Analysis**
 ```bash
-# You clean up code structure
-g o
-# AI generates: "Refactor authentication module for better maintainability"
+g status                   # Enhanced status with insights
+# Shows: file changes + AI insights + recent activity summary
+
+g config --set conventional=true  # Enable conventional commits
+g ls --detailed --limit 5         # Analyze recent commit patterns
 ```
 
-## 🔥 Pro Tips
+## 🔥 Enhanced Pro Tips
+
+### 🎯 **Perfect Enhanced Workflow**
+```bash
+g setup --api-key gemini  # One-time AI setup (fast & free)
+g s                       # Check status with AI insights  
+g i                       # Interactive commit for complex changes
+g sync                    # Smart sync instead of manual pull
+g o --set-upstream        # Push with automatic upstream setup
+```
 
-### 🎯 Perfect Workflow
+### 🧠 **Smart Development Patterns**
 ```bash
-g p                 # Pull latest changes
-# ... code your features ...
-g s                 # Preview AI suggestion from staged changes
-g s --all           # Or stage everything and suggest
-g l                 # Commit locally first
-# ... test your changes ...
-g o --set-upstream  # Push with automatic upstream setup on first push
+# Feature development
+g stash             # Stash with AI description
+g b 5 feature-x     # Branch from specific commit
+g preview           # Preview changes before committing
+g s --multiple      # Get multiple commit options
+g l && g sync       # Commit locally, then smart sync
+
+# Code review preparation
+g ls --detailed     # Review commit history
+g config --set conventional=true  # Enable conventional commits
+g amend             # Update last commit with AI message
 ```
 
-### 🧠 Smart Branching
+### 🛡️ **Safe & Smart Operations**
 ```bash
-g ls                # See numbered history
-g b 5 hotfix        # Branch from commit #5
-g l                 # Make changes and commit
-g checkout main && g pull  # Back to main
+# Experimentation
+g stash             # AI-described stash
+g l                 # Commit experiment
+g preview           # Check what you're about to commit
+g u --yes           # Quick undo if needed
+
+# Team collaboration
+g sync --rebase     # Clean history with rebase
+g status            # Check insights before committing
+g config --global   # Set team-wide preferences
 ```
 
-### 🛡️ Safe Experimentation
+### ⚡ **Power User Shortcuts**
 ```bash
-g l                 # Commit your experiment
-# ... code breaks something ...
-g r 1 --soft --yes  # Soft reset to previous commit (confirmed)
-# ... or ...
-g u --yes           # Undo last commit (soft)
+# Single-letter workflow
+g s                 # Enhanced status
+g p                 # Quick preview  
+g i                 # Interactive mode
+g sg --multiple     # Multiple suggestions
+g h --detailed      # Detailed history
+g l && g o          # Local commit then push
+
+# Configuration
+g config --set autoStage=true     # Auto-stage by default
+g config --set progressIndicators=false  # Disable progress bars
+g config --list                   # Review all settings
 ```
 
-## ⚙️ Configuration
+## ⚙️ Enhanced Configuration
+
+### Setup Wizard (Recommended)
+```bash
+g setup  # Interactive configuration wizard
+# Detects project type, configures AI providers, sets preferences
+```
 
 ### Environment Variables
 
-| Variable | Purpose |
-|----------|---------|
-| `OPENAI_API_KEY` | OpenAI API access |
-| `GEMINI_API_KEY` | Google Gemini API access |
-| `GROQ_API_KEY` | Groq API access (OpenAI-compatible) |
-| `GROQ_BASE_URL` | Groq API base URL (optional) |
-| `GIMS_PROVIDER` | Default provider: `auto` | `openai` | `gemini` | `groq` | `none` |
-| `GIMS_MODEL` | Default model identifier for provider |
-| `GIMS_CONVENTIONAL` | `1` to enable Conventional Commits by default |
-| `GIMS_COPY` | `0` to disable clipboard copying in `g s` by default |
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `OPENAI_API_KEY` | OpenAI API access | - |
+| `GEMINI_API_KEY` | Google Gemini API access | - |
+| `GROQ_API_KEY` | Groq API access | - |
+| `GROQ_BASE_URL` | Groq API base URL | `https://api.groq.com/openai/v1` |
+| `GIMS_PROVIDER` | Default provider | `auto` |
+| `GIMS_MODEL` | Default model identifier | (provider-specific) |
+| `GIMS_CONVENTIONAL` | Enable Conventional Commits | `0` |
+| `GIMS_COPY` | Enable clipboard copying | `1` |
+| `GIMS_AUTO_STAGE` | Auto-stage changes | `0` |
+| `GIMS_CACHE` | Enable AI response caching | `1` |
+| `GIMS_PROGRESS` | Show progress indicators | `1` |
+
+### Configuration Management
+```bash
+# Set configuration values
+g config --set provider=gemini
+g config --set conventional=true --global
+g config --set autoStage=true
+
+# View configuration
+g config --list
+g config --get provider
+
+# Project vs Global config
+g config --set conventional=true          # Project-specific
+g config --set conventional=true --global # Global (all projects)
+```
 
-### .gimsrc (optional)
+### .gimsrc Configuration Files
 
-Place a `.gimsrc` JSON file in your repo root or home directory to set defaults:
+**Project-level** (`./.gimsrc`):
+```json
+{
+  "provider": "gemini",
+  "model": "gemini-2.0-flash",
+  "conventional": true,
+  "autoStage": false,
+  "projectType": "react"
+}
+```
 
+**Global** (`~/.gimsrc`):
 ```json
 {
   "provider": "auto",
-  "model": "gpt-4o-mini",
-  "conventional": true,
-  "copy": true
+  "conventional": false,
+  "copy": true,
+  "cacheEnabled": true,
+  "progressIndicators": true,
+  "maxDiffSize": 100000
 }
 ```
 
@@ -273,20 +427,49 @@ jkl3456 Update API documentation with new endpoint examples
 mno7890 Fix memory leak in image processing pipeline
 ```
 
-## 📈 Stats
+## 📈 Enhanced Stats & Benefits
+
+- ⚡ **50% faster** commits with interactive mode and smart defaults
+- 🎯 **Higher accuracy** with multiple AI suggestions and caching
+- 🧠 **Smart insights** help improve code quality and commit patterns
+- 📚 **Zero learning curve** - enhanced Git workflow, not replacement
+- 🌍 **Universal compatibility** - Mac, Windows, Linux, WSL
+- � **Modular architecture** - better performance and extensibility
 
-- ⚡ Faster commits than traditional Git workflow
-- 🎯 High accuracy in commit message relevance
-- 📚 Zero learning curve - if you know Git, you know GIMS
-- 🌍 Works everywhere - Mac, Windows, Linux, WSL
+## 🆕 What's New in Enhanced GIMS
+
+### ✨ **Major Enhancements**
+- **Interactive Commit Wizard** - guided workflow with multiple suggestions
+- **Smart Status & Insights** - AI analyzes your changes and provides tips
+- **Enhanced Configuration** - setup wizard and flexible config management
+- **Progress Indicators** - visual feedback for all AI operations
+- **Caching System** - faster repeated operations
+- **Better Error Handling** - actionable guidance when things go wrong
+
+### 🔧 **Developer Experience**
+- **Project Type Detection** - automatically adapts to React, Node, Python, etc.
+- **Smart Sync** - intelligent pull with rebase/merge options
+- **Enhanced Stash** - AI-generated stash descriptions
+- **Preview Mode** - see exactly what will be committed
+- **Modular Architecture** - cleaner code and better maintainability
 
 ## 🗺️ Roadmap
 
+### 🎯 **Completed (v0.6.0)**
+- [x] Interactive commit wizard
+- [x] Enhanced status with AI insights
+- [x] Smart configuration management
+- [x] Progress indicators and better UX
+- [x] Caching and performance improvements
+- [x] Modular architecture
+
+### 🚀 **Coming Next**
 - [ ] 🔌 Plugin system for custom AI providers
-- [ ] 📊 Commit message templates and customization
+- [ ] 📊 Commit message templates and team standards
 - [ ] 🌐 Multi-language commit message support
-- [ ] 🔄 Integration with popular Git GUIs
-- [ ] 📱 Mobile companion app
+- [ ] 🔄 Integration with popular Git GUIs (VS Code, etc.)
+- [ ] 📱 Web dashboard for team commit analytics
+- [ ] 🤖 Advanced AI features (code review suggestions, etc.)
 
 ## 📄 License