# @super-repo/czar

> Conventional Commits parser, validator, AI suggest, sanity checks, and Ink components — one binary that replaces commitizen + commitlint.

[![NPM](https://nodei.co/npm/@super-repo/czar.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/@super-repo/czar)

[![npm version](https://img.shields.io/npm/v/@super-repo/czar.svg)](https://www.npmjs.com/package/@super-repo/czar)
[![npm downloads](https://img.shields.io/npm/dm/@super-repo/czar.svg)](https://www.npmjs.com/package/@super-repo/czar)
[![license](https://img.shields.io/npm/l/@super-repo/czar.svg)](./LICENSE)

When you commit the same change across N stack repos at once, you want one structured message that lands identically everywhere. Free-form text invites drift, and gluing `commitizen` + `commitlint` + a custom secret-scanner together to enforce structure is a lot of moving parts.

Czar (aka **commitizar** / **caesar** — three interchangeable bin names) is a single binary that parses, validates, builds, AI-suggests, and sanity-checks conventional commits. The data layer is pure (no UI, no peer deps); the CLI is interactive Ink; the sanity gate is plugin-based and ships with `.env*`-blocking, large-file, private-key, secret-scan, and envx-audit plugins out of the box.

## Getting started

```sh
pnpm add -D @super-repo/czar
```

```ts
// czar.config.ts
import { defineConfig } from '@super-repo/czar'

export default defineConfig({
  strict: true,
  shortcuts: [
    { key: 'g', label: 'quick chore', message: 'chore: quick commit' },
    { key: 'w', label: 'WIP',         message: 'chore: WIP' },
  ],
  sanity: { enabled: true, blockEnvFiles: true, detectSecrets: true },
})
```

```sh
# replace `git commit` with the interactive flow
npx czar push
# or validate a commit message non-interactively (for commit-msg hooks)
echo "feat: rotate tokens" | npx czar
```

For everything else — full schema, plugin protocol, hook recipes, AI setup — see [Docs](#docs).

## Features

- **One binary, three names** — `czar`, `commitizar`, and `caesar` all resolve to the same CLI; pick the one your fingers prefer.
- **Pure data layer** — `formatCommitMessage`, `parseCommitMessage`, `validateCommitMessage` with zero UI peer deps; embeddable in any tool.
- **Interactive Ink builder** — `CommitForm` and `CommitPreview` components drop into any Ink TUI; the CLI uses them directly.
- **AI suggest** — `--ai` generates a Conventional Commits message from your staged diff via Anthropic or OpenAI; works on the whole staged set or per-file.
- **Walk-through commits** — `czar walk` iterates every changed file and lets you commit each one individually, optionally with AI per-file.
- **Plugin-based sanity gate** — block `.env*` files, large files, private keys, and known credential patterns; bring your own `SanityPlugin` or compose with `envxAuditPlugin`.
- **Layered config** — `czar.config.{ts,js,mjs,json}` or a `czar` field in `package.json`, with `extends` and array merging.

## CLI

| Command         | What it does                                                                                |
| --------------- | ------------------------------------------------------------------------------------------- |
| `czar validate` | Validate a Conventional Commits message from a file or stdin. Default subcommand.           |
| `czar build`    | Launch the Ink form; print the formatted message to stdout on submit.                       |
| `czar push`     | Build (or accept) a message → stage → run sanity checks → commit → push.                    |
| `czar walk`     | Iterate every changed file; commit each one individually. Pair with `--ai` for suggestions. |

Full subcommand and flag reference: [docs/cli.md](./docs/cli.md).

## Comparison

| capability                       | `@super-repo/czar`        | `commitizen` (`cz-cli`)   | `commitlint`              |
| -------------------------------- | :-----------------------: | :-----------------------: | :-----------------------: |
| Interactive commit builder       | ✓ (Ink)                   | ✓ (Inquirer adapters)     | ✗                         |
| Conventional Commits validation  | ✓                         | ✗                         | ✓                         |
| AI-suggested messages            | ✓ (Anthropic / OpenAI)    | ✗                         | ✗                         |
| Per-file walk commits            | ✓                         | ✗                         | ✗                         |
| Pre-commit sanity checks         | first-class plugin system | ✗                         | ✗ (rules-only)            |
| Embeddable Ink components        | ✓                         | ✗                         | ✗                         |
| Single binary for both flows     | ✓                         | needs commitlint too      | needs commitizen too      |

Czar collapses the typical commitizen + commitlint + custom-secret-scanner setup into a single dependency with a single config file.

## Pre-commit hooks & CI

`npx czar "$1"` drops straight into a `commit-msg` hook for Husky, lefthook, simple-git-hooks, or native git. `czar push --no-push --no-stage --strict` works as a pre-push gate.

See [docs/hooks.md](./docs/hooks.md) for Husky, lefthook, simple-git-hooks, native-git, pre-push, and GitHub Actions recipes.

## Embedding the data layer

Re-use the parser, validator, and formatter inside your own tool:

```ts
import { formatCommitMessage, parseCommitMessage, validateCommitMessage } from '@super-repo/czar'

formatCommitMessage({ type: 'feat', scope: 'auth', description: 'rotate tokens', breaking: true })
// → "feat(auth)!: rotate tokens"
```

Or embed the Ink form directly — see [docs/library-api.md](./docs/library-api.md) for the full prop reference.

## Docs

Deep references and worked examples live alongside this package in [./docs/](./docs/):

- **[cli.md](./docs/cli.md)** — every subcommand, every flag, exit codes.
- **[configuration.md](./docs/configuration.md)** — full `CzarConfig` schema, discovery walk, `extends` semantics.
- **[plugins.md](./docs/plugins.md)** — the `SanityPlugin` protocol, built-in plugin reference, custom-plugin walkthrough.
- **[hooks.md](./docs/hooks.md)** — Husky / lefthook / simple-git-hooks / native-git / pre-push / GitHub Actions recipes.
- **[library-api.md](./docs/library-api.md)** — every exported function, type, and Ink component.
- **[recipes.md](./docs/recipes.md)** — replacing commitizen + commitlint, AI workflows, embedding inside another CLI.

## References

- [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) — the spec czar parses and validates against.
- [`@super-repo/envx-libs`](../envx) — secret-scanner consumed by `envxAuditPlugin` for staged-file audits.
- [`commitizen`](https://github.com/commitizen/cz-cli) and [`commitlint`](https://github.com/conventional-changelog/commitlint) — the upstream tools czar consolidates.

## License

MIT © Super-Repo contributors. See [LICENSE](./LICENSE).