@intentius/chant 0.124.77 → 0.124.79

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 (228) hide show
  1. package/dist/__fixtures__/notify-messages/events.d.ts +9 -0
  2. package/dist/__fixtures__/notify-messages/events.d.ts.map +1 -0
  3. package/dist/__fixtures__/notify-messages/events.js +21 -0
  4. package/dist/__fixtures__/product-words.d.ts +14 -0
  5. package/dist/__fixtures__/product-words.d.ts.map +1 -1
  6. package/dist/__fixtures__/product-words.js +11 -0
  7. package/dist/__fixtures__/terragucci-notify.d.ts +66 -0
  8. package/dist/__fixtures__/terragucci-notify.d.ts.map +1 -0
  9. package/dist/__fixtures__/terragucci-notify.js +133 -0
  10. package/dist/action-pins.d.ts +8 -0
  11. package/dist/action-pins.d.ts.map +1 -1
  12. package/dist/action-pins.js +8 -0
  13. package/dist/agent-guard.d.ts.map +1 -1
  14. package/dist/agent-guard.js +1 -2
  15. package/dist/change-set.d.ts +10 -1
  16. package/dist/change-set.d.ts.map +1 -1
  17. package/dist/change-set.js +4 -1
  18. package/dist/ci-agent.d.ts +16 -2
  19. package/dist/ci-agent.d.ts.map +1 -1
  20. package/dist/ci-agent.js +6 -1
  21. package/dist/ci-commit.d.ts +66 -2
  22. package/dist/ci-commit.d.ts.map +1 -1
  23. package/dist/ci-commit.js +147 -19
  24. package/dist/ci-own-jobs.d.ts.map +1 -1
  25. package/dist/ci-own-jobs.js +1 -2
  26. package/dist/ci-product-words.d.ts +18 -4
  27. package/dist/ci-product-words.d.ts.map +1 -1
  28. package/dist/ci-product-words.js +26 -6
  29. package/dist/ci-product.d.ts +7 -3
  30. package/dist/ci-product.d.ts.map +1 -1
  31. package/dist/ci-product.js +8 -5
  32. package/dist/cli/handlers/release.d.ts +8 -0
  33. package/dist/cli/handlers/release.d.ts.map +1 -1
  34. package/dist/cli/handlers/release.js +68 -6
  35. package/dist/cli/handlers/run-wave.js +1 -0
  36. package/dist/cli/main.d.ts.map +1 -1
  37. package/dist/cli/main.js +7 -0
  38. package/dist/cli/mcp/product-tools.d.ts +6 -0
  39. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  40. package/dist/cli/mcp/product-tools.js +7 -0
  41. package/dist/cli/mcp/read-only.d.ts +12 -0
  42. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  43. package/dist/cli/mcp/read-only.js +16 -0
  44. package/dist/cli/mcp/server.d.ts +11 -0
  45. package/dist/cli/mcp/server.d.ts.map +1 -1
  46. package/dist/cli/mcp/server.js +26 -5
  47. package/dist/cli/mcp/types.d.ts +5 -1
  48. package/dist/cli/mcp/types.d.ts.map +1 -1
  49. package/dist/components/capability.d.ts +42 -0
  50. package/dist/components/capability.d.ts.map +1 -1
  51. package/dist/components/group-digest.d.ts +17 -0
  52. package/dist/components/group-digest.d.ts.map +1 -0
  53. package/dist/components/group-digest.js +18 -0
  54. package/dist/components/groups.d.ts +2 -11
  55. package/dist/components/groups.d.ts.map +1 -1
  56. package/dist/components/groups.js +2 -12
  57. package/dist/components/index.d.ts +1 -1
  58. package/dist/components/index.d.ts.map +1 -1
  59. package/dist/components/pr-env-components.d.ts.map +1 -1
  60. package/dist/components/pr-env-components.js +1 -2
  61. package/dist/config.d.ts +28 -8
  62. package/dist/config.d.ts.map +1 -1
  63. package/dist/config.js +21 -1
  64. package/dist/lexicon.d.ts +8 -0
  65. package/dist/lexicon.d.ts.map +1 -1
  66. package/dist/lexicon.js +8 -0
  67. package/dist/lifecycle/release-cut.d.ts +7 -1
  68. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  69. package/dist/lifecycle/release-cut.js +1 -0
  70. package/dist/lifecycle/release-images.d.ts +86 -3
  71. package/dist/lifecycle/release-images.d.ts.map +1 -1
  72. package/dist/lifecycle/release-images.js +131 -6
  73. package/dist/lifecycle/release-publish.d.ts +8 -1
  74. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  75. package/dist/lifecycle/release-publish.js +30 -3
  76. package/dist/lifecycle/release-version.d.ts +86 -0
  77. package/dist/lifecycle/release-version.d.ts.map +1 -0
  78. package/dist/lifecycle/release-version.js +209 -0
  79. package/dist/mcp/types.d.ts +26 -0
  80. package/dist/mcp/types.d.ts.map +1 -1
  81. package/dist/notify-product.d.ts +11 -2
  82. package/dist/notify-product.d.ts.map +1 -1
  83. package/dist/notify-product.js +15 -4
  84. package/dist/notify-relay.d.ts.map +1 -1
  85. package/dist/notify-relay.js +1 -2
  86. package/dist/notify.d.ts +36 -4
  87. package/dist/notify.d.ts.map +1 -1
  88. package/dist/notify.js +31 -21
  89. package/dist/notify.schema.json +1 -0
  90. package/dist/op/activities/review-product.d.ts +111 -0
  91. package/dist/op/activities/review-product.d.ts.map +1 -0
  92. package/dist/op/activities/review-product.js +115 -0
  93. package/dist/op/gate.d.ts +17 -0
  94. package/dist/op/gate.d.ts.map +1 -1
  95. package/dist/op/gate.js +36 -0
  96. package/dist/op/index.d.ts +8 -6
  97. package/dist/op/index.d.ts.map +1 -1
  98. package/dist/op/index.js +5 -4
  99. package/dist/op/op-waves-after-plan.d.ts +76 -1
  100. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  101. package/dist/op/op-waves-after-plan.js +142 -3
  102. package/dist/op/op-waves-capability-spec.js +1 -2
  103. package/dist/op/op-waves-capability.d.ts +89 -2
  104. package/dist/op/op-waves-capability.d.ts.map +1 -1
  105. package/dist/op/op-waves-capability.js +215 -7
  106. package/dist/op/op-waves-run-hooks.d.ts +104 -0
  107. package/dist/op/op-waves-run-hooks.d.ts.map +1 -0
  108. package/dist/op/op-waves-run-hooks.js +146 -0
  109. package/dist/op/op-waves-run.d.ts +21 -0
  110. package/dist/op/op-waves-run.d.ts.map +1 -1
  111. package/dist/op/op-waves-run.js +233 -13
  112. package/dist/op/op-waves.d.ts +11 -1
  113. package/dist/op/op-waves.d.ts.map +1 -1
  114. package/dist/op/op-waves.js +7 -1
  115. package/dist/op/runtime.d.ts +2 -0
  116. package/dist/op/runtime.d.ts.map +1 -1
  117. package/dist/policy-engine.d.ts.map +1 -1
  118. package/dist/policy-engine.js +1 -2
  119. package/dist/pr-forge-reads.d.ts +124 -0
  120. package/dist/pr-forge-reads.d.ts.map +1 -0
  121. package/dist/pr-forge-reads.js +322 -0
  122. package/dist/pr-forge.d.ts +14 -0
  123. package/dist/pr-forge.d.ts.map +1 -1
  124. package/dist/pr-forge.js +21 -13
  125. package/dist/pr-plan-note.d.ts +293 -0
  126. package/dist/pr-plan-note.d.ts.map +1 -0
  127. package/dist/pr-plan-note.js +361 -0
  128. package/dist/release-floors.d.ts +13 -1
  129. package/dist/release-floors.d.ts.map +1 -1
  130. package/dist/release-floors.js +13 -1
  131. package/dist/state-export.d.ts.map +1 -1
  132. package/dist/state-export.js +1 -2
  133. package/dist/state-migration.d.ts.map +1 -1
  134. package/dist/state-migration.js +1 -2
  135. package/dist/state-unlock.d.ts.map +1 -1
  136. package/dist/state-unlock.js +1 -2
  137. package/dist/wave-runtime.mjs +314 -314
  138. package/dist/workspace/change-set.schema.json +7 -0
  139. package/dist/workspace/release-workflow.d.ts +7 -0
  140. package/dist/workspace/release-workflow.d.ts.map +1 -1
  141. package/dist/workspace/release-workflow.js +13 -2
  142. package/package.json +1 -1
  143. package/src/__fixtures__/notify-messages/events.ts +23 -0
  144. package/src/__fixtures__/notify-messages/messages.json +50 -0
  145. package/src/__fixtures__/pr-loop/terragucci-plan.note.golden.md +53 -0
  146. package/src/__fixtures__/pr-loop/terragucci-plan.note.json +83 -0
  147. package/src/__fixtures__/product-words.ts +12 -0
  148. package/src/__fixtures__/review-agent/terragucci-review.json +94 -0
  149. package/src/__fixtures__/terragucci-notify.ts +170 -0
  150. package/src/action-pins.test.ts +11 -1
  151. package/src/action-pins.ts +9 -0
  152. package/src/agent-guard.test.ts +1 -2
  153. package/src/agent-guard.ts +1 -2
  154. package/src/change-set.test.ts +20 -0
  155. package/src/change-set.ts +11 -1
  156. package/src/ci-agent.test.ts +9 -0
  157. package/src/ci-agent.ts +15 -2
  158. package/src/ci-commit.test.ts +162 -0
  159. package/src/ci-commit.ts +167 -21
  160. package/src/ci-own-jobs.test.ts +1 -2
  161. package/src/ci-own-jobs.ts +1 -2
  162. package/src/ci-product-words.ts +35 -7
  163. package/src/ci-product.ts +9 -6
  164. package/src/cli/handlers/build-pr-loop-control.test.ts +1 -2
  165. package/src/cli/handlers/build-run-group.test.ts +1 -2
  166. package/src/cli/handlers/release.ts +60 -7
  167. package/src/cli/handlers/run-wave.ts +1 -0
  168. package/src/cli/main.ts +7 -0
  169. package/src/cli/mcp/product-tools.test.ts +50 -0
  170. package/src/cli/mcp/product-tools.ts +8 -0
  171. package/src/cli/mcp/read-only.ts +19 -0
  172. package/src/cli/mcp/server.test.ts +30 -0
  173. package/src/cli/mcp/server.ts +28 -5
  174. package/src/cli/mcp/types.ts +6 -1
  175. package/src/components/capability.ts +41 -0
  176. package/src/components/group-digest.ts +20 -0
  177. package/src/components/groups.ts +3 -13
  178. package/src/components/index.ts +2 -0
  179. package/src/components/pr-env-components.test.ts +1 -2
  180. package/src/components/pr-env-components.ts +1 -2
  181. package/src/config.ts +38 -3
  182. package/src/gate-policy-bundle.test.ts +1 -1
  183. package/src/lexicon.ts +9 -0
  184. package/src/lifecycle/release-cut.ts +11 -0
  185. package/src/lifecycle/release-images-dockerfile.test.ts +229 -0
  186. package/src/lifecycle/release-images.ts +171 -8
  187. package/src/lifecycle/release-publish.ts +34 -3
  188. package/src/lifecycle/release-version.test.ts +155 -0
  189. package/src/lifecycle/release-version.ts +227 -0
  190. package/src/mcp/types.ts +27 -0
  191. package/src/notify-message-words.test.ts +185 -0
  192. package/src/notify-product.ts +16 -4
  193. package/src/notify-relay.ts +1 -2
  194. package/src/notify.schema.json +1 -0
  195. package/src/notify.ts +59 -19
  196. package/src/op/activities/review-product.test.ts +116 -0
  197. package/src/op/activities/review-product.ts +199 -0
  198. package/src/op/gate.ts +46 -0
  199. package/src/op/index.ts +10 -4
  200. package/src/op/op-waves-after-plan-wave.test.ts +226 -0
  201. package/src/op/op-waves-after-plan.ts +170 -5
  202. package/src/op/op-waves-capability-spec.ts +1 -1
  203. package/src/op/op-waves-capability.test.ts +6 -0
  204. package/src/op/op-waves-capability.ts +243 -10
  205. package/src/op/op-waves-run-hooks.test.ts +184 -0
  206. package/src/op/op-waves-run-hooks.ts +195 -0
  207. package/src/op/op-waves-run.ts +240 -16
  208. package/src/op/op-waves-step-wave.test.ts +277 -0
  209. package/src/op/op-waves.ts +15 -2
  210. package/src/op/runtime.ts +2 -0
  211. package/src/op/schedule-overdue.test.ts +26 -0
  212. package/src/policy-engine.test.ts +1 -2
  213. package/src/policy-engine.ts +1 -2
  214. package/src/pr-forge-reads.test.ts +285 -0
  215. package/src/pr-forge-reads.ts +424 -0
  216. package/src/pr-forge.ts +30 -16
  217. package/src/pr-plan-note.test.ts +105 -0
  218. package/src/pr-plan-note.ts +520 -0
  219. package/src/release-floors.ts +19 -1
  220. package/src/state-export.test.ts +1 -2
  221. package/src/state-export.ts +1 -2
  222. package/src/state-migration.test.ts +1 -2
  223. package/src/state-migration.ts +1 -2
  224. package/src/state-unlock.test.ts +1 -2
  225. package/src/state-unlock.ts +1 -2
  226. package/src/workspace/change-set.schema.json +7 -0
  227. package/src/workspace/release-workflow.test.ts +18 -0
  228. package/src/workspace/release-workflow.ts +23 -2
