@kyubiware/commit-mint 0.2.1 → 0.3.1

package/README.md

@@ -1,50 +1,55 @@
 # commit-mint
 
-> A commit tool that actually handles hook failures.
+> commit-mint groups changed files into individual commits, generates commit messages, and cleanly handles commit hook failures. It wraps the entire commit lifecycle — stage, generate, review, attempt, recover, retry — so you never lose a message or stare at raw hook output again.
 
-> **⚠️ WORK IN PROGRESS** — This is an early-stage project. The core commit flow, hook error parsing, and recovery menu work, but AI message generation is still a placeholder (`generateMessage` always returns `"chore: initial commit"`). Expect breaking changes.
+## Quick Start
 
-## The Problem
-
-When `git commit` fails due to pre-commit hooks (lint-staged, biome, eslint, tsc, vitest, jest), you get a wall of raw error output with no clear next step. Your commit message is lost. You fix the errors, try to remember or regenerate the message, and retry manually.
-
-Every existing AI commit tool has the same gap — they generate a message, call `git commit`, and if hooks fail, they just die.
-
-## What commit-mint does differently
-
-commit-mint wraps the entire commit lifecycle — stage, generate, attempt, recover, retry — in one CLI tool:
-
-```
-stage files → generate message → attempt commit → hooks fail?
-                                                          ├─ copy errors to clipboard
-                                                          ├─ skip hooks & commit
-                                                          └─ re-stage & retry
+```bash
+npm install -g @kyubiware/commit-mint
 ```
 
-## Installation
-
 ```bash
-npm install -g @kyubiware/commit-mint
+cmint
 ```
 
 Requires **Node.js 18+**.
 
+```
+stage files → generate message → review message → attempt commit → hooks fail?
+                                                                    ├─ copy errors to clipboard
+                                                                    ├─ skip hooks & commit
+                                                                    ├─ re-stage & retry
+                                                                    ├─ edit message
+                                                                    └─ cancel (cached for --retry)
+```
+
 ## Usage
 
 ```bash
-# Normal commit flow
+# Normal commit flow (interactive staging if multiple files)
 cmint
 
-# Auto-stage all tracked files
+# Auto-stage all tracked files (skip staging menu)
 cmint -a
 
 # Skip AI, provide your own message
 cmint -m "feat: add dark mode"
 
+# Pass context hint to AI for better messages
+cmint -H "refactoring auth module"
+cmint --hint "splitting monolith into services"
+
 # Retry last failed commit (uses cached message)
 cmint --retry
 cmint -r
 
+# Review staged changes with AI
+cmint --review
+cmint -R
+
+# Debug mode — timestamped stderr output
+cmint --debug
+
 # Configuration
 cmint config get GROQ_API_KEY
 cmint config set GROQ_API_KEY=gsk_...
@@ -55,6 +60,45 @@ cmint config set model openai/gpt-oss-20b
 
 If no `GROQ_API_KEY` is set in `~/.commit-mint` or `$GROQ_API_KEY`, you'll be prompted to enter one. It's saved to `~/.commit-mint` for future runs.
 
