@kud/ai-conventional-commit-cli 0.4.0 → 0.4.2

package/README.md

@@ -1,145 +1,183 @@
 # ai-conventional-commit
 
-Opinionated, style-aware AI assistant for crafting, splitting, and refining git commit messages via the local `opencode` CLI. Uses your installed `opencode` models (default `github-copilot/gpt-5`).
+<p align="center">
+  <b>AI‑assisted, style‑aware Conventional Commit generator & splitter</b><br/>
+  Opinionated CLI that learns your repo's commit style and produces polished single or multi commits – safely, quickly, repeatably.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@kud/ai-conventional-commit-cli"><img alt="npm version" src="https://img.shields.io/npm/v/%40kud%2Fai-conventional-commit-cli?color=brightgreen" /></a>
+  <a href="https://www.npmjs.com/package/@kud/ai-conventional-commit-cli"><img alt="downloads" src="https://img.shields.io/npm/dm/%40kud%2Fai-conventional-commit-cli" /></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/%40kud%2Fai-conventional-commit-cli" /></a>
+  <a href="https://nodejs.org"><img alt="node version" src="https://img.shields.io/node/v/%40kud%2Fai-conventional-commit-cli" /></a>
+  <a href="https://www.conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg" /></a>
+</p>
+
+> TL;DR: Stage your changes, run `ai-conventional-commit` (or `split` for multiple commits), accept, done. Add `--gitmoji` if you like emoji. Refine later with `refine`.
+
+---
+
+## Table of Contents
+
+- [Why](#why)
+- [Features](#features)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Command Reference](#command-reference)
+- [Examples](#examples)
+- [Gitmoji Modes](#gitmoji-modes)
+- [Privacy Modes](#privacy-modes)
+- [Configuration](#configuration-aiccrc)
+- [Refinement Workflow](#refinement-workflow)
+- [Plugin API](#plugin-api)
+- [Title Formatting Helper](#title-formatting-helper)
+- [Security](#security)
+- [Roadmap Ideas](#roadmap-ideas)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Why
 
-Manual commit messages are noisy, inconsistent, and often miss context. ai-conventional-commit inspects your staged diff, learns your repo's commit style, and produces Conventional Commit messages (single or split) with explanations—optionally decorated with gitmoji.
+Manual commit messages are often noisy, inconsistent, and context‑poor. This tool:
 
-## Key Features
+- Learns _your_ recent commit style (length, scopes, emoji, prefixes)
+- Respects Conventional Commits & normalizes edge cases
+- Proposes **multi‑commit splits** when changes are logically separable
+- Lets you iteratively refine wording – without rewriting history prematurely
 
-- Style fingerprinting (average title length, scope usage ratio, gitmoji ratio, top prefixes)
-- Single (`ai-conventional-commit` / `ai-conventional-commit generate`) or multi-commit planning (`ai-conventional-commit split`)
-- Refinement workflow (`ai-conventional-commit refine`) to iteratively tweak a prior result
-- Gitmoji modes: `--gitmoji[-pure]` (plain adds emoji + type, pure removes type)
+## Features
 
-- Privacy tiers governing diff detail sent to model
-- Title normalization + guardrails (length, conventional schema, secret heuristic)
-- Plugin system (transform + validate phases)
-- Session persistence for later refinement (`.git/.aicc-cache/last-session.json`)
-- Deterministic mock provider mode for tests / CI
+| Category           | Highlights                                                               |
+| ------------------ | ------------------------------------------------------------------------ |
+| Style Intelligence | Style fingerprint (avg length, scope ratio, gitmoji usage, top prefixes) |
+| Generation Modes   | Single, multi‑commit planning (`split`), iterative refinement (`refine`) |
+| Commit Splitting   | Real selective staging per proposed commit (no fake plan output)         |
+| Gitmoji            | Standard / emoji+type / pure emoji modes                                 |
+| Guardrails         | Title normalization, Conventional syntax enforcement, length checks      |
+| Privacy            | Tiered diff detail (low / medium / high)                                 |
+| Plugins            | Transform & validate hooks over candidates                               |
+| Determinism        | Mock provider for CI & tests (`AICC_DEBUG_PROVIDER=mock`)                |
+| UX                 | Timing output, scoped prompts, animated header (optional)                |
 
-## Install (Dev)
+## Install
+
+Global (recommended for daily use):
 
 ```bash
-npm install
-npm run build
-npm link
-# then
-ai-conventional-commit --help
+npm install -g @kud/ai-conventional-commit-cli
 ```
 
-### Optional Alias (Short Name)
-
-If you prefer a shorter alias, add this to your shell profile:
+Local + npx:
 
 ```bash
-alias aicc='ai-conventional-commit'
+npm install --save-dev @kud/ai-conventional-commit-cli
+npx ai-conventional-commit --help
 ```
 
-## Publishing
-
-A build is automatically produced on `npm publish` via the `prepublishOnly` script so you can simply bump the version and run:
+From source (dev):
 
 ```bash
-npm publish
+npm install
+npm run build
+npm link
+ai-conventional-commit --help
 ```
 
-Only `dist`, `README.md`, and `LICENSE` are included in the published package (see the `files` field). If you need to test the packaging result first:
+Optional shell alias:
 
 ```bash
-npm publish --dry-run
+alias aicc='ai-conventional-commit'
 ```
 
 ## Quick Start
 
 ```bash
-# Stage your changes
+# Stage changes
 git add .
+
 # Generate a single commit suggestion
 ai-conventional-commit
-# Multi-commit proposal (interactive confirm)
+
+# Propose multiple commits (interactive confirm + real selective staging)
 ai-conventional-commit split
-# Use gitmoji with emoji+type form
+
+# Add emoji decorations
 ai-conventional-commit --gitmoji
-# Pure gitmoji (emoji: subject)
-ai-conventional-commit --gitmoji-pure
 
+# Pure emoji style (emoji: subject)
+ai-conventional-commit --gitmoji-pure
 
-# Refine previous session’s first commit making it shorter
+# Refine previous session's first commit (shorter wording)
 ai-conventional-commit refine --shorter
 ```
 
-## Timed Output
+## Command Reference
+
+| Command                           | Purpose                                     |
+| --------------------------------- | ------------------------------------------- |
+| `ai-conventional-commit`          | Generate single commit suggestion (default) |
+| `ai-conventional-commit generate` | Explicit alias of root                      |
+| `ai-conventional-commit split`    | Propose & execute multiple commits          |
+| `ai-conventional-commit refine`   | Refine last session (or indexed) commit     |
+
+Helpful flags:
+
+- `--gitmoji` / `--gitmoji-pure`
+- `--model <provider/name>` (override)
+- `--scope <scope>` (refine)
+- `--shorter` / `--longer`
+- `--emoji` (add appropriate emoji in refine)
+
+## Examples
+
+### Single Commit (standard)
+
+```
+feat(api): add pagination metadata to list endpoint
+
+Adds `total`, `limit`, `offset` fields to response; updates tests.
+```
 
-Final success lines now include count + duration, e.g.:
+### Split Workflow (illustrative)
 
 ```
-└ ✨ commit created in 850ms.
-└ ✨ 3 commits created in 2.4s.
+1. refactor(parser): simplify token scanning (no behavior change)
+2. feat(parser): support negated glob segments
+3. test(parser): add cases for brace + extglob combos
 ```
 
-Durations under 100ms show raw milliseconds; otherwise one decimal second precision.
+Each proposed commit is _actually_ staged & committed with only its files.
 
-## Commands
+### Refinement
 
-| Command                           | Purpose                                     |
-| --------------------------------- | ------------------------------------------- |
-| `ai-conventional-commit`          | Generate single commit suggestion (default) |
-| `ai-conventional-commit generate` | Same as root (explicit)                     |
-| `ai-conventional-commit split`    | Propose multiple commits (plan)             |
-| `ai-conventional-commit refine`   | Refine last session result                  |
-
-### Help Output
-
-```text
-$ ai-conventional-commit --help
-ai-conventional-commit vX.Y.Z
-
-Usage:
-  ai-conventional-commit [generate] [options]   Generate a commit (default)
-  ai-conventional-commit split [options]        Propose multiple commits
-  ai-conventional-commit refine [options]       Refine last or indexed commit
-
-Global Options:
-  -m, --model <provider/name>   Override model provider/name
-  --gitmoji[-pure]              Gitmoji modes (emoji + type / pure emoji only)
-  -h, --help                    Show this help
-  -V, --version                 Show version
-
-Refine Options:
-  --shorter / --longer          Adjust message length
-  --scope <scope>               Add or replace scope
-  --emoji                       Add suitable gitmoji
-  --index <n>                   Select commit index
-
-Examples:
-  ai-conventional-commit --gitmoji
-  ai-conventional-commit split --max 3
-  ai-conventional-commit refine --scope api --emoji
+```
+$ ai-conventional-commit refine --scope cli --shorter
+✔ Updated: feat(cli): add split timing output
 ```
 
 ## Gitmoji Modes
 
-| Mode               | Example                   | Notes                                |
-| ------------------ | ------------------------- | ------------------------------------ |
-| standard (default) | `feat: add search box`    | No emoji decoration                  |
-| gitmoji            | `✨ feat: add search box` | Emoji + conventional type retained   |
-| gitmoji-pure       | `✨: add search box`      | Type removed, emoji acts as category |
+| Mode         | Example                   | Notes                                |
+| ------------ | ------------------------- | ------------------------------------ |
+| standard     | `feat: add search box`    | No emoji                             |
+| gitmoji      | `✨ feat: add search box` | Emoji + type retained                |
+| gitmoji-pure | `✨: add search box`      | Type removed; emoji acts as category |
 
-Enable via CLI flags (`--gitmoji` or `--gitmoji-pure`, shorthand `--gitmoji[-pure]`) or config (`gitmoji: true`, `gitmojiMode`).
+Enable via CLI flags or config (`gitmoji: true`, `gitmojiMode`).
 
 ## Privacy Modes
 
-| Mode   | Data Sent to Model                                                    |
-| ------ | --------------------------------------------------------------------- |
-| low    | Hunk headers + first 40 changed/context lines per hunk (may truncate) |
-| medium | File + hunk hash + line counts + function context only                |
-| high   | File names with aggregate add/remove counts only                      |
+| Mode   | Data Sent                                              |
+| ------ | ------------------------------------------------------ |
+| low    | Hunk headers + first 40 changed/context lines per hunk |
+| medium | File + hunk hash + line counts + function context only |
+| high   | File names + aggregate add/remove counts only          |
+
+Pick based on sensitivity; higher privacy may reduce stylistic richness.
 
 ## Configuration (.aiccrc)
 
-Uses cosmiconfig; supports JSON, YAML, etc. Example:
+Resolves via cosmiconfig (JSON/YAML/etc). Example:
 
 ```json
 {
@@ -147,32 +185,20 @@ Uses cosmiconfig; supports JSON, YAML, etc. Example:
   "privacy": "low",
   "gitmoji": true,
   "gitmojiMode": "gitmoji",
-
   "styleSamples": 120,
   "plugins": ["./src/sample-plugin/example-plugin.ts"],
   "maxTokens": 512
 }
 ```
 
-### Environment Overrides
+Environment overrides (prefix `AICC_`):
+`MODEL`, `PRIVACY`, `STYLE_SAMPLES`, `GITMOJI`, `MAX_TOKENS`, `VERBOSE`, `MODEL_TIMEOUT_MS`, `DEBUG`, `PRINT_LOGS`, `DEBUG_PROVIDER=mock`.
 
-(Note: Environment variable prefix remains `AICC_` for backward compatibility.)
-
-- `AICC_MODEL`
-- `AICC_PRIVACY`
-- `AICC_STYLE_SAMPLES`
-- `AICC_GITMOJI` ("true")
-- `AICC_MAX_TOKENS`
-- `AICC_VERBOSE`
-- `AICC_MODEL_TIMEOUT_MS`
-- `AICC_DEBUG` (provider debug logs)
-- `AICC_PRINT_LOGS` (stream model raw output)
-- `AICC_DEBUG_PROVIDER=mock` (deterministic JSON response)
-
-## Conventional Commits Enforcement
+## Refinement Workflow
 
-Types: feat, fix, chore, docs, refactor, test, ci, perf, style, build, revert, merge, security, release.
-Malformed titles are auto-normalized (fallback to `chore:`) before gitmoji formatting.
+1. Generate (`ai-conventional-commit` or `split`) – session cached under `.git/.aicc-cache/last-session.json`.
+2. Run `refine` with flags (`--shorter`, `--longer`, `--scope=ui`, `--emoji`).
+3. Accept or reject; refined output does _not_ auto‑amend history until you use it.
 
 ## Plugin API
 
@@ -194,25 +220,29 @@ interface Plugin {
 }
 ```
 
-Register via `plugins` array. Transform runs once on candidate list; validate runs per chosen candidate before commit.
+Register via `plugins` array. `transform` runs once over the candidate list; `validate` runs per chosen candidate before commit.
 
-## Refinement Workflow
-
-1. Generate (`ai-conventional-commit` or `ai-conventional-commit split`) – session stored.
-2. Run `ai-conventional-commit refine` with flags (`--shorter`, `--longer`, `--scope=ui`, `--emoji`).
-3. Accept or reject refined candidate (does not auto-amend existing git history; just updates session cache for subsequent refinement or manual use).
-
-## Testing & Mocking
+### Example Plugin (lightweight scope normalizer)
 
-Use `AICC_DEBUG_PROVIDER=mock` to bypass model invocation and get a deterministic single commit JSON payload for faster tests / CI.
+```ts
+export default {
+  name: 'scope-normalizer',
+  transformCandidates(cands) {
+    return cands.map((c) => ({
+      ...c,
+      title: c.title.replace('(UI)', '(ui)'),
+    }));
+  },
+};
+```
 
 ## Title Formatting Helper
 
-All gitmoji + normalization logic centralized in `src/title-format.ts` (`formatCommitTitle`). Ensures consistent application across generate, split, and refine flows; tests in `test/title-format.test.ts`.
+All gitmoji + normalization logic: `src/title-format.ts` (`formatCommitTitle`). Tested in `test/title-format.test.ts`.
 
 ## Security
 
-Lightweight heuristic secret scan on body; pair with a dedicated scanner (e.g., gitleaks) for stronger assurance.
+Lightweight heuristic secret scan of commit body (add/removed lines) – not a substitute for dedicated scanners (e.g. gitleaks). Pair with your existing pipelines.
 
 ## Roadmap Ideas
 
@@ -229,7 +259,7 @@ PRs welcome. Please:
 
 - Keep dependencies minimal
 - Add tests for new formatting or parsing logic
-- Feature-flag experimental behavior
+- Feature‑flag experimental behavior
 
 ## License
 

package/dist/index.js

@@ -1134,7 +1134,7 @@ async function loadConfig(cwd = process.cwd()) {
 // package.json
 var package_default = {
   name: "@kud/ai-conventional-commit-cli",
-  version: "0.4.0",
+  version: "0.4.2",
   type: "module",
   description: "Opinionated, style-aware AI assistant for crafting and splitting git commits (opencode-based, provider-agnostic).",
   bin: {
@@ -1192,7 +1192,15 @@ var package_default = {
   engines: {
     node: ">=18.17"
   },
-  license: "MIT"
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/kud/ai-conventional-commit-cli.git"
+  },
+  bugs: {
+    url: "https://github.com/kud/ai-conventional-commit-cli/issues"
+  },
+  homepage: "https://github.com/kud/ai-conventional-commit-cli#readme"
 };
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kud/ai-conventional-commit-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Opinionated, style-aware AI assistant for crafting and splitting git commits (opencode-based, provider-agnostic).",
   "bin": {
@@ -58,5 +58,13 @@
   "engines": {
     "node": ">=18.17"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kud/ai-conventional-commit-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kud/ai-conventional-commit-cli/issues"
+  },
+  "homepage": "https://github.com/kud/ai-conventional-commit-cli#readme"
 }