···11+# If you prefer the allow list template instead of the deny list, see community template:
22+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
33+#
44+# Binaries for programs and plugins
55+*.exe
66+*.exe~
77+*.dll
88+*.so
99+*.dylib
1010+1111+# Test binary, built with `go test -c`
1212+*.test
1313+1414+# Code coverage profiles and other test artifacts
1515+*.out
1616+coverage.*
1717+*.coverprofile
1818+profile.cov
1919+2020+# Dependency directories (remove the comment below to include it)
2121+# vendor/
2222+2323+# Go workspace file
2424+go.work
2525+go.work.sum
2626+2727+# env file
2828+.env
2929+3030+# Editor/IDE
3131+# .idea/
3232+# .vscode/
+259
PROJECT.md
···11+# `storm` — Project Guide
22+33+> Internal operations and release workflow
44+55+This document outlines:
66+77+- The release lifecycle
88+- CLI integration into development workflows
99+- Distribution setup for major package managers
1010+1111+## Lifecycle
1212+1313+### Local Development
1414+1515+- Edit and test locally:
1616+1717+ ```bash
1818+ go run ./cmd/storm unreleased add --type fixed --summary "Fix diff rendering"
1919+ go run ./cmd/storm unreleased list
2020+ go run ./cmd/storm unreleased review
2121+ ```
2222+2323+- Each `.changes/*.md` entry represents one meaningful change.
2424+2525+### 2. Preparing a Release
2626+2727+1. **Generate and review**
2828+2929+ ```bash
3030+ storm generate v1.2.0 HEAD --interactive
3131+ ```
3232+3333+ - Opens a Bubble Tea UI for categorization.
3434+ - Outputs candidate `.changes/` files if confirmed.
3535+3636+2. **Verify unreleased notes**
3737+3838+ ```bash
3939+ storm unreleased list
4040+ ```
4141+4242+3. **Promote to changelog**
4343+4444+ ```bash
4545+ storm release --version 1.3.0
4646+ ```
4747+4848+ This:
4949+5050+ - Merges `.changes/*.md` into `CHANGELOG.md`
5151+ - Inserts the date
5252+ - Clears `.changes/`
5353+ - (Optional) creates an annotated Git tag
5454+5555+4. **Commit and tag**
5656+5757+ ```bash
5858+ git add CHANGELOG.md
5959+ git commit -m "Release 1.3.0"
6060+ git tag -a v1.3.0 -m "Release 1.3.0"
6161+ ```
6262+6363+### Validation
6464+6565+Before pushing:
6666+6767+```bash
6868+go test ./...
6969+go run ./cmd/storm release --dry-run
7070+```
7171+7272+Once satisfied:
7373+7474+```bash
7575+git push origin main --tags
7676+```
7777+7878+## CLI Integration in Workflows
7979+8080+`storm` is meant to sit between `git log` and `CHANGELOG.md`.
8181+Use it at the end of development cycles or integrate it into CI pipelines.
8282+8383+### Example integrations
8484+8585+#### Local Workflow
8686+8787+- Add a new `.changes` file per PR or major commit.
8888+- Review unreleased entries before each merge to `main`.
8989+- Run `storm release` when preparing a new version.
9090+9191+#### Automated Release Job (CI)
9292+9393+Example pseudo-pipeline (GitHub Actions / Drone / Woodpecker):
9494+9595+```yaml
9696+steps:
9797+ - name: Generate changelog
9898+ run: |
9999+ go install ./cmd/storm
100100+ storm release --version ${{ steps.bump.outputs.version }}
101101+ - name: Tag and push
102102+ run: |
103103+ git add CHANGELOG.md
104104+ git commit -m "Release ${{ steps.bump.outputs.version }}"
105105+ git tag -a v${{ steps.bump.outputs.version }} -m "Release ${{ steps.bump.outputs.version }}"
106106+ git push origin main --tags
107107+```
108108+109109+#### Integration with other tools
110110+111111+- **Taskfile / Justfile:** add `release` recipe calling `storm release`.
112112+- **GoReleaser:** run `storm release` in `before.hooks`.
113113+- **Custom TUI tools:** embed `internal/changeset` and `changelog` packages directly.
114114+115115+## Packaging & Distribution
116116+117117+### Homebrew (macOS / Linux)
118118+119119+#### Create a tap repo
120120+121121+Make a repo: `github.com/stormlightlabs/homebrew-tools`.
122122+123123+#### Formula template (`storm.rb`)
124124+125125+```ruby
126126+class Gostorm < Formula
127127+ desc "Git-aware changelog manager with TUI review"
128128+ homepage "https://github.com/stormlightlabs/storm"
129129+ version "1.3.0"
130130+ url "https://github.com/stormlightlabs/storm/archive/refs/tags/v1.3.0.tar.gz"
131131+ sha256 "<insert_sha256_here>"
132132+ license "MIT"
133133+134134+ depends_on "go" => :build
135135+136136+ def install
137137+ system "go", "build", *std_go_args, "./cmd/storm"
138138+ end
139139+140140+ test do
141141+ system "#{bin}/storm", "--help"
142142+ end
143143+end
144144+```
145145+146146+#### Update formula on each release
147147+148148+Automate with `goreleaser`:
149149+150150+```yaml
151151+brews:
152152+ - tap: stormlightlabs/homebrew-tools
153153+ name: storm
154154+ folder: Formula
155155+ commit_author:
156156+ name: Owais Jamil
157157+ email: owais@example.com
158158+```
159159+160160+### Chocolatey (Windows)
161161+162162+#### Create package skeleton
163163+164164+```sh
165165+tools/
166166+ chocolateyinstall.ps1
167167+ VERIFICATION.txt
168168+storm.nuspec
169169+```
170170+171171+#### `chocolateyinstall.ps1`
172172+173173+```powershell
174174+$ErrorActionPreference = 'Stop'
175175+$toolsDir = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)"
176176+$url = 'https://github.com/stormlightlabs/storm/releases/download/v1.3.0/storm_1.3.0_windows_amd64.zip'
177177+178178+Install-ChocolateyZipPackage 'storm' $url $toolsDir
179179+```
180180+181181+#### `.nuspec`
182182+183183+```xml
184184+<package>
185185+ <metadata>
186186+ <id>storm</id>
187187+ <version>1.3.0</version>
188188+ <authors>Owais Jamil</authors>
189189+ <description>Git-aware changelog manager with TUI review</description>
190190+ <licenseUrl>https://opensource.org/licenses/MIT</licenseUrl>
191191+ <projectUrl>https://github.com/stormlightlabs/storm</projectUrl>
192192+ </metadata>
193193+</package>
194194+```
195195+196196+#### Build & push
197197+198198+```bash
199199+choco pack
200200+choco push storm.1.3.0.nupkg --source https://push.chocolatey.org/
201201+```
202202+203203+### AUR
204204+205205+#### Create PKGBUILD
206206+207207+```bash
208208+pkgname=storm
209209+pkgver=1.3.0
210210+pkgrel=1
211211+pkgdesc="Git-aware changelog manager with TUI review"
212212+arch=('x86_64')
213213+url="https://github.com/stormlightlabs/storm"
214214+license=('MIT')
215215+depends=('git' 'go')
216216+source=("$url/archive/refs/tags/v${pkgver}.tar.gz")
217217+sha256sums=('SKIP')
218218+219219+build() {
220220+ cd "$srcdir/storm-$pkgver"
221221+ go build -o storm ./cmd/storm
222222+}
223223+224224+package() {
225225+ install -Dm755 storm "$pkgdir/usr/bin/storm"
226226+}
227227+```
228228+229229+#### Submit
230230+231231+Clone AUR repo:
232232+233233+```bash
234234+git clone ssh://aur@aur.archlinux.org/storm.git
235235+cp PKGBUILD storm/
236236+cd storm
237237+makepkg --printsrcinfo > .SRCINFO
238238+git add .
239239+git commit -m "Add storm v1.3.0"
240240+git push
241241+```
242242+243243+## Summary
244244+245245+| Step | Action | Output |
246246+| ---- | ---------------------------------------------- | --------------------------- |
247247+| 1 | `storm generate v1.2.0 HEAD --interactive` | Draft unreleased notes |
248248+| 2 | `storm release --version 1.3.0` | Updated `CHANGELOG.md` |
249249+| 3 | `git tag -a v1.3.0` | Annotated release tag |
250250+| 4 | `goreleaser release --clean` | Builds + publishes binaries |
251251+| 5 | Update tap / choco / AUR formulas | Public distribution |
252252+253253+## Maintenance Notes
254254+255255+- Keep `.changes/` entries atomic and descriptive.
256256+- Avoid retroactive changelog edits outside releases.
257257+- Tag every release in Git with an exact semantic version (`vX.Y.Z`).
258258+- Ensure TUI remains optional (disable automatically in CI).
259259+- Treat changelog generation as a testable unit — not a side effect.
+117
README.md
···11+# `storm`
22+33+> A Go-based changelog manager built for clarity, speed, and interaction.
44+55+## Goals
66+77+- Use Git as a data source, not a dependency.
88+- Store unreleased notes locally (`.changes/*.md`) in a simple, editable format.
99+- Provide a terminal UI for reviewing commits and changes interactively.
1010+- Generate Markdown in strict [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
1111+1212+## Design Overview
1313+1414+### Core Packages
1515+1616+```sh
1717+.
1818+├── cmd
1919+├── internal
2020+│ ├── gitlog # Parse and structure commit history via `go-git`
2121+│ ├── diff # Minimal line diff for display and review
2222+│ ├── changeset # Manage `.changes/*.md` files
2323+│ ├── changelog # Build and update `CHANGELOG.md` sections
2424+│ ├── tui # Bubble Tea–based interactive interface
2525+│ └── style # Centralized Lip Gloss palette and formatting
2626+├── PROJECT.md
2727+└── README.md
2828+```
2929+3030+## Command Model
3131+3232+### Unreleased Changes
3333+3434+```sh
3535+storm unreleased add --type added --scope cli --summary "Add changelog command"
3636+storm unreleased list
3737+storm unreleased review
3838+```
3939+4040+Adds or reviews pending `.changes/*.md` entries.
4141+4242+### Generate From Git
4343+4444+```sh
4545+storm generate <from> <to> [--interactive]
4646+```
4747+4848+Pulls commits between refs, categorizes them by prefix, and optionally opens an interactive review.
4949+5050+### Release
5151+5252+```sh
5353+storm release --version 1.3.0 [--tag]
5454+```
5555+5656+Merges `.changes/*.md` into the changelog, writes a new section, and optionally tags the repository.
5757+5858+## Architecture
5959+6060+- **Git integration:** Uses `go-git` for commit history and tag resolution — no shell calls.
6161+- **Diffing:** Custom lightweight diff engine for readable line-by-line output.
6262+- **Unreleased storage:** Simple Markdown files with YAML frontmatter (no external formats).
6363+- **Interactive mode:** Bubble Tea model for categorizing and confirming changes.
6464+- **Output:** Always produces Keep a Changelog–compliant Markdown.
6565+6666+## Development Guidance
6767+6868+1. Composable
6969+ Each subsystem (`diff`, `gitlog`, `tui`, etc.) should work standalone and be callable from tests or other Go programs.
7070+2. Frontmatter
7171+7272+ ```yaml
7373+ type: added
7474+ scope: cli
7575+ summary: Add changelog command
7676+ ```
7777+7878+3. Consistent Palette
7979+8080+ | Type | Color |
8181+ | -------- | --------- |
8282+ | Added | `#10b981` |
8383+ | Changed | `#0ea5e9` |
8484+ | Fixed | `#f43f5e` |
8585+ | Removed | `#f59e0b` |
8686+ | Security | `#9333ea` |
8787+8888+4. Commands should chain naturally and script cleanly:
8989+9090+ ```sh
9191+ storm unreleased list --json
9292+ storm generate --since v1.2.0 --interactive
9393+ storm release --version 1.3.0
9494+ ```
9595+9696+5. Tests
9797+ - Research testing bubbletea programs
9898+ - Use golden files for diff/changelog output.
9999+ - Use in-memory `go-git` repos in unit tests.
100100+101101+## Roadmap
102102+103103+| Phase | Deliverable |
104104+| ----- | ---------------------------------------------- |
105105+| 1 | Core CLI (`generate`, `unreleased`, `release`) |
106106+| 2 | Git integration and commit parsing |
107107+| 3 | Diff engine and styling |
108108+| 4 | `.changes` storage and parsing |
109109+| 5 | Interactive TUI |
110110+| 6 | Keep a Changelog writer |
111111+| 7 | Git tagging and CI integration |
112112+113113+## Notes
114114+115115+- No external dependencies beyond `cobra`, `go-git`, `bubbletea`, `lipgloss`, and `yaml.v3`.
116116+- Keep the workflow simple and reproducible so changelogs can be deterministically derived from local data.
117117+- Make sure interactive sessions degrade gracefully in non-TTY environments.