@kyubiware/commit-mint 0.5.1 → 0.5.3

package/README.md

@@ -1,11 +1,14 @@
-# 🌿 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.
 
 ```
-┌  🌿 commit-mint
+┌  commit-mint
 │
 ◇  Files analyzed
 │
@@ -21,76 +24,34 @@
 │    ✓ eslint
 │    ✓ tsc
 │    ✓ vitest
-◇  Message generated
-│
-●  feat(text-study): add compound component support to ReadingInspectorPanel
-│
-◇  Committed successfully.
-│
-●    ✓ prettier
-│    ✓ eslint
-│    ✓ tsc
-│    ✓ vitest
 │
-●  Commit group 3 of 3: "Reading study list update"
+●  Commit group 2 of 3: "Panel refactor"
 ◇  Message generated
 │
-●  feat(reading-study-list-body): add compound component support to reading study list
+●  feat(text-study): add compound component support to ReadingInspectorPanel
 │
 ◇  Committed successfully.
 │
-●    ✓ prettier
-│    ✓ eslint
-│    ✓ tsc
-│    ✓ vitest
-│
 └  All groups committed.
 ```
 
-Requires **Node.js 18+**.
-
-## Quick Start
+## Quick start
 
 ```bash
 npm install -g @kyubiware/commit-mint
-```
-
-```bash
 cmint -a
 ```
 
-On first run, you'll be prompted for a `GROQ_API_KEY` if it's not set in `~/.commit-mint` or as an environment variable. It's saved for future runs.
-
-## Why commit-mint?
-
-- **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. Walk away and come back to clean history.
-- **Hook failures handled in-flow.** When pre-commit hooks fail, you get a parsed error summary and a menu to copy, skip, retry, or edit. No raw stderr dumps.
-- **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 exactly where you left off.
-
-## Auto mode (`-a`)
-
-`cmint -a` is the primary way to use commit-mint. It runs the full pipeline with no prompts:
+On first run, you'll be prompted for an API key if one isn't set. It's saved for future runs.
 
-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
+## Features
 
-Use this when you want clean history without the ceremony.
-
-## Manual mode
-
-Run `cmint` without flags for the interactive flow:
-
-1. **Staging menu** — stage all, select files, auto-group, or cancel
-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.
+- **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
 
@@ -111,7 +72,7 @@ cmint -H "refactoring auth module"
 cmint -r
 
 # Skip pre-commit checks
-cmint -n
+cmint -N
 
 # Debug mode
 cmint -d
@@ -119,6 +80,7 @@ cmint -d
 # 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
 ```
 
@@ -128,18 +90,48 @@ cmint config set model openai/gpt-oss-20b
 | `-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 |
+| `-N, --noCheck` | Skip pre-commit checks |
 | `-d, --debug` | Enable debug output |
 | `-h, --help` | Show help |
 | `-v, --version` | Show version |
 
-## Message review
+## Modes
 
-Before every commit, choose what to do with the generated message:
+### Auto mode (`-a`)
 
-- **Use as-is** — accept the AI-generated message
-- **Edit** — modify the message in a prompt
-- **Cancel** — exit (message is cached for `--retry`)
+`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
+
+### 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>`.
+
+> [!TIP]
+> All providers use OpenAI-compatible APIs. Groq uses the official SDK; Cerebras and Mistral use a built-in fetch client.
 
 ## Recovery menu
 
@@ -155,6 +147,7 @@ When a pre-commit hook blocks your commit, commit-mint parses the error output a
 │  What do you want to do?                         │
 │                                                  │
 │    Copy error report to clipboard                │
+│    View full output                              │
 │    Skip hooks and commit (--no-verify)           │
 │    Re-stage files and retry                      │
 │    Edit commit message                           │
@@ -165,21 +158,21 @@ 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` |
 
-The recovery menu also appears when cmint config pre-commit checks fail.
-
-commit-mint parses errors from **lint-staged**, **biome**, **TypeScript** (`tsc`), **vitest** / **jest**, and **ESLint**. Unrecognized output falls back to raw stderr.
+Errors are parsed from **lint-staged**, **biome**, **TypeScript** (`tsc`), **vitest**/**jest**, and **ESLint**. Unrecognized output falls back to raw stderr.
 
 ## Pre-commit 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}`
 
