@intentius/chant 0.124.78 → 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 (150) hide show
  1. package/dist/action-pins.d.ts.map +1 -1
  2. package/dist/action-pins.js +1 -2
  3. package/dist/change-set.d.ts +10 -1
  4. package/dist/change-set.d.ts.map +1 -1
  5. package/dist/change-set.js +4 -1
  6. package/dist/ci-agent.d.ts +16 -2
  7. package/dist/ci-agent.d.ts.map +1 -1
  8. package/dist/ci-agent.js +6 -1
  9. package/dist/ci-commit.d.ts.map +1 -1
  10. package/dist/ci-commit.js +2 -3
  11. package/dist/ci-product.d.ts +6 -2
  12. package/dist/ci-product.d.ts.map +1 -1
  13. package/dist/ci-product.js +5 -1
  14. package/dist/cli/handlers/release.d.ts +8 -0
  15. package/dist/cli/handlers/release.d.ts.map +1 -1
  16. package/dist/cli/handlers/release.js +64 -2
  17. package/dist/cli/handlers/run-wave.js +1 -0
  18. package/dist/cli/main.d.ts.map +1 -1
  19. package/dist/cli/main.js +7 -0
  20. package/dist/cli/mcp/product-tools.d.ts +6 -0
  21. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  22. package/dist/cli/mcp/product-tools.js +7 -0
  23. package/dist/cli/mcp/read-only.d.ts +12 -0
  24. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  25. package/dist/cli/mcp/read-only.js +16 -0
  26. package/dist/cli/mcp/server.d.ts +11 -0
  27. package/dist/cli/mcp/server.d.ts.map +1 -1
  28. package/dist/cli/mcp/server.js +26 -5
  29. package/dist/cli/mcp/types.d.ts +5 -1
  30. package/dist/cli/mcp/types.d.ts.map +1 -1
  31. package/dist/components/capability.d.ts +42 -0
  32. package/dist/components/capability.d.ts.map +1 -1
  33. package/dist/components/group-digest.d.ts +17 -0
  34. package/dist/components/group-digest.d.ts.map +1 -0
  35. package/dist/components/group-digest.js +18 -0
  36. package/dist/components/groups.d.ts +2 -11
  37. package/dist/components/groups.d.ts.map +1 -1
  38. package/dist/components/groups.js +2 -12
  39. package/dist/components/index.d.ts +1 -1
  40. package/dist/components/index.d.ts.map +1 -1
  41. package/dist/config.d.ts +14 -0
  42. package/dist/config.d.ts.map +1 -1
  43. package/dist/config.js +5 -0
  44. package/dist/lexicon.d.ts.map +1 -1
  45. package/dist/lexicon.js +1 -2
  46. package/dist/lifecycle/release-cut.d.ts +7 -1
  47. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  48. package/dist/lifecycle/release-cut.js +1 -0
  49. package/dist/lifecycle/release-images.d.ts +12 -3
  50. package/dist/lifecycle/release-images.d.ts.map +1 -1
  51. package/dist/lifecycle/release-images.js +6 -7
  52. package/dist/lifecycle/release-publish.d.ts +8 -1
  53. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  54. package/dist/lifecycle/release-publish.js +30 -3
  55. package/dist/lifecycle/release-version.d.ts +86 -0
  56. package/dist/lifecycle/release-version.d.ts.map +1 -0
  57. package/dist/lifecycle/release-version.js +209 -0
  58. package/dist/mcp/types.d.ts +26 -0
  59. package/dist/mcp/types.d.ts.map +1 -1
  60. package/dist/notify-product.d.ts.map +1 -1
  61. package/dist/notify-product.js +1 -2
  62. package/dist/op/activities/review-product.d.ts.map +1 -1
  63. package/dist/op/activities/review-product.js +1 -2
  64. package/dist/op/gate.d.ts +17 -0
  65. package/dist/op/gate.d.ts.map +1 -1
  66. package/dist/op/gate.js +36 -0
  67. package/dist/op/index.d.ts +8 -6
  68. package/dist/op/index.d.ts.map +1 -1
  69. package/dist/op/index.js +5 -4
  70. package/dist/op/op-waves-after-plan.d.ts +76 -1
  71. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  72. package/dist/op/op-waves-after-plan.js +142 -3
  73. package/dist/op/op-waves-capability-spec.js +1 -2
  74. package/dist/op/op-waves-capability.d.ts +89 -2
  75. package/dist/op/op-waves-capability.d.ts.map +1 -1
  76. package/dist/op/op-waves-capability.js +215 -7
  77. package/dist/op/op-waves-run-hooks.d.ts +104 -0
  78. package/dist/op/op-waves-run-hooks.d.ts.map +1 -0
  79. package/dist/op/op-waves-run-hooks.js +146 -0
  80. package/dist/op/op-waves-run.d.ts +21 -0
  81. package/dist/op/op-waves-run.d.ts.map +1 -1
  82. package/dist/op/op-waves-run.js +233 -13
  83. package/dist/op/op-waves.d.ts +11 -1
  84. package/dist/op/op-waves.d.ts.map +1 -1
  85. package/dist/op/op-waves.js +7 -1
  86. package/dist/op/runtime.d.ts +2 -0
  87. package/dist/op/runtime.d.ts.map +1 -1
  88. package/dist/pr-plan-note.d.ts.map +1 -1
  89. package/dist/pr-plan-note.js +1 -2
  90. package/dist/release-floors.d.ts +5 -1
  91. package/dist/release-floors.d.ts.map +1 -1
  92. package/dist/release-floors.js +9 -5
  93. package/dist/wave-runtime.mjs +314 -314
  94. package/dist/workspace/change-set.schema.json +7 -0
  95. package/dist/workspace/release-workflow.d.ts +7 -0
  96. package/dist/workspace/release-workflow.d.ts.map +1 -1
  97. package/dist/workspace/release-workflow.js +11 -1
  98. package/package.json +1 -1
  99. package/src/action-pins.test.ts +1 -2
  100. package/src/action-pins.ts +1 -3
  101. package/src/change-set.test.ts +20 -0
  102. package/src/change-set.ts +11 -1
  103. package/src/ci-agent.test.ts +9 -0
  104. package/src/ci-agent.ts +15 -2
  105. package/src/ci-commit.test.ts +2 -3
  106. package/src/ci-commit.ts +2 -3
  107. package/src/ci-product.ts +6 -2
  108. package/src/cli/handlers/release.ts +55 -2
  109. package/src/cli/handlers/run-wave.ts +1 -0
  110. package/src/cli/main.ts +7 -0
  111. package/src/cli/mcp/product-tools.test.ts +50 -0
  112. package/src/cli/mcp/product-tools.ts +8 -0
  113. package/src/cli/mcp/read-only.ts +19 -0
  114. package/src/cli/mcp/server.test.ts +30 -0
  115. package/src/cli/mcp/server.ts +28 -5
  116. package/src/cli/mcp/types.ts +6 -1
  117. package/src/components/capability.ts +41 -0
  118. package/src/components/group-digest.ts +20 -0
  119. package/src/components/groups.ts +3 -13
  120. package/src/components/index.ts +2 -0
  121. package/src/config.ts +15 -0
  122. package/src/lexicon.ts +1 -2
  123. package/src/lifecycle/release-cut.ts +11 -0
  124. package/src/lifecycle/release-images-dockerfile.test.ts +10 -2
  125. package/src/lifecycle/release-images.ts +12 -8
  126. package/src/lifecycle/release-publish.ts +34 -3
  127. package/src/lifecycle/release-version.test.ts +155 -0
  128. package/src/lifecycle/release-version.ts +227 -0
  129. package/src/mcp/types.ts +27 -0
  130. package/src/notify-message-words.test.ts +1 -2
  131. package/src/notify-product.ts +1 -2
  132. package/src/op/activities/review-product.ts +1 -2
  133. package/src/op/gate.ts +46 -0
  134. package/src/op/index.ts +10 -4
  135. package/src/op/op-waves-after-plan-wave.test.ts +226 -0
  136. package/src/op/op-waves-after-plan.ts +170 -5
  137. package/src/op/op-waves-capability-spec.ts +1 -1
  138. package/src/op/op-waves-capability.test.ts +6 -0
  139. package/src/op/op-waves-capability.ts +243 -10
  140. package/src/op/op-waves-run-hooks.test.ts +184 -0
  141. package/src/op/op-waves-run-hooks.ts +195 -0
  142. package/src/op/op-waves-run.ts +240 -16
  143. package/src/op/op-waves-step-wave.test.ts +277 -0
  144. package/src/op/op-waves.ts +15 -2
  145. package/src/op/runtime.ts +2 -0
  146. package/src/pr-plan-note.ts +1 -2
  147. package/src/release-floors.ts +11 -5
  148. package/src/workspace/change-set.schema.json +7 -0
  149. package/src/workspace/release-workflow.test.ts +18 -0
  150. package/src/workspace/release-workflow.ts +21 -1
