@releasekit/notes 0.42.1 → 0.43.1

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.
@@ -14,7 +14,7 @@ import {
14
14
  unwrapEnvelope,
15
15
  warn,
16
16
  writeMarkdown
17
- } from "./chunk-CBMVDKDR.js";
17
+ } from "./chunk-YIHEHXCU.js";
18
18
 
19
19
  // ../config/dist/index.js
20
20
  import * as fs from "fs";
@@ -84,13 +84,17 @@ var VersionCargoConfigSchema = z.object({
84
84
  enabled: z.boolean().default(true).describe(
85
85
  "Version Cargo.toml manifests. Detected Rust packages are versioned by default; set false to opt out (e.g. a vendored crate, or Rust versioning handled elsewhere)."
86
86
  ),
87
- paths: z.array(z.string()).optional().describe("Directories to search for Cargo.toml files")
87
+ paths: z.array(z.string()).optional().describe(
88
+ "Directories, relative to each package, to bump a Cargo.toml in instead of the package's own directory. Not searched recursively. Ignored in group mode."
89
+ )
88
90
  });
89
91
  var VersionPubConfigSchema = z.object({
90
92
  enabled: z.boolean().default(true).describe(
91
- "Version pubspec.yaml manifests. Detected Dart/Flutter packages are versioned by default; set false to opt out."
93
+ "Version pubspec.yaml manifests. Detected Dart/Flutter packages are versioned by default; set false to opt out, which also stops a pubspec.yaml beside a package.json from publishing."
92
94
  ),
93
- paths: z.array(z.string()).optional().describe("Directories to search for pubspec.yaml files")
95
+ paths: z.array(z.string()).optional().describe(
96
+ "Directories, relative to each package, to bump a pubspec.yaml in instead of the package's own directory. Not searched recursively. Ignored in group mode."
97
+ )
94
98
  });