+### Interactive staging
+
+When you have multiple changed files, commit-mint shows an interactive staging menu:
+
+- **Stage all files** — auto-stage everything (same as `cmint -a`)
+- **Select files** — multi-select specific files to stage
+- **Auto-group into commits** — AI groups files into logical commits (see below)
+- **Cancel**
+
+If only one file has changed, it's staged automatically.
+
+### Auto-group
+
+The auto-group feature uses AI to analyze your changed files and group them into logical, cohesive commits. Each group is committed separately with its own AI-generated message.
+
+```
+1. AI analyzes changed files → proposes groups (name, description, files)
+2. You confirm or cancel the groupings
+3. For each group: stage → generate message → review → commit
+4. Hook failures show the recovery menu per-group
+```
+
+Select "Auto-group into commits" from the staging menu, or it's automatically available when you have multiple changed files.
+
+### Message review
+
+Before every commit, you can review the generated message:
+
+- **Use as-is** — accept the AI-generated message
+- **Edit** — modify the message in a prompt
+- **Review with OpenCode** — run a code review on your staged changes before committing
+- **Cancel** — exit (message is cached for `--retry`)
+
+### Code review
+
+Use `cmint --review` or `cmint -R` to review staged changes without committing. commit-mint checks for [OpenCode](https://github.com/opencode-ai/opencode) first — if available, it uses OpenCode for the review. Otherwise, it falls back to the Groq API.
+
+The review looks for bugs, security issues, performance problems, code quality, and edge cases. Results are shown in a structured report, with an option to copy findings to clipboard.
+
 ## Recovery menu
 
 When a pre-commit hook blocks your commit, commit-mint parses the error output and presents an interactive menu:
@@ -104,9 +148,9 @@ Stored in `~/.commit-mint` (INI format):
 GROQ_API_KEY=gsk_...
 model=openai/gpt-oss-20b
 locale=en
-max-length=100
 type=conventional
 timeout=10000
+proxy=
 ```
 
 | Key | Default | Description |
@@ -114,9 +158,9 @@ timeout=10000
 | `GROQ_API_KEY` | — | Groq API key for AI message generation |
 | `model` | `openai/gpt-oss-20b` | AI model for commit message generation |
 | `locale` | `en` | Locale for generated messages |
-| `max-length` | `100` | Max commit message length |
 | `type` | — | Commit type prefix (e.g. `conventional`) |
 | `timeout` | `10000` | AI request timeout (ms) |
+| `proxy` | — | Proxy URL for API requests |
 
 You can also set `GROQ_API_KEY` via environment variable.
 
@@ -133,6 +177,9 @@ cmint --help
     --retry, -r      Retry the last failed commit (default: false)
     --all, -a        Auto-stage all tracked files (default: false)
     --message, -m    Provide a commit message directly (skip AI generation)
+    --hint, -H       Add context hint for AI commit message generation
+    --review, -R     Review staged changes with a coding model (default: false)
+    --debug, -d      Enable debug output (default: false)
     --help, -h       Show help
     --version, -v    Show version
 
@@ -152,25 +199,37 @@ commit-mint/
 │   ├── cli.ts              # Entry point, argument parsing (cleye)
 │   ├── commands/
 │   │   ├── commit.ts       # Main commit flow orchestrator
+│   │   ├── auto-group.ts   # Auto-group multi-commit flow
+│   │   ├── review.ts       # Code review command
 │   │   └── config.ts       # Config get/set subcommand
 │   ├── services/
 │   │   ├── git.ts          # Git operations (stage, commit, diff, HEAD)
+│   │   ├── ai.ts           # Groq AI commit message generation (3-tier diff compression)
+│   │   ├── grouping.ts     # AI-powered file grouping into logical commits
+│   │   ├── review-ai.ts    # AI code review via Groq
 │   │   ├── hooks.ts        # Hook error parser (lint-staged, biome, tsc, etc.)
 │   │   ├── config.ts       # INI config read/write at ~/.commit-mint
 │   │   └── clipboard.ts    # Cross-platform clipboard (xclip/wl-copy/pbcopy)
 │   ├── ui/
-│   │   └── menu.ts         # Interactive recovery TUI (@clack/prompts)
+│   │   ├── menu.ts         # Interactive recovery TUI + staging menu
+│   │   ├── grouping.ts     # Grouping confirmation UI
+│   │   └── review-message.ts # Message review step (use/edit/review/cancel)
 │   └── utils/
-│       └── cache.ts        # Commit message persistence at ~/.cache/commit-mint/
+│       ├── cache.ts        # Commit message persistence at ~/.cache/commit-mint/
+│       └── debug.ts        # Timestamped debug logging to stderr
 ```
 
 ## Key differentiators
 
 1. **Hook error parsing** — No other commit tool parses lint-staged/biome/eslint output into a clean summary
-2. **Interactive recovery menu** — Copy/skip/retry as an in-flow choice, not a manual post-mortem
+2. **Interactive recovery menu** — Copy/skip/retry/edit as an in-flow choice, not a manual post-mortem
 3. **Message caching on failure** — `--retry` restores the last message without regenerating
 4. **Re-stage & retry loop** — Fix errors in another terminal, come back, hit "re-stage & retry"
-5. **Clipboard integration** — Copy error report and hand it to an AI coding agent for fixes
+5. **Auto-group** — AI groups changed files into logical commits, each committed separately
+6. **In-flow code review** — Review staged changes with OpenCode or Groq before committing
+7. **Message review step** — Accept, edit, or review the AI-generated message before committing
+8. **Post-commit summary** — Shows which hook tools passed/failed after every successful commit
+9. **Clipboard integration** — Copy error report and hand it to an AI coding agent for fixes
 
 ## Requirements