-They run after staging, before AI message generation, so a failing check never wastes an API call.
+Checks run after staging, before AI message generation, so a failing check never wastes an API call.
 
 ```js
 export default {
@@ -195,7 +188,7 @@ Glob patterns use [picomatch](https://github.com/micromatch/picomatch). String c
 
 ### TypeScript config
 
-Use `.cmintrc.ts` or `cmint.config.ts` for type safety without adding commit-mint as a project dependency. Add an inline interface and use `satisfies`:
+Use `.cmintrc.ts` or `cmint.config.ts` for type safety without adding commit-mint as a project dependency:
 
 ```ts
 interface Cmintrc {
@@ -208,36 +201,33 @@ export default {
 } satisfies Cmintrc;
 ```
 
-This gives you editor autocomplete and catches invalid values (e.g. numbers, objects) at edit time — no package install needed.
+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.
 
-### When checks run
-
-- **Manual mode**: The staging menu shows a "Run checks" option when a cmint config file exists
-- **Auto-group mode**: Checks run automatically on all staged files before grouping
-- **Normal commit**: Checks run on staged files after staging, before diff/AI
-
 ### Check failure menu
 
-When a check fails, you get a menu with three options:
+When a check fails, you get a menu with four options:
 
 | 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` |
 
-Pass `--noCheck` or `-n` to skip checks entirely.
+Pass `--noCheck` or `-N` to skip checks entirely.
 
 ## Configuration
 
-Stored in `~/.commit-mint` (INI format):
+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=
@@ -245,69 +235,26 @@ proxy=
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `GROQ_API_KEY` | — | Groq API key for AI message generation |
-| `model` | `openai/gpt-oss-20b` | AI model for commit message generation |
+| `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 |
 | `locale` | `en` | Locale for generated messages |
+| `max-length` | `100` | Maximum commit message length |
 | `type` | — | Commit type prefix (e.g. `conventional`) |
-| `timeout` | `10000` | AI request timeout (ms) |
+| `timeout` | `10000` | AI request timeout in ms |
 | `proxy` | — | Proxy URL for API requests |
 
-You can also set `GROQ_API_KEY` via environment variable.
-
-## CLI reference
-
-```
-cmint --help
-
-  cmint
-
-  A commit tool that actually handles hook failures
-
-  Options:
-    --retry, -r      Retry the last failed commit (default: false)
-    --auto, -a       Auto-group files into commits, accept all messages (default: false)
-    --message, -m    Provide a commit message directly (skip AI generation)
-    --hint, -H       Add context hint for AI commit message generation
-    --noCheck, -n    Skip pre-commit checks (default: false)
-    --debug, -d      Enable debug output (default: false)
-    --help, -h       Show help
-    --version, -v    Show version
-
-  Commands:
-    config           Get/set configuration values
-```
+Model resolution follows a chain: `model_<provider>` → global `model` → provider default. Per-provider keys prevent cross-provider model leaks when switching providers.
 
 ## Retry persistence
 
 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.
 
-## How it works
-
-```
-commit-mint/
-├── src/
-│   ├── cli.ts              # Entry point, argument parsing (cleye)
-│   ├── commands/
-│   │   ├── commit.ts       # Main commit flow orchestrator
-│   │   ├── auto-group.ts   # Auto-group multi-commit flow
-│   │   └── 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
-│   │   ├── hooks.ts        # Hook error parser (lint-staged, biome, tsc, etc.)
-│   │   ├── checks.ts       # Pre-commit checks via cmint config files (glob matching, command execution)
-│   │   ├── config.ts       # INI config read/write at ~/.commit-mint
-│   │   └── clipboard.ts    # Cross-platform clipboard (xclip/wl-copy/pbcopy)
-│   ├── ui/
-│   │   ├── menu.ts         # Interactive recovery TUI + staging menu
-│   │   ├── grouping.ts     # Grouping confirmation UI
-│   │   └── review-message.ts # Message review step (use/edit/cancel)
-│   └── utils/
-│       ├── cache.ts        # Commit message persistence at ~/.cache/commit-mint/
-│       └── debug.ts        # Timestamped debug logging to stderr
-```
-
 ## Requirements
 
 - **Node.js 18+**
@@ -317,11 +264,7 @@ commit-mint/
 
 ## Non-goals
 
-- 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, prettier
-- Not a git TUI — use lazygit, gitui
-- Not a commitizen replacement — just generates conventional commit messages via AI
-
-## License
-
-MIT © kyubiware
+- 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.