gims 0.6.7 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [0.8.1] - 2025-12-19
+
+### 🚀 Smart Sync Fix
+New `g fix` command to handle branch sync issues (diverged/ahead/behind):
+
+| Option | What it does |
+|--------|--------------|
+| `g fix` | Show status and available options |
+| `g fix --ai` | Get AI recommendation for best approach |
+| `g fix --merge` | Merge remote into local |
+| `g fix --rebase` | Rebase local onto remote |
+| `g fix --local --yes` | Force push local to remote |
+| `g fix --remote --yes` | Reset to remote, discard local |
+
+### 🔧 Conflict Helper
+New `g conflicts` command shows conflicted files and how to resolve them.
+
+---
+
+## [0.8.0] - 2025-12-19
+
+### 🚀 New Workflow Shorthand Commands
+Multi-step git workflows simplified to single commands:
+
+| Command | Alias | What it does |
+|---------|-------|--------------|
+| `safe-pull` | `sp` | Stash → Pull → Stash pop (safe pull with uncommitted changes) |
+| `main` | - | Switch to main/master and pull latest |
+| `unstage` | `us` | Unstage all staged files |
+| `discard` | `x` | Discard all changes (with --yes confirmation) |
+| `stash-save` | `ss` | Quick stash all changes with auto-generated name |
+| `stash-pop` | `pop` | Pop the latest stash |
+| `delete-branch` | `del` | Delete branch locally and remotely |
+| `cleanup` | `clean` | Remove local branches deleted from remote |
+| `last` | - | Show last commit details and diff |
+
+---
+
+## [0.7.2] - 2025-12-18
+
+### 🐛 Bug Fix
+- **Fixed progress spinner garbage output**: Spinner now properly clears the line when stopping, preventing partial text artifacts like ` (1ms)rating AI review ⠋`
+
+---
+
+## [0.7.1] - 2025-12-18
+
+### 🐛 Bug Fix
+- **Fixed AI suggestions in interactive mode**: Multiple suggestions now correctly display message strings instead of `[object Object]`
+
+---
+
+## [0.7.0] - 2025-12-18
+
+### 🚀 New Intelligent Commands
+- **`g wip`**: Quick work-in-progress commit - stage all and commit instantly
+- **`g today` / `g t`**: Show all commits made today with timestamps
+- **`g stats`**: Personal commit statistics with streak tracking, type breakdown, and style analysis
+- **`g review` / `g r`**: AI code review before committing - shows complexity, detected patterns, and suggested message
+- **`g split`**: Smart suggestions for splitting large changesets into atomic commits
+
+### ✨ Enhanced Status
+- **File type emojis**: 📄 JS, 🎨 CSS, 🧪 tests, ⚙️ config, 📦 package.json, etc.
+- **Session awareness**: Shows time since last commit and daily commit count
+- **Branch context**: Detects branch type from naming patterns (feat/, fix/, etc.)
+- **Smarter insights**: Suggests staging, split commits, and more
+
+### 🧠 Intelligence Module
+- **Commit pattern analysis**: Learns your style from git history
+- **Semantic change detection**: Identifies breaking changes, new features, bug fixes
+- **Complexity analysis**: Visual indicators for simple/moderate/complex changes
+
+### 📊 UX Improvements
+- **Time elapsed display**: Shows how long operations take
+- **Random tips**: Contextual tips to help learn GIMS features
+- **Cached response indicators**: Know when AI cache is used
+- **Better quick-help**: Reorganized command reference with new commands
+
+---
+
 ## [0.6.7] - 2025-10-26
 
 ### 🔧 Fixes

package/README.md