@@ -155,6 +155,13 @@
155
155
  },
156
156
  "description": "Added in contract 1 by #4463, written by chant 0.124.54 and newer. The inputs the member was previewed with stand-in values for (#4463), as var.<name>, sorted. Every attribute they drive is marked unknown in its entries, and its planDigest covers them."
157
157
  },
158
+ "outputs": {
159
+ "type": "array",
160
+ "items": {
161
+ "type": "string"
162
+ },
163
+ "description": "Added in contract 1 by #4849, written by chant 0.124.79 and newer. The outputs the member's plan changes, by name, sorted. Absent when it changes none. A member with any is a change even when every entry is a no-op. Its planDigest covers them."
164
+ },
158
165
  "holes": {
159
166
  "type": "array",
160
167
  "description": "What the planner could not read, so the plan says nothing about it.",
@@ -68,6 +68,13 @@ export interface ReleaseWorkflowInput {
68
68
  imageArchives?: string[];
69
69
  /** `release.lane` (#4692): the gate's green lane. */
70
70
  lane?: string;
71
+ /**
72
+ * The config declares `release.version` (#4840): the publish job runs
73
+ * `chant release stamp <label>` before the images and the build, so what
74
+ * it builds and publishes carries the label as its version. The cut
75
+ * stamps on its own.
76
+ */
77
+ version?: boolean;
71
78
  /**
72
79
  * `release.publish` (#4767). On GitHub, a `forge: "github"` target with no
73
80
  * `tokenEnv` reads `GITHUB_TOKEN`, so the publish job sets it to the job's
@@ -1 +1 @@
1
- {"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,8HAA8H;IAC9H,OAAO,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAC7B,iLAAiL;IACjL,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAC7B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yJAAyJ;IACzJ,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,kMAAkM;IAClM,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAOlE,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAoGzE;AAkFD,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AA6L9D,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DvG"}
1
+ {"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,8HAA8H;IAC9H,OAAO,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAC7B,iLAAiL;IACjL,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAC7B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yJAAyJ;IACzJ,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,kMAAkM;IAClM,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9E;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAOlE,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAuGzE;AAoFD,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAoM9D,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DvG"}
@@ -59,6 +59,7 @@ export function renderReleaseWorkflow(input) {
59
59
  const flags = publishFlags(input.groups).join(" ");
60
60
  const after = p.after ?? [];
61
61
  const images = input.images === true;
62
+ const version = input.version === true;
62
63
  const extra = jobExtras(p, input.forge);
63
64
  // #4767: Forgejo's job token is not a GitHub token, and GitLab has no such expression.
64
65
  const forgeToken = input.forge === "github" && p.env?.GITHUB_TOKEN === undefined && (input.publish ?? []).some((t) => t.type === "forge" && t.forge === "github" && !t.tokenEnv)
@@ -66,7 +67,7 @@ export function renderReleaseWorkflow(input) {
66
67
  : [];
67
68
  if (p.trigger === "dispatch") {
68
69
  const archives = images ? (input.imageArchives ?? []).map((a) => (root ? `${root}/${a.replace(/^\.\//, "")}` : a.replace(/^\.\//, ""))) : [];
69
- const o = { chant, install, build, root, verify, flags, after, images, archives, forge: input.forge, extra, forgeToken, gate: p.gate ?? "last-green", ...(input.lane ? { lane: input.lane } : {}) };
70
+ const o = { chant, install, build, root, verify, flags, after, images, version, archives, forge: input.forge, extra, forgeToken, gate: p.gate ?? "last-green", ...(input.lane ? { lane: input.lane } : {}) };
70
71
  return input.forge === "gitlab" ? renderGitlabDispatch(o) : renderGithubDispatch(o);
71
72
  }
72
73
  // #4657: the images are built from the release, so chant/lifecycle is fetched before them and the build after.
@@ -86,6 +87,7 @@ export function renderReleaseWorkflow(input) {
86
87
  ...(root ? [` - cd ${root}`] : []),
87
88
  ` - ${install}`,
88
89
  ...extra.gitlabScript.map((l) => ` - ${l}`),
90
+ ...(version ? [` - ${chant} release stamp ${label}`] : []),
89
91
  ...(images ? [...fetches, ...imageLines(label, `export CHANT_RELEASE_DIGESTS="$PWD/${RELEASE_DIGESTS_FILE}"`).map((l) => ` - ${l}`)] : []),
90
92
  ...(build ? [` - ${build}`] : []),
91
93
  ...(images ? [] : fetches),
@@ -117,6 +119,7 @@ export function renderReleaseWorkflow(input) {
117
119
  ...githubSetup(),
118
120
  ` - run: ${install}`,
119
121
  ...extra.githubSteps,
122
+ ...(version ? [` - run: ${chant} release stamp ${label}`] : []),
120
123
  ...(images ? [...fetches, ...imageLines(label, `echo "CHANT_RELEASE_DIGESTS=$PWD/${RELEASE_DIGESTS_FILE}" >> "$GITHUB_ENV"`).map((l) => ` - run: ${l}`)] : []),
121
124
  ...(build ? [` - run: ${build}`] : []),
122
125
  ...(images ? [] : fetches),
@@ -198,6 +201,10 @@ function commonDir(paths) {
198
201
  function imagesLine(o) {
199
202
  return `${o.chant} release images "$CHANT_RELEASE_LABEL"${o.archives.length > 0 ? " --no-build" : ""} -o ${RELEASE_DIGESTS_FILE}`;
200
203
  }
204
+ /** The publish job's `release stamp` line (#4840). */
205
+ function stampLine(o) {
206
+ return `${o.chant} release stamp "$CHANT_RELEASE_LABEL"`;
207
+ }
201
208
  /** The node one-liner that prints a JSON document's field from stdin, or from the file its argument names. */
202
209
  const field = (path) => `node -e 'const f=process.argv[1];const t=f?require("fs").readFileSync(f,"utf8"):require("fs").readFileSync(0,"utf8");const d=JSON.parse(t);process.stdout.write(String(${path}??""))'`;
203
210
  /** The gate's shell: the commit to cut, from `ci last-green`, refused when there is none or, under `head`, when it is not the dispatched one. */
@@ -298,6 +305,7 @@ function renderGithubDispatch(o) {
298
305
  ...(o.archives.length > 0
299
306
  ? [` - uses: ${usesRef(o.forge === "forgejo" ? ACTION_PINS.downloadArtifact3 : ACTION_PINS.downloadArtifact4)}`, " with:", ` name: ${RELEASE_IMAGES_ARTIFACT}`, ` path: ${commonDir(o.archives)}`]
300
307
  : []),
308
+ ...(o.version ? [` - run: ${stampLine(o)}`] : []),
301
309
  ...(o.images ? [` - run: ${imagesLine(o)}`, ` - run: echo "CHANT_RELEASE_DIGESTS=$PWD/${RELEASE_DIGESTS_FILE}" >> "$GITHUB_ENV"`] : []),
302
310
  ...(o.build ? [` - run: ${o.build}`] : []),
303
311
  ...(o.verify ? [` - run: ${o.chant} release verify "$CHANT_RELEASE_LABEL"`] : []),
@@ -348,6 +356,7 @@ function renderGitlabDispatch(o) {
348
356
  ...o.extra.gitlabScript,
349
357
  ...fetches,
350
358
  ...auth,
359
+ ...(o.version ? [stampLine(o)] : []),
351
360
  ...(o.images ? [imagesLine(o), `export CHANT_RELEASE_DIGESTS="$PWD/${RELEASE_DIGESTS_FILE}"`] : []),
352
361
  ...(o.build ? [o.build] : []),
353
362
  ...(o.verify ? [`${o.chant} release verify "$CHANT_RELEASE_LABEL"`] : []),
@@ -409,6 +418,7 @@ export async function runReleaseWorkflow(ctx) {
409
418
  ...(release?.workflow ? { pipeline: release.workflow } : {}),
410
419
  ...((release?.images?.length ?? 0) > 0 ? { images: true, imageArchives: resolveReleaseImages(release.images).map((i) => i.archive) } : {}),
411
420
  ...(release?.lane ? { lane: release.lane } : {}),
421
+ ...(release?.version ? { version: true } : {}),
412
422
  ...(release?.publish ? { publish: release.publish } : {}),
413
423
  ...(args.ciInstall ? { install: args.ciInstall } : {}),
414
424
  ...(args.buildCommand ? { build: args.buildCommand } : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant",
3
- "version": "0.124.78",
3
+ "version": "0.124.79",
4
4
  "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://intentius.io/chant",
@@ -2,7 +2,6 @@ import { describe, expect, it } from "vitest";
2
2
  import { readdirSync, readFileSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { ACTION_PINS, CACHE4_PIN_FLOOR, pinAtMajor, pinMajor, tagComments, unpinnedActions, usesRef } from "./action-pins";
5
- import { NEXT_RELEASE } from "./release-floors";
6
5
 
7
6
  describe("the action pin table", () => {
8
7
  it("holds a full commit SHA and a release of the row's major for every action", () => {
@@ -46,7 +45,7 @@ describe("the action pin table", () => {
46
45
  // The restore row shares the commit; moving it keeps its own subpath.
47
46
  expect(pinAtMajor(ACTION_PINS.cacheRestore4.sha, "v4")).toBe(ACTION_PINS.cacheRestore4);
48
47
  expect(tagComments(` uses: ${usesRef(ACTION_PINS.cache4)}`)).toBe(` uses: ${usesRef(ACTION_PINS.cache4)} # v4.3.0`);
49
- expect(CACHE4_PIN_FLOOR).toBe(NEXT_RELEASE);
48
+ expect(CACHE4_PIN_FLOOR).toBe("0.124.78");
50
49
  });
51
50
  });
52
51
 
@@ -19,10 +19,8 @@
19
19
  * gh api repos/actions/checkout/commits/v6 --jq .sha
20
20
  */
21
21
 
22
- import { NEXT_RELEASE } from "./release-floors";
23
-
24
22
  /** The first chant whose table has the `cache4` row (#4816). */
25
- export const CACHE4_PIN_FLOOR = NEXT_RELEASE;
23
+ export const CACHE4_PIN_FLOOR = "0.124.78";
26
24
 
27
25
  export interface ActionPin {
28
26
  /** The action, with its subpath: `actions/cache/restore`. */
@@ -315,3 +315,23 @@ describe("a grouped member (ws-107, #4440)", () => {
315
315
  expect(isEmptyChangeSet(composeChangeSet([part("a", { digest, reads: [] }), part("b", { digest, reads: ["a.id"] })]))).toBe(false);
316
316
  });
317
317
  });
318
+
319
+ describe("a member whose plan changes outputs (#4849)", () => {
320
+ const part = (member: string, outputs?: string[]): ChangeSetPart => ({
321
+ member: { member, lexicon: "terraform", planner: "tofu", status: "planned", planDigest: computePlanDigest("p", member), holes: [], ...(outputs ? { outputs } : {}) },
322
+ entries: [{ member, lexicon: "terraform", planner: "tofu", address: "aws_s3_bucket.a", type: "aws_s3_bucket", name: "a", action: "no-op", attributes: [] }],
323
+ });
324
+
325
+ test("a change set whose only change is an output is not empty", () => {
326
+ expect(isEmptyChangeSet(composeChangeSet([part("a"), part("b")]))).toBe(true);
327
+ expect(isEmptyChangeSet(composeChangeSet([part("a"), part("b", ["url"])]))).toBe(false);
328
+ });
329
+
330
+ test("the outputs are not hashed again, since the member's plan digest covers them, and the schema reads them", () => {
331
+ const plain = composeChangeSet([part("a"), part("b")]);
332
+ const outputs = composeChangeSet([part("a"), part("b", ["url"])]);
333
+ expect(outputs.digest).toBe(plain.digest);
334
+ expect(verifyChangeSetDigest(outputs)).toBe(true);
335
+ expectValid(outputs);
336
+ });
337
+ });
package/src/change-set.ts CHANGED
@@ -200,6 +200,14 @@ export interface ChangeSetMember {
200
200
  placeholders?: string[];
201
201
  /** The planner's own digest of the same plan, when it prints one (choudoufu's per-root digest). */
202
202
  nativeDigest?: string;
203
+ /**
204
+ * The outputs the member's plan changes, by name, sorted (#4849). Absent
205
+ * when it changes none. A member with any is a change, even when every
206
+ * entry is a no-op ({@link isEmptyChangeSet}). Not hashed again: the
207
+ * member's `planDigest` already covers them. Added within contract 1 by
208
+ * chant `CHANGE_SET_OUTPUTS_FLOOR` (release-floors).
209
+ */
210
+ outputs?: string[];
203
211
  holes: ChangeSetHole[];
204
212
  /**
205
213
  * Set on a member a capability planned with others as one group (ws-107,
@@ -475,12 +483,14 @@ export function verifyChangeSetDigest(
475
483
  * planner marked `mayAppear`. A release gate over such a document passes
476
484
  * without an approval. A member that reads a value its group computes in its
477
485
  * apply (`group.reads`, ws-107 ruling 4) makes it not empty: what the plan
478
- * shows may not be all the apply does.
486
+ * shows may not be all the apply does. A member whose plan changes an
487
+ * output (`outputs`, #4849) makes it not empty too.
479
488
  */
480
489
  export function isEmptyChangeSet(doc: Pick<ChangeSetDocument, "members" | "entries">): boolean {
481
490
  if (doc.members.length === 0) return false;
482
491
  for (const m of doc.members) {
483
492
  if (m.status !== "planned" || m.provisional === true || m.holes.length > 0) return false;
493
+ if (m.outputs && m.outputs.length > 0) return false;
484
494
  if (m.group && m.group.reads.length > 0) return false;
485
495
  }
486
496
  return doc.entries.every((e) => (e.action === "no-op" || e.action === "read") && e.mayAppear !== true);
@@ -345,4 +345,13 @@ describe("the run record", () => {
345
345
  expect(r).toMatchObject({ op: "plywood-drift-app", env: "local", status: "ok", labels: { Agent: "drift" }, outcomes: { agent: { trigger: "drift", result: "opened", usage: { usd: 0.4 } } } });
346
346
  expect(r.phases[0]!.steps[0]).toMatchObject({ fn: "agent:drift", status: "ok", durationMs: 300_000 });
347
347
  });
348
+
349
+ test("takes a product's own trigger word and records it as given (#4817)", () => {
350
+ const settings = { name: "terragucci-review", on: "review", env: "local" };
351
+ const r = agentRunRecordInput({ settings, started: "2026-10-27T11:00:00Z", ended: "2026-10-27T11:01:00Z", result: "updated", reason: "noted" });
352
+ expect(r).toMatchObject({ op: "terragucci-review", labels: { Agent: "review" }, outcomes: { agent: { trigger: "review", result: "updated" } } });
353
+ expect(r.phases[0]!.steps[0]).toMatchObject({ fn: "agent:review", status: "ok" });
354
+ const refused = agentRunRecordInput({ settings: { ...settings, name: "terragucci-refused-wave", on: "refused-wave" }, started: "2026-10-27T11:00:00Z", ended: "2026-10-27T11:00:00Z", result: "refused", reason: "refused" });
355
+ expect(refused).toMatchObject({ status: "ok", labels: { Agent: "refused-wave" }, outcomes: { agent: { trigger: "refused-wave" } } });
356
+ });
348
357
  });
package/src/ci-agent.ts CHANGED
@@ -51,6 +51,14 @@ export const CI_AGENT_FLOOR = "0.124.55";
51
51
  export type AgentTrigger = "comment" | "drift";
52
52
  export const AGENT_TRIGGERS: readonly AgentTrigger[] = ["comment", "drift"];
53
53
 
54
+ /**
55
+ * The trigger a run record names (#4817): one of chant's {@link AgentTrigger}s,
56
+ * or a product's own word for a model run it records on the same ledger, such
57
+ * as terragucci's `review` and `refused-wave`. A record's `trigger` was always
58
+ * a plain string, so a record written with chant's two words reads the same.
59
+ */
60
+ export type AgentRunTrigger = AgentTrigger | (string & {});
61
+
54
62
  /**
55
63
  * A scheduled Op spec's `agent` (#4616): the agent jobs the Op generator
56
64
  * writes. With `on: "comment"` the spec is the agent's own workflow,
@@ -763,9 +771,14 @@ export interface LandInput {
763
771
  runUrl?: string;
764
772
  }
765
773
 
766
- /** The run record of one agent run (#4551): op `<name>`, one phase with one step, the outcome in `outcomes`. */
774
+ /**
775
+ * The run record of one agent run (#4551): op `<name>`, one phase with one
776
+ * step, the outcome in `outcomes`. `settings.on` is the outcome's `trigger`,
777
+ * the `Agent` label and the step's `agent:<on>`. A trigger outside
778
+ * {@link AGENT_TRIGGERS}, a product's own word (#4817), is recorded as given.
779
+ */
767
780
  export function agentRunRecordInput(o: {
768
- settings: Pick<AgentSettings, "name" | "on" | "env">;
781
+ settings: Pick<AgentSettings, "name" | "env"> & { on: AgentRunTrigger };
769
782
  started: string;
770
783
  ended: string;
771
784
  result: AgentResult;
@@ -36,7 +36,6 @@ import {
36
36
  } from "./ci-commit";
37
37
  import { assertProductWords, parseProductComment } from "./ci-product-words";
38
38
  import { PLYWOOD } from "./__fixtures__/product-words";
39
- import { NEXT_RELEASE } from "./release-floors";
40
39
  import type { OpRunRecord, OpRunRecordInput } from "./op/runtime";
41
40
  import type { PullRequestHead } from "./pr-forge";
42
41
 
@@ -574,7 +573,7 @@ describe("the comment's argument (#4820)", () => {
574
573
  });
575
574
 
576
575
  test("the floor is the next release until it ships", () => {
577
- expect(CI_COMMIT_ARG_FLOOR).toBe(NEXT_RELEASE);
576
+ expect(CI_COMMIT_ARG_FLOOR).toBe("0.124.78");
578
577
  });
579
578
  });
580
579
 
@@ -642,6 +641,6 @@ describe("the harness's BREAK switch for land (#4836)", () => {
642
641
  });
643
642
 
644
643
  test("the floor is the next release until it ships", () => {
645
- expect(CI_COMMIT_HARNESS_BREAK_FLOOR).toBe(NEXT_RELEASE);
644
+ expect(CI_COMMIT_HARNESS_BREAK_FLOOR).toBe("0.124.78");
646
645
  });
647
646
  });
package/src/ci-commit.ts CHANGED
@@ -32,7 +32,6 @@ import { CHANT_EXIT } from "./exit-codes";
32
32
  import { FORGE_TOKEN_VARS } from "./ci-handover";
33
33
  import { agentForbiddenPaths, AgentError, branchOk, errText, LOGIN, readSmall, SHA, type AgentGit } from "./ci-agent";
34
34
  import { COMMIT_COMMENT_ARG, parseProductComment, type CiProductWords } from "./ci-product-words";
35
- import { NEXT_RELEASE } from "./release-floors";
36
35
  import type { OpRunRecord, OpRunRecordInput } from "./op/runtime";
37
36
  import type { RunOrigin } from "./lifecycle/release-ledger";
38
37
  import type { PrForge } from "./pr-forge";
@@ -51,9 +50,9 @@ export const CI_COMMIT_FILES_FLOOR = "0.124.73";
51
50
  */
52
51
  export const CI_COMMIT_REPLY_FLOOR = "0.124.77";
53
52
  /** The first chant whose commit job takes `commentArg`, one argument after the comment's word passed into the argv (#4820). */
54
- export const CI_COMMIT_ARG_FLOOR = NEXT_RELEASE;
53
+ export const CI_COMMIT_ARG_FLOOR = "0.124.78";
55
54
  /** The first chant whose `commit land` reads {@link COMMIT_HARNESS_BREAK_ENV} in a BREAK arm of chant's e2e harness (#4836). */
56
- export const CI_COMMIT_HARNESS_BREAK_FLOOR = NEXT_RELEASE;
55
+ export const CI_COMMIT_HARNESS_BREAK_FLOOR = "0.124.78";
57
56
 
58
57
  /** What starts a commit run: a person's comment, or a check job's finding. */
59
58
  export type CommitTrigger = "comment" | "check";
package/src/ci-product.ts CHANGED
@@ -322,9 +322,13 @@ export type { ProductMcpContext, ProductMcpHook } from "./cli/mcp/product-tools"
322
322
  * true` for these, and its hook gains `propose?: boolean`. Feature-detect on
323
323
  * `PRODUCT_MCP_PROPOSE_FLOOR`: on an older chant the read-only server drops a
324
324
  * `forgeWrite` tool, and `--propose` is not a flag it parses.
325
+ *
326
+ * `tools/list` gives each tool's MCP annotations from `MCP_TOOL_ANNOTATIONS_FLOOR`
327
+ * on (chant#4823): `readOnly: true` and `forgeWrite: true` set `readOnlyHint`
328
+ * and `destructiveHint`, and a contribution's `annotations` add the rest.
325
329
  */
326
- export { PRODUCT_MCP_PROPOSE_FLOOR, PRODUCT_TOOL_PROPOSE_WORDS } from "./cli/mcp/product-tools";
327
- export type { McpToolContribution } from "./mcp/types";
330
+ export { MCP_TOOL_ANNOTATIONS_FLOOR, PRODUCT_MCP_PROPOSE_FLOOR, PRODUCT_TOOL_PROPOSE_WORDS } from "./cli/mcp/product-tools";
331
+ export type { McpToolContribution, ToolAnnotations } from "./mcp/types";
328
332
  export {
329
333
  activeOtlp,
330
334
  configureOtlp,
@@ -120,6 +120,11 @@ async function releaseImagesOf(cwd: string): Promise<import("../../lifecycle/rel
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) {
@@ -176,7 +181,7 @@ export async function runReleaseImages(ctx: CommandContext): Promise<number> {
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) {
@@ -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",