@kyubiware/commit-mint 0.5.5 → 0.5.6

package/README.md

@@ -1,11 +1,13 @@
-# commit-mint
+# 🌿 commit-mint
 
 [![npm version](https://img.shields.io/npm/v/@kyubiware/commit-mint.svg)](https://www.npmjs.com/package/@kyubiware/commit-mint)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/kyubiware/commit-mint/ci.yml?style=flat-square)](https://github.com/kyubiware/commit-mint/actions)
 ![Node.js](https://img.shields.io/badge/Node.js->=18-3c873a?style=flat-square)
 [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 
-> Auto-group your changes into clean, conventional commits. AI handles the grouping, messages, and hook failures so you don't have to.
+**AI commit messages that actually handle what goes wrong.**
+
+commit-mint generates conventional commit messages from your diff — and when hooks fail, it parses the errors and gives you a recovery menu instead of dumping raw stderr. It auto-groups unrelated changes into separate commits, runs your checks before generating messages, and caches failed attempts for instant retries.
 
 ```
 ┌  commit-mint
@@ -20,7 +22,7 @@
 │
 ◇  Committed successfully.
 │
-●    ✓ prettier
+●    ✓ biome
 │    ✓ eslint
 │    ✓ tsc
 │    ✓ vitest
@@ -35,65 +37,63 @@
 └  All groups committed.
 ```
 
-## Quick start
+## Why commit-mint
 
-```bash
-npm install -g @kyubiware/commit-mint
-cmint -a
-```
-
-On first run, you'll be prompted for an API key if one isn't set. It's saved for future runs.
+Most AI commit tools generate a message and hope for the best. commit-mint handles the full loop:
 
-## Features
+- **Auto-groups files by intent** — 10 changed files across 3 concerns? Three separate commits, each with its own message. No competitor does this.
+- **Hook failures get a recovery menu** — Parsed errors from biome, tsc, vitest, eslint, and lint-staged. Copy, skip, restage, edit, or cancel. No raw stderr dumps.
+- **Pre-flight checks before AI generation** — `.cmintrc` runs your checks after staging but before the API call, so a failing check never wastes tokens.
+- **Works without OpenAI** — Groq, Cerebras, and Mistral out of the box. No OpenAI key required.
+- **Cached retries** — Failed commit? Fix the error and `cmint --retry` picks up the same message.
 
-- **Auto-group by intent** — AI reads your diff and groups files into logical commits. No more `feat: update stuff` that bundles unrelated changes.
-- **Zero-prompt auto mode** — `cmint -a` stages, groups, generates messages, and commits without a single prompt.
-- **Hook failures handled in-flow** — Parsed error summary with a recovery menu to copy, skip, retry, or edit. No raw stderr dumps.
-- **Multi-provider AI** — Works with Groq, Cerebras, and Mistral out of the box. Per-provider model configuration supported.
-- **Built-in pre-commit checks** — Define checks in a cmint config file and run them before AI generation. A failing check never wastes an API call.
-- **Message caching on failure** — A failed commit caches its message. Fix the error, run `cmint --retry`, and pick up where you left off.
-
-## Usage
+## Install
 
 ```bash
-# Auto-group and commit everything (no prompts)
-cmint -a
+npm install -g @kyubiware/commit-mint
+```
 
-# Normal interactive flow
-cmint
+Or try it without installing:
 
-# Skip AI, provide your own message
-cmint -m "feat: add dark mode"
+```bash
+npx @kyubiware/commit-mint
+```
 
-# Pass context hint for better messages
-cmint -H "refactoring auth module"
+## Quick start
 
-# Retry last failed commit (uses cached message)
-cmint -r
+```bash
+cmint config    # set provider + API key (interactive wizard)
+cmint -a        # auto-group, generate messages, commit everything
+```
 
-# Skip pre-commit checks
-cmint -N
+On first run you'll be prompted for an API key if one isn't configured. It's saved for future runs.
 
-# Debug mode
-cmint -d
+## Usage
 
-# Configuration
-cmint config get GROQ_API_KEY
-cmint config set GROQ_API_KEY=gsk_...
-cmint config set provider cerebras
-cmint config set model openai/gpt-oss-20b
+```bash
+cmint -a              # auto-group and commit everything
+cmint                 # interactive flow (staging → checks → review → commit)
+cmint -m "feat: ..."  # skip AI, use your own message
+cmint -H "context"    # pass a hint for better AI messages
+cmint -r              # retry last failed commit (cached message)
+cmint -N              # skip pre-flight checks
+cmint -d              # debug mode (timestamped stderr)
+cmint config          # interactive configuration wizard
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-a, --auto` | Auto-group files into commits, accept all messages |
-| `-m, --message` | Provide a commit message directly (skip AI) |
-| `-H, --hint` | Add context hint for AI message generation |
-| `-r, --retry` | Retry the last failed commit |
-| `-N, --noCheck` | Skip pre-commit checks |
-| `-d, --debug` | Enable debug output |
-| `-h, --help` | Show help |
-| `-v, --version` | Show version |
+## Comparison
+
+| | commit-mint | aicommits | opencommit | cz-git | commitizen |
+|---|:---:|:---:|:---:|:---:|:---:|
+| **Auto-group files into commits** | ✅ | — | — | — | — |
+| **Hook failure recovery menu** | ✅ | — | — | — | — |
+| **Pre-commit checks in-flow** | ✅ | — | — | — | — |
+| **AI message generation** | ✅ | ✅ | ✅ | ✅ | — |
+| **No OpenAI required** | ✅ Groq, Cerebras, Mistral | ✅ Together, Ollama | — default OpenAI | — OpenAI only | n/a |
+| **Message review before commit** | ✅ | ✅ | ✅ | ✅ interactive | ✅ interactive |
+| **Zero-prompt auto mode** | ✅ | ✅ | ✅ | — | — |
+| **Conventional commits** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Retry cached message** | ✅ | — | — | ✅ | — |
 
 ## Modes
 
@@ -101,41 +101,26 @@ cmint config set model openai/gpt-oss-20b
 
 `cmint -a` runs the full pipeline with no prompts:
 
-1. AI analyzes all changed files
-2. Files are grouped into logical commits by intent
-3. Each group gets its own AI-generated conventional commit message
-4. Groups are committed sequentially
-5. Hook failures per group trigger the recovery menu
+1. Excluded files (lockfiles, generated) are committed upfront.
+2. `.cmintrc` checks run before AI grouping.
+3. AI groups files into logical commits by intent.
+4. Each group gets a generated conventional commit message.
+5. Groups are committed sequentially. Hook failures pause the sequence with a recovery menu.
 
 ### Manual mode
 
 Run `cmint` without flags for the interactive flow:
 
-1. **Staging menu** — stage all, select files, auto-group, or run checks
-2. **File selection** — multi-select specific files if you don't want everything
-3. **Message review** — review the AI-generated message before committing
-4. **Commit attempt** — hooks run, recovery menu appears on failure
-
-If only one file changed, it's staged automatically.
-
-## Providers
-
-commit-mint supports multiple AI providers with per-provider configuration:
-
-| Provider | Env key | Default model |
-|----------|---------|---------------|
-| **Groq** | `GROQ_API_KEY` | `openai/gpt-oss-20b` |
-| **Cerebras** | `CEREBRAS_API_KEY` | `gpt-oss-120b` |
-| **Mistral** | `MISTRAL_API_KEY` | `mistral-small` |
-
-Switch providers with `cmint config set provider <name>`. Override the model per-provider with `cmint config set model_cerebras <model>`.
+1. **Staging menu** — stage all, select files, auto-group, or run checks.
+2. **Pre-flight checks** — `.cmintrc` checks run automatically (skip with `-N`).
+3. **Message review** — review the AI message before committing.
+4. **Commit** — hooks run, recovery menu on failure.
 
-> [!TIP]
-> All providers use OpenAI-compatible APIs. Groq uses the official SDK; Cerebras and Mistral use a built-in fetch client.
+Single-file changes are staged automatically.
 
 ## Recovery menu
 
-When a pre-commit hook blocks your commit, commit-mint parses the error output and presents an interactive menu:
+When a pre-commit hook blocks your commit, commit-mint parses the error and presents an interactive menu:
 
 ```
 ╭─────────────────────────────────────────────────╮
@@ -155,116 +140,62 @@ When a pre-commit hook blocks your commit, commit-mint parses the error output a
 ╰─────────────────────────────────────────────────╯
 ```
 
-| Option | What it does |
-|--------|-------------|
-| **Copy error report** | Copies parsed, clean error output to clipboard |
-| **View full output** | Shows raw stderr from the failed hook |
-| **Skip hooks** | Re-runs `git commit --no-verify` with the same message |
-| **Re-stage & retry** | Runs `git add -A` again, then retries the commit |
-| **Edit message** | Opens a prompt to modify the commit message, then retries |
-| **Cancel** | Exits. Commit message is cached for `cmint --retry` |
-
-Errors are parsed from **lint-staged**, **biome**, **TypeScript** (`tsc`), **vitest**/**jest**, and **ESLint**. Unrecognized output falls back to raw stderr.
+Errors are parsed from **lint-staged**, **biome**, **tsc**, **vitest**/**jest**, and **eslint**. Unrecognized output falls back to raw stderr.
 
-## Pre-commit checks
+## Pre-flight checks
 
-Define custom checks in a cmint config file at your project root. Supported file names (checked in priority order):
-
-`.cmintrc`, `.cmintrc.json`, `.cmintrc.{mjs,mts,js,ts,cjs,cts}`, `cmint.config.{mjs,mts,js,ts,cjs,cts}`
-
-Checks run after staging, before AI message generation, so a failing check never wastes an API call.
+`.cmintrc` is commit-mint's in-flow replacement for lint-staged. Define checks once at your project root and commit-mint runs them after staging but before AI generation — so failing checks never waste an API call.
 
 ```js
+// .cmintrc.ts
 export default {
-  // String: matched files are appended as arguments
   "*.{js,ts,json}": "biome check --write --no-errors-on-unmatched",
-
-  // Function: receive matched filenames, return command(s)
   "*.ts": () => ["tsc --noEmit", "vitest run --passWithNoTests"],
 };
 ```
 
-Glob patterns use [picomatch](https://github.com/micromatch/picomatch). String commands receive matched files as trailing arguments. Functions receive the matched file list and return one or more commands to run.
-
-### TypeScript config
-
-Use `.cmintrc.ts` or `cmint.config.ts` for type safety without adding commit-mint as a project dependency:
-
-```ts
-interface Cmintrc {
-  [glob: string]: string | string[] | ((filenames: string[]) => string | string[]);
-}
-
-export default {
-  "*.{js,ts,json}": "biome check --write --no-errors-on-unmatched",
-  "*.ts": () => ["tsc --noEmit", "vitest run --passWithNoTests"],
-} satisfies Cmintrc;
-```
-
-This gives you editor autocomplete and catches invalid values at edit time — no package install needed.
-
-Checks execute sequentially and fail fast. Each command has a 60-second timeout.
+Glob patterns use [picomatch](https://github.com/micromatch/picomatch). String commands receive matched files as trailing arguments. Functions receive the file list and return one or more commands. Checks run sequentially and fail fast (60s timeout per command).
 
-### Check failure menu
+Supported config file names: `.cmintrc`, `.cmintrc.json`, `.cmintrc.{mjs,mts,js,ts,cjs,cts}`, `cmint.config.{mjs,mts,js,ts,cjs,cts}`
 
-When a check fails, you get a menu with four options:
+## Providers
 
-| Option | What it does |
-|--------|-------------|
-| **Copy error report** | Copies the error output to clipboard |
-| **View full output** | Shows the raw check output |
-| **Skip checks** | Proceeds without running checks |
-| **Cancel** | Exits. Message is cached for `cmint --retry` |
+| Provider | Env key | Default model |
+|----------|---------|---------------|
+| **Groq** | `GROQ_API_KEY` | `openai/gpt-oss-20b` |
+| **Cerebras** | `CEREBRAS_API_KEY` | `gpt-oss-120b` |
+| **Mistral** | `MISTRAL_API_KEY` | `mistral-small` |
 
-Pass `--noCheck` or `-N` to skip checks entirely.
+Use `cmint config` to switch providers or override the model per-provider. All providers use OpenAI-compatible APIs (Groq via official SDK, Cerebras and Mistral via built-in fetch client).
 
 ## Configuration
 
-Stored in `~/.commit-mint` (INI format). Set values via `cmint config set <key> <value>`.
-
-```ini
-provider=groq
-GROQ_API_KEY=gsk_...
-model=openai/gpt-oss-20b
-locale=en
-max-length=100
-type=conventional
-timeout=10000
-proxy=
+Stored in `~/.commit-mint` (INI format). Run the wizard:
+
+```bash
+cmint config
 ```
 
 | Key | Default | Description |
 |-----|---------|-------------|
 | `provider` | `groq` | AI provider (`groq`, `cerebras`, or `mistral`) |
-| `GROQ_API_KEY` | — | Groq API key (or set `GROQ_API_KEY` env var) |
-| `CEREBRAS_API_KEY` | — | Cerebras API key (or set `CEREBRAS_API_KEY` env var) |
-| `MISTRAL_API_KEY` | — | Mistral API key (or set `MISTRAL_API_KEY` env var) |
-| `model` | `openai/gpt-oss-20b` | Default AI model for message generation |
-| `model_groq` | — | Model override for Groq provider |
-| `model_cerebras` | — | Model override for Cerebras provider |
-| `model_mistral` | — | Model override for Mistral provider |
+| `model` | `openai/gpt-oss-20b` | Default model (overridable per-provider with `model_groq`, `model_cerebras`, `model_mistral`) |
 | `locale` | `en` | Locale for generated messages |
-| `max-length` | `100` | Maximum commit message length |
-| `type` | — | Commit type prefix (e.g. `conventional`) |
+| `max-length` | `100` | Max commit message length |
+| `type` | — | Commit type prefix |
 | `timeout` | `10000` | AI request timeout in ms |
 | `proxy` | — | Proxy URL for API requests |
 
-Model resolution follows a chain: `model_<provider>` → global `model` → provider default. Per-provider keys prevent cross-provider model leaks when switching providers.
-
-## Retry persistence
+## Excluded files
 
-Failed commit messages are cached to `~/.cache/commit-mint/<repo-hash>.json`. Running `cmint --retry` reuses the last message without regenerating. Fix errors in another terminal, come back, and retry.
+Lockfiles, build output, and generated files are excluded from AI generation. When all staged files match excludes, commit-mint uses a hardcoded message (`chore: update lockfile` or `chore: update generated files`). In auto-group mode, lockfiles are promoted alongside their companion manifests (e.g. `package-lock.json` with `package.json`).
 
 ## Requirements
 
 - **Node.js 18+**
-- **Git** (any modern version)
-- **Linux** (primary target; macOS works via `pbcopy`; WSL untested)
-- **xclip**, **wl-copy**, **xsel**, or **pbcopy** for clipboard support
+- **Git**
+- Optional clipboard tool for error copy: `wl-copy`, `xclip`, `xsel`, or `pbcopy`
 
-## Non-goals
+## License
 
-- Not a git hook manager — cmint config checks run in-flow, not via git hooks. For git hooks, use husky or lefthook.
-- Not a linter/formatter — use biome, eslint, or prettier.
-- Not a git TUI — use lazygit or gitui.
-- Not a commitizen replacement — generates conventional commit messages via AI.
+[MIT](LICENSE)