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.
Files changed (54) hide show
  1. package/README.md +261 -12
  2. package/dist/bin/cli.js +428 -331
  3. package/dist/bin/cli.js.map +1 -1
  4. package/dist/generator.d.ts.map +1 -1
  5. package/dist/generator.js +25 -44
  6. package/dist/generator.js.map +1 -1
  7. package/dist/index.d.ts +17 -3
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +47 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/output-index.d.ts +71 -1
  12. package/dist/output-index.d.ts.map +1 -1
  13. package/dist/output-index.js +333 -1
  14. package/dist/output-index.js.map +1 -1
  15. package/dist/output-path.d.ts +61 -0
  16. package/dist/output-path.d.ts.map +1 -0
  17. package/dist/output-path.js +182 -0
  18. package/dist/output-path.js.map +1 -0
  19. package/dist/promote.d.ts +133 -0
  20. package/dist/promote.d.ts.map +1 -0
  21. package/dist/promote.js +0 -0
  22. package/dist/promote.js.map +1 -0
  23. package/dist/prompt-session.d.ts +172 -0
  24. package/dist/prompt-session.d.ts.map +1 -0
  25. package/dist/prompt-session.js +484 -0
  26. package/dist/prompt-session.js.map +1 -0
  27. package/dist/prompts/builder.d.ts +77 -0
  28. package/dist/prompts/builder.d.ts.map +1 -1
  29. package/dist/prompts/builder.js +134 -0
  30. package/dist/prompts/builder.js.map +1 -1
  31. package/dist/release-date.d.ts +14 -0
  32. package/dist/release-date.d.ts.map +1 -0
  33. package/dist/release-date.js +54 -0
  34. package/dist/release-date.js.map +1 -0
  35. package/dist/release-document.d.ts +150 -0
  36. package/dist/release-document.d.ts.map +1 -0
  37. package/dist/release-document.js +651 -0
  38. package/dist/release-document.js.map +1 -0
  39. package/dist/release.d.ts +27 -3
  40. package/dist/release.d.ts.map +1 -1
  41. package/dist/release.js +88 -2
  42. package/dist/release.js.map +1 -1
  43. package/dist/text-diff.d.ts +19 -0
  44. package/dist/text-diff.d.ts.map +1 -0
  45. package/dist/text-diff.js +81 -0
  46. package/dist/text-diff.js.map +1 -0
  47. package/dist/types.d.ts +10 -7
  48. package/dist/types.d.ts.map +1 -1
  49. package/dist/types.js.map +1 -1
  50. package/package.json +1 -1
  51. package/prompts/release-notes-edit-system.md +48 -0
  52. package/prompts/release-notes-promote-opening.md +59 -0
  53. package/prompts/release-notes-session-router.md +68 -0
  54. 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
- | `--release-date <value>` | Release date: `now` (default), `tag`, or an ISO date such as `2026-07-20` |
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
- | `--output-dir <dir>` | Output directory (auto-names the file) |
122
- | `--format <md\|html>` | Output format (default: `md`) |
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 --release-date now
138
- ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --release-date tag
139
- ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --release-date 2026-07-20
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 `releaseDate`. The older `date`
143
- field remains available when you need to supply an already formatted display
144
- date.
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
- outputDir: "./docs/releases",
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