@@ -114,12 +114,17 @@ async function laneOf(ctx: CommandContext, cwd: string): Promise<string | undefi
114
114
  }
115
115
  }
116
116
 
117
- /** The member's `release.images` (#4657), or none when the config declares none. */
118
- async function releaseImagesOf(cwd: string): Promise<Array<{ name: string; build: string; archive: string }>> {
117
+ /** The member's `release.images` (#4657), or none when the config declares none. A Dockerfile entry (#4819) keeps its form, so its prepare command runs. */
118
+ async function releaseImagesOf(cwd: string): Promise<import("../../lifecycle/release-images").ReleaseImageDeclaration[]> {
119
119
  const { loadChantConfig } = await import("../../config");
120
120
  return (await loadChantConfig(cwd)).config.release?.images ?? [];
121
121
  }
122
122
 
123
+ async function releaseVersionOf(cwd: string): Promise<import("../../lifecycle/release-version").ReleaseVersionConfig | undefined> {
124
+ const { loadChantConfig } = await import("../../config");
125
+ return (await loadChantConfig(cwd)).config.release?.version;
126
+ }
127
+
123
128
  /** Copy each `release.images` archive from the directory the cut built it in to the same path under `to`. */
124
129
  export function copyImageArchives(images: ReadonlyArray<{ archive: string }>, from: string, to: string): void {
125
130
  for (const i of images) {
@@ -155,7 +160,7 @@ export async function runReleaseImages(ctx: CommandContext): Promise<number> {
155
160
  if (!ref) return fail("release-not-named", "release images needs a release, by label or digest", USAGE);
156
161
  const cwd = resolve(".");
157
162
  const { resolveRelease } = await import("../../lifecycle/release-store");
158
- const { buildReleaseImages, releaseImageDigests, writeReleaseDigests, ReleaseImageError, RELEASE_DIGESTS_ENV } = await import("../../lifecycle/release-images");
163
+ const { buildReleaseImages, releaseImageDigests, resolveReleaseImages, writeReleaseDigests, ReleaseImageError, RELEASE_DIGESTS_ENV } = await import("../../lifecycle/release-images");
159
164
  const { ociArchiveDigest } = await import("../../lifecycle/publish-oci");
160
165
  const { getHeadCommit } = await import("../../lifecycle/git");
161
166
  const found = await resolveRelease(ref, { cwd });
@@ -171,12 +176,12 @@ export async function runReleaseImages(ctx: CommandContext): Promise<number> {
171
176
  try {
172
177
  // --no-build: the archives the cut built were handed to this job, so they are read as they are.
173
178
  built = args.noBuild
174
- ? declared.map((d) => {
179
+ ? resolveReleaseImages(declared).map((d) => {
175
180
  const abs = resolve(cwd, d.archive);
176
181
  if (!existsSync(abs)) throw new ReleaseImageError("release-image-no-archive", `image "${d.name}" has no archive at ${d.archive}`, "Hand this job the archives the cut built, or run without --no-build to build them again.");
177
182
  return { component: d.name, kind: "image" as const, path: d.archive, digest: ociArchiveDigest(abs) };
178
183
  })
179
- : buildReleaseImages({ images: declared, cwd, sourceDateEpoch: commitTime(cwd, release.commit), label, archiveDigest: ociArchiveDigest });
184
+ : buildReleaseImages({ images: declared, cwd, sourceDateEpoch: commitTime(cwd, release.commit), label, archiveDigest: ociArchiveDigest, ...((await releaseVersionOf(cwd)) ? { versionArg: true } : {}) });
180
185
  } catch (err) {
181
186
  if (err instanceof ReleaseImageError) return fail(err.code, err.message, err.fix);
182
187
  throw err;
@@ -200,6 +205,38 @@ export async function runReleaseImages(ctx: CommandContext): Promise<number> {
200
205
  return 0;
201
206
  }
202
207
 
208
+ /**
209
+ * `release stamp <label> [--json]` (#4840): write the label into the files
210
+ * `release.version` names, as the cut does before its build, and leave them
211
+ * so. The publish job runs it before its build; `chant release publish`
212
+ * takes those files, stamped with the release's label, as the commit's.
213
+ * `git checkout -- <files>` puts them back.
214
+ */
215
+ export async function runReleaseStamp(ctx: CommandContext): Promise<number> {
216
+ const { args } = ctx;
217
+ const label = args.extraPositional ?? null;
218
+ const fail = (code: string, message: string, fix?: string): number => {
219
+ if (args.json) console.log(JSON.stringify({ label, error: { code, message, ...(fix ? { fix } : {}) } }, null, 2));
220
+ else console.error(formatError({ message: `${message} [${code}]`, ...(fix ? { hint: fix } : {}) }));
221
+ return 1;
222
+ };
223
+ if (label === null) return fail("release-version-no-label", "release stamp needs the release's label", "chant release stamp <label> [--json]");
224
+ const cwd = resolve(".");
225
+ const config = await releaseVersionOf(cwd);
226
+ if (!config) return fail("release-version-not-declared", "this member's chant.config.ts has no release.version, so there is nothing to stamp", "Name the package directories: release: { version: { packages: [\"packages/cli\"] } }");
227
+ const { stampReleaseVersion, ReleaseVersionError } = await import("../../lifecycle/release-version");
228
+ let files: string[];
229
+ try {
230
+ files = stampReleaseVersion({ cwd, config, label }).files;
231
+ } catch (err) {
232
+ if (err instanceof ReleaseVersionError) return fail(err.code, err.message, err.fix);
233
+ throw err;
234
+ }
235
+ if (args.json) console.log(JSON.stringify({ label, files }, null, 2));
236
+ else console.error(formatSuccess(`Stamped ${label} into ${files.join(", ")}`));
237
+ return 0;
238
+ }
239
+
203
240
  function describeActorSource(source: import("../../lifecycle/release-workstation").ActorSource): string {
204
241
  switch (source) {
205
242
  case "flag":
@@ -259,6 +296,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
259
296
  };
260
297
  const at = await import("../../lifecycle/release-at");
261
298
  let checkout: import("../../lifecycle/release-at").CommitCheckout | null = null;
299
+ let stamped: import("../../lifecycle/release-version").Stamped | null = null;
262
300
 
263
301
  try {
264
302
  // The workstation checks come first, in the order #4027 lists them; the
@@ -352,6 +390,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
352
390
  // --at: the cut reads, compiles and builds the commit's tree, not the checkout's.
353
391
  if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
354
392
  const cutCwd = checkout?.memberDir ?? cwd;
393
+ const versionConfig = await releaseVersionOf(cutCwd);
355
394
  // #4657: the images release.images declares are built first, and their digests handed to the build command.
356
395
  const declaredImages = await releaseImagesOf(cutCwd);
357
396
  const digestsFile = declaredImages.length > 0 ? join(tmpdir(), `chant-release-digests-${process.pid}.json`) : undefined;
@@ -361,7 +400,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
361
400
  const { buildReleaseImages, writeReleaseDigests, ReleaseImageError } = await import("../../lifecycle/release-images");
362
401
  const { ociArchiveDigest } = await import("../../lifecycle/publish-oci");
363
402
  try {
364
- const built = buildReleaseImages({ images: declaredImages, cwd: cutCwd, sourceDateEpoch: commitTime(cutCwd, at), label, archiveDigest: ociArchiveDigest });
403
+ const built = buildReleaseImages({ images: declaredImages, cwd: cutCwd, sourceDateEpoch: commitTime(cutCwd, at), label, archiveDigest: ociArchiveDigest, ...(versionConfig ? { versionArg: true } : {}) });
365
404
  writeReleaseDigests(digestsFile, Object.fromEntries(built.map((a) => [a.component, a.digest])));
366
405
  return built;
367
406
  } catch (err) {
@@ -371,6 +410,18 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
371
410
  }
372
411
  }
373
412
  : undefined;
413
+ // #4840: release.version stamps the label into package.json once the cut has found the tree clean.
414
+ const stamp = versionConfig
415
+ ? async () => {
416
+ const { stampReleaseVersion, ReleaseVersionError } = await import("../../lifecycle/release-version");
417
+ try {
418
+ if (!stamped) stamped = stampReleaseVersion({ cwd: cutCwd, config: versionConfig, label });
419
+ } catch (err) {
420
+ if (err instanceof ReleaseVersionError) throw new ReleaseCutError(err.code as import("../../lifecycle/release-cut").ReleaseCutCode, `no release was cut: ${err.message}`, err.fix);
421
+ throw err;
422
+ }
423
+ }
424
+ : undefined;
374
425
  // #4692: the lane is the commit's own config's under --at.
375
426
  const lane = await laneOf(ctx, cutCwd);
376
427
  const request = {
@@ -385,6 +436,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
385
436
  ...(args.overrideGreen ? { overrideGreen: true } : {}),
386
437
  ...(Object.keys(images).length > 0 ? { images } : {}),
387
438
  ...(buildImages ? { buildImages } : {}),
439
+ ...(stamp ? { stamp } : {}),
388
440
  };
389
441
 
390
442
  if (dryRun) {
@@ -473,7 +525,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
473
525
  // #4657: under --at the images were built in the commit's own checkout, which is removed below; the archives the
474
526
  // release records are put where release.images names them here, so the job's next step (the hand-off to the
475
527
  // publish job) finds them.
476
- if (checkout && declaredImages.length > 0) copyImageArchives(declaredImages, cutCwd, cwd);
528
+ if (checkout && declaredImages.length > 0) copyImageArchives((await import("../../lifecycle/release-images")).resolveReleaseImages(declaredImages), cutCwd, cwd);
477
529
  const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
478
530
  // The tag names the release's label, which a re-cut with no label reads from the earlier cut.
479
531
  let tagged: { name: string; created: boolean } | null = null;
@@ -540,6 +592,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
540
592
  }
541
593
  throw err;
542
594
  } finally {
595
+ (stamped as import("../../lifecycle/release-version").Stamped | null)?.restore();
543
596
  checkout?.remove();
544
597
  }
545
598
  }
@@ -108,6 +108,7 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
108
108
  ...(product?.afterPlan ? { afterPlan: product.afterPlan } : {}),
109
109
  ...(product?.capabilities ? { capabilities: product.capabilities } : {}),
110
110
  ...(product?.hookExec ? { hookExec: product.hookExec } : {}),
111
+ ...(product?.runHooks ? { runHooks: product.runHooks } : {}),
111
112
  spec,
112
113
  specFile: relative(process.cwd(), path),
113
114
  wave: args.wave,
package/src/cli/main.ts CHANGED
@@ -531,6 +531,11 @@ Releases:
531
531
  the release's commit, refuse one whose digest is not
532
532
  the recorded one, and write the recorded digests to
533
533
  the file CHANT_RELEASE_DIGESTS names for the build.
534
+ release stamp <label> [--json]
535
+ Write the label as the version of each package.json
536
+ release.version names, and the lockfile's entries for
537
+ them, as the cut does before its build. The publish
538
+ job runs it before its build.
534
539
  release workflow [--forge github|gitlab|forgejo] [--install <command>]
535
540
  [--build <command>] [--chant <command>] [--output <file>]
536
541
  Write the publish workflow, run on a release/** tag.
@@ -1910,6 +1915,8 @@ export const commandRegistry: CommandDef[] = [
1910
1915
  { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseVerify(ctx) },
1911
1916
  // #4657: build a release's images again in its publish job, checked against the digests it records.
1912
1917
  { name: "release images", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseImages(ctx) },
1918
+ // #4840: the label into the package.json files release.version names, in the publish job before its build.
1919
+ { name: "release stamp", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseStamp(ctx) },
1913
1920
  { name: "release workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-workflow")).runReleaseWorkflow(ctx) },
1914
1921
  // #4168 4.3: mode (b), chosen changes composed onto a base on chant/compose/<name>.
1915
1922
  { name: "release compose", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompose(ctx) },
@@ -17,6 +17,7 @@ import * as ciProduct from "../../ci-product";
17
17
  import { reportReader, reportToolKey, safeReportKey } from "./report-tools";
18
18
  import type { ToolDefinition } from "./types";
19
19
  import type { McpToolContribution } from "../../mcp/types";
20
+ import { NEXT_RELEASE } from "../../release-floors";
20
21
 
21
22
  const tool = (name: string, readOnly?: boolean, handler: McpToolContribution["handler"] = async () => ({ name })): McpToolContribution => ({
22
23
  name,
@@ -176,3 +177,52 @@ describe("the report tool's keys (#4555)", () => {
176
177
  expect(safeReportKey("/a/b/")).toBe("a/b");
177
178
  });
178
179
  });
180
+
181
+ describe("tool annotations in tools/list (#4823)", () => {
182
+ async function annotations(server: McpServer): Promise<Map<string, Record<string, unknown> | undefined>> {
183
+ const res = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
184
+ return new Map((res.result as { tools: Array<ToolDefinition & { annotations?: Record<string, unknown> }> }).tools.map((t) => [t.name, t.annotations]));
185
+ }
186
+ const READ = { readOnlyHint: true, destructiveHint: false };
187
+
188
+ test("a product's readOnly tool reads as read-only, a forgeWrite tool as an additive write, and its own annotations pass through", async () => {
189
+ const hook: ProductMcpHook = {
190
+ product: "terragucci",
191
+ propose: true,
192
+ tools: () => [
193
+ { ...tool("index", true), annotations: { idempotentHint: true, openWorldHint: false } },
194
+ { ...tool("request_from_template"), forgeWrite: true },
195
+ ],
196
+ };
197
+ const listedAnnotations = await annotations(new McpServer([], { product: hook }));
198
+ expect(listedAnnotations.get("terragucci:index")).toEqual({ ...READ, idempotentHint: true, openWorldHint: false });
199
+ expect(listedAnnotations.get("terragucci:request_from_template")).toEqual({ readOnlyHint: false, destructiveHint: false });
200
+ });
201
+
202
+ test("the declaration wins over an annotation that says otherwise", async () => {
203
+ const hook: ProductMcpHook = { product: "plywood", tools: () => [{ ...tool("stacks", true), annotations: { readOnlyHint: false, destructiveHint: true, title: "Stacks" } }] };
204
+ expect((await annotations(new McpServer([], { product: hook }))).get("plywood:stacks")).toEqual({ ...READ, title: "Stacks" });
205
+ });
206
+
207
+ test("a plugin's readOnly tool is annotated, and a tool that declares nothing is not", async () => {
208
+ const plugin = { name: "lex", mcpTools: () => [tool("catalog", true), tool("generate")] } as unknown as import("../../lexicon").LexiconPlugin;
209
+ const listedAnnotations = await annotations(new McpServer([plugin]));
210
+ expect(listedAnnotations.get("lex:catalog")).toEqual(READ);
211
+ expect(listedAnnotations.get("lex:generate")).toBeUndefined();
212
+ });
213
+
214
+ test("a read-only core tool is annotated, a mutating one is not, and lint is read-only only without fix", async () => {
215
+ const open = await annotations(new McpServer([]));
216
+ expect(open.get("search")).toEqual(READ);
217
+ expect(open.get("op-status")).toEqual(READ);
218
+ expect(open.get("op-run")).toBeUndefined();
219
+ expect(open.get("lint")).toBeUndefined();
220
+ const closed = await annotations(new McpServer([], { readOnly: true }));
221
+ expect(closed.get("lint")).toEqual(READ);
222
+ for (const [name, a] of closed) expect(a, name).toEqual(READ);
223
+ });
224
+
225
+ test("the floor names the next release", () => {
226
+ expect(ciProduct.MCP_TOOL_ANNOTATIONS_FLOOR).toBe(NEXT_RELEASE);
227
+ });
228
+ });
@@ -33,6 +33,7 @@
33
33
  */
34
34
 
35
35
  import type { McpToolContribution } from "../../mcp/types";
36
+ import { NEXT_RELEASE } from "../../release-floors";
36
37
  import { reportReader, reportUrlFor, type ReportReader } from "./report-tools";
37
38
 
38
39
  /** What a product's tools are handed. */
@@ -78,6 +79,13 @@ export interface ProductMcpHook {
78
79
  */
79
80
  export const PRODUCT_MCP_PROPOSE_FLOOR = "0.124.58";
80
81
 
82
+ /**
83
+ * The first chant whose `tools/list` gives MCP tool annotations: a tool's
84
+ * `annotations`, and `readOnlyHint`/`destructiveHint` from `readOnly: true`
85
+ * or `forgeWrite: true` (chant#4823).
86
+ */
87
+ export const MCP_TOOL_ANNOTATIONS_FLOOR = NEXT_RELEASE;
88
+
81
89
  /** The words a `forgeWrite` tool's name may hold on the `--propose` tier, which the write-word check passes over (chant#4655). */
82
90
  export const PRODUCT_TOOL_PROPOSE_WORDS = ["request", "propose"] as const;
83
91
 
@@ -17,6 +17,25 @@
17
17
  import { workspaceReadTools, workspaceWriteTools } from "./workspace-tools";
18
18
  import { ledgerReadTools } from "./ledger-tools";
19
19
  import { reportReadTools } from "./report-tools";
20
+ import type { McpToolContribution, ToolAnnotations } from "../../mcp/types";
21
+
22
+ /** The annotations of a tool that changes nothing (chant#4823). */
23
+ export const READ_ONLY_ANNOTATIONS: Readonly<ToolAnnotations> = Object.freeze({ readOnlyHint: true, destructiveHint: false });
24
+
25
+ /** The annotations of a product's `forgeWrite` tool, which adds a pull request or a comment and deletes nothing (chant#4823). */
26
+ export const FORGE_WRITE_ANNOTATIONS: Readonly<ToolAnnotations> = Object.freeze({ readOnlyHint: false, destructiveHint: false });
27
+
28
+ /**
29
+ * A contributed tool's annotations in `tools/list` (chant#4823): its own,
30
+ * with `readOnlyHint` and `destructiveHint` set from `readOnly: true` or
31
+ * `forgeWrite: true`, so a hint never says more than the rule the server
32
+ * serves the tool by. Undefined when the tool gives and declares nothing.
33
+ */
34
+ export function contributedToolAnnotations(tool: Pick<McpToolContribution, "readOnly" | "forgeWrite" | "annotations">): ToolAnnotations | undefined {
35
+ const declared = tool.readOnly === true ? READ_ONLY_ANNOTATIONS : tool.forgeWrite === true ? FORGE_WRITE_ANNOTATIONS : undefined;
36
+ if (!declared && !tool.annotations) return undefined;
37
+ return { ...tool.annotations, ...declared };
38
+ }
20
39
 
21
40
  /**
22
41
  * Core tools that change nothing, served in both modes.
@@ -344,6 +344,36 @@ describe("McpServer", () => {
344
344
  expect(result.structuredContent).toBeUndefined();
345
345
  });
346
346
 
347
+ // MCP's CallToolResult.structuredContent is a JSON object (schema
348
+ // 2025-06-18: `structuredContent?: { [key: string]: unknown }`), and the
349
+ // MCP SDK's Client.callTool refuses anything else (#4822).
350
+ test("an array-returning handler gets its array as structuredContent.items, and the array as text", async () => {
351
+ const rows = [{ id: "a" }, { id: "b" }];
352
+ const plugin = createMockPlugin({
353
+ name: "test-lex",
354
+ mcpTools: () => [
355
+ {
356
+ name: "rows",
357
+ description: "Rows",
358
+ inputSchema: { type: "object", properties: {} },
359
+ handler: async () => rows,
360
+ },
361
+ ],
362
+ });
363
+ const s = new McpServer([plugin]);
364
+ const response = await s.handleRequest({
365
+ jsonrpc: "2.0",
366
+ id: 1,
367
+ method: "tools/call",
368
+ params: { name: "test-lex:rows", arguments: {} },
369
+ });
370
+ const result = response!.result as { content: Array<{ type: string; text: string }>; structuredContent?: unknown };
371
+ const sc = result.structuredContent;
372
+ expect(typeof sc === "object" && sc !== null && !Array.isArray(sc)).toBe(true);
373
+ expect(sc).toEqual({ items: rows });
374
+ expect(result.content).toEqual([{ type: "text", text: JSON.stringify(rows, null, 2) }]);
375
+ });
376
+
347
377
  test("an isError response has no structuredContent", async () => {
348
378
  const response = await server.handleRequest({
349
379
  jsonrpc: "2.0",
@@ -19,7 +19,7 @@ import { buildResourcesList, handleResourcesRead } from "./resource-handlers";
19
19
  import { createLedgerTools } from "./ledger-tools";
20
20
  import { createReportTools } from "./report-tools";
21
21
  import { activeProductMcpHook, productMcpContext, productToolsServed, type ProductMcpHook } from "./product-tools";
22
- import { MUTATING_CORE_TOOLS, READ_ONLY_CORE_TOOLS, ReadOnlyRegistrationError, servesContributedTool } from "./read-only";
22
+ import { contributedToolAnnotations, MUTATING_CORE_TOOLS, READ_ONLY_ANNOTATIONS, READ_ONLY_CORE_TOOLS, ReadOnlyRegistrationError, servesContributedTool } from "./read-only";
23
23
  import { CHANT_VERSION } from "../version";
24
24
 
25
25
  /**
@@ -220,7 +220,11 @@ export class McpServer {
220
220
  // and its forgeWrite tools on the --propose tier (chant#4655).
221
221
  if (product) {
222
222
  for (const tool of productToolsServed(product, productMcpContext(product, cwd, this.readOnly, this.propose))) {
223
- this.registerTool({ name: namespacedToolName(product.product, tool.name), description: tool.description, inputSchema: tool.inputSchema }, tool.handler);
223
+ const annotations = contributedToolAnnotations(tool);
224
+ this.registerTool(
225
+ { name: namespacedToolName(product.product, tool.name), description: tool.description, inputSchema: tool.inputSchema, ...(annotations ? { annotations } : {}) },
226
+ tool.handler,
227
+ );
224
228
  }
225
229
  }
226
230
  }
@@ -241,11 +245,13 @@ export class McpServer {
241
245
  for (const tool of tools) {
242
246
  // A read-only server serves a plugin tool only when it says it changes nothing (chant#4543).
243
247
  if (!servesContributedTool(tool, this.readOnly)) continue;
248
+ const annotations = contributedToolAnnotations(tool);
244
249
  this.registerTool(
245
250
  {
246
251
  name: namespacedToolName(plugin.name, tool.name),
247
252
  description: tool.description,
248
253
  inputSchema: tool.inputSchema,
254
+ ...(annotations ? { annotations } : {}),
249
255
  },
250
256
  tool.handler,
251
257
  );
@@ -276,13 +282,17 @@ export class McpServer {
276
282
  * Register a core tool. On a read-only server a mutating core tool is
277
283
  * left out, and a core tool on neither list of ./read-only.ts is refused
278
284
  * with an error, so a new tool cannot reach a read-only server unsorted.
285
+ *
286
+ * A tool on the read-only list is listed with {@link READ_ONLY_ANNOTATIONS}
287
+ * (chant#4823), except the ordinary server's `lint`, whose `fix` writes.
279
288
  */
280
289
  private registerCoreTool(definition: ToolDefinition, handler: ToolHandler): void {
281
290
  if (this.readOnly && !READ_ONLY_CORE_TOOLS.has(definition.name)) {
282
291
  if (MUTATING_CORE_TOOLS.has(definition.name)) return;
283
292
  throw new ReadOnlyRegistrationError(definition.name);
284
293
  }
285
- this.registerTool(definition, handler);
294
+ const reads = READ_ONLY_CORE_TOOLS.has(definition.name) && definition !== lintTool;
295
+ this.registerTool(reads ? { ...definition, annotations: { ...READ_ONLY_ANNOTATIONS } } : definition, handler);
286
296
  }
287
297
 
288
298
  /**
@@ -400,7 +410,7 @@ export class McpServer {
400
410
  // The client, from this request's _meta (2026-07-28) or else from initialize.
401
411
  const clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
402
412
  const result = await handler(toolParams, clientInfo ? { clientInfo } : {});
403
- const isStructured = typeof result === "object" && result !== null;
413
+ const structured = structuredContentOf(result);
404
414
  return {
405
415
  content: [
406
416
  {
@@ -412,7 +422,7 @@ export class McpServer {
412
422
  // objects that get stringified above, so agents that want the
413
423
  // parsed shape directly get it here too, alongside the text block
414
424
  // kept for backward compatibility (#1194).
415
- ...(isStructured ? { structuredContent: result } : {}),
425
+ ...(structured ? { structuredContent: structured } : {}),
416
426
  };
417
427
  } catch (error) {
418
428
  return {
@@ -470,6 +480,19 @@ export class McpServer {
470
480
  }
471
481
  }
472
482
 
483
+ /**
484
+ * A tool result's `structuredContent`, which MCP types as a JSON object
485
+ * (`{ [key: string]: unknown }`): a plain object as it is, an array as
486
+ * `{ items: [...] }` (#4822), and nothing for a string or other scalar. The
487
+ * text block still carries the result as the handler returned it, so a
488
+ * client that reads text sees the array.
489
+ */
490
+ export function structuredContentOf(result: unknown): Record<string, unknown> | undefined {
491
+ if (Array.isArray(result)) return { items: result };
492
+ if (typeof result === "object" && result !== null) return result as Record<string, unknown>;
493
+ return undefined;
494
+ }
495
+
473
496
  /**
474
497
  * Start MCP server, loading plugins from the project
475
498
  */
@@ -35,6 +35,8 @@ export interface McpRequestMeta {
35
35
  "io.modelcontextprotocol/clientInfo"?: McpClientInfo;
36
36
  }
37
37
 
38
+ import type { ToolAnnotations } from "../../mcp/types";
39
+
38
40
  /**
39
41
  * Tool definition for MCP
40
42
  */
@@ -49,13 +51,16 @@ export interface ToolDefinition {
49
51
  /**
50
52
  * JSON schema for `structuredContent` (2025-06-18+), when a tool's result
51
53
  * shape is obvious and stable enough to declare. Optional and additive —
52
- * most tools omit it (#1194).
54
+ * most tools omit it (#1194). A handler that returns an array has it
55
+ * sent as `{ items: [...] }` (#4822), so its schema describes that object.
53
56
  */
54
57
  outputSchema?: {
55
58
  type: "object";
56
59
  properties: Record<string, unknown>;
57
60
  required?: string[];
58
61
  };
62
+ /** The tool's annotations in `tools/list` (chant#4823): the read-only core and contributed tools say so. */
63
+ annotations?: ToolAnnotations;
59
64
  }
60
65
 
61
66
  /**
@@ -125,6 +125,22 @@ export interface DeployContext {
125
125
  * its packs where they stand.
126
126
  */
127
127
  policyBase?: string;
128
+ /**
129
+ * Environment variables the run's engine runs with, over the job's
130
+ * (#4842): an op wave's run hook gives them per run, such as a role's
131
+ * credentials or values read from a secret store. A capability passes them
132
+ * to every command it runs for the plan and the apply. Absent: the job's
133
+ * environment as it is.
134
+ */
135
+ processEnv?: Record<string, string>;
136
+ /**
137
+ * A check to call once the engine has initialised the run and before its
138
+ * plan runs any of the run's code (#4842), such as a check of the module
139
+ * and provider sources the init fetched. It throws to stop the plan. A
140
+ * capability that has no separate init calls it before it plans. Absent:
141
+ * nothing to call.
142
+ */
143
+ afterInit?: () => Promise<void>;
128
144
  /**
129
145
  * The run's row lease (#4594), set by an apply path that plans inside its
130
146
  * steps (`run --components`, `components fan-out`, a promote). The driver
@@ -395,6 +411,31 @@ export interface Capability<In = unknown, Out = unknown> {
395
411
  * error is a moved plan ({@link isPlanMovedError}).
396
412
  */
397
413
  runGroup?(ctx: GroupContext, run: GroupRun, members: readonly GroupMember<In>[]): Promise<CapabilityGroupOutcome>;
414
+ /**
415
+ * Optional (#4842): the runs of an op wave whose runs are found at plan
416
+ * time (`discover`), such as a Terragrunt repo's units in one layer of
417
+ * `terragrunt find`'s graph. `input` is the step's input with `{op}` and
418
+ * `{wave}` filled and `{target}` left as written. Each run found then
419
+ * plans with `{target}` filled, one at a time, or with `planGroup` on a
420
+ * wave marked `together`. Throwing fails the wave before anything plans.
421
+ */
422
+ discoverRuns?(ctx: RunDiscoveryContext, input: In): Promise<DiscoveredRuns>;
423
+ }
424
+
425
+ /** What `discoverRuns` is asked with (#4842). */
426
+ export interface RunDiscoveryContext {
427
+ /** The environment the wave's runs plan in, as `DeployContext.env`. */
428
+ env: string;
429
+ /** The wave: its name in the spec and its number from 1. A `rest` wave past the spec's asks with each number in turn. */
430
+ wave: { name: string; number: number };
431
+ }
432
+
433
+ /** What `discoverRuns` answers (#4842). */
434
+ export interface DiscoveredRuns {
435
+ /** The wave's runs, by target, in the order they apply. Empty: the wave has none, and applies nothing. */
436
+ targets: string[];
437
+ /** How many waves the discovery found, which a `rest` wave walks to. */
438
+ waves?: number;
398
439
  }
399
440
 
400
441
  /**
@@ -0,0 +1,20 @@
1
+ /**
2
+ * The group digest of a capability group (ws-107), in a module of its own
3
+ * so an op wave planned `together` (#4842) binds the same digest without
4
+ * the wave-job runtime bundle loading `./groups.ts`.
5
+ */
6
+
7
+ import { computePlanDigest } from "../lifecycle/plan-digest";
8
+
9
+ /**
10
+ * The group digest (ws-107): over the capability's kind, each member's
11
+ * component, change-set member and own plan digest, sorted, and the
12
+ * capability's digest of the composition. One member more, or the same
13
+ * members composed differently, moves it.
14
+ */
15
+ export function groupDigest(kind: string, members: ReadonlyArray<{ component: string; member: string; planDigest: string }>, composition: string): string {
16
+ const sorted = [...members]
17
+ .map((m) => ({ component: m.component, member: m.member, planDigest: m.planDigest }))
18
+ .sort((a, b) => a.component.localeCompare(b.component) || a.member.localeCompare(b.member));
19
+ return computePlanDigest("capability-group", { kind, members: sorted, composition });
20
+ }
@@ -27,6 +27,9 @@
27
27
  */
28
28
 
29
29
  import { computePlanDigest } from "../lifecycle/plan-digest";
30
+ import { groupDigest } from "./group-digest";
31
+
32
+ export { groupDigest };
30
33
  import type { ChangeSetPart } from "../change-set";
31
34
  import type { PlanShape } from "./covered-round";
32
35
  import {
@@ -575,19 +578,6 @@ export function groupsByComponent(plan: Pick<FanOutPlan, "groups">): Map<string,
575
578
  return new Map((plan.groups ?? []).flatMap((g) => g.components.map((c) => [c, g] as const)));
576
579
  }
577
580
 
578
- /**
579
- * The group digest (ws-107): over the capability's kind, each member's
580
- * component, change-set member and own plan digest, sorted, and the
581
- * capability's digest of the composition. One member more, or the same
582
- * members composed differently, moves it.
583
- */
584
- export function groupDigest(kind: string, members: ReadonlyArray<{ component: string; member: string; planDigest: string }>, composition: string): string {
585
- const sorted = [...members]
586
- .map((m) => ({ component: m.component, member: m.member, planDigest: m.planDigest }))
587
- .sort((a, b) => a.component.localeCompare(b.component) || a.member.localeCompare(b.member));
588
- return computePlanDigest("capability-group", { kind, members: sorted, composition });
589
- }
590
-
591
581
  /**
592
582
  * A member's plan with its group folded in (ws-107), after `bindTargets`:
593
583
  * its digest becomes the digest over its own and the group's, written into
@@ -68,6 +68,8 @@ export {
68
68
  type DeclaredRead,
69
69
  type DeclaredReadMember,
70
70
  type DeclaredReadsContext,
71
+ type DiscoveredRuns,
72
+ type RunDiscoveryContext,
71
73
  CapabilityRegistry,
72
74
  CapabilityNotImplementedError,
73
75
  } from "./capability";
@@ -4,7 +4,6 @@
4
4
  * that records what it was asked. No engine, ledger or forge is reached.
5
5
  */
6
6
  import { describe, expect, test } from "vitest";
7
- import { NEXT_RELEASE } from "../release-floors";
8
7
  import { componentsPrEnvAdapter, componentsPrEnvTeardown, PR_ENV_COMPONENTS_FLOOR, type PrEnvComponentPlan } from "./pr-env-components";
9
8
  import { prEnvDown, prEnvUp, type PrEnvApproval, type PrEnvPorts } from "./pr-env-run";
10
9
  import { livePrEnvironments, type PrEnvRecord } from "./pr-environment";
@@ -133,6 +132,6 @@ describe("componentsPrEnvTeardown", () => {
133
132
  });
134
133
 
135
134
  test("its floor is the next release", () => {
136
- expect(PR_ENV_COMPONENTS_FLOOR).toBe(NEXT_RELEASE);
135
+ expect(PR_ENV_COMPONENTS_FLOOR).toBe("0.124.77");
137
136
  });
138
137
  });
@@ -23,12 +23,11 @@
23
23
  */
24
24
  import { waveSetDigest } from "../gated-waves";
25
25
  import type { TeardownOutcome } from "../lexicon";
26
- import { NEXT_RELEASE } from "../release-floors";
27
26
  import type { PrEnvAdapter, PrEnvPlanned, PrEnvTarget } from "./pr-env-run";
28
27
  import type { LivePrEnvironment, PrEnvReportRow, PrEnvTeardownAdapter } from "./pr-environment";
29
28
 
30
29
  /** The first chant with the component adapter and teardown, and the terraform lexicon's copies on them (#4762). */
31
- export const PR_ENV_COMPONENTS_FLOOR = NEXT_RELEASE;
30
+ export const PR_ENV_COMPONENTS_FLOOR = "0.124.77";
32
31
 
33
32
  /** One component's plan, as an engine answers it. */
34
33
  export interface PrEnvComponentPlan {