@kyubiware/commit-mint 0.6.0 → 0.6.2

package/README.md

@@ -2,13 +2,13 @@
 
 [![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)
+[![GitHub stars](https://img.shields.io/github/stars/kyubiware/commit-mint?style=flat&logo=github)](https://github.com/kyubiware/commit-mint)
 
-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.
+- Runs your pre-commit checks on changed files, then digests failures into a
+  structured error report you can copy to clipboard — paste straight into a
+  coding agent.
+- Looks at what you changed and uses AI to group files into logical commits.
+- Generates a good commit message for each group.
 
 ## Install
 
@@ -28,16 +28,13 @@ API key. The key is saved to `~/.commit-mint` (INI).
 ## Usage
 
 ```bash
-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.
+cmint             # interactive: stage → checks → review → commit
+cmint -a          # auto-group, generate messages, commit everything
+cmint config      # edit provider, model, locale, etc.
 ```
 
+See [all flags](#all-flags) for the full list.
+
 ## Pre-flight checks (`.cmintrc`)
 
 `.cmintrc` is commit-mint's pre-commit check system. The config syntax is
@@ -45,55 +42,10 @@ 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.
 
-This matters for three reasons:
-
-**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.
-
-**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.
-
-**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.
-
-```
-.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
-```
-
-`.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`.
-
-### Config shape
+**Already using lint-staged?** Rename your config file to `.cmintrc` — same
+syntax, no changes needed.
 
-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.
+Run `cmint config` to auto-generate one, or create it manually:
 
 ```ts
 // .cmintrc.ts
@@ -103,85 +55,25 @@ export default {
 };
 ```
 
-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.
+(This is the actual `.cmintrc.ts` commit-mint ships with for its own
+development.)
 
-**String commands** get matched files appended as trailing arguments. Files
-with spaces in their paths are quoted automatically.
+Checks run inside commit-mint's flow for three reasons:
 
-```ts
-export default {
-	"*.ts": "eslint --fix", // runs `eslint --fix src/foo.ts src/bar.ts`
-};
-```
+**1. Checks run before the AI call.** A failing check short-circuits before
+any API call. With lint-staged, the hook fires after the message is already
+finalized — a broken check wastes the message.
 
-**String arrays** run sequentially, each as a separate command. First failure
-stops the run.
+**2. Failures get a recovery menu, not raw stderr.** commit-mint parses biome,
+tsc, vitest/jest, eslint, and lint-staged output into structured errors, then
+lets you copy the error report to clipboard — paste straight into a coding
+agent.
 
-```ts
-export default {
-	"*.ts": ["eslint --fix", "prettier --write"],
-};
-```
+**3. Live retry.** Fix the error in another terminal, pick "Retry checks" in
+the menu — no need to exit and re-run `cmint`.
 
-**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:
-
-```ts
-export default {
-	"*.ts": (files) =>
-		files.length > 5 ? `vitest run ${files.join(" ")}` : "vitest run",
-};
-```
-
-### Glob matching
-
-- 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.
-
-### Behavior
-
-- 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 check fails, the same `parseHookErrors` pipeline that handles git
-hooks runs, and a menu appears:
-
-```
-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
-```
-
-- **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.
-
-For tsc failures specifically, the summary includes up to 3 file:line:column
-diagnostics inline, with a `+N more` line if there are more.
+Config shape details, file name patterns, and the failure menu are documented
+[below](#config-reference).
 
 ## Auto-group mode (`-a`)
 
@@ -207,6 +99,50 @@ What do you want to stage?
   Run checks
 ```
 
+## AI Agent Mode
+
+`cmint --agent` runs non-interactively with JSON output for AI coding agents.
+
+| Combination | Behavior |
+|---|---|
+| `--agent` | Auto-group, AI generates, no review, JSON output |
+| `--agent --message "msg"` | Single-commit mode, use provided message, no AI |
+| `--agent --retry` | ERROR: incompatible (exit 1) |
+| `--agent --noCheck` | Skip user-defined checks |
+| `--agent --hint "..."` | Pass hint to AI |
+| `--agent --debug` | Verbose logging to stderr |
+
+### JSON output schema
+
+The command returns a single JSON object to stdout.
+
+```json
+{"status":"success","commits":[{"message":"feat: add X","hash":"abc123","files":["src/a.ts"]}]}
+{"status":"no_changes","commits":[]}
+{"status":"failure","commits":[],"errors":["error detail"]}
+{"status":"cancelled","commits":[]}
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Generic error |
+| 2 | No changes |
+| 3 | Git error |
+| 4 | AI error |
+| 5 | Check failure |
+| 6 | Hook failure |
+
+### AI Coding Agent Integration
+
+For OpenCode or other AI coding environments, you can install cmint as a skill:
+
+```bash
+npx skills add kyubiware/commit-mint
+```
+
 ## Recovery menu
 
 When a git hook blocks the commit, commit-mint parses the output and shows:
@@ -277,6 +213,7 @@ timeout.
 | `type`           | —                    | Force commit type prefix                          |
 | `timeout`        | `10000`              | AI request timeout in ms                          |
 | `proxy`          | —                    | Proxy URL for API requests                        |
+| `--agent`       | `false`              | Headless JSON-output mode for AI agents           |
 
 API key lookup checks the env var first, then the INI file.
 
@@ -297,6 +234,126 @@ files` for the rest. In auto-group mode, lockfiles (`package-lock.json`,
 alongside their companion manifest (e.g. `package-lock.json` stays with
 `package.json`).
 
+## All flags
+
+| Flag                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `-m`, `--message`       | Use your own message instead of AI generation    |
+| `-H`, `--hint`          | Context hint to the AI (e.g. "refactor only")    |
+| `-r`, `--retry`         | Retry last failed commit (cached message)        |
+| `-N`, `--noCheck`       | Skip pre-flight checks                           |
+| `-d`, `--debug`         | Debug logging to stderr                          |
+| `--agent`               | Headless JSON mode for AI coding agents          |
+
+## Config reference
+
+### Config file names
+
+Checked in this order. First match wins.
+
+```
+.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
+```
+
+`.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`.
+
+### Config shape
+
+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.
+
+**String commands** get matched files appended as trailing arguments. Files
+with spaces in their paths are quoted automatically.
+
+```ts
+export default {
+	"*.ts": "eslint --fix", // runs `eslint --fix src/foo.ts src/bar.ts`
+};
+```
+
+**String arrays** run sequentially, each as a separate command. First failure
+stops the run.
+
+```ts
+export default {
+	"*.ts": ["eslint --fix", "prettier --write"],
+};
+```
+
+**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:
+
+```ts
+export default {
+	"*.ts": (files) =>
+		files.length > 5 ? `vitest run ${files.join(" ")}` : "vitest run",
+};
+```
+
+### Glob matching
+
+- 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.
+
+### Behavior
+
+- 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 check fails, the same `parseHookErrors` pipeline that handles git
+hooks runs, and a menu appears:
+
+```
+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
+```
+
+- **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.
+
+For tsc failures specifically, the summary includes up to 3 file:line:column
+diagnostics inline, with a `+N more` line if there are more.
+
 ## Requirements
 
 - Node.js 18+