@@ -1,78 +1,318 @@
+<div align="center">
+
 # 🚀 GIMS - Git Made Simple
 
 [![npm version](https://img.shields.io/npm/v/gims.svg)](https://npmjs.org/package/gims)
+[![npm downloads](https://img.shields.io/npm/dm/gims.svg)](https://npmjs.org/package/gims)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![AI Powered](https://img.shields.io/badge/AI-Powered-blueviolet.svg)](https://github.com/s41r4j/gims)
+[![Node.js](https://img.shields.io/badge/Node.js->=18.18.0-green.svg)](https://nodejs.org)
 
 **AI-powered Git CLI that writes your commit messages for you**
 
 *Because life's too short for "fix stuff" commits* 🎯
 
-## ⚡ Quick Start
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Commands](#-commands) • [AI Setup](#-ai-providers) • [Configuration](#-configuration)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🤖 **AI-Generated Commits** — Let AI analyze your changes and write meaningful commit messages
+- 📊 **Smart Status** — Enhanced git status with file type detection and insights
+- 🔄 **Workflow Shortcuts** — Common multi-step operations condensed to single commands
+- 📈 **Commit Analytics** — Track your commit streak, patterns, and statistics
+- 🔍 **Code Review** — Get AI-powered code review before committing
+- 🛡️ **Safe Operations** — Built-in safeguards for destructive commands
+- ⚡ **Lightning Fast** — Optimized for speed with intelligent caching
+
+---
+
+## 📦 Installation
 
 ```bash
-# Install
 npm install -g gims
+```
+
+**Requirements:** Node.js >= 18.18.0
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# 1. Setup AI provider (choose one)
+g setup --api-key gemini    # 🆓 Free & fast (recommended)
+g setup --api-key openai    # 🎯 High quality
+g setup --api-key groq      # ⚡ Ultra fast
+
+# 2. Start using it!
+g s                         # Check status with AI insights
+g o                         # AI commit + push (one command!)
+```
+
+### Your New Workflow
 
-# Setup AI (choose one)
-g setup --api-key gemini    # Free & fast (recommended)
-g setup --api-key openai    # High quality
-g setup --api-key groq      # Ultra fast
+```bash
+# Before (traditional git)
+git add .
+git commit -m "trying to think of message..."
+git push
 
-# Use it
-g s    # Check status with AI insights
-g o    # AI commit + push
+# After (with GIMS)
+g o                         # That's it. AI handles the rest.
 ```
 
-## 🎯 Main Commands
+---
+
+## 📚 Commands
+
+### 🧠 Core Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `g status` | `g s` | Enhanced status with AI insights & file type emojis |
+| `g oneshot` | `g o` | Stage all → AI commit → Push (full workflow) |
+| `g local` | `g l` | Stage all → AI commit (no push) |
+| `g suggest` | `g sg` | Get AI commit message suggestions |
+| `g wip` | — | Quick work-in-progress commit |
+
+### 📊 Analytics & Review
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `g review` | `g r` | AI code review with complexity analysis |
+| `g today` | `g t` | Show all commits made today |
+| `g stats` | — | Personal statistics: streak, patterns, style |
+| `g split` | — | AI suggestions for splitting large changesets |
+
+### ⚡ Workflow Shortcuts
+
+| Command | Alias | What it does |
+|---------|-------|--------------|
+| `g safe-pull` | `g sp` | Stash → Pull → Pop (safe pull with uncommitted changes) |
+| `g fix` | — | Smart fix for diverged/ahead/behind branches |
+| `g main` | — | Switch to main/master + pull latest |
+| `g stash-save` | `g ss` | Quick stash with auto-generated name |
+| `g stash-pop` | `g pop` | Pop the latest stash |
+| `g unstage` | `g us` | Unstage all staged files |
+| `g discard` | `g x` | Discard all changes (requires `--yes`) |
+
+### 🛠️ Git Helpers
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `g last` | — | Show last commit details with diff |
+| `g conflicts` | — | Conflict resolution helper |
+| `g cleanup` | `g clean` | Remove local branches deleted from remote |
+| `g list` | `g ls` | Compact commit history |
+| `g amend` | `g a` | Amend the previous commit |
+| `g undo` | `g u` | Undo last commit (keep changes) |
+| `g delete-branch` | `g del` | Delete branch locally and remotely |
+
+### 🔧 Setup & Config
 
 | Command | Description |
 |---------|-------------|
-| `g s` | Enhanced status with AI insights |
-| `g i` | Initialize git repository |
-| `g int` | Interactive commit wizard |
-| `g o` | AI commit + push |
-| `g l` | AI commit locally |
-| `g ls` | Commit history (short) |
-| `g ll` | Commit history (detailed) |
-| `g h` | Commit history (alias for ls) |
-| `g a` | Amend previous commit (keeps message) |
+| `g setup` | Interactive setup wizard |
+| `g setup --api-key <provider>` | Quick API key setup |
+| `g config --list` | View all settings |
+| `g config --set key=value` | Update configuration |
+| `g quick-help` / `g q` | Quick command reference |
+
+---
 
-## 🤖 AI Models
+## 🤖 AI Providers
 
-- **Gemini**: `gemini-2.5-flash` (Free, fast, recommended)
-- **OpenAI**: `gpt-5` (High quality)
-- **Groq**: `groq/compound` (Ultra fast)
+GIMS supports multiple AI providers. Choose based on your needs:
 
-## 📖 Examples
+| Provider | Model | Speed | Quality | Cost |
+|----------|-------|-------|---------|------|
+| **Gemini** | `gemini-3-flash-preview` | ⚡⚡⚡ | ⭐⭐⭐ | 🆓 Free |
+| **Groq** | `groq/compound` | ⚡⚡⚡⚡ | ⭐⭐⭐ | 🆓 Free tier |
+| **OpenAI** | `gpt-5.2-2025-12-11` | ⚡⚡ | ⭐⭐⭐⭐ | 💰 Paid |
+
+### Setting Up API Keys
+
+#### Option 1: Interactive Setup (Recommended)
 
 ```bash
-# Daily workflow
-g s              # Check what changed
-g int            # Interactive commit
-g o              # Quick commit + push
-
-# Advanced
-g sg --multiple  # Get 3 AI suggestions
-g ll             # Detailed history
-g sync --rebase  # Smart sync
+g setup --api-key gemini    # Guided setup with instructions
+g setup --api-key openai
+g setup --api-key groq
 ```
 
+#### Option 2: Environment Variables (Auto-detected)
+
+GIMS automatically detects API keys from environment variables. Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
+
+```bash
+# Gemini (recommended - free)
+export GEMINI_API_KEY="your-api-key-here"
+
+# OpenAI
+export OPENAI_API_KEY="your-api-key-here"
+
+# Groq
+export GROQ_API_KEY="your-api-key-here"
+```
+
+Then reload your shell: `source ~/.zshrc`
+
+> **💡 Tip:** If multiple API keys are set, GIMS auto-selects in order: Gemini → OpenAI → Groq
+
+### Getting API Keys
+
+<details>
+<summary><b>🔷 Gemini (Recommended)</b></summary>
+
+1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. Create a new API key
+3. Set it: `export GEMINI_API_KEY="your-key"` or run `g setup --api-key gemini`
+
+</details>
+
+<details>
+<summary><b>🟢 Groq</b></summary>
+
+1. Visit [Groq Console](https://console.groq.com/keys)
+2. Create a new API key
+3. Set it: `export GROQ_API_KEY="your-key"` or run `g setup --api-key groq`
+
+</details>
+
+<details>
+<summary><b>🟡 OpenAI</b></summary>
+
+1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
+2. Create a new API key
+3. Set it: `export OPENAI_API_KEY="your-key"` or run `g setup --api-key openai`
+
+</details>
+
+---
+
 ## 🔧 Configuration
 
 ```bash
-g config --set conventional=true   # Enable conventional commits
-g config --set autoStage=true      # Auto-stage changes
-g config --list                    # View all settings
+# View current settings
+g config --list
+
+# Enable conventional commits (feat:, fix:, etc.)
+g config --set conventional=true
+
+# Auto-stage all changes before commit
+g config --set autoStage=true
+
+# Disable clipboard copy
+g config --set copy=false
+
+# Show/hide progress indicators
+g config --set progressIndicators=true
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | string | `auto` | AI provider: `gemini`, `openai`, `groq`, `auto`, `none` |
+| `model` | string | — | Override default model for provider |
+| `conventional` | boolean | `false` | Use Conventional Commits format |
+| `autoStage` | boolean | `false` | Auto-stage all changes |
+| `copy` | boolean | `true` | Copy suggestions to clipboard |
+| `progressIndicators` | boolean | `true` | Show progress spinners |
+
+---
+
+## 📖 Usage Examples
+
+### Daily Workflow
+
+```bash
+g s              # Check what's changed
+g sp             # Safe pull (won't lose uncommitted work)
+# ... do your work ...
+g o              # Commit everything with AI message + push
+```
+
+### Code Review Before Commit
+
+```bash
+g r              # Get AI review of your changes
+g o              # Commit if review looks good
 ```
 
-## 🆘 Help
+### Handling Branch Issues
 
 ```bash
-g --help    # All commands
-g q         # Quick reference
+g fix            # See sync status and options
+g fix --ai       # Get AI recommendation
+g fix --merge    # Merge remote changes
+g fix --rebase   # Rebase onto remote
 ```
 
+### Working with Stashes
+
+```bash
+g ss             # Quick stash
+g main           # Switch to main and pull
+# ... check something ...
+g pop            # Get your work back
+```
+
+### Large Changeset
+
+```bash
+g split          # Get suggestions for splitting changes
+g sg --multiple  # Get multiple commit message options
+```
+
+---
+
+## 🆚 GIMS vs Plain Git
+
+| Task | Git | GIMS |
+|------|-----|------|
+| Commit & push | `git add . && git commit -m "msg" && git push` | `g o` |
+| Pull with uncommitted changes | `git stash && git pull && git stash pop` | `g sp` |
+| Check status | `git status` | `g s` (+ AI insights) |
+| Fix diverged branch | Multiple commands + decisions | `g fix --ai` |
+| Code review | External tool | `g r` |
+
+---
+
+## 🆘 Getting Help
+
+```bash
+g --help         # Full command list with descriptions
+g q              # Quick reference card
+g <command> -h   # Help for specific command
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Feel free to:
+
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔧 Submit pull requests
+
+---
+
 ## 📄 License
 
-MIT © [S41R4J](https://github.com/s41r4j)
+MIT © [S41R4J](https://github.com/s41r4j)
+
+---
+
+<div align="center">
+
+**[⬆ Back to Top](#-gims---git-made-simple)**
+
+Made with ❤️ for developers who'd rather code than write commit messages
+
+</div>