ai-release-notes 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +261 -12
- package/dist/bin/cli.js +428 -331
- package/dist/bin/cli.js.map +1 -1
- package/dist/generator.d.ts.map +1 -1
- package/dist/generator.js +25 -44
- package/dist/generator.js.map +1 -1
- package/dist/index.d.ts +17 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +47 -1
- package/dist/index.js.map +1 -1
- package/dist/output-index.d.ts +71 -1
- package/dist/output-index.d.ts.map +1 -1
- package/dist/output-index.js +333 -1
- package/dist/output-index.js.map +1 -1
- package/dist/output-path.d.ts +61 -0
- package/dist/output-path.d.ts.map +1 -0
- package/dist/output-path.js +182 -0
- package/dist/output-path.js.map +1 -0
- package/dist/promote.d.ts +133 -0
- package/dist/promote.d.ts.map +1 -0
- package/dist/promote.js +0 -0
- package/dist/promote.js.map +1 -0
- package/dist/prompt-session.d.ts +172 -0
- package/dist/prompt-session.d.ts.map +1 -0
- package/dist/prompt-session.js +484 -0
- package/dist/prompt-session.js.map +1 -0
- package/dist/prompts/builder.d.ts +77 -0
- package/dist/prompts/builder.d.ts.map +1 -1
- package/dist/prompts/builder.js +134 -0
- package/dist/prompts/builder.js.map +1 -1
- package/dist/release-date.d.ts +14 -0
- package/dist/release-date.d.ts.map +1 -0
- package/dist/release-date.js +54 -0
- package/dist/release-date.js.map +1 -0
- package/dist/release-document.d.ts +150 -0
- package/dist/release-document.d.ts.map +1 -0
- package/dist/release-document.js +651 -0
- package/dist/release-document.js.map +1 -0
- package/dist/release.d.ts +27 -3
- package/dist/release.d.ts.map +1 -1
- package/dist/release.js +88 -2
- package/dist/release.js.map +1 -1
- package/dist/text-diff.d.ts +19 -0
- package/dist/text-diff.d.ts.map +1 -0
- package/dist/text-diff.js +81 -0
- package/dist/text-diff.js.map +1 -0
- package/dist/types.d.ts +10 -7
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
- package/prompts/release-notes-edit-system.md +48 -0
- package/prompts/release-notes-promote-opening.md +59 -0
- package/prompts/release-notes-session-router.md +68 -0
- package/dist/prompts/translation-system.md +0 -8
package/README.md
CHANGED
|
@@ -113,15 +113,15 @@ time. Translated releases include every translation call in these totals.
|
|
|
113
113
|
| `--from <version>` | Previous version tag, or `start` for the full history (default: `start`) |
|
|
114
114
|
| `--to <version>` | Current version tag |
|
|
115
115
|
| `--env <env>` | **Required.** Environment name (PROD, STAGING, etc.) |
|
|
116
|
-
| `--
|
|
117
|
-
| `--date <value>` | Alias for `--release-date` |
|
|
116
|
+
| `--date <date>` | Release date: `now` (default), `tag`, or an ISO date such as `2026-07-20` |
|
|
118
117
|
| `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
|
|
118
|
+
| `--lang <language>` | Write one configured language only (default: all of them) |
|
|
119
119
|
| `--config <path>` | Path to config file |
|
|
120
120
|
| `--output <path>` | Output file path (overrides `output.saveTo`) |
|
|
121
|
-
| `--
|
|
122
|
-
| `--format <
|
|
121
|
+
| `--to-dir <dir>` | Write the release into this folder (auto-names the file) |
|
|
122
|
+
| `--format <markdown\|html>` | Output format (default: `markdown`) |
|
|
123
123
|
| `--template <path>` | Custom template file |
|
|
124
|
-
| `--changelog <path>` | Raw changelog file (skip git) |
|
|
124
|
+
| `--changelog-file <path>` | Raw changelog file (skip git) |
|
|
125
125
|
| `--context <paths...>` | Context files or directories (mixed) |
|
|
126
126
|
| `--dry-run` | Show prompts without calling LLM |
|
|
127
127
|
| `-v, --verbose` | Show applied instructions and generation steps |
|
|
@@ -134,14 +134,203 @@ Use the current date (the default), the selected `--to` tag's creation date,
|
|
|
134
134
|
or an explicit ISO date:
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --
|
|
138
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --
|
|
139
|
-
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --
|
|
137
|
+
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date now
|
|
138
|
+
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date tag
|
|
139
|
+
ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date 2026-07-20
|
|
140
140
|
```
|
|
141
141
|
|
|
142
|
-
In the library API, pass the same values as `
|
|
143
|
-
|
|
144
|
-
|
|
142
|
+
In the library API, pass the same values as `date`.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Promoting a release to the next environment
|
|
147
|
+
|
|
148
|
+
A release note written for QUA has already been read, corrected and agreed on.
|
|
149
|
+
When that same release reaches PROD, nothing about it has changed — so
|
|
150
|
+
`promote` reuses the files QUA already holds instead of asking a model to write
|
|
151
|
+
them again. **Promoting one release builds no prompt and calls no provider**,
|
|
152
|
+
which is also why no API key is needed:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# Everything PROD is missing, in one command
|
|
156
|
+
npx ai-release-notes promote --from-env QUA --to-env PROD
|
|
157
|
+
|
|
158
|
+
# Or one explicit range
|
|
159
|
+
npx ai-release-notes promote --from-env QUA --to-env PROD --from start --to v0.23.0
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Each release file names the range it covers, so the files themselves form the
|
|
163
|
+
chain — `start → v0.23.0`, `v0.23.0 → v0.24.0`, and so on. Promoting reads that
|
|
164
|
+
chain rather than the version numbers, so a project that does not release in
|
|
165
|
+
ascending order is followed just as well.
|
|
166
|
+
|
|
167
|
+
- **One file covers the range** — it is promoted as it stands, word for word.
|
|
168
|
+
- **Several files cover it** — they are merged into the one note that covers
|
|
169
|
+
the whole range: sections carrying the same heading become one section,
|
|
170
|
+
their scopes become one scope, their lists become one list, and a line two
|
|
171
|
+
releases both carry is listed once. Inside a list the newest release's lines
|
|
172
|
+
come first, then the ones released before them.
|
|
173
|
+
- **A note whose shape cannot be read back** — it is never rewritten to fit.
|
|
174
|
+
The notes are kept whole and put one after another instead. Nothing to
|
|
175
|
+
choose: a note that does not survive being read and written out unchanged
|
|
176
|
+
answers this on its own.
|
|
177
|
+
|
|
178
|
+
Every section survives that merge word for word — the reviewed wording is the
|
|
179
|
+
whole point. What cannot survive it is the opening: three headings, three dates
|
|
180
|
+
and three summaries do not add up to one release note. So the merged note is
|
|
181
|
+
given a single opening, and that is the one thing a model is asked for:
|
|
182
|
+
|
|
183
|
+
```text
|
|
184
|
+
🚀 Promoting QUA → PROD: v1.25.7 → v1.28.0
|
|
185
|
+
v1.25.7 → v1.26.0
|
|
186
|
+
v1.26.0 → v1.27.0
|
|
187
|
+
v1.27.0 → v1.28.0
|
|
188
|
+
Sections merged word for word; one title and summary written for the range.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The model is shown the three openings and nothing else, so it cannot reach the
|
|
192
|
+
sections, and an answer that comes back carrying sections of its own is
|
|
193
|
+
refused.
|
|
194
|
+
|
|
195
|
+
When no provider is configured, when the call fails, or when the answer is
|
|
196
|
+
refused, the newest release's title and summary stand for the range instead,
|
|
197
|
+
with the environment and the version it followed pointed at what was actually
|
|
198
|
+
promoted. That is a true opening, only narrower than the range it covers, so
|
|
199
|
+
the run says so rather than reading as a success:
|
|
200
|
+
|
|
201
|
+
```text
|
|
202
|
+
⚠️ The v1.28.0 title and summary stand for the whole range: no provider is configured.
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
With no `--from`, promotion starts where the target environment already is, so
|
|
206
|
+
running it twice does nothing the second time. With no `--to`, it goes to the
|
|
207
|
+
newest release the source environment holds. The target environment's output
|
|
208
|
+
index is updated exactly as a generation would update it.
|
|
209
|
+
|
|
210
|
+
### Where the files are
|
|
211
|
+
|
|
212
|
+
Promotion reads and writes the paths `output.saveTo` already describes, so a
|
|
213
|
+
layout naming its environment needs nothing else:
|
|
214
|
+
|
|
215
|
+
```yaml
|
|
216
|
+
output:
|
|
217
|
+
- format: html
|
|
218
|
+
saveTo: ./releases/{env}/release-notes_{from}_{to}.html
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
When each environment lives in a folder that the path does not name, point at
|
|
222
|
+
the folders instead — their names become the environments:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
npx ai-release-notes promote --from-dir ./releases/env1 --to-dir ./releases/env2
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
A `saveTo` with neither `{from}` nor `{to}` holds every release in one file
|
|
229
|
+
rather than one release per file, so there is nothing to promote from it; those
|
|
230
|
+
outputs are reported as skipped.
|
|
231
|
+
|
|
232
|
+
### Promote options
|
|
233
|
+
|
|
234
|
+
| Option | Description |
|
|
235
|
+
|--------|-------------|
|
|
236
|
+
| `--from-env <environment>` | Environment to promote from (default: `--from-dir`'s folder name) |
|
|
237
|
+
| `--to-env <environment>` | Environment to promote to (default: `--to-dir`'s folder name) |
|
|
238
|
+
| `--from <version>` | Start of the range (default: where the target environment is) |
|
|
239
|
+
| `--to <version>` | End of the range (default: the newest release in the source) |
|
|
240
|
+
| `--from-dir <dir>` / `--to-dir <dir>` | Read/write the releases in these folders |
|
|
241
|
+
| `--pattern <pattern>` | File name inside those folders (default: the configured one) |
|
|
242
|
+
| `--with <provider>` | LLM provider used to write the opening of a merged range |
|
|
243
|
+
| `--lang <language>` | Promote one language only |
|
|
244
|
+
| `--date <date>` | Release date: `now` (default), `tag`, or an ISO date |
|
|
245
|
+
| `--config <path>` | Path to config file |
|
|
246
|
+
| `--dry-run` | Show what would be promoted without writing anything |
|
|
247
|
+
| `-v, --verbose` | Show what was promoted, release by release |
|
|
248
|
+
| `--stdout` | Write the promoted notes to the terminal without saving files |
|
|
249
|
+
|
|
250
|
+
An HTML release note is read back out of the page it was written into and
|
|
251
|
+
rendered into the template again, so the promoted page states its own
|
|
252
|
+
environment, versions and date. A page written through a template this cannot
|
|
253
|
+
read is copied as it stands, which is the whole point of promoting.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Asking for a change
|
|
258
|
+
|
|
259
|
+
A generated note is rarely wrong so much as not yet right: it repeats a line,
|
|
260
|
+
it says more about the build than anyone wants to read, or it drifted from your
|
|
261
|
+
own writing rules. Regenerating answers none of that — the changelog has not
|
|
262
|
+
changed, so the same note comes back and every correction already made to it is
|
|
263
|
+
lost.
|
|
264
|
+
|
|
265
|
+
`prompt` opens the notes an environment holds and asks what you would like to
|
|
266
|
+
change. You answer in your own words:
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
npx ai-release-notes prompt --env PRD --from v1.25.7 --to v1.28.0 --with mistral
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
```
|
|
273
|
+
📝 2 release notes open for PRD
|
|
274
|
+
releases/PRD/release-notes_v1.25.7_v1.26.0.md v1.25.7 → v1.26.0
|
|
275
|
+
releases/PRD/release-notes_v1.26.0_v1.28.0.md v1.26.0 → v1.28.0
|
|
276
|
+
|
|
277
|
+
💬 Is there anything you would like to change?
|
|
278
|
+
Say it in your own words. Say you are done when you are done.
|
|
279
|
+
|
|
280
|
+
› remove the exact duplicate lines
|
|
281
|
+
› drop the technical section, I don't want to talk about the docker part
|
|
282
|
+
› group everything about "update endpoint logic" under one line
|
|
283
|
+
› format them against the project instructions again
|
|
284
|
+
› that's it, save them
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
There is nothing to learn first. Every answer is read by a model that works out
|
|
288
|
+
what it meant — a change to make, a change to take back, a request to save, or
|
|
289
|
+
that you are done — so "put that back", "actually leave it", and "that's all"
|
|
290
|
+
all work.
|
|
291
|
+
|
|
292
|
+
Without `--from` and `--to`, every release note the environment holds is opened
|
|
293
|
+
at once, and each request is applied to all of them.
|
|
294
|
+
|
|
295
|
+
- **Nothing is written until you say so.** Each request shows what it changed,
|
|
296
|
+
line by line, and the files stay as they were until you ask for them to be
|
|
297
|
+
saved.
|
|
298
|
+
- **Repeated lines are compared, not rewritten.** Asking for exact duplicates to
|
|
299
|
+
go calls no model at all: the lines are compared here, the first of each stays
|
|
300
|
+
where you meet it, and a section left empty goes with them.
|
|
301
|
+
- **A revision changes what a note says, never which release it is**, so the
|
|
302
|
+
release index still describes it and is left alone.
|
|
303
|
+
|
|
304
|
+
### In CI
|
|
305
|
+
|
|
306
|
+
Pass the requests instead of answering them, and the same session runs with
|
|
307
|
+
nothing to type. It saves at the end, and exits non-zero if a request failed:
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
npx ai-release-notes prompt --env PRD \
|
|
311
|
+
--ask "remove exact duplicate lines" \
|
|
312
|
+
--ask "drop any line about internal tooling" \
|
|
313
|
+
--dry-run
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Prompt options
|
|
317
|
+
|
|
318
|
+
| Option | Description |
|
|
319
|
+
|--------|-------------|
|
|
320
|
+
| `--env <environment>` | **Required.** Whose release notes to open |
|
|
321
|
+
| `--from <version>` / `--to <version>` | Open only the releases a range covers |
|
|
322
|
+
| `--lang <language>` | Open one language only |
|
|
323
|
+
| `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
|
|
324
|
+
| `--config <path>` | Path to config file |
|
|
325
|
+
| `--ask <request>` | Apply a request with nothing to answer. Repeatable, for CI |
|
|
326
|
+
| `--dry-run` | Show what the requests would change without writing anything |
|
|
327
|
+
| `-v, --verbose` | Show the provider and instructions the requests are answered with |
|
|
328
|
+
| `--stdout` | Write the revised notes to the terminal without saving files (needs `--ask`) |
|
|
329
|
+
|
|
330
|
+
An HTML release note is a whole page, so only the note on it is ever sent or
|
|
331
|
+
replaced: the page keeps its head, its styles, its footer, and the values the
|
|
332
|
+
template filled in when it was generated. A page whose note cannot be told apart
|
|
333
|
+
from the page around it is reported and left alone.
|
|
145
334
|
|
|
146
335
|
---
|
|
147
336
|
|
|
@@ -330,6 +519,11 @@ travels with the repository. Both are treated as untrusted:
|
|
|
330
519
|
- **Safe rendering.** Raw HTML in a release note is escaped and link targets are
|
|
331
520
|
limited to `http`, `https`, `mailto`, and relative paths.
|
|
332
521
|
- **Bounded spend.** `git.maxCommits` (default 200) caps one run.
|
|
522
|
+
- **Promotion.** `promote` reuses files this tool already wrote, whose markup was
|
|
523
|
+
escaped when it was generated; those files are trusted like the rest of your
|
|
524
|
+
repository. Merging several of them reaches a provider once, for the opening
|
|
525
|
+
alone: the sections are never sent, and the answer is sanitized like any other
|
|
526
|
+
model output before it reaches a page.
|
|
333
527
|
- **Endpoint checks.** `baseURL` must be `http`/`https`, and a non-local one
|
|
334
528
|
warns before any prompt leaves the machine.
|
|
335
529
|
|
|
@@ -350,7 +544,7 @@ const result = await generate({
|
|
|
350
544
|
environment: "PROD",
|
|
351
545
|
provider: "claude", // only ANTHROPIC_API_KEY is needed
|
|
352
546
|
format: "html",
|
|
353
|
-
|
|
547
|
+
toDir: "./docs/releases",
|
|
354
548
|
context: ["./specs/api-v2.md", "./docs/models/"],
|
|
355
549
|
});
|
|
356
550
|
|
|
@@ -365,6 +559,61 @@ template, which supplies the page title and footer:
|
|
|
365
559
|
markdownToHtml(markdown, { trustedHtml: true });
|
|
366
560
|
```
|
|
367
561
|
|
|
562
|
+
`promote(options)` returns the files a promotion would write, without writing
|
|
563
|
+
any of them, so you can review or publish them yourself:
|
|
564
|
+
|
|
565
|
+
```typescript
|
|
566
|
+
import { promote } from "ai-release-notes";
|
|
567
|
+
|
|
568
|
+
const { files, plan } = await promote({
|
|
569
|
+
fromEnvironment: "QUA",
|
|
570
|
+
toEnvironment: "PROD",
|
|
571
|
+
});
|
|
572
|
+
|
|
573
|
+
console.log(plan.segments.map((s) => `${s.fromVersion} → ${s.toVersion}`));
|
|
574
|
+
for (const file of files) {
|
|
575
|
+
console.log(file.path, "←", file.sources);
|
|
576
|
+
}
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
`PromptSession` opens the notes an environment holds and applies requests to
|
|
580
|
+
them. Nothing reaches the disk until `save`, and `callModel` lets the session
|
|
581
|
+
run on a model of your own:
|
|
582
|
+
|
|
583
|
+
```typescript
|
|
584
|
+
import { PromptSession } from "ai-release-notes";
|
|
585
|
+
|
|
586
|
+
const session = await PromptSession.open({ environment: "PROD" });
|
|
587
|
+
|
|
588
|
+
const { action, instruction } = await session.route("drop the docker line");
|
|
589
|
+
const result = action === "dedupe"
|
|
590
|
+
? session.dedupe()
|
|
591
|
+
: await session.revise(instruction);
|
|
592
|
+
|
|
593
|
+
for (const edit of result.edits) {
|
|
594
|
+
console.log(edit.path, edit.changed ? "revised" : edit.skipped ?? "unchanged");
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
await session.save();
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
Each step is exported on its own when you need only part of it:
|
|
601
|
+
|
|
602
|
+
| Function | What it does |
|
|
603
|
+
|----------|--------------|
|
|
604
|
+
| `discoverReleases(saveTo, values)` | Read a `saveTo` pattern back off disk: which releases exist, and what their paths say about them |
|
|
605
|
+
| `formatOutputPath(saveTo, values)` | Fill `{env}`, `{lang}`, `{from}`, `{to}`; anything not supplied stays a placeholder |
|
|
606
|
+
| `planPromotion({ available, … })` | Chain release files into the run that carries one version to another |
|
|
607
|
+
| `mergeReleaseDocuments(docs, format, opts)` | Merge release notes by section and list; `leadWith: "newest"` puts the last release's lines first |
|
|
608
|
+
| `splitReleaseOpening(content, format)` | Cut a note where its first section begins: the title, date and summary on one side, the sections on the other |
|
|
609
|
+
| `dedupeReleaseDocument(content, format)` | Drop the lines a note lists twice, and report which they were |
|
|
610
|
+
| `parseReleaseDocument` / `serializeReleaseDocument` | A release note as a section tree, and back again |
|
|
611
|
+
| `extractReleaseContent(page, template?)` | Read a release note back out of the HTML page it was rendered into |
|
|
612
|
+
| `replaceReleaseContent(page, revised, template?)` | Put a revised note back on its page, leaving the page around it standing |
|
|
613
|
+
| `sanitizeReleaseHtml(html)` | Reduce model-written markup to what a release note is made of |
|
|
614
|
+
| `diffLines(before, after)` | What a revision changed, line by line |
|
|
615
|
+
| `updateOutputIndexes(params)` | Add a release to every configured index, creating the ones that do not exist |
|
|
616
|
+
|
|
368
617
|
---
|
|
369
618
|
|
|
370
619
|
## CI/CD Integration
|