@kyubiware/commit-mint 0.9.1 → 0.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +277 -224
- package/dist/bin.mjs +8 -2
- package/dist/bin.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,66 +1,91 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# 🌿 commit-mint
|
|
4
|
+
|
|
5
|
+
**AI-powered git commits — auto-group, generate, recover**
|
|
2
6
|
|
|
3
7
|
[](https://www.npmjs.com/package/@kyubiware/commit-mint)
|
|
4
8
|
[](https://github.com/kyubiware/commit-mint/actions)
|
|
5
9
|
[](https://github.com/kyubiware/commit-mint)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
|
|
12
|
+
`commit-mint` (`cmint`) is an AI-powered wrapper around `git commit` that wraps
|
|
13
|
+
the full lifecycle — stage, generate, attempt, recover — and never leaves you
|
|
14
|
+
holding a lost message and a wall of raw stderr.
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
> Every AI commit tool generates a message, calls `git commit`, and dies on
|
|
19
|
+
> hook failure. `commit-mint` parses the failure, hands you a recovery menu
|
|
20
|
+
> (copy errors to clipboard, skip hooks, re-stage and retry), and caches the
|
|
21
|
+
> message so `cmint -r` resumes exactly where you stopped.
|
|
6
22
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
- Looks at what you changed and uses AI to group files into logical commits.
|
|
11
|
-
- Generates a good commit message for each group.
|
|
23
|
+
`cmint` runs your pre-commit checks, generates a conventional commit message
|
|
24
|
+
with AI, attempts the commit, and on failure shows a recovery menu with the
|
|
25
|
+
parsed error report ready to paste into a coding agent.
|
|
12
26
|
|
|
13
|
-
##
|
|
27
|
+
## Quick Start
|
|
14
28
|
|
|
15
29
|
```bash
|
|
16
30
|
npm install -g @kyubiware/commit-mint
|
|
17
31
|
```
|
|
18
32
|
|
|
19
|
-
Or run without installing:
|
|
20
|
-
|
|
21
33
|
```bash
|
|
22
|
-
|
|
34
|
+
cmint config # set your API key and preferred provider
|
|
23
35
|
```
|
|
24
36
|
|
|
25
|
-
|
|
26
|
-
|
|
37
|
+
```bash
|
|
38
|
+
cmint # interactive cli for committing changes
|
|
39
|
+
```
|
|
27
40
|
|
|
28
|
-
##
|
|
41
|
+
## Why commit-mint?
|
|
42
|
+
|
|
43
|
+
- [x] **Checks run before the AI call.** A failing check short-circuits before
|
|
44
|
+
any API call. With `lint-staged`, the hook fires after the message is
|
|
45
|
+
already finalized — a broken check wastes the message.
|
|
46
|
+
- [x] **Failures get a recovery menu, not raw stderr.** Output from `biome`,
|
|
47
|
+
`tsc`, `vitest`/`jest`, `eslint`, and `lint-staged` is parsed into
|
|
48
|
+
structured errors and presented in a 6-option menu.
|
|
49
|
+
- [x] **Live retry.** Fix the error in another terminal, pick "Retry checks" in
|
|
50
|
+
the menu — no need to exit and re-run `cmint`.
|
|
51
|
+
- [x] **Auto-group mode.** Ten changed files across three concerns become three
|
|
52
|
+
commits, each with its own AI-generated message.
|
|
53
|
+
- [x] **Message caching on failure.** Cached to `~/.cache/commit-mint/`. `cmint
|
|
54
|
+
-r` re-attempts with the same message after you fix the underlying issue.
|
|
55
|
+
|
|
56
|
+
## Comparison
|
|
57
|
+
|
|
58
|
+
| | commit-mint | aicommits | opencommit | cz-git | commitizen |
|
|
59
|
+
| -------------------------------------------------------- | :---------: | :-------: | :--------: | :-----: | :--------: |
|
|
60
|
+
| **Auto-group files into commits** | ✅ | — | — | — | — |
|
|
61
|
+
| **Hook failure recovery menu** | ✅ | — | — | — | — |
|
|
62
|
+
| **Pre-commit checks in-flow** (`.cmintrc`) | ✅ | — | — | — | — |
|
|
63
|
+
| **AI message generation** | ✅ | ✅ | ✅ | ✅ | — |
|
|
64
|
+
| **No OpenAI required** (Groq, Cerebras, Mistral) | ✅ | ✅ | — | — | n/a |
|
|
65
|
+
| **Message review before commit** | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
66
|
+
| **Zero-prompt auto mode** | ✅ | ✅ | ✅ | — | — |
|
|
67
|
+
| **Conventional commits** | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
68
|
+
| **Retry cached message** (`cmint -r`) | ✅ | — | — | ✅ | — |
|
|
69
|
+
|
|
70
|
+
## Command Reference
|
|
29
71
|
|
|
30
72
|
```bash
|
|
31
73
|
cmint # interactive: stage → checks → review → commit
|
|
32
74
|
cmint -a # auto-group, generate messages, commit everything
|
|
75
|
+
cmint -s # stage all tracked files in single commit, skip staging menu
|
|
33
76
|
cmint config # edit provider, model, locale, etc.
|
|
34
77
|
cmint update # update cmint to the latest published version
|
|
35
78
|
```
|
|
36
79
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
## Providers
|
|
40
|
-
|
|
41
|
-
| Provider | Env var | Default model |
|
|
42
|
-
| -------- | ----------------- | -------------------- |
|
|
43
|
-
| Groq | `GROQ_API_KEY` | `openai/gpt-oss-20b` |
|
|
44
|
-
| Cerebras | `CEREBRAS_API_KEY` | `gpt-oss-120b` |
|
|
45
|
-
| Mistral | `MISTRAL_API_KEY` | `mistral-small` |
|
|
46
|
-
|
|
47
|
-
All three use OpenAI-compatible APIs and have a generous free tier. Groq uses the official SDK; Cerebras and
|
|
48
|
-
Mistral use a built-in fetch client. Per-provider model overrides: set
|
|
49
|
-
`model_groq`, `model_cerebras`, or `model_mistral` in `~/.commit-mint`.
|
|
50
|
-
Resolution order is `model_<provider>` → `model` → provider default.
|
|
51
|
-
|
|
52
|
-
`cmint config` walks you through provider, API key, model, locale, and
|
|
53
|
-
timeout.
|
|
54
|
-
|
|
55
|
-
## Pre-flight checks (`.cmintrc`)
|
|
80
|
+
## Pre-flight Checks (`.cmintrc`)
|
|
56
81
|
|
|
57
82
|
`.cmintrc` is commit-mint's pre-commit check system. The config syntax is
|
|
58
|
-
identical to [lint-staged](https://github.com/okonet/lint-staged) — glob keys
|
|
83
|
+
identical to [`lint-staged`](https://github.com/okonet/lint-staged) — glob keys
|
|
59
84
|
mapping to shell commands — but the checks run inside commit-mint's flow, not
|
|
60
85
|
as a separate git hook.
|
|
61
86
|
|
|
62
|
-
**Already using lint-staged
|
|
63
|
-
syntax, no changes needed.
|
|
87
|
+
> **Already using `lint-staged`?** Rename your config file to `.cmintrc` — same
|
|
88
|
+
> syntax, no changes needed.
|
|
64
89
|
|
|
65
90
|
Run `cmint config` to auto-generate one, or create it manually:
|
|
66
91
|
|
|
@@ -75,116 +100,37 @@ export default {
|
|
|
75
100
|
(This is the actual `.cmintrc.ts` commit-mint ships with for its own
|
|
76
101
|
development.)
|
|
77
102
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
**1. Checks run before the AI call.** A failing check short-circuits before
|
|
81
|
-
any API call. With lint-staged, the hook fires after the message is already
|
|
82
|
-
finalized — a broken check wastes the message.
|
|
83
|
-
|
|
84
|
-
**2. Failures get a recovery menu, not raw stderr.** commit-mint parses biome,
|
|
85
|
-
tsc, vitest/jest, eslint, and lint-staged output into structured errors, then
|
|
86
|
-
lets you copy the error report to clipboard — paste straight into a coding
|
|
87
|
-
agent.
|
|
88
|
-
|
|
89
|
-
**3. Live retry.** Fix the error in another terminal, pick "Retry checks" in
|
|
90
|
-
the menu — no need to exit and re-run `cmint`.
|
|
91
|
-
|
|
92
|
-
Config shape details, file name patterns, and the failure menu are documented
|
|
93
|
-
[below](#config-reference).
|
|
94
|
-
|
|
95
|
-
## Auto-group mode (`-a`)
|
|
96
|
-
|
|
97
|
-
When you have 10 changed files across 3 concerns, `cmint -a` makes 3 commits,
|
|
98
|
-
each with its own message. The flow:
|
|
99
|
-
|
|
100
|
-
1. Excluded files (lockfiles, build output) are committed upfront with a
|
|
101
|
-
hardcoded `chore: update lockfile` message.
|
|
102
|
-
2. `.cmintrc` checks run on the remaining files.
|
|
103
|
-
3. The AI groups files by intent.
|
|
104
|
-
4. Each group is staged, diffed, and committed sequentially. A per-group
|
|
105
|
-
message is generated, and (in non-`auto` mode) reviewed.
|
|
106
|
-
5. A hook failure on any group shows the recovery menu and stops the sequence
|
|
107
|
-
— the remaining groups are not committed.
|
|
108
|
-
|
|
109
|
-
`cmint` (no `-a`) shows a staging menu for any number of changed files
|
|
110
|
-
(including one). The menu is also the only place the `a` and `c` hotkeys
|
|
111
|
-
toggle persistent modes, so it always runs:
|
|
103
|
+
When a check fails:
|
|
112
104
|
|
|
113
105
|
```
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
● Stage all files
|
|
119
|
-
○ Auto-group into commits
|
|
120
|
-
○ Run checks
|
|
121
|
-
...
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
- **`a` — Auto-accept** — skip the message review step. Persisted in
|
|
125
|
-
`~/.commit-mint` as `auto-accept`.
|
|
126
|
-
- **`c` — Pre-commit checks** — when OFF, skip the user-defined pre-commit
|
|
127
|
-
checks (the `.cmintrc` phase). Persisted in `~/.commit-mint` as
|
|
128
|
-
`run-checks` (default `true`/ON). Same effect as `cmint -N`, but persists
|
|
129
|
-
across runs. Only shown when a `.cmintrc` file exists.
|
|
130
|
-
|
|
131
|
-
## Self-update (`cmint update`)
|
|
132
|
-
|
|
133
|
-
`cmint update` checks the npm registry for a newer version and, if one exists,
|
|
134
|
-
runs the appropriate global install command for your package manager (detected
|
|
135
|
-
from `npm_config_user_agent` — npm, pnpm, yarn, or bun; falls back to npm).
|
|
136
|
-
|
|
137
|
-
- If you're already on the latest version, it exits silently.
|
|
138
|
-
- Otherwise it prints `current → latest` and asks for confirmation before
|
|
139
|
-
running the install (live npm output is streamed to your terminal).
|
|
140
|
-
- `cmint update -y` (or `--yes`) skips the confirmation prompt — useful in
|
|
141
|
-
scripts.
|
|
142
|
-
|
|
143
|
-
## AI Agent Mode
|
|
144
|
-
|
|
145
|
-
`cmint --agent` runs non-interactively with JSON output for AI coding agents.
|
|
106
|
+
Pre-commit check failed
|
|
107
|
+
• [biome] src/services/ai.ts:12:1 lint/suspicious/noExplicitAny — Unexpected any...
|
|
108
|
+
• [tsc] src/services/ai.ts:55:18 — error TS2345: Argument of type 'string' is...
|
|
146
109
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
| `--agent --hint "..."` | Pass hint to AI |
|
|
154
|
-
| `--agent --debug` | Verbose logging to stderr |
|
|
155
|
-
|
|
156
|
-
### JSON output schema
|
|
157
|
-
|
|
158
|
-
The command returns a single JSON object to stdout.
|
|
159
|
-
|
|
160
|
-
```json
|
|
161
|
-
{"status":"success","commits":[{"message":"feat: add X","hash":"abc123","files":["src/a.ts"]}]}
|
|
162
|
-
{"status":"no_changes","commits":[]}
|
|
163
|
-
{"status":"failure","commits":[],"errors":["error detail"]}
|
|
164
|
-
{"status":"cancelled","commits":[]}
|
|
110
|
+
What do you want to do?
|
|
111
|
+
Copy error report to clipboard
|
|
112
|
+
View full error output
|
|
113
|
+
Retry checks
|
|
114
|
+
Skip checks and commit
|
|
115
|
+
Cancel
|
|
165
116
|
```
|
|
166
117
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
| 4 | AI error |
|
|
176
|
-
| 5 | Check failure |
|
|
177
|
-
| 6 | Hook failure |
|
|
178
|
-
|
|
179
|
-
### AI Coding Agent Integration
|
|
118
|
+
- **Copy error report** — copies the raw stderr to clipboard (formatted for an
|
|
119
|
+
AI agent).
|
|
120
|
+
- **View full error output** — shows the raw stderr.
|
|
121
|
+
- **Retry checks** — re-runs the same checks. Fix in another terminal, hit
|
|
122
|
+
enter, no restart.
|
|
123
|
+
- **Skip checks and commit** — proceed to commit despite the failure.
|
|
124
|
+
- **Cancel** — exit. The message is cached so `cmint -r` re-attempts with the
|
|
125
|
+
same message.
|
|
180
126
|
|
|
181
|
-
For
|
|
127
|
+
For `tsc` failures specifically, the summary includes up to 3 `file:line:column`
|
|
128
|
+
diagnostics inline, with a `+N more` line if there are more.
|
|
182
129
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
```
|
|
130
|
+
Config shape, file name patterns, and glob matching rules are documented in
|
|
131
|
+
the [API Reference](#pre-flight-check-config).
|
|
186
132
|
|
|
187
|
-
## Recovery
|
|
133
|
+
## Recovery Menu
|
|
188
134
|
|
|
189
135
|
When a git hook blocks the commit, commit-mint parses the output and shows:
|
|
190
136
|
|
|
@@ -219,62 +165,82 @@ Hook progress is shown in real time during the commit — `[STARTED]` /
|
|
|
219
165
|
`[COMPLETED]` / `[FAILED]` markers from each task are streamed to stderr as
|
|
220
166
|
they happen.
|
|
221
167
|
|
|
222
|
-
Errors are parsed from
|
|
223
|
-
and
|
|
224
|
-
|
|
225
|
-
## Configuration
|
|
226
|
-
|
|
227
|
-
`~/.commit-mint` (INI format). Run `cmint config` to edit.
|
|
228
|
-
|
|
229
|
-
| Key | Default | Description |
|
|
230
|
-
| ---------------- | -------------------- | ------------------------------------------------- |
|
|
231
|
-
| `provider` | `groq` | `groq`, `cerebras`, or `mistral` |
|
|
232
|
-
| `model` | `openai/gpt-oss-20b` | Default model; overridable per provider |
|
|
233
|
-
| `model_groq` | — | Override default when provider is `groq` |
|
|
234
|
-
| `model_cerebras` | — | Override default when provider is `cerebras` |
|
|
235
|
-
| `model_mistral` | — | Override default when provider is `mistral` |
|
|
236
|
-
| `locale` | `en` | Locale for generated messages |
|
|
237
|
-
| `max-length` | `100` | Max commit message length |
|
|
238
|
-
| `type` | — | Force commit type prefix |
|
|
239
|
-
| `timeout` | `10000` | AI request timeout in ms |
|
|
240
|
-
| `proxy` | — | Proxy URL for API requests |
|
|
241
|
-
| `auto-accept` | `false` | `a` hotkey: skip message review step |
|
|
242
|
-
| `run-checks` | `true` | `c` hotkey: run user-defined pre-commit checks |
|
|
243
|
-
| `--agent` | `false` | Headless JSON-output mode for AI agents |
|
|
168
|
+
Errors are parsed from **`lint-staged`**, **`biome`**, **`tsc`**,
|
|
169
|
+
**`vitest`/`jest`**, and **`eslint`**. Unrecognized output falls back to a
|
|
170
|
+
single raw-stderr entry.
|
|
244
171
|
|
|
245
|
-
API
|
|
172
|
+
## API Reference
|
|
246
173
|
|
|
247
|
-
|
|
174
|
+
### Subcommands
|
|
248
175
|
|
|
249
|
-
|
|
176
|
+
| Name | Description |
|
|
177
|
+
|---|---|
|
|
178
|
+
| `cmint` | Default. Run the interactive commit flow. |
|
|
179
|
+
| `cmint auto` | Alias for `cmint -a`. Auto-group, generate, commit. |
|
|
180
|
+
| `cmint config` | Interactive TUI for reading/writing `~/.commit-mint`. |
|
|
181
|
+
| `cmint logs` | Show the debug log from the last session. |
|
|
182
|
+
| `cmint update` | Update cmint to the latest published version. |
|
|
250
183
|
|
|
251
|
-
|
|
252
|
-
package-lock.json
|
|
253
|
-
node_modules/** dist/** build/** .next/** coverage/**
|
|
254
|
-
*.log *.min.js *.min.css *.lock .DS_Store
|
|
255
|
-
```
|
|
184
|
+
### Flags
|
|
256
185
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
`
|
|
186
|
+
| Flag | Description |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `-a`, `--auto` | Auto-stage tracked files and auto-group into commits |
|
|
189
|
+
| `-m`, `--message <msg>` | Use your own message instead of AI generation |
|
|
190
|
+
| `-H`, `--hint <hint>` | Context hint to the AI (e.g. `"refactor only"`) |
|
|
191
|
+
| `-r`, `--retry` | Retry last failed commit (uses cached message) |
|
|
192
|
+
| `-N`, `--noCheck` | Skip pre-flight checks |
|
|
193
|
+
| `-d`, `--debug` | Debug logging to stderr |
|
|
194
|
+
| `--agent` | Headless JSON-output mode for AI coding agents |
|
|
195
|
+
| `-y`, `--yes` | Skip confirmation prompt (used with `cmint update`) |
|
|
196
|
+
|
|
197
|
+
### Config Keys
|
|
198
|
+
|
|
199
|
+
Stored in `~/.commit-mint` (INI format). Run `cmint config` to edit.
|
|
200
|
+
|
|
201
|
+
| Key | Default | Description |
|
|
202
|
+
|---|---|---|
|
|
203
|
+
| `provider` | `groq` | `groq`, `cerebras`, or `mistral` |
|
|
204
|
+
| `model` | `openai/gpt-oss-20b` | Default model; overridable per provider |
|
|
205
|
+
| `model_groq` | — | Override default when provider is `groq` |
|
|
206
|
+
| `model_cerebras` | — | Override default when provider is `cerebras` |
|
|
207
|
+
| `model_mistral` | — | Override default when provider is `mistral` |
|
|
208
|
+
| `locale` | `en` | Locale for generated messages |
|
|
209
|
+
| `max-length` | `100` | Max commit message length |
|
|
210
|
+
| `type` | — | Force commit type prefix |
|
|
211
|
+
| `timeout` | `10000` | AI request timeout in ms |
|
|
212
|
+
| `proxy` | — | Proxy URL for API requests |
|
|
213
|
+
| `auto-accept` | `false` | `a` hotkey: skip message review step |
|
|
214
|
+
| `run-checks` | `true` | `c` hotkey: run user-defined pre-commit checks |
|
|
215
|
+
|
|
216
|
+
API key lookup checks the env var first, then the INI file.
|
|
217
|
+
|
|
218
|
+
### Environment Variables
|
|
219
|
+
|
|
220
|
+
| Variable | Used by | Required |
|
|
221
|
+
|---|---|---|
|
|
222
|
+
| `GROQ_API_KEY` | `cmint` (when `provider=groq`) | Yes, unless set in `~/.commit-mint` |
|
|
223
|
+
| `CEREBRAS_API_KEY` | `cmint` (when `provider=cerebras`) | Yes, unless set in `~/.commit-mint` |
|
|
224
|
+
| `MISTRAL_API_KEY` | `cmint` (when `provider=mistral`) | Yes, unless set in `~/.commit-mint` |
|
|
225
|
+
| `https_proxy` / `HTTPS_PROXY` | All providers | Optional — overrides `proxy` config key |
|
|
226
|
+
| `NO_COLOR` | All UI | Optional — disables `kolorist` color output |
|
|
263
227
|
|
|
264
|
-
|
|
228
|
+
### Providers
|
|
265
229
|
|
|
266
|
-
|
|
|
267
|
-
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
|
|
|
271
|
-
| `-N`, `--noCheck` | Skip pre-flight checks |
|
|
272
|
-
| `-d`, `--debug` | Debug logging to stderr |
|
|
273
|
-
| `--agent` | Headless JSON mode for AI coding agents |
|
|
230
|
+
| Provider | Env var | Default model | Client |
|
|
231
|
+
|---|---|---|---|
|
|
232
|
+
| `groq` | `GROQ_API_KEY` | `openai/gpt-oss-20b` | `groq-sdk` |
|
|
233
|
+
| `cerebras` | `CEREBRAS_API_KEY` | `gpt-oss-120b` | Built-in fetch |
|
|
234
|
+
| `mistral` | `MISTRAL_API_KEY` | `mistral-small` | Built-in fetch |
|
|
274
235
|
|
|
275
|
-
|
|
236
|
+
All three use OpenAI-compatible APIs and have a generous free tier. Per-
|
|
237
|
+
provider model overrides: set `model_groq`, `model_cerebras`, or `model_mistral`
|
|
238
|
+
in `~/.commit-mint`. Resolution order is `model_<provider>` → `model` →
|
|
239
|
+
provider default.
|
|
276
240
|
|
|
277
|
-
###
|
|
241
|
+
### Pre-flight Check Config
|
|
242
|
+
|
|
243
|
+
#### File names
|
|
278
244
|
|
|
279
245
|
Checked in this order. First match wins.
|
|
280
246
|
|
|
@@ -295,18 +261,23 @@ cmint.config.cjs
|
|
|
295
261
|
cmint.config.cts
|
|
296
262
|
```
|
|
297
263
|
|
|
298
|
-
`.ts`/`.cts`/`.cjs` are loaded via [jiti](https://github.com/unjs/jiti) —
|
|
299
|
-
TypeScript syntax freely. `.json` is parsed as plain JSON. Everything else
|
|
300
|
-
loaded as ESM with `import default`.
|
|
264
|
+
`.ts`/`.cts`/`.cjs` are loaded via [`jiti`](https://github.com/unjs/jiti) —
|
|
265
|
+
use TypeScript syntax freely. `.json` is parsed as plain JSON. Everything else
|
|
266
|
+
is loaded as ESM with `import default`.
|
|
301
267
|
|
|
302
|
-
|
|
268
|
+
#### Shape
|
|
303
269
|
|
|
304
|
-
A default export. Each key is a [picomatch](https://github.com/micromatch/picomatch)
|
|
270
|
+
A default export. Each key is a [`picomatch`](https://github.com/micromatch/picomatch)
|
|
305
271
|
glob; each value is a command string, a string array, or a function that
|
|
306
272
|
returns either.
|
|
307
273
|
|
|
308
|
-
|
|
309
|
-
|
|
274
|
+
| Form | Behavior |
|
|
275
|
+
|---|---|
|
|
276
|
+
| `string` | Matched files are appended as trailing arguments. Paths with spaces are quoted automatically. |
|
|
277
|
+
| `string[]` | Commands run sequentially, each as a separate command. First failure stops the run. |
|
|
278
|
+
| `(files) => string \| string[]` | Function receives the matched files. Use when the command depends on the file list. |
|
|
279
|
+
|
|
280
|
+
**String command:**
|
|
310
281
|
|
|
311
282
|
```ts
|
|
312
283
|
export default {
|
|
@@ -314,8 +285,7 @@ export default {
|
|
|
314
285
|
};
|
|
315
286
|
```
|
|
316
287
|
|
|
317
|
-
**String
|
|
318
|
-
stops the run.
|
|
288
|
+
**String array:**
|
|
319
289
|
|
|
320
290
|
```ts
|
|
321
291
|
export default {
|
|
@@ -323,9 +293,7 @@ export default {
|
|
|
323
293
|
};
|
|
324
294
|
```
|
|
325
295
|
|
|
326
|
-
**Function
|
|
327
|
-
of commands. Use these when the command depends on the file list, or you want
|
|
328
|
-
multiple commands from one glob:
|
|
296
|
+
**Function command:**
|
|
329
297
|
|
|
330
298
|
```ts
|
|
331
299
|
export default {
|
|
@@ -334,14 +302,14 @@ export default {
|
|
|
334
302
|
};
|
|
335
303
|
```
|
|
336
304
|
|
|
337
|
-
|
|
305
|
+
#### Glob matching
|
|
338
306
|
|
|
339
307
|
- Globs without a `/` match at any depth (e.g. `*.ts` matches `src/foo.ts` and
|
|
340
308
|
`a/b/c.ts`).
|
|
341
309
|
- Dotfiles are included.
|
|
342
310
|
- Paths with spaces are quoted before being appended.
|
|
343
311
|
|
|
344
|
-
|
|
312
|
+
#### Behavior
|
|
345
313
|
|
|
346
314
|
- Checks run after `git add`, before the AI call.
|
|
347
315
|
- Globs are processed in declaration order.
|
|
@@ -349,43 +317,128 @@ export default {
|
|
|
349
317
|
and skips remaining globs.
|
|
350
318
|
- 60s timeout per command. ENOENT (command not found) and timeouts are
|
|
351
319
|
reported back to the menu as their own error.
|
|
352
|
-
- Skipped entirely with `cmint -N
|
|
320
|
+
- Skipped entirely with `cmint -N` or the `c` hotkey toggle.
|
|
321
|
+
|
|
322
|
+
### Exit Codes
|
|
323
|
+
|
|
324
|
+
`cmint --agent` uses 7 documented exit codes. Interactive `cmint` always exits
|
|
325
|
+
with `0` or `1`.
|
|
326
|
+
|
|
327
|
+
| Code | Meaning |
|
|
328
|
+
|---|---|
|
|
329
|
+
| 0 | Success |
|
|
330
|
+
| 1 | Generic error |
|
|
331
|
+
| 2 | No changes |
|
|
332
|
+
| 3 | Git error |
|
|
333
|
+
| 4 | AI error |
|
|
334
|
+
| 5 | Check failure |
|
|
335
|
+
| 6 | Hook failure |
|
|
353
336
|
|
|
354
|
-
###
|
|
337
|
+
### Agent JSON Output Schema
|
|
355
338
|
|
|
356
|
-
|
|
357
|
-
|
|
339
|
+
The command returns a single JSON object to stdout. See the [Agent
|
|
340
|
+
Flow](#agent-flow---agent) section for invocation patterns.
|
|
358
341
|
|
|
342
|
+
```ts
|
|
343
|
+
type AgentResult = {
|
|
344
|
+
status: "success" | "no_changes" | "failure" | "cancelled";
|
|
345
|
+
commits: Array<{
|
|
346
|
+
message: string;
|
|
347
|
+
hash: string;
|
|
348
|
+
files: string[];
|
|
349
|
+
groupName?: string;
|
|
350
|
+
}>;
|
|
351
|
+
errors?: string[];
|
|
352
|
+
};
|
|
359
353
|
```
|
|
360
|
-
Pre-commit check failed
|
|
361
|
-
• [biome] src/services/ai.ts:12:1 lint/suspicious/noExplicitAny — Unexpected any...
|
|
362
|
-
• [tsc] src/services/ai.ts:55:18 — error TS2345: Argument of type 'string' is...
|
|
363
354
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
355
|
+
### Excluded Files
|
|
356
|
+
|
|
357
|
+
These patterns are filtered from AI generation by default:
|
|
358
|
+
|
|
359
|
+
```
|
|
360
|
+
package-lock.json
|
|
361
|
+
node_modules/** dist/** build/** .next/** coverage/**
|
|
362
|
+
*.log *.min.js *.min.css *.lock .DS_Store
|
|
370
363
|
```
|
|
371
364
|
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
- **Cancel** — exit. The message is cached so `cmint -r` re-attempts with the
|
|
379
|
-
same message.
|
|
365
|
+
When every staged file matches an exclude, commit-mint uses a hardcoded
|
|
366
|
+
message: `chore: update lockfile` for lockfiles, `chore: update generated
|
|
367
|
+
files` for the rest. In auto-group mode, lockfiles (`package-lock.json`,
|
|
368
|
+
`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `bun.lockb`) are promoted
|
|
369
|
+
alongside their companion manifest (e.g. `package-lock.json` stays with
|
|
370
|
+
`package.json`).
|
|
380
371
|
|
|
381
|
-
|
|
382
|
-
|
|
372
|
+
### Debug Logs
|
|
373
|
+
|
|
374
|
+
`cmint --debug` streams timestamped log lines to stderr. The same log is
|
|
375
|
+
persisted to `~/.cache/commit-mint/debug.log` with a `--- session <ISO
|
|
376
|
+
timestamp> ---` header on every CLI invocation.
|
|
377
|
+
|
|
378
|
+
View the last session's log:
|
|
379
|
+
|
|
380
|
+
```bash
|
|
381
|
+
cmint logs # entire last session
|
|
382
|
+
cmint logs -n 50 # last 50 lines
|
|
383
|
+
```
|
|
383
384
|
|
|
384
385
|
## Requirements
|
|
385
386
|
|
|
386
|
-
- Node.js 18+
|
|
387
|
-
- git
|
|
388
|
-
-
|
|
387
|
+
- [x] Node.js 18+
|
|
388
|
+
- [x] git
|
|
389
|
+
- [x] One of: `GROQ_API_KEY`, `CEREBRAS_API_KEY`, or `MISTRAL_API_KEY`
|
|
390
|
+
(or run `cmint config` to set one)
|
|
391
|
+
- [x] Optional, for clipboard copy: `wl-copy`, `xclip`, `xsel`, or `pbcopy`
|
|
392
|
+
|
|
393
|
+
## Support
|
|
394
|
+
|
|
395
|
+
- [GitHub Issues](https://github.com/kyubiware/commit-mint/issues) — bug
|
|
396
|
+
reports and feature requests
|
|
397
|
+
- [GitHub Discussions](https://github.com/kyubiware/commit-mint/discussions) —
|
|
398
|
+
questions and ideas
|
|
399
|
+
- [npm](https://www.npmjs.com/package/@kyubiware/commit-mint) — releases and
|
|
400
|
+
install stats
|
|
401
|
+
|
|
402
|
+
## Built With
|
|
403
|
+
|
|
404
|
+
- [TypeScript](https://www.typescriptlang.org/) — strict, ESM-only, `tsdown`
|
|
405
|
+
bundler
|
|
406
|
+
- [@clack/prompts](https://github.com/natemoo-re/clack) + [`kolorist`](https://github.com/marvinhagemeister/kolorist) —
|
|
407
|
+
interactive TUI primitives
|
|
408
|
+
- [`cleye`](https://github.com/alloc/cleye) — CLI argument parsing
|
|
409
|
+
- [`execa`](https://github.com/sindresorhus/execa) — subprocess execution with
|
|
410
|
+
clean stderr capture
|
|
411
|
+
- [`groq-sdk`](https://github.com/groq/groq-typescript) — official Groq client
|
|
412
|
+
- [`picomatch`](https://github.com/micromatch/picomatch) — glob matching
|
|
413
|
+
- [`jiti`](https://github.com/unjs/jiti) — TypeScript config loader
|
|
414
|
+
- [`ini`](https://github.com/npm/ini) — INI config parsing
|
|
415
|
+
- [`semver`](https://github.com/npm/node-semver) — version comparison for
|
|
416
|
+
`cmint update`
|
|
417
|
+
|
|
418
|
+
## AI Agent Skill
|
|
419
|
+
|
|
420
|
+
> If you're an AI coding agent, this section is for you.
|
|
421
|
+
|
|
422
|
+
Install `commit-mint` as a skill in OpenCode, Cursor, or any agent that loads
|
|
423
|
+
[npm skills](https://www.npmjs.com/package/skills):
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
npx skills add kyubiware/commit-mint
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
The skill teaches the agent the non-interactive agent flow:
|
|
430
|
+
|
|
431
|
+
1. Run `cmint --agent` (or `cmint --agent --noCheck` to skip pre-commit
|
|
432
|
+
checks).
|
|
433
|
+
2. Parse the JSON `AgentResult` from stdout.
|
|
434
|
+
3. Read the `process.exitCode` against the [Exit Codes](#exit-codes) table.
|
|
435
|
+
|
|
436
|
+
The agent never has to interact with the recovery menu — failures are
|
|
437
|
+
surfaced as `status: "failure"` with an `errors[]` array, or one of the
|
|
438
|
+
`--agent`-specific exit codes (3 = git, 4 = AI, 5 = check, 6 = hook).
|
|
439
|
+
|
|
440
|
+
For OpenCode, the skill is also shipped with the project at
|
|
441
|
+
[`skills/cmint/SKILL.md`](skills/cmint/SKILL.md).
|
|
389
442
|
|
|
390
443
|
## License
|
|
391
444
|
|
package/dist/bin.mjs
CHANGED
|
@@ -33,7 +33,7 @@ var __exportAll = (all, no_symbols) => {
|
|
|
33
33
|
//#region package.json
|
|
34
34
|
var package_default = {
|
|
35
35
|
name: "@kyubiware/commit-mint",
|
|
36
|
-
version: "0.9.
|
|
36
|
+
version: "0.9.2",
|
|
37
37
|
description: "🌿 AI-powered git commit tool — auto-group changed files, generate messages, run pre-commit checks",
|
|
38
38
|
type: "module",
|
|
39
39
|
bin: { "cmint": "./dist/bin.mjs" },
|
|
@@ -681,9 +681,15 @@ async function getChangedFiles() {
|
|
|
681
681
|
if (!stdout.trim()) return [];
|
|
682
682
|
const files = stdout.split("\n").filter(Boolean).map((line) => {
|
|
683
683
|
const indexStatus = line[0];
|
|
684
|
+
const worktreeStatus = line[1];
|
|
685
|
+
let path = line.slice(3);
|
|
686
|
+
if (indexStatus === "R" || worktreeStatus === "R") {
|
|
687
|
+
const arrow = path.lastIndexOf(" -> ");
|
|
688
|
+
if (arrow !== -1) path = path.slice(arrow + 4);
|
|
689
|
+
}
|
|
684
690
|
return {
|
|
685
691
|
status: line.slice(0, 2).trim(),
|
|
686
|
-
path
|
|
692
|
+
path,
|
|
687
693
|
staged: indexStatus !== " " && indexStatus !== "?"
|
|
688
694
|
};
|
|
689
695
|
});
|