# Integrations

This document shows recommended integration patterns for `smart-commit CLI` in shell-first automation.

If you have not run the CLI manually yet, start with [`getting-started.md`](./getting-started.md) first. Integration is much easier after you have already verified `config resolve` and `bridge --dry-run`.

## Principles

- Prefer `bridge` as the enforcement entrypoint for hooks and agents
- Prefer `report generate` as the reporting entrypoint for scheduled or post-task automation
- Parse JSON output instead of scraping stderr
- Gate logic on `schemaVersion`, `status`, and `error.code`
- Keep hook integrations in `--no-commit --no-push` mode unless you explicitly want the CLI to own Git side effects

## Husky

Recommended use:

- Use `pre-commit` to review staged changes before Git creates a commit
- Keep Husky in review-only mode with `--no-commit --no-push`
- Let Git itself continue to own the actual commit lifecycle

Suggested layout:

- Wrapper script: [`examples/hooks/smart-commit-bridge.sh`](../examples/hooks/smart-commit-bridge.sh)
- Husky example: [`examples/hooks/husky-pre-commit.sh`](../examples/hooks/husky-pre-commit.sh)

Example:

```sh
cp examples/hooks/husky-pre-commit.sh .husky/pre-commit
chmod +x .husky/pre-commit
```

## Cursor Hook

Cursor hook registration details can vary by version, so the most stable approach is:

- register a shell script as the hook target
- let the shell script invoke `smart-commit bridge`
- consume JSON output if your hook host supports it

Suggested wrapper:

- [`examples/hooks/cursor-bridge-wrapper.sh`](../examples/hooks/cursor-bridge-wrapper.sh)

Recommended behavior:

- run before commit or before custom repo actions
- use `--no-commit --no-push`
- inspect `status`
  `ready` and `passed` mean continue
  `blocked` means stop and surface the review reason
  `error` means stop and surface the runtime or config problem

## External Agent

For custom agents, CI bots, or local automation runners:

- spawn `smart-commit bridge` or `smart-commit report generate`
- parse stdout as JSON
- check `schemaVersion`
- branch behavior on `status`

Example consumers:

- [`examples/agent/bridge-agent.mjs`](../examples/agent/bridge-agent.mjs)
- [`examples/agent/report-agent.mjs`](../examples/agent/report-agent.mjs)

## Exit Codes

- `0`: success
- `2`: blocked business decision, such as review blocked or auto-stage dry-run warning
- `3`: config error
- `4`: runtime error

JSON payloads should remain the primary contract. Exit codes are best used as a coarse first filter.

## Recommended Rollout

1. Start with `smart-commit config resolve` in CI or local scripts to verify merged config.
2. Wire `bridge` into Husky or Cursor hook in `--no-commit --no-push` mode.
3. Enable `passHistory`.
4. Add `report generate` in scheduled automation or agent workflows.
5. Optionally enable AI reporting with local fallback after the local flow is already stable.