1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# AGENTS.md
 8
 9This file provides guidance to AI coding agents when working with code in this repository.
10
11## Development Commands
12
13- **Build**: `just build` (outputs binary as `formatted-commit`)
14- **Run during development**: `just run [flags]`
15- **Format code**: `just fmt`
16- **Update dependencies**: `go mod tidy`
17- **Test**: `go test ./...`
18
19Example usage:
20
21```bash
22just run -t feat -m "add validation" -T "Co-authored-by: Name <email>"
23```
24
25## Project Purpose
26
27This is a CLI tool that formats git commit messages according to Conventional Commits specification and pipes them directly to `git commit -F -`. It enforces:
28
291. Subject length: max 50 characters in format `type(scope): message`
302. Body wrapping: strictly 72 columns using Markdown formatter
313. Trailer validation: follows git's trailer specification
32
33## Architecture
34
35Single-file CLI application (`main.go`) using:
36
37- **cobra**: CLI framework for flags and commands
38- **fang**: Charmbracelet's execution wrapper (provides version handling, etc.)
39- Future: Will need a Markdown formatter for body text (likely from Charmbracelet ecosystem based on dependencies)
40
41## Critical Implementation Details
42
43### Subject Validation (50 char limit)
44
45The subject is constructed as `type(scope): message` or `type: message` (when scope is empty). Breaking changes add a `!` after the type/scope like `type(scope)!: message`.
46
47When validation fails, clearly mark where the subject exceeds 50 characters in error output.
48
49### Body Formatting
50
51The body (`-b` flag) must be:
52
531. Sanitised because it should only be basic text and bullets
542. Formatted as Markdown, properly wrapping bullets with hanging indents on
55   following lines like this
563. Strictly wrapped to 72 columns using a pure-Go formatter
574. Separated from subject by one blank line
585. Separated from trailers by one blank line
59
60### Trailer Formatting (Critical)
61
62Trailers follow git's specification precisely:
63
64- Format: `Key: value` (newline-delimited pairs)
65- No whitespace before or inside the key
66- Any number of spaces/tabs allowed between key and separator `:`
67- Values can be multiline with continuation lines starting with whitespace (RFC 822 folding)
68- The trailer group must be:
69  - At the end of input, OR
70  - The last non-whitespace lines before a line starting with `---`
71  - Preceded by one or more empty/whitespace-only lines
72
73Example valid trailer:
74
75```
76Co-authored-by: This is a very long value, with spaces and
77  newlines in it.
78```
79
80### Flag Nuance
81
82- `-B` / `--breaking`: Boolean flag for breaking changes (adds `!` to subject)
83- `-b` / `--body`: String flag for commit body text
84- `-T` / `--trailer`: Repeatable flag for trailers
85
86### Final Output
87
88The formatted commit message must be piped to `git commit -F -` to read from stdin.