@kyubiware/commit-mint 0.5.5 → 0.6.0

package/README.md

@@ -1,270 +1,308 @@
 # 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)
+[![npm](https://img.shields.io/npm/v/@kyubiware/commit-mint.svg)](https://www.npmjs.com/package/@kyubiware/commit-mint)
+[![CI](https://img.shields.io/github/actions/workflow/status/kyubiware/commit-mint/ci.yml)](https://github.com/kyubiware/commit-mint/actions)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-3c873a)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-> Auto-group your changes into clean, conventional commits. AI handles the grouping, messages, and hook failures so you don't have to.
+A commit tool that handles hook failures. Generates conventional commit messages
+from your diff, auto-groups unrelated changes into separate commits, runs your
+checks before any API call, and gives you a recovery menu when hooks block the
+commit instead of dumping raw stderr.
 
-```
-┌  commit-mint
-│
-◇  Files analyzed
-│
-●  Commit group 1 of 3: "Reading view refactor"
-│
-◇  Message generated
-│
-●  feat(compound): add compound utilities and token handling for text study
-│
-◇  Committed successfully.
-│
-●    ✓ prettier
-│    ✓ eslint
-│    ✓ tsc
-│    ✓ vitest
-│
-●  Commit group 2 of 3: "Panel refactor"
-◇  Message generated
-│
-●  feat(text-study): add compound component support to ReadingInspectorPanel
-│
-◇  Committed successfully.
-│
-└  All groups committed.
-```
-
-## Quick start
+## Install
 
 ```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.
+Or run without installing:
 
-## Features
+```bash
+npx @kyubiware/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.
-- **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.
+Requires Node.js 18+ and git. Run `cmint config` once to set the AI provider and
+API key. The key is saved to `~/.commit-mint` (INI).
 
 ## Usage
 
 ```bash
-# Auto-group and commit everything (no prompts)
-cmint -a
+cmint                  # interactive: stage → checks → review → commit
+cmint -a               # auto-group, generate messages, commit everything
+cmint -m "feat: ..."   # skip AI, use your own message
+cmint -H "context"     # hint to the AI (e.g. "refactor only, no behavior change")
+cmint -r               # retry the last failed commit (cached message)
+cmint -N               # skip pre-flight checks
+cmint -d               # debug logging to stderr
+cmint config           # edit provider, model, locale, etc.
+```
 
-# Normal interactive flow
-cmint
+## Pre-flight checks (`.cmintrc`)
 
-# Skip AI, provide your own message
-cmint -m "feat: add dark mode"
+`.cmintrc` is commit-mint's pre-commit check system. The config syntax is
+identical to [lint-staged](https://github.com/okonet/lint-staged) — glob keys
+mapping to shell commands — but the checks run inside commit-mint's flow, not
+as a separate git hook.
 
-# Pass context hint for better messages
-cmint -H "refactoring auth module"
+This matters for three reasons:
 
-# Retry last failed commit (uses cached message)
-cmint -r
+**1. Checks run before the AI call.** commit-mint runs checks before
+generating the commit message. A failing check short-circuits before any API
+call. With lint-staged, the hook fires after the message is already finalized
+(if the AI call was made) or the user has typed one in — so a broken check
+wastes the message.
 
-# Skip pre-commit checks
-cmint -N
+**2. Failures get a recovery menu, not raw stderr.** lint-staged prints whatever
+the tool emitted and exits. commit-mint parses biome, tsc, vitest/jest, eslint,
+and lint-staged output into structured errors. Then commit-mint lets you copy the error report to clipboard,
+so you can paste straight to your coding agent.
 
-# Debug mode
-cmint -d
+**3. Live retry.** After your coding agent fixes the error in another terminal, pick "Retry checks" in
+the menu, no need to exit and re-run `cmint`.
+
+Same syntax, fewer moving parts, and the checks live in the same process as
+the rest of the commit.
+
+### Config file names
+
+Checked in this order. First match wins.
 
-# 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
+```
+.cmintrc
+.cmintrc.json
+.cmintrc.mjs
+.cmintrc.mts
+.cmintrc.js
+.cmintrc.ts
+.cmintrc.cjs
+.cmintrc.cts
+cmint.config.mjs
+cmint.config.mts
+cmint.config.js
+cmint.config.ts
+cmint.config.cjs
+cmint.config.cts
 ```
 
-| 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 |
+`.ts`/`.cts`/`.cjs` are loaded via [jiti](https://github.com/unjs/jiti) — use
+TypeScript syntax freely. `.json` is parsed as plain JSON. Everything else is
+loaded as ESM with `import default`.
 
-## Modes
+### Config shape
 
-### Auto mode (`-a`)
+A default export. Each key is a [picomatch](https://github.com/micromatch/picomatch)
+glob; each value is a command string, a string array, or a function that
+returns either.
 
-`cmint -a` runs the full pipeline with no prompts:
+```ts
+// .cmintrc.ts
+export default {
+	"*.{js,ts,json}": "biome check --write --no-errors-on-unmatched --error-on-warnings",
+	"*.ts": () => ["tsc --noEmit", "vitest run --passWithNoTests", "npm run build"],
+};
+```
 
-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
+This is the actual `.cmintrc.ts` commit-mint ships with for its own
+development — biome on staged JS/TS/JSON, then tsc + vitest + build on staged
+TS.
 
-### Manual mode
+**String commands** get matched files appended as trailing arguments. Files
+with spaces in their paths are quoted automatically.
 
-Run `cmint` without flags for the interactive flow:
+```ts
+export default {
+	"*.ts": "eslint --fix", // runs `eslint --fix src/foo.ts src/bar.ts`
+};
+```
 
-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
+**String arrays** run sequentially, each as a separate command. First failure
+stops the run.
 
-If only one file changed, it's staged automatically.
+```ts
+export default {
+	"*.ts": ["eslint --fix", "prettier --write"],
+};
+```
 
-## Providers
+**Function commands** receive the matched files and return a command or array
+of commands. Use these when the command depends on the file list, or you want
+multiple commands from one glob:
 
-commit-mint supports multiple AI providers with per-provider configuration:
+```ts
+export default {
+	"*.ts": (files) =>
+		files.length > 5 ? `vitest run ${files.join(" ")}` : "vitest run",
+};
+```
 
-| 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` |
+### Glob matching
 
-Switch providers with `cmint config set provider <name>`. Override the model per-provider with `cmint config set model_cerebras <model>`.
+- Globs without a `/` match at any depth (e.g. `*.ts` matches `src/foo.ts` and
+  `a/b/c.ts`).
+- Dotfiles are included.
+- Paths with spaces are quoted before being appended.
 
-> [!TIP]
-> All providers use OpenAI-compatible APIs. Groq uses the official SDK; Cerebras and Mistral use a built-in fetch client.
+### Behavior
 
-## Recovery menu
+- Checks run after `git add`, before the AI call.
+- Globs are processed in declaration order.
+- Commands run sequentially per glob. First failure stops the run (fail-fast)
+  and skips remaining globs.
+- 60s timeout per command. ENOENT (command not found) and timeouts are
+  reported back to the menu as their own error.
+- Skipped entirely with `cmint -N`.
+
+### Failure menu
 
-When a pre-commit hook blocks your commit, commit-mint parses the error output and presents an interactive menu:
+When a check fails, the same `parseHookErrors` pipeline that handles git
+hooks runs, and a menu appears:
 
 ```
-╭─────────────────────────────────────────────────╮
-│  ✘ Pre-commit hook failed                       │
-│                                                  │
-│  • biome: src/cli.ts — unused variable           │
-│  • vitest: 1 test failed in test/cli.test.ts     │
-│                                                  │
-│  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                           │
-│    Cancel                                        │
-╰─────────────────────────────────────────────────╯
+Pre-commit check failed
+  • [biome] src/services/ai.ts:12:1 lint/suspicious/noExplicitAny — Unexpected any...
+  • [tsc] src/services/ai.ts:55:18 — error TS2345: Argument of type 'string' is...
+
+What do you want to do?
+  Copy error report to clipboard
+  View full error output
+  Retry checks
+  Skip checks and commit
+  Cancel
 ```
 
-| 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` |
+- **Copy error report** — copies the raw stderr (works with `wl-copy`,
+  `xclip`, `xsel`, or `pbcopy`).
+- **View full error output** — shows the raw stderr.
+- **Retry checks** — re-runs the same checks. Fix in another terminal, hit
+  enter, no restart.
+- **Skip checks and commit** — proceed to commit despite the failure.
+- **Cancel** — exit. The message is cached so `cmint -r` re-attempts with the
+  same message.
 
-Errors are parsed from **lint-staged**, **biome**, **TypeScript** (`tsc`), **vitest**/**jest**, and **ESLint**. Unrecognized output falls back to raw stderr.
+For tsc failures specifically, the summary includes up to 3 file:line:column
+diagnostics inline, with a `+N more` line if there are more.
 
-## Pre-commit checks
+## Auto-group mode (`-a`)
 
-Define custom checks in a cmint config file at your project root. Supported file names (checked in priority order):
+When you have 10 changed files across 3 concerns, `cmint -a` makes 3 commits,
+each with its own message. The flow:
 
-`.cmintrc`, `.cmintrc.json`, `.cmintrc.{mjs,mts,js,ts,cjs,cts}`, `cmint.config.{mjs,mts,js,ts,cjs,cts}`
+1. Excluded files (lockfiles, build output) are committed upfront with a
+   hardcoded `chore: update lockfile` message.
+2. `.cmintrc` checks run on the remaining files.
+3. The AI groups files by intent.
+4. Each group is staged, diffed, and committed sequentially. A per-group
+   message is generated, and (in non-`auto` mode) reviewed.
+5. A hook failure on any group shows the recovery menu and stops the sequence
+   — the remaining groups are not committed.
 
-Checks run after staging, before AI message generation, so a failing check never wastes an API call.
+`cmint` (no `-a`) on multiple files shows a staging menu:
 
-```js
-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"],
-};
+```
+What do you want to stage?
+  Stage all files
+  Select files...
+  Auto-group into commits
+  Run checks
 ```
 
-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.
+## Recovery menu
 
-### TypeScript config
+When a git hook blocks the commit, commit-mint parses the output and shows:
 
-Use `.cmintrc.ts` or `cmint.config.ts` for type safety without adding commit-mint as a project dependency:
+```
+Pre-commit hook failed
+  • [biome] src/cli.ts — unused variable
+  • [vitest] 1 test failed in test/cli.test.ts
+
+What do you want to do?
+  Copy error report to clipboard
+  View full error output
+  Skip hooks and commit (--no-verify)
+  Re-stage files and retry
+  Edit commit message
+  Cancel
+```
 
-```ts
-interface Cmintrc {
-  [glob: string]: string | string[] | ((filenames: string[]) => string | string[]);
-}
+Six options, none are dead ends:
 
-export default {
-  "*.{js,ts,json}": "biome check --write --no-errors-on-unmatched",
-  "*.ts": () => ["tsc --noEmit", "vitest run --passWithNoTests"],
-} satisfies Cmintrc;
-```
+- **Copy error report** — raw stderr to clipboard, formatted for an AI agent.
+- **View full error output** — show the unparsed stderr in a note.
+- **Skip hooks** — commit with `--no-verify`. Use when the failure is
+  understood and not worth blocking on.
+- **Re-stage** — `git add -A`, retry the commit. Picks up fixes you make in
+  another terminal without restarting cmint. If re-stage still fails, the
+  menu re-shows the errors.
+- **Edit** — tweak the AI message, then retry.
+- **Cancel** — exit. The message is cached; `cmint -r` re-attempts with the
+  same message after you fix the underlying issue.
 
-This gives you editor autocomplete and catches invalid values at edit time — no package install needed.
+Hook progress is shown in real time during the commit — `[STARTED]` /
+`[COMPLETED]` / `[FAILED]` markers from each task are streamed to stderr as
+they happen.
 
-Checks execute sequentially and fail fast. Each command has a 60-second timeout.
+Errors are parsed from **lint-staged**, **biome**, **tsc**, **vitest**/**jest**,
+and **eslint**. Unrecognized output falls back to a single raw-stderr entry.
 
-### Check failure menu
+## Providers
 
-When a check fails, you get a menu with four options:
+| Provider | Env var           | Default model        |
+| -------- | ----------------- | -------------------- |
+| Groq     | `GROQ_API_KEY`    | `openai/gpt-oss-20b` |
+| Cerebras | `CEREBRAS_API_KEY` | `gpt-oss-120b`     |
+| Mistral  | `MISTRAL_API_KEY` | `mistral-small`      |
 
-| 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` |
+All three use OpenAI-compatible APIs. Groq uses the official SDK; Cerebras and
+Mistral use a built-in fetch client. Per-provider model overrides: set
+`model_groq`, `model_cerebras`, or `model_mistral` in `~/.commit-mint`.
+Resolution order is `model_<provider>` → `model` → provider default.
 
-Pass `--noCheck` or `-N` to skip checks entirely.
+`cmint config` walks you through provider, API key, model, locale, and
+timeout.
 
 ## 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=
-```
+`~/.commit-mint` (INI format). Run `cmint config` to edit.
+
+| Key              | Default              | Description                                       |
+| ---------------- | -------------------- | ------------------------------------------------- |
+| `provider`       | `groq`               | `groq`, `cerebras`, or `mistral`                  |
+| `model`          | `openai/gpt-oss-20b` | Default model; overridable per provider           |
+| `model_groq`     | —                    | Override default when provider is `groq`          |
+| `model_cerebras` | —                    | Override default when provider is `cerebras`      |
+| `model_mistral`  | —                    | Override default when provider is `mistral`       |
+| `locale`         | `en`                 | Locale for generated messages                     |
+| `max-length`     | `100`                | Max commit message length                         |
+| `type`           | —                    | Force commit type prefix                          |
+| `timeout`        | `10000`              | AI request timeout in ms                          |
+| `proxy`          | —                    | Proxy URL for API requests                        |
+
+API key lookup checks the env var first, then the INI file.
 
-| 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 |
-| `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 in ms |
-| `proxy` | — | Proxy URL for API requests |
+## Excluded files
 
-Model resolution follows a chain: `model_<provider>` → global `model` → provider default. Per-provider keys prevent cross-provider model leaks when switching providers.
+These patterns are filtered from AI generation by default:
 
-## Retry persistence
+```
+package-lock.json
+node_modules/**  dist/**  build/**  .next/**  coverage/**
+*.log  *.min.js  *.min.css  *.lock  .DS_Store
+```
 
-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.
+When every staged file matches an exclude, commit-mint uses a hardcoded
+message: `chore: update lockfile` for lockfiles, `chore: update generated
+files` for the rest. In auto-group mode, lockfiles (`package-lock.json`,
+`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `bun.lockb`) are promoted
+alongside their companion manifest (e.g. `package-lock.json` stays 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
+- Node.js 18+
+- git
+- Optional, for clipboard 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)