@releasekit/notes 0.3.0 → 0.4.0

package/docs/llm-providers.md

@@ -0,0 +1,246 @@
+# LLM Providers
+
+`@releasekit/notes` can use an LLM to enhance changelog entries, generate summaries, or produce prose release notes. All LLM configuration lives under `notes.releaseNotes.llm` in `releasekit.config.json`.
+
+## Supported Providers
+
+| Provider key | Service | Auth |
+|---|---|---|
+| `openai` | OpenAI (GPT models) | `OPENAI_API_KEY` |
+| `anthropic` | Anthropic (Claude models) | `ANTHROPIC_API_KEY` |
+| `ollama` | Ollama (local models) | None |
+| `openai-compatible` | Any OpenAI-compatible endpoint | Varies |
+
+---
+
+## Storing API Keys
+
+Use the `auth` subcommand to store API keys securely in `~/.config/releasekit/auth.json`:
+
+```bash
+# Interactive prompt
+releasekit-notes auth openai
+releasekit-notes auth anthropic
+
+# Pass key directly
+releasekit-notes auth openai --key sk-...
+```
+
+Alternatively, set the provider's environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). Environment variables take precedence over stored keys.
+
+---
+
+## Provider Setup
+
+### OpenAI
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "tasks": { "enhance": true }
+      }
+    }
+  }
+}
+```
+
+Set `OPENAI_API_KEY` or run `releasekit-notes auth openai`.
+
+Recommended models: `gpt-4o-mini` (fast, cheap), `gpt-4o` (higher quality).
+
+### Anthropic
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "anthropic",
+        "model": "claude-haiku-4-5",
+        "tasks": { "releaseNotes": true }
+      }
+    }
+  }
+}
+```
+
+Set `ANTHROPIC_API_KEY` or run `releasekit-notes auth anthropic`.
+
+Recommended models: `claude-haiku-4-5` (fast), `claude-sonnet-4-5` (balanced).
+
+### Ollama (local)
+
+Ollama runs entirely on your machine — no API key required.
+
+```bash
+# Pull a model first
+ollama pull llama3.2
+```
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "ollama",
+        "model": "llama3.2",
+        "tasks": { "enhance": true }
+      }
+    }
+  }
+}
+```
+
+Ollama defaults to `http://localhost:11434`. Override with `baseURL` if needed.
+
+### OpenAI-Compatible Endpoint
+
+For self-hosted or third-party OpenAI-compatible APIs (LM Studio, vLLM, Azure OpenAI, etc.):
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "openai-compatible",
+        "model": "mistral-7b-instruct",
+        "baseURL": "http://localhost:1234/v1",
+        "tasks": { "enhance": true }
+      }
+    }
+  }
+}
+```
+
+Set `baseURL` to the endpoint's base path. If the endpoint requires authentication, set `apiKey` in the config or store it with `releasekit-notes auth openai-compatible`.
+
+---
+
+## LLM Tasks
+
+Tasks are configured under `llm.tasks`. Multiple tasks can be enabled simultaneously.
+
+### `enhance`
+
+Rewrites each changelog entry description to be clearer and more user-facing.
+
+**Input:** `"fix: npe in auth middleware when token is null"`
+**Output:** `"Fixed a crash that could occur during authentication when no token was present"`
+
+```json
+{ "tasks": { "enhance": true } }
+```
+
+Entry descriptions are processed in parallel (default concurrency: 3). Adjust with `concurrency`:
+
+```json
+{ "concurrency": 5 }
+```
+
+### `summarize`
+
+Generates a one-paragraph summary of the entire release, added to the template context as `enhanced.summary`.
+
+```json
+{ "tasks": { "summarize": true } }
+```
+
+### `categorize`
+
+Groups entries into user-friendly categories rather than conventional commit types. The result is available in templates as `enhanced.categories`.
+
+```json
+{ "tasks": { "categorize": true } }
+```
+
+Provide category hints for better grouping:
+
+```json
+{
+  "tasks": { "categorize": true },
+  "categories": [
+    { "name": "New Features", "description": "New user-facing functionality" },
+    { "name": "Bug Fixes", "description": "Corrections to existing behaviour" },
+    { "name": "Under the Hood", "description": "Internal changes users may not notice" }
+  ]
+}
+```
+
+### `releaseNotes`
+
+Generates complete prose release notes for the version — suitable for a GitHub release body. Available in the pipeline result as `releaseNotes` and used automatically when `publish.githubRelease.body` is set to `"releaseNotes"`.
+
+```json
+{ "tasks": { "releaseNotes": true } }
+```
+
+You do not need `mode` or `file` configured for this task — the generated text is passed through the pipeline even without file output.
+
+---
+
+## Prompt Customisation
+
+Override the built-in prompt instructions or templates for any task. Keys are task names.
+
+### Custom instructions
+
+Append extra instructions to the built-in prompt:
+
+```json
+{
+  "llm": {
+    "prompts": {
+      "instructions": {
+        "enhance": "Write in a friendly tone for non-technical users. Keep entries under 15 words.",
+        "releaseNotes": "Start with a one-sentence headline, then group changes by theme."
+      }
+    }
+  }
+}
+```
+
+### Full prompt template override
+
+Replace the entire prompt for a task. The string is sent to the LLM verbatim — no placeholder substitution is applied.
+
+```json
+{
+  "llm": {
+    "prompts": {
+      "templates": {
+        "enhance": "You are a technical writer. Rewrite the changelog entry below as a single, concise sentence in plain English. Return only the rewritten text, nothing else."
+      }
+    }
+  }
+}
+```
+
+---
+
+## CLI Flags
+
+LLM options can also be set via CLI flags without a config file:
+
+```bash
+releasekit-notes \
+  --llm-provider anthropic \
+  --llm-model claude-haiku-4-5 \
+  --llm-tasks enhance,release-notes \
+  --input version-output.json
+```
+
+Use `--no-llm` to disable LLM processing even when it is configured:
+
+```bash
+releasekit-notes --no-llm
+```
+
+Use `--no-release-notes` to disable release notes entirely (including LLM):
+
+```bash
+releasekit-notes --no-release-notes
+```

package/docs/monorepo.md

@@ -0,0 +1,124 @@
+# Monorepo Support
+
+`@releasekit/notes` can write changelogs and release notes at the repo root, inside each package directory, or both — controlled independently for changelog and release notes output.
+
+## Output Modes
+
+| Mode | Changelog written to | Release notes written to |
+|------|---------------------|--------------------------|
+| `"root"` | `<repo-root>/CHANGELOG.md` | `<repo-root>/RELEASE_NOTES.md` |
+| `"packages"` | `packages/<name>/CHANGELOG.md` (each package) | `packages/<name>/RELEASE_NOTES.md` |
+| `"both"` | Both root and per-package | Both root and per-package |
+
+Set `mode` on `changelog` and `releaseNotes` independently:
+
+```json
+{
+  "notes": {
+    "changelog": { "mode": "packages" },
+    "releaseNotes": { "mode": "root" }
+  }
+}
+```
+
+---
+
+## Root Changelog (aggregated)
+
+In `"root"` or `"both"` mode, the root changelog aggregates entries from all packages. Packages with a `@scope/` prefix include the package name in the version header:
+
+```markdown
+## [@myorg/core@2.0.0] — 2026-03-15
+
+### Added
+- New streaming API
+
+## [utils@1.1.0] — 2026-03-15
+
+### Fixed
+- Memory leak in event handler
+```
+
+Unscoped packages omit the name:
+
+```markdown
+## [2.0.0] — 2026-03-15
+```
+
+---
+
+## Per-Package Changelogs
+
+In `"packages"` or `"both"` mode, a separate changelog is written inside each package directory. The path is determined by the package's location in the workspace.
+
+Custom file name applies to all packages:
+
+```json
+{
+  "notes": {
+    "changelog": { "mode": "packages", "file": "CHANGES.md" }
+  }
+}
+```
+
+---
+
+## CLI Flags
+
+Use `--changelog-mode` / `--release-notes-mode` to override config:
+
+```bash
+# Root changelog only
+releasekit-notes --changelog-mode root
+
+# Per-package changelogs
+releasekit-notes --changelog-mode packages
+
+# Both outputs
+releasekit-notes --changelog-mode both
+
+# Use --monorepo as a shorthand (applies to both outputs)
+releasekit-notes --monorepo packages
+```
+
+When `--monorepo` is set, it applies to both `changelog` and `releaseNotes` modes. Explicit `--changelog-mode` or `--release-notes-mode` flags take priority over `--monorepo` when both are present.
+
+---
+
+## Monorepo Path Configuration
+
+Package locations are detected automatically from your workspace configuration (`pnpm-workspace.yaml`, `package.json` workspaces). To override root or packages directory paths, use the top-level `monorepo` config:
+
+```json
+{
+  "monorepo": {
+    "rootPath": ".",
+    "packagesPath": "packages"
+  },
+  "notes": {
+    "changelog": { "mode": "both" }
+  }
+}
+```
+
+---
+
+## LLM with Monorepo
+
+LLM tasks run per-package. Each package's entries are processed independently. With concurrency set, multiple packages can be processed in parallel:
+
+```json
+{
+  "notes": {
+    "changelog": { "mode": "packages" },
+    "releaseNotes": {
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "concurrency": 5,
+        "tasks": { "enhance": true }
+      }
+    }
+  }
+}
+```

package/docs/templates.md

@@ -0,0 +1,204 @@
+# Templates
+
+`@releasekit/notes` supports custom templates for both changelog and release notes output. Templates can be single files or composable directory layouts, and can use Liquid, Handlebars, or EJS.
+
+## Built-in Templates
+
+| Name | Engine | Default for |
+|------|--------|-------------|
+| `keep-a-changelog` | Liquid | Changelog (default) |
+| `angular` | Handlebars | — |
+| `github-release` | EJS | — |
+
+The default `keep-a-changelog` template produces [Keep a Changelog](https://keepachangelog.com)-formatted output. Switch to a different built-in via the `engine` option or use `--template` / `--engine` on the CLI.
+
+---
+
+## Custom Templates
+
+### Single-file template
+
+Pass a path to any single template file:
+
+```bash
+releasekit-notes --template ./my-changelog.liquid
+```
+
+```json
+{
+  "notes": {
+    "changelog": {
+      "templates": { "path": "./my-changelog.liquid" }
+    }
+  }
+}
+```
+
+The file receives the full [Document context](#document-context) and must render the complete changelog document.
+
+### Composable directory layout
+
+Pass a directory containing named template files. Each file renders a different level of the document:
+
+```
+templates/
+├── document.liquid    # Outer document wrapper (receives DocumentContext)
+├── version.liquid     # One version block (receives TemplateContext)
+└── entry.liquid       # One changelog entry (receives ChangelogEntry)
+```
+
+```bash
+releasekit-notes --template ./templates/
+```
+
+All three files are optional — omit any you don't need to customise, and the built-in for that level is used.
+
+---
+
+## Template Context
+
+### Document context
+
+The outermost template (`document`) receives:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `project.name` | `string` | Repository/package name |
+| `project.repoUrl` | `string \| null` | Repository URL |
+| `versions` | `TemplateContext[]` | All rendered versions, newest first |
+| `unreleased` | `TemplateContext \| undefined` | Unreleased changes, if any |
+
+### Version context
+
+Each version block (`version`) receives:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `packageName` | `string` | Package name (e.g. `@releasekit/notes`) |
+| `version` | `string` | New version string (e.g. `1.2.0`) |
+| `previousVersion` | `string \| null` | Previous version string |
+| `date` | `string` | Release date in `YYYY-MM-DD` format |
+| `repoUrl` | `string \| null` | Repository URL |
+| `compareUrl` | `string \| undefined` | Link to diff between previous and current version |
+| `entries` | `ChangelogEntry[]` | Raw changelog entries |
+| `enhanced` | `EnhancedData \| undefined` | LLM-processed data (see below) |
+
+### Entry
+
+Each entry in `entries` has:
+
+| Field | Type | Values |
+|-------|------|--------|
+| `type` | `ChangelogType` | `"added"`, `"changed"`, `"deprecated"`, `"removed"`, `"fixed"`, `"security"` |
+| `description` | `string` | Entry description (enhanced by LLM if `tasks.enhance` is on) |
+| `scope` | `string \| undefined` | Conventional commit scope |
+| `breaking` | `boolean \| undefined` | `true` for breaking changes |
+| `issueIds` | `string[] \| undefined` | Referenced issue/PR numbers |
+
+### Enhanced data (`enhanced`)
+
+Present when any LLM task ran successfully:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enhanced.summary` | `string \| undefined` | One-paragraph release summary (`summarize` task) |
+| `enhanced.categories` | `Category[] \| undefined` | Grouped entries (`categorize` task) |
+| `enhanced.releaseNotes` | `string \| undefined` | Full prose release notes (`releaseNotes` task) |
+
+Each `Category` in `enhanced.categories`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Category display name |
+| `entries` | `ChangelogEntry[]` | Entries in this category |
+
+---
+
+## Examples
+
+### Liquid (single file)
+
+```liquid
+# Changelog
+
+{% for v in versions %}
+## [{{ v.version }}] — {{ v.date }}
+
+{% if v.enhanced.summary %}
+{{ v.enhanced.summary }}
+
+{% endif %}
+{% for entry in v.entries %}
+- **{{ entry.type }}**: {{ entry.description }}{% if entry.scope %} *({{ entry.scope }})*{% endif %}
+{% endfor %}
+
+{% endfor %}
+```
+
+### Liquid (composable — `version.liquid`)
+
+```liquid
+## [{{ version }}]({{ compareUrl }}) — {{ date }}
+
+{% if enhanced.categories %}
+{% for cat in enhanced.categories %}
+### {{ cat.name }}
+
+{% for entry in cat.entries %}
+- {{ entry.description }}
+{% endfor %}
+{% endfor %}
+{% else %}
+{% for entry in entries %}
+- {{ entry.description }}
+{% endfor %}
+{% endif %}
+```
+
+### Handlebars (`version.hbs`)
+
+```handlebars
+## [{{version}}] — {{date}}
+
+{{#if enhanced.summary}}
+> {{enhanced.summary}}
+
+{{/if}}
+{{#each entries}}
+- **{{type}}**: {{description}}
+{{/each}}
+```
+
+### EJS (`release.md.ejs`)
+
+```ejs
+## <%= version %> — <%= date %>
+
+<% if (enhanced && enhanced.releaseNotes) { %>
+<%= enhanced.releaseNotes %>
+<% } else { %>
+<% entries.forEach(entry => { %>
+- **<%= entry.type %>**: <%= entry.description %>
+<% }) %>
+<% } %>
+```
+
+---
+
+## Engine Selection
+
+The engine is inferred from the file extension (`.liquid`, `.hbs`/`.handlebars`, `.ejs`) if not explicitly set. Override via config or CLI:
+
+```json
+{
+  "notes": {
+    "changelog": {
+      "templates": { "path": "./templates/", "engine": "handlebars" }
+    }
+  }
+}
+```
+
+```bash
+releasekit-notes --template ./templates/ --engine handlebars
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@releasekit/notes",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Release notes and changelog generation with LLM-powered enhancement and flexible templating",
   "type": "module",
   "module": "./dist/index.js",
@@ -38,6 +38,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "templates",
     "README.md",
     "LICENSE"
@@ -51,7 +52,7 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "ejs": "^4.0.1",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "liquidjs": "^10.25.0",
     "openai": "^6.27.0",
     "smol-toml": "^1.6.1",