95
99
  var VersionGroupSchema = z.object({
96
100
  packages: z.array(z.string()).min(1).describe(
@@ -125,7 +129,7 @@ var VersionConfigSchema = z.object({
125
129
  groups: z.record(z.string(), VersionGroupSchema).optional().describe(
126
130
  "Named version groups. Each group binds a set of package patterns to a fixed, linked, or independent sync mode. fixed: any releasable change in any member releases ALL members at the shared group version (bump(max(member baselines))). linked: only members with releasable changes release, but every releasing member shares the same computed version. independent: only members with releasable changes release, each on its own commit-driven version line (no shared version), but the set is atomic \u2014 targeting any member pulls in the whole group. Packages not matched by any group version independently. A package may belong to at most one group. Set version.sync to false when using groups."
127
131
  ),
128
- packages: z.array(z.string()).default([]).describe("Packages to include in versioning"),
132
+ packages: z.array(z.string()).default([]).describe("Packages to include in versioning. Empty includes every discovered package."),
129
133
  sharedPackages: z.array(z.string()).optional().describe(
130
134
  'Foundational packages whose changes belong in every package\u2019s changelog. A commit touching only a shared package (exact name or glob) is classified as repo-level and surfaced under "Project-wide changes" rather than attributed to that one package. Default: none \u2014 no package is treated as shared unless declared.'
131
135
  ),
@@ -139,7 +143,10 @@ var VersionConfigSchema = z.object({
139
143
  includePrivate: z.boolean().default(false).describe(
140
144
  'Include npm packages marked "private": true (in package.json) in the release flow. Default false: private packages are skipped at discovery \u2014 they cannot be published to any registry, mirroring the Cargo `publish = false` and pub `publish_to: none` skips already applied during discovery. Set true to version a private package for internal tracking. Packages explicitly named in version.packages are always included regardless of this setting.'
141
145
  ),
142
- commitMessage: z.string().optional().describe("Template for release commit messages"),
146
+ commitMessage: z.string().optional().describe(
147
+ // biome-ignore lint/suspicious/noTemplateCurlyInString: documenting placeholder syntax to the user
148
+ "Template for the release commit message. Supports ${version} and ${packageName}. Default: 'chore: release ${packageName} v${version}' for sync and single-package releases; otherwise 'chore: release' followed by each released package and version."
149
+ ),
143
150
  mismatchStrategy: z.enum(["error", "warn", "ignore", "prefer-package", "prefer-git"]).default("warn").describe("How to handle version mismatches"),
144
151
  versionPrefix: z.string().default("").describe("Prefix for version tags"),
145
152
  prereleaseIdentifier: z.string().optional().describe("Identifier for prerelease versions (e.g., 'alpha', 'beta')"),
@@ -170,15 +177,19 @@ var CargoPublishConfigSchema = z.object({
170
177
  enabled: z.boolean().default(true).describe(
171
178
  "Publish to crates.io. Detected Rust packages are published by default; set false to opt out (version and tag only)."
172
179
  ),
173
- noVerify: z.boolean().default(false).describe("Skip verification before publish"),
174
- publishOrder: z.array(z.string()).default([]).describe("Order in which to publish packages"),
175
- clean: z.boolean().default(false).describe("Clean before publishing")
180
+ noVerify: z.boolean().default(false).describe(
181
+ "Pass --no-verify to cargo publish, skipping the pre-publish build of the packaged crate. Use only as a temporary workaround for a build that fails in CI."
182
+ ),
183
+ publishOrder: z.array(z.string()).default([]).describe(
184
+ "Crate names to publish first, in this order; the rest follow in discovery order. Empty sorts crates by their path dependencies."
185
+ ),
186
+ clean: z.boolean().default(false).describe("Run cargo clean in each crate's directory before publishing.")
176
187
  });
177
188
  var PubPublishConfigSchema = z.object({
178
189
  enabled: z.boolean().default(true).describe(
179
190
  "Publish to pub.dev. Detected Dart/Flutter packages are published by default; set false to opt out (version and tag only)."
180
191
  ),
181
- publishOrder: z.array(z.string()).default([]).describe("Order in which to publish packages")
192
+ publishOrder: z.array(z.string()).default([]).describe("Package names to publish first, in this order; the rest follow in discovery order.")
182
193
  });
183
194
  var PublishGitConfigSchema = z.object({
184
195
  push: z.boolean().optional().describe("Push tags and commits to remote. When unset, inherits the top-level git.push (which defaults to push)."),
@@ -199,26 +210,28 @@ var GitHubReleaseConfigSchema = z.object({
199
210
  /* biome-ignore lint/suspicious/noTemplateCurlyInString: default template value */
200
211
  titleTemplate: z.string().default("${packageName}: ${version}").describe(
201
212
  // biome-ignore lint/suspicious/noTemplateCurlyInString: documenting placeholder syntax to the user
202
- "Template for the GitHub release title when a package name is resolved. Available variables: ${packageName} (original scoped name, e.g. '@scope/pkg'), ${version} (e.g. 'v1.0.0'). Version-only tags always use the tag string directly."
213
+ "Template for the GitHub release title when a package name is resolved. Available variables: ${packageName} (original scoped name, e.g. '@scope/pkg'), ${version} (the package's new version, with a 'v' when its tag has one, e.g. 'v1.0.0'). Tags without a package name, e.g. 'v1.0.0' or 'release-1.0.0', are used as the title unchanged."
203
214
  ),
204
- skipPackages: z.array(z.string()).default([]).describe("Package names to exclude from GitHub release creation")
215
+ skipPackages: z.array(z.string()).default([]).describe(
216
+ "Package names to exclude from GitHub release creation. The name as tags spell it also matches, e.g. 'scope-pkg' for '@scope/pkg'."
217
+ )
205
218
  });
206
219
  var VerifyRegistryNpmConfigSchema = z.object({
207
220
  enabled: z.boolean().default(true).describe("Verify NPM publish"),
208
221
  maxAttempts: z.number().int().positive().default(5).describe("Maximum verification attempts"),
209
- initialDelay: z.number().int().positive().default(15e3).describe("Initial delay in milliseconds"),
222
+ initialDelay: z.number().int().positive().default(15e3).describe("Wait in ms after the first failed check; each later wait is multiplied by backoffMultiplier."),
210
223
  backoffMultiplier: z.number().positive().default(2).describe("Exponential backoff multiplier")
211
224
  });
212
225
  var VerifyRegistryCargoConfigSchema = z.object({
213
226
  enabled: z.boolean().default(true).describe("Verify Cargo publish"),
214
227
  maxAttempts: z.number().int().positive().default(10).describe("Maximum verification attempts"),
215
- initialDelay: z.number().int().positive().default(3e4).describe("Initial delay in milliseconds"),
228
+ initialDelay: z.number().int().positive().default(3e4).describe("Wait in ms after the first failed check; each later wait is multiplied by backoffMultiplier."),
216
229
  backoffMultiplier: z.number().positive().default(2).describe("Exponential backoff multiplier")
217
230
  });
218
231
  var VerifyRegistryPubConfigSchema = z.object({
219
232
  enabled: z.boolean().default(true).describe("Verify Dart pub publish"),
220
233
  maxAttempts: z.number().int().positive().default(10).describe("Maximum verification attempts"),
221
- initialDelay: z.number().int().positive().default(3e4).describe("Initial delay in milliseconds"),
234
+ initialDelay: z.number().int().positive().default(3e4).describe("Wait in ms after the first failed check; each later wait is multiplied by backoffMultiplier."),
222
235
  backoffMultiplier: z.number().positive().default(2).describe("Exponential backoff multiplier")
223
236
  });
224
237
  var VerifyConfigSchema = z.object({
@@ -227,19 +240,21 @@ var VerifyConfigSchema = z.object({
227
240
  maxAttempts: 5,
228
241
  initialDelay: 15e3,
229
242
  backoffMultiplier: 2
230
- }),
243
+ }).describe("Poll npm after each publish until the new version is visible."),
231
244
  cargo: VerifyRegistryCargoConfigSchema.default({
232
245
  enabled: true,
233
246
  maxAttempts: 10,
234
247
  initialDelay: 3e4,
235
248
  backoffMultiplier: 2
236
- }),
249
+ }).describe(
250
+ "Poll crates.io after each publish until the new version is visible. Its index updates more slowly than npm's, so the defaults wait longer."
251
+ ),
237
252
  pub: VerifyRegistryPubConfigSchema.default({
238
253
  enabled: true,
239
254
  maxAttempts: 10,
240
255
  initialDelay: 3e4,
241
256
  backoffMultiplier: 2
242
- })
257
+ }).describe("Poll pub.dev after each publish until the new version is visible.")
243
258
  });
244
259
  var PublishConfigSchema = z.object({
245
260
  git: PublishGitConfigSchema.optional().describe("Git publishing options"),
@@ -295,8 +310,8 @@ var PublishConfigSchema = z.object({
295
310
  }).describe("Registry verification configuration")
296
311
  });
297
312
  var TemplateConfigSchema = z.object({
298
- path: z.string().optional().describe("Path to custom template"),
299
- engine: z.enum(["handlebars", "liquid", "ejs"]).optional().describe("Template engine")
313
+ path: z.string().optional().describe("Template file, or a directory of composable templates."),
314
+ engine: z.enum(["handlebars", "liquid", "ejs"]).optional().describe("Template engine. Detected from the template files when omitted; ignored without path.")
300
315
  });
301
316
  var LocationModeSchema = z.enum(["root", "packages", "both"]);
302
317
  var ReleaseNotesFileConfigSchema = z.object({
@@ -304,7 +319,7 @@ var ReleaseNotesFileConfigSchema = z.object({
304
319
  });
305
320
  var ChangelogConfigSchema = z.object({
306
321
  mode: LocationModeSchema.optional().describe(
307
- "Where to write changelog files. root: repo root only. packages: per-package (monorepos). both: repo root and per-package. When omitted entirely (no changelog config), defaults to root."
322
+ "Where to write changelog files: 'root' (the default) at the repo root, 'packages' in each package (monorepos only), or 'both'."
308
323
  ),
309
324
  file: z.string().optional().describe("Changelog file name override (default: CHANGELOG.md)"),
310
325
  templates: TemplateConfigSchema.optional().describe("Template configuration for changelog"),
@@ -312,25 +327,25 @@ var ChangelogConfigSchema = z.object({
312
327
  "How `#NNN` issue/PR refs in the changelog are rendered. Applies to the whole entry \u2014 both the appended label and any bare `#N` carried over from the commit subject into the description (a description ref that also appears in the appended label is de-duplicated away). 'link' (default): the PR and the issues it closed are labelled as `(PR #503 \xB7 closes #500)`, where the PR links to its canonical /pull/ URL with `PR #503` as the visible text \u2014 this keeps the GitHub hovercard but stops the bare-token rich inline card that duplicated the entry; closed issues link to /issues/. An entry with no identifiable PR (a non-squash commit, or a non-GitHub repo) falls back to a plain ref list. 'escape': plain text \\#NNN (no link, no hovercard, no PR/closes labelling). 'strip': refs are removed entirely. Scoped-package / @user mentions in entry text are always neutralised regardless of this setting."
313
328
  ),
314
329
  demoteScopes: z.array(z.string()).default([...DEFAULT_DEMOTE_SCOPES]).describe(
315
- 'Conventional-commit scopes whose changelog entries are demoted into a trailing "Dependencies & version bumps" subsection instead of interleaving with Added / Fixed / Changed. Applies to the standing-PR changelogs \u2014 each releasable row and the "Show all changes" footer. Nothing is hidden or dropped: low-signal dependency bumps just stop crowding the user-facing changes at the top, and a reader who wants the exact per-package deps expands the subsection. The de-duplicated change count is unchanged. Default: ["deps", "deps-dev"] (the scopes Dependabot uses for production and development bumps). Set to [] to render every scope inline.'
330
+ 'Conventional-commit scopes whose changelog entries move to a trailing "Dependencies & version bumps" subsection instead of mixing with Added / Fixed / Changed. A breaking change still comes first, under Breaking. Applies to the release preview comment and the standing-PR changelogs (each releasable row and the "Show all changes" footer). Entries are moved, not dropped, so the de-duplicated change count is unchanged. Default: ["deps", "deps-dev"], the scopes Dependabot uses. Set to [] to render every scope inline.'
316
331
  )
317
332
  }).describe("Changelog file configuration");
318
333
  var LLMOptionsSchema = z.object({
319
- timeout: z.number().int().optional().describe("Idle timeout in ms: a streamed response fails only when nothing arrives for this long"),
320
- maxTokens: z.number().int().optional().describe("Max tokens to generate"),
321
- temperature: z.number().optional().describe("Sampling temperature")
334
+ timeout: z.number().int().optional().describe("Idle timeout in ms: a streamed response fails only when nothing arrives for this long. Default: 60000."),
335
+ maxTokens: z.number().int().optional().describe("Max tokens to generate. Default: 16384."),
336
+ temperature: z.number().optional().describe("Sampling temperature. Default: 0.7; the anthropic provider ignores it.")
322
337
  });
323
338
  var LLMRetryConfigSchema = z.object({
324
- maxAttempts: z.number().int().positive().optional().describe("Maximum number of attempts"),
325
- initialDelay: z.number().int().nonnegative().optional().describe("Initial delay in ms"),
326
- maxDelay: z.number().int().positive().optional().describe("Maximum delay in ms"),
327
- backoffFactor: z.number().positive().optional().describe("Delay multiplier per attempt")
339
+ maxAttempts: z.number().int().positive().optional().describe("Maximum number of attempts, including the first. Default: 3."),
340
+ initialDelay: z.number().int().nonnegative().optional().describe("Delay in ms before the first retry. Default: 1000."),
341
+ maxDelay: z.number().int().positive().optional().describe("Maximum delay in ms between attempts. Default: 30000."),
342
+ backoffFactor: z.number().positive().optional().describe("Delay multiplier per attempt. Default: 2.")
328
343
  });
329
344
  var LLMTasksConfigSchema = z.object({
330
- summarize: z.boolean().optional().describe("Enable summarization"),
331
- enhance: z.boolean().optional().describe("Enable entry enhancement"),
332
- categorize: z.boolean().optional().describe("Enable categorization"),
333
- releaseNotes: z.boolean().optional().describe("Enable release note generation")
345
+ summarize: z.boolean().optional().describe("Write a 2\u20133 sentence summary of the release."),
346
+ enhance: z.boolean().optional().describe("Rewrite each entry's description to be clearer for users."),
347
+ categorize: z.boolean().optional().describe("Group entries into the configured categories."),
348
+ releaseNotes: z.boolean().optional().describe("Write prose release notes for the GitHub Release body and any release-notes files.")
334
349
  });
335
350
  var LLMCategorySchema = z.object({
336
351
  name: z.string().describe("Category label shown in release notes (e.g. 'Features')"),
@@ -352,15 +367,15 @@ var ScopeConfigSchema = z.object({
352
367
  rules: ScopeRulesSchema.optional().describe("Scope validation and transformation rules")
353
368
  });
354
369
  var LLMPromptOverridesSchema = z.object({
355
- enhance: z.string().optional().describe("Instruction override for the enhance task"),
356
- categorize: z.string().optional().describe("Instruction override for the categorize task"),
357
- enhanceAndCategorize: z.string().optional().describe("Instruction override for the combined enhance + categorize task"),
358
- summarize: z.string().optional().describe("Instruction override for the summarize task"),
359
- releaseNotes: z.string().optional().describe("Instruction override for the release-notes task")
370
+ enhance: z.string().optional().describe("For the enhance task when categorize is off."),
371
+ categorize: z.string().optional().describe("For the categorize task when enhance is off."),
372
+ enhanceAndCategorize: z.string().optional().describe("For the combined task that replaces enhance and categorize when both are on."),
373
+ summarize: z.string().optional().describe("For the summarize task."),
374
+ releaseNotes: z.string().optional().describe("For the releaseNotes task.")
360
375
  });
361
376
  var LLMPromptsConfigSchema = z.object({
362
377
  instructions: LLMPromptOverridesSchema.optional().describe(
363
- "Per-task instruction overrides appended to the built-in prompts."
378
+ "Extra instructions appended to a task's built-in system prompt. The task's output format is unchanged."
364
379
  )
365
380
  });
366
381
  var LLMConfigBaseSchema = z.object({
@@ -369,29 +384,39 @@ var LLMConfigBaseSchema = z.object({
369
384
  "Model identifier for the selected provider. Required \u2014 releasekit ships no default, so enabling LLM enhancement needs an explicit, current model (a missing model fails config validation)."
370
385
  ),
371
386
  baseURL: z.string().optional().describe("Custom API base URL. Required for the openai-compatible provider."),
372
- apiKey: z.string().optional().describe("API key"),
373
- options: LLMOptionsSchema.optional(),
374
- concurrency: z.number().int().positive().optional().describe("Concurrent LLM requests"),
375
- retry: LLMRetryConfigSchema.optional(),
376
- tasks: LLMTasksConfigSchema.optional(),
387
+ apiKey: z.string().optional().describe(
388
+ "API key. When unset, releasekit uses the key saved by releasekit-notes auth, then the provider's environment variable (e.g. OPENAI_API_KEY); prefer either to an inline key."
389
+ ),
390
+ options: LLMOptionsSchema.optional().describe("Options for each request to the provider."),
391
+ concurrency: z.number().int().positive().optional().describe(
392
+ "Maximum packages processed at once and, separately, entries a package's standalone enhance task rewrites at once. Default: 5."
393
+ ),
394
+ retry: LLMRetryConfigSchema.optional().describe("Retries for LLM requests that fail with a retryable error."),
395
+ tasks: LLMTasksConfigSchema.optional().describe("LLM tasks to run. Each is off unless set to true."),
377
396
  categories: z.array(LLMCategorySchema).default(() => [
378
397
  { name: "Breaking", description: "Breaking changes that require user action to upgrade" },
379
398
  { name: "New", description: "New features and capabilities" },
380
399
  { name: "Changed", description: "Changes to existing functionality" },
381
400
  { name: "Fixed", description: "Bug fixes" },
382
401
  { name: "Developer", description: "Internal changes: CI, tooling, dependencies, refactoring" }
383
- ]),
402
+ ]).describe(
403
+ "Categories the categorize task sorts entries into. Default: Breaking, New, Changed, Fixed and Developer, each with a built-in description."
404
+ ),
384
405
  style: z.string().default(
385
406
  'Write in past tense ("Added feature", not "Add feature"). Be concise and user-focused. Lead with the impact, not the implementation detail.'
386
- ).describe("Writing style for LLM"),
387
- scopes: ScopeConfigSchema.optional(),
388
- prompts: LLMPromptsConfigSchema.optional(),
389
- examples: z.number().int().min(0).max(5).default(3).describe("Number of few-shot examples to include in LLM prompts (0\u20135)."),
407
+ ).describe(
408
+ "Writing-style instruction for the enhance task, alone or combined with categorize. Default: past tense, concise and user-focused, leading with the impact."
409
+ ),
410
+ scopes: ScopeConfigSchema.optional().describe("Validation of the scopes the LLM assigns to entries."),
411
+ prompts: LLMPromptsConfigSchema.optional().describe("Per-task prompt additions."),
412
+ examples: z.number().int().min(0).max(5).default(3).describe(
413
+ "Number of the project's past GitHub Releases (0\u20135) used as style examples in the combined enhance and categorize prompt and the releaseNotes prompt. Needs GITHUB_TOKEN or GH_TOKEN."
414
+ ),
390
415
  context: z.object({
391
- pullRequests: z.boolean().default(true).describe("Include linked pull request titles/bodies as context.")
416
+ pullRequests: z.boolean().default(true).describe("Fetch the title and body of each entry's linked PR as LLM context. Needs GITHUB_TOKEN or GH_TOKEN.")
392
417
  }).default({ pullRequests: true }).describe("Additional context sources for the LLM."),
393
418
  categoryOrder: z.array(z.string()).optional().describe(
394
- "Explicit ordering of categories in the output. Categories not listed retain their configured order after the listed ones."
419
+ "Order of the rendered categories. Listed ones come first; the rest keep their order in categories, except Breaking, which stays first unless listed."
395
420
  ),
396
421
  cache: z.boolean().default(false).describe(
397
422
  "Cache LLM responses on disk (under the OS temp dir), keyed by a hash of the provider, model, prompt, and request options. A re-run or backfill with the same inputs reuses the cached generation instead of re-calling the provider. Off by default."
@@ -420,16 +445,20 @@ var ReleaseNotesConfigSchema = z.object({
420
445
  label: z.string().describe("Link text"),
421
446
  url: z.string().url().describe("Link URL")
422
447
  })
423
- ).optional().describe("Static list of links to append."),
424
- fromPRBodyMarker: z.string().optional().describe("Marker string in PR bodies; content after it is extracted and appended as links."),
425
- title: z.string().optional().describe("Heading for the links section.")
426
- }).optional().describe("Extra links to append to the release notes."),
448
+ ).optional().describe("Static links, each { label, url }, listed first."),
449
+ fromPRBodyMarker: z.string().optional().describe(
450
+ "Also collect links from linked PR bodies: each line starting with this marker adds its markdown link or bare URL, skipping URLs already listed. Needs llm.context.pullRequests."
451
+ ),
452
+ title: z.string().optional().describe("Heading for the links section. Default: Links.")
453
+ }).optional().describe(
454
+ "Links section the built-in renderer appends to each version. Rendered only when the categorize task produced categories."
455
+ ),
427
456
  firstRelease: z.union([
428
457
  z.literal(false).describe("Set to false to disable the first-release placeholder intro."),
429
458
  z.object({
430
459
  text: z.string().optional().describe(
431
460
  // biome-ignore lint/suspicious/noTemplateCurlyInString: documenting placeholder syntax to the user
432
- "Placeholder intro line for a package's first release. Supports ${packageName} and ${version}. Defaults to a factual line so it reads cleanly even when published unedited."
461
+ "Placeholder intro line for a package's first release. Supports ${packageName} and ${version}. Default: '_First release of ${packageName}._'."
433
462
  )
434
463
  })
435
464
  ]).optional().describe(
@@ -441,10 +470,12 @@ var NotesInputConfigSchema = z.object({
441
470
  file: z.string().optional()
442
471
  });
443
472
  var NotesConfigSchema = z.object({
444
- changelog: z.union([z.literal(false).describe("Set to false to disable changelog generation"), ChangelogConfigSchema]).optional(),
445
- releaseNotes: z.union([z.literal(false).describe("Set to false to disable release notes"), ReleaseNotesConfigSchema]).optional(),
473
+ changelog: z.union([z.literal(false).describe("Set to false to disable changelog generation"), ChangelogConfigSchema]).optional().describe("Changelog generation, on by default. Set to false to disable."),
474
+ releaseNotes: z.union([z.literal(false).describe("Set to false to disable release notes"), ReleaseNotesConfigSchema]).optional().describe(
475
+ "Release notes for the GitHub Release body and optional per-version files. Off unless set. {} turns them on using each version's changelog section; set llm or templates to change the content."
476
+ ),
446
477
  updateStrategy: z.enum(["prepend", "regenerate"]).optional().describe(
447
- "How to update existing changelog files. 'prepend' adds new entries to the top; 'regenerate' rewrites the file from scratch."
478
+ "How to update existing changelog files. 'prepend' (the default) adds the new entries at the top; 'regenerate' overwrites the file with this run's output."
448
479
  )
449
480
  });
450
481
  var CILabelsConfigSchema = z.object({
@@ -454,8 +485,10 @@ var CILabelsConfigSchema = z.object({
454
485
  graduatePackagePrefix: z.string().default("graduate:").describe(
455
486
  "Prefix for per-package graduate labels on the standing PR. A `graduate:<package>` label graduates just that prerelease package (and, atomically, any fixed/linked group it belongs to) to its stable base version on the next update, while other prerelease packages stay on their line. The whole-batch `graduate` label still graduates everything. Standing-pr mode only."
456
487
  ),
457
- prerelease: z.string().default("channel:prerelease").describe("Label to create a prerelease"),
458
- skip: z.string().default("release:skip").describe("Label to suppress a release on this PR"),
488
+ prerelease: z.string().default("channel:prerelease").describe("Label that makes the release a prerelease. In label-trigger mode it needs a bump label too."),
489
+ skip: z.string().default("release:skip").describe(
490
+ "Label that stops a merged PR from releasing. Commit-trigger mode only; in label mode, leave off the bump label instead."
491
+ ),
459
492
  immediate: z.string().default("release:immediate").describe("Label to bypass the standing PR for one merge \u2014 triggers a direct release. Standing-pr mode only."),
460
493
  retry: z.string().default("release:retry").describe("Label to retry a failed publish by re-applying it to a merged standing PR. Standing-pr mode only."),
461
494
  previewNotes: z.string().default("release:preview-notes").describe(
@@ -469,18 +502,24 @@ var CILabelsConfigSchema = z.object({
469
502
  )
470
503
  });
471
504
  var StandingPrConfigSchema = z.object({
472
- branch: z.string().default("release/next").describe("Branch name for the standing release PR."),
505
+ branch: z.string().default("release/next").describe(
506
+ "Branch name for the standing release PR. Each update resets it to the base branch and force-pushes it, so don't commit to it."
507
+ ),
473
508
  title: z.string().optional().describe(
474
509
  // biome-ignore lint/suspicious/noTemplateCurlyInString: documenting placeholder syntax to the user
475
- "PR title template. Variables: ${count} (publishable package count), ${version} (raw version), ${tag} (version with tag prefix). Also the release commit's subject, so it must match a release.ci.skipPatterns entry and carry no CI-skip marker. A title with a CI-skip marker is replaced by 'chore: release preparation'. So is one the skip patterns miss, if they match 'chore: release preparation'. The run warns either way. Default depends on the versioning strategy: 'chore: release ${tag}' in sync mode, 'chore: release ${count} package(s)' otherwise."
510
+ "PR title template. Variables: ${count} (publishable package count), ${version} (the first publishable package's new version), ${tag} (version with tag prefix). Also the release commit's subject, so it must match a release.ci.skipPatterns entry and carry no CI-skip marker. A title with a CI-skip marker is replaced by 'chore: release preparation'. So is one the skip patterns miss, if they match 'chore: release preparation'. The run warns either way. Default depends on the versioning strategy: 'chore: release ${tag}' in sync mode, 'chore: release ${count} package(s)' otherwise."
511
+ ),
512
+ labels: z.array(z.string()).default(["release"]).describe(
513
+ "Labels to apply to the standing release PR. Don't include bump, channel, scope or release labels: the standing PR reads its own labels as release overrides."
476
514
  ),
477
- labels: z.array(z.string()).default(["release"]).describe("Labels to apply to the standing release PR."),
478
515
  deleteBranchOnMerge: z.boolean().default(true).describe(
479
516
  "Whether to auto-delete the release branch after the PR is merged. Publish keeps it if an update has moved it since the merge, or if the merged PR's head commit can't be read."
480
517
  ),
481
- mergeMethod: z.enum(["merge", "squash", "rebase"]).default("merge").describe("Merge method to use when merging the standing release PR via CLI."),
518
+ mergeMethod: z.enum(["merge", "squash", "rebase"]).default("merge").describe(
519
+ "Merge method for releasekit standing-pr merge. Use 'squash' or 'rebase' so the release commit's subject reaches the base branch, where release.ci.skipPatterns can match it."
520
+ ),
482
521
  minAge: z.string().optional().describe(
483
- "Minimum age of the standing PR before it can be merged. Duration string, e.g. '6h', '30m', '1d'. Gate enforced via the releasekit/standing-pr commit status check; configure it as a required status check in branch protection to block merges."
522
+ "Minimum age of the standing PR, counted from when it was first opened, before it can be merged. Duration string, e.g. '6h', '30m', '1d'. Gate enforced via the releasekit/standing-pr commit status check; configure it as a required status check in branch protection to block merges."
484
523
  ),
485
524
  minPackages: z.number().int().positive().optional().describe(
486
525
  "Minimum number of packages with releasable changes required to create or maintain the standing PR. Below this threshold the PR is closed and no new PR is opened."
@@ -501,7 +540,7 @@ var StandingPrConfigSchema = z.object({
501
540
  "Refuse to publish the standing PR when the actor who merged it is not authorized (defense-in-depth behind a branch-protection ruleset, which is the primary merge gate). Set false to rely on branch protection alone."
502
541
  )
503
542
  }).optional().describe(
504
- "Restrict who can steer the standing PR \u2014 its selection checkboxes, per-row channel toggles, release labels, and merge. Omit to allow anyone with the GitHub permission GitHub itself requires for each action (today\u2019s behavior)."
543
+ "Restrict who can steer the standing PR \u2014 its selection checkboxes, per-row channel toggles, release labels, and merge. Omit to allow anyone with the GitHub permission GitHub itself requires for each action."
505
544
  ),
506
545
  primaryPackages: z.array(z.string()).default([]).describe(
507
546
  "Packages that drive releases \u2014 rendered as parent rows in the standing-PR selection list, with their coupled group-mates and changed prerequisites nested beneath, so one parent toggle holds back the whole release unit. Glob patterns or exact names. Empty (default) \u2192 flat per-package list (current behavior)."
@@ -510,7 +549,7 @@ var StandingPrConfigSchema = z.object({
510
549
  "How the selection list renders when primaryPackages is set. streamlined: one checkbox per primary, coupled members shown read-only in a collapsed pane, and a held-back primary cascades to its unit. granular: every package keeps its own checkbox, nested under its primary, with no cascade. No effect when primaryPackages is empty."
511
550
  ),
512
551
  combinedChangelogFooter: z.boolean().default(true).describe(
513
- "Append the de-duplicated combined-changelog footer to the standing PR: every change listed once, flat across packages and grouped by change type (Added/Fixed/Changed). It complements the per-row changelogs co-located with each releasable row. Set false to suppress this redundant per-package summary \u2014 the per-row changelogs remain, project-wide (shared) changes are still shown in their own block, and sync releases (which have no per-row changelogs) always show the combined changelog regardless of this setting."
552
+ "Append the de-duplicated combined-changelog footer to the standing PR: every change listed once, flat across packages and grouped by change type (Added/Fixed/Changed), breaking changes first. It complements the per-row changelogs co-located with each releasable row. Set false to suppress this redundant per-package summary \u2014 the per-row changelogs remain, project-wide (shared) changes are still shown in their own block, and sync releases (which have no per-row changelogs) always show the combined changelog regardless of this setting."
514
553
  ),
515
554
  channelToggle: z.boolean().default(false).describe(
516
555
  "Add a per-row channel toggle to the standing-PR selection list: a nested checkbox under each releasable row to ship a stable package as a prerelease (\u2192 X.Y.Z-next.0 on the `next` dist-tag) or graduate a prerelease package to its stable base \u2014 shifting just that package (and its group) without narrowing the release. Off by default so repos that do not need it keep the tight one-line-per-package list. A held-back (unticked) row hides its channel toggle. No effect on sync releases (which ship atomically as one unit)."
@@ -530,14 +569,14 @@ var CIConfigSchema = z.object({
530
569
  z.boolean(),
531
570
  z.object({
532
571
  enabled: z.boolean().default(true).describe("Whether PR preview comments are posted."),
533
- refreshAfterRelease: z.boolean().default(false).describe(
534
- 'After a release completes, replay the preview comment on still-open feeder PRs so their "what would release" estimate is not left stale against the moved baseline. Cosmetic and best-effort \u2014 a failure here never fails the release. Driven automatically in-process after a successful release (both the direct and standing-PR publish paths); the standalone `refresh-after-release` command also performs it for setups that run it as a separate step.'
572
+ markStaleAfterRelease: z.boolean().default(false).describe(
573
+ "After a standing-PR publish, or a `releasekit release` that pushes the release branch, mark the preview on open PRs into that branch as stale until the PR's next push or label change. `releasekit publish` on its own doesn't. Best-effort: a failure never fails the release."
535
574
  )
536
575
  })
537
576
  ]).default(true).transform(
538
- (v) => typeof v === "boolean" ? { enabled: v, refreshAfterRelease: false } : { enabled: v.enabled ?? true, refreshAfterRelease: v.refreshAfterRelease ?? false }
577
+ (v) => typeof v === "boolean" ? { enabled: v, markStaleAfterRelease: false } : { enabled: v.enabled ?? true, markStaleAfterRelease: v.markStaleAfterRelease ?? false }
539
578
  ).describe(
540
- "PR preview comments showing what would be released if the PR is merged. `true`/`false` toggles them; the object form additionally enables `refreshAfterRelease` to refresh feeder-PR previews after a release."
579
+ "PR preview comments showing what would be released if the PR is merged. `true`/`false` toggles them; the object form additionally enables `markStaleAfterRelease` to mark feeder-PR previews stale after a release."
541
580
  ),
542
581
  labels: CILabelsConfigSchema.default({
543
582
  graduate: "release:graduate",
@@ -560,7 +599,9 @@ var CIConfigSchema = z.object({
560
599
  )
561
600
  });
562
601
  var ReleaseCIConfigSchema = z.object({
563
- skipPatterns: z.array(z.string().min(1)).optional().describe("Commit message prefixes that prevent a release (e.g. 'chore(deps):', 'ci:')"),
602
+ skipPatterns: z.array(z.string().min(1)).optional().describe(
603
+ "Strings that skip a release, gate run or standing-PR update when found anywhere in the HEAD commit's subject. When unset, only standing-PR updates skip, and only on 'chore: release '."
604
+ ),
564
605
  minChanges: z.number().int().positive().optional().describe("Minimum number of packages with releasable changes required to trigger a release"),
565
606
  githubRelease: z.literal(false).optional().describe("Set to false to disable GitHub release creation in CI"),
566
607
  notes: z.literal(false).optional().describe("Set to false to disable changelog generation in CI")
@@ -710,6 +751,11 @@ function assertNoRemovedTopLevelFields(config) {
710
751
  `ci no longer supports ${removed.join(", ")}. autoRelease was removed (it had no effect); skipPatterns and minChanges live under release.ci (release.ci.skipPatterns / release.ci.minChanges).`
711
752
  );
712
753
  }
754
+ if (isRecord(config.ci.prPreview) && "refreshAfterRelease" in config.ci.prPreview) {
755
+ throw new ConfigError(
756
+ "ci.prPreview.refreshAfterRelease was renamed to markStaleAfterRelease. It now marks open PRs' previews stale after a release instead of recomputing them."
757
+ );
758
+ }
713
759
  }
714
760
  if (isRecord(config.monorepo) && "mainPackage" in config.monorepo) {
715
761
  throw new ConfigError("monorepo.mainPackage was removed \u2014 use version.mainPackage instead.");
@@ -762,6 +808,10 @@ var InputParseError = class extends NotesError {
762
808
  "Use --input-source to specify format"
763
809
  ];
764
810
  };
811
+ var InputValidationError = class extends NotesError {
812
+ code = "INPUT_VALIDATION_ERROR";
813
+ suggestions = ["Pass `releasekit version --json` output unchanged"];
814
+ };
765
815
  var TemplateError = class extends NotesError {
766
816
  code = "TEMPLATE_ERROR";
767
817
  suggestions = [
@@ -809,6 +859,7 @@ function getExitCode(error2) {
809
859
  case "CONFIG_ERROR":
810
860
  return EXIT_CODES.CONFIG_ERROR;
811
861
  case "INPUT_PARSE_ERROR":
862
+ case "INPUT_VALIDATION_ERROR":
812
863
  return EXIT_CODES.INPUT_ERROR;
813
864
  case "TEMPLATE_ERROR":
814
865
  return EXIT_CODES.TEMPLATE_ERROR;
@@ -823,6 +874,44 @@ function getExitCode(error2) {
823
874
 
824
875
  // src/input/version-output.ts
825
876
  import * as fs5 from "fs";
877
+
878
+ // ../core/dist/version-output-schema.js
879
+ import { z as z3 } from "zod";
880
+ var VersionChangelogEntrySchema = z3.looseObject({
881
+ type: z3.string(),
882
+ description: z3.string(),
883
+ issueIds: z3.array(z3.string()).optional(),
884
+ prNumber: z3.string().optional(),
885
+ scope: z3.string().optional(),
886
+ originalType: z3.string().optional(),
887
+ breaking: z3.boolean().optional()
888
+ });
889
+ var VersionPackageChangelogSchema = z3.looseObject({
890
+ packageName: z3.string(),
891
+ version: z3.string(),
892
+ previousVersion: z3.string().nullable(),
893
+ revisionRange: z3.string(),
894
+ repoUrl: z3.string().nullable(),
895
+ entries: z3.array(VersionChangelogEntrySchema)
896
+ });
897
+ var VersionPackageUpdateSchema = z3.looseObject({
898
+ packageName: z3.string(),
899
+ newVersion: z3.string(),
900
+ filePath: z3.string(),
901
+ files: z3.array(z3.string()).optional(),
902
+ tag: z3.string().optional()
903
+ });
904
+ var VersionOutputSchema = z3.looseObject({
905
+ dryRun: z3.boolean(),
906
+ updates: z3.array(VersionPackageUpdateSchema),
907
+ changelogs: z3.array(VersionPackageChangelogSchema),
908
+ commitMessage: z3.string().optional(),
909
+ tags: z3.array(z3.string()),
910
+ baselineTags: z3.array(z3.string()).optional()
911
+ });
912
+
913
+ // src/input/version-output.ts
914
+ var NotesVersionOutputSchema = VersionOutputSchema.pick({ changelogs: true });
826
915
  function normalizeEntryType(type) {
827
916
  const typeMap = {
828
917
  added: "added",
@@ -882,7 +971,13 @@ function parseVersionOutput(json) {
882
971
  } catch (error2) {
883
972
  throw new InputParseError(error2 instanceof Error ? error2.message : String(error2));
884
973
  }
885
- return versionOutputToChangelogInput(data);
974
+ const result = NotesVersionOutputSchema.safeParse(data);
975
+ if (!result.success) {
976
+ const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
977
+ throw new InputValidationError(`Version output failed schema validation:
978
+ ${issues}`);
979
+ }
980
+ return versionOutputToChangelogInput(result.data);
886
981
  }
887
982
  function parseVersionOutputFile(filePath) {
888
983
  const content = fs5.readFileSync(filePath, "utf-8");
@@ -981,11 +1076,10 @@ function isBotComment(comment) {
981
1076
  if (!user) {
982
1077
  return true;
983
1078
  }
984
- return user.type === "Bot" || user.login !== void 0 && user.login.endsWith("[bot]");
1079
+ return user.type === "Bot" || user.login?.endsWith("[bot]") === true;
985
1080
  }
986
1081
  var REPO_PERMISSIONS = ["admin", "maintain", "write", "triage", "read", "none"];
987
1082
  var MAX_RELEASE_PAGES = 3;
988
- var MAX_OPEN_PR_PAGES = 5;
989
1083
  function labelNames(labels) {
990
1084
  return (labels ?? []).map((label) => typeof label === "string" ? label : label.name ?? "");
991
1085
  }
@@ -1039,25 +1133,27 @@ var GitHubForge = class {
1039
1133
  });
1040
1134
  return data.map((pr) => ({ number: pr.number, mergedAt: pr.merged_at }));
1041
1135
  }
1042
- async listOpenPullRequests() {
1136
+ async listOpenPullRequests(base, limit) {
1043
1137
  const prs = [];
1044
- for (let page = 1; page <= MAX_OPEN_PR_PAGES; page++) {
1138
+ const perPage = Math.min(limit, 100);
1139
+ for (let page = 1; prs.length < limit; page++) {
1045
1140
  const { data } = await this.octokit.rest.pulls.list({
1046
1141
  ...this.base,
1047
1142
  state: "open",
1143
+ base,
1048
1144
  sort: "updated",
1049
1145
  direction: "desc",
1050
- per_page: 100,
1146
+ per_page: perPage,
1051
1147
  page
1052
1148
  });
1053
1149
  for (const pr of data) {
1054
- prs.push({ number: pr.number, headRef: pr.head.ref, draft: pr.draft ?? false, baseSha: pr.base.sha });
1150
+ prs.push({ number: pr.number, headRef: pr.head.ref, baseRef: pr.base.ref });
1055
1151
  }
1056
- if (data.length < 100) {
1152
+ if (data.length < perPage) {
1057
1153
  break;
1058
1154
  }
1059
1155
  }
1060
- return prs;
1156
+ return prs.slice(0, limit);
1061
1157
  }
1062
1158
  async getIssue(issueNumber) {
1063
1159
  const { data } = await this.octokit.rest.issues.get({ ...this.base, issue_number: issueNumber });
@@ -1070,7 +1166,13 @@ var GitHubForge = class {
1070
1166
  }
1071
1167
  async getPullRequest(prNumber) {
1072
1168
  const { data } = await this.octokit.rest.pulls.get({ ...this.base, pull_number: prNumber });
1073
- return { body: data.body ?? "", labels: labelNames(data.labels), headSha: data.head?.sha };
1169
+ return {
1170
+ body: data.body ?? "",
1171
+ labels: labelNames(data.labels),
1172
+ headSha: data.head?.sha,
1173
+ headRef: data.head?.ref,
1174
+ baseRef: data.base?.ref
1175
+ };
1074
1176
  }
1075
1177
  async createPullRequest(pr) {
1076
1178
  const { data } = await this.octokit.rest.pulls.create({ ...this.base, ...pr });
@@ -2148,23 +2250,23 @@ ${instructions}`;
2148
2250
  }
2149
2251
 
2150
2252
  // src/llm/schemas.ts
2151
- import { z as z3 } from "zod";
2152
- var EntryOutputSchema = z3.object({
2153
- description: z3.string(),
2154
- category: z3.string(),
2155
- scope: z3.string().nullable(),
2156
- breaking: z3.boolean().nullable(),
2157
- leadIn: z3.string().nullable()
2253
+ import { z as z4 } from "zod";
2254
+ var EntryOutputSchema = z4.object({
2255
+ description: z4.string(),
2256
+ category: z4.string(),
2257
+ scope: z4.string().nullable(),
2258
+ breaking: z4.boolean().nullable(),
2259
+ leadIn: z4.string().nullable()
2158
2260
  });
2159
- var EnhanceAndCategorizeOutputSchema = z3.object({
2160
- entries: z3.array(EntryOutputSchema)
2261
+ var EnhanceAndCategorizeOutputSchema = z4.object({
2262
+ entries: z4.array(EntryOutputSchema)
2161
2263
  });
2162
- var CategorizeEntryOutputSchema = z3.object({
2163
- category: z3.string(),
2164
- scope: z3.string().nullable()
2264
+ var CategorizeEntryOutputSchema = z4.object({
2265
+ category: z4.string(),
2266
+ scope: z4.string().nullable()
2165
2267
  });
2166
- var CategorizeOutputSchema = z3.object({
2167
- entries: z3.array(CategorizeEntryOutputSchema)
2268
+ var CategorizeOutputSchema = z4.object({
2269
+ entries: z4.array(CategorizeEntryOutputSchema)
2168
2270
  });
2169
2271
  function nullableString() {
2170
2272
  return { anyOf: [{ type: "string" }, { type: "null" }] };
@@ -3364,7 +3466,7 @@ async function runPipeline(input, config, dryRun, pipelineOptions) {
3364
3466
  const dir = releaseNotesConfig.file.dir;
3365
3467
  info(`Generating release notes \u2192 ${dir}`);
3366
3468
  try {
3367
- const { detectMonorepo } = await import("./aggregator-DYYIWNIK.js");
3469
+ const { detectMonorepo } = await import("./aggregator-SCGIHWXW.js");
3368
3470
  const nested = detectMonorepo(process.cwd()).isMonorepo || contexts.length > 1;
3369
3471
  const renderContent = (ctx) => {
3370
3472
  if (releaseNotesConfig.templates?.path) {
@@ -3428,7 +3530,7 @@ async function processInput(inputJson, config, dryRun, pipelineOptions) {
3428
3530
  return runPipeline(input, config, dryRun, pipelineOptions);
3429
3531
  }
3430
3532
  async function writeMonorepoFiles(contexts, config, dryRun, fileName, refs) {
3431
- const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-DYYIWNIK.js");
3533
+ const { detectMonorepo, writeMonorepoChangelogs } = await import("./aggregator-SCGIHWXW.js");
3432
3534
  const cwd = process.cwd();
3433
3535
  const detected = detectMonorepo(cwd);
3434
3536
  if (!detected.isMonorepo) {
@@ -3657,6 +3759,7 @@ export {
3657
3759
  saveAuth,
3658
3760
  NotesError,
3659
3761
  InputParseError,
3762
+ InputValidationError,
3660
3763
  TemplateError,
3661
3764
  LLMError,
3662
3765
  GitHubError,