@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
@@ -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";
package/src/config.ts CHANGED
@@ -128,6 +128,11 @@ export const ChantConfigSchema = z.object({
128
128
  )
129
129
  .optional(),
130
130
  lane: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "a ci.green lane name: lowercase letters, digits and dashes").optional(),
131
+ // #4840: the label stamped into these packages' package.json at the cut and the publish.
132
+ version: z.object({
133
+ packages: z.array(z.string().min(1)).min(1),
134
+ lockfile: z.union([z.string().min(1), z.literal(false)]).optional(),
135
+ }).strict().optional(),
131
136
  workflow: z.object({
132
137
  trigger: z.enum(["tag", "dispatch"]).optional(),
133
138
  gate: z.enum(["last-green", "head"]).optional(),
@@ -423,6 +428,16 @@ export interface ChantConfig {
423
428
  * rather than `ci/green/<sha>`.
424
429
  */
425
430
  lane?: string;
431
+ /**
432
+ * The package directories whose `package.json` the release stamps with
433
+ * its label (#4840), so the version needs no commit: the cut stamps them
434
+ * before it builds the images and runs the build and puts them back, and
435
+ * the publish job stamps them with `chant release stamp <label>` before
436
+ * its build. The lockfile's entries for them follow (`lockfile`, default
437
+ * `package-lock.json` when there is one). See
438
+ * ./lifecycle/release-version.ts.
439
+ */
440
+ version?: import("./lifecycle/release-version").ReleaseVersionConfig;
426
441
  /**
427
442
  * The release pipeline `chant release workflow` writes (#4656): a
428
443
  * dispatched release with gate, cut, publish and post-release jobs, the
package/src/lexicon.ts CHANGED
@@ -47,7 +47,6 @@ import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption"
47
47
  import type { OwnerChainVerdict } from "./owner-chain";
48
48
  import type { CommandGroup } from "./cli/command-group";
49
49
  import type { Archetype } from "./components/component";
50
- import { NEXT_RELEASE } from "./release-floors";
51
50
 
52
51
  // Re-exported so a lexicon that hosts Op runs (#2121) can type its
53
52
  // `opRuntime` from the same entry it imports the plugin contract from.
@@ -1322,7 +1321,7 @@ export interface CompositeEntry {
1322
1321
  * {@link LexiconPlugin.ciSetup}, so it freezes with chant's release; the
1323
1322
  * lexicon re-exports it as `PULUMI_CI_SETUP_FLOOR`.
1324
1323
  */
1325
- export const CI_SETUP_UNLINKED_FLOOR = NEXT_RELEASE;
1324
+ export const CI_SETUP_UNLINKED_FLOOR = "0.124.78";
1326
1325
 
1327
1326
  export interface LexiconPlugin {
1328
1327
  // ── Required ──────────────────────────────────────────────
@@ -114,6 +114,10 @@ export type ReleaseCutCode =
114
114
  | "release-image-unknown-component"
115
115
  | "release-image-name-taken"
116
116
  | "release-image-build-failed"
117
+ | "release-version-no-label"
118
+ | "release-version-label-invalid"
119
+ | "release-version-no-package"
120
+ | "release-version-invalid"
117
121
  | "release-unsigned"
118
122
  | "release-signer-refused"
119
123
  | "declaration-invalid";
@@ -179,6 +183,12 @@ export interface CutRequest {
179
183
  * Given the commit being cut; returns each as an image artifact.
180
184
  */
181
185
  buildImages?: (commit: string) => Promise<ReleaseArtifact[]> | ReleaseArtifact[];
186
+ /**
187
+ * Stamp the label into the files `release.version` names (#4840), once the
188
+ * tree is found clean and before the images are built or any environment
189
+ * compiled. The caller puts the files back after the cut.
190
+ */
191
+ stamp?: () => void | Promise<void>;
182
192
  }
183
193
 
184
194
  export interface CutResult {
@@ -456,6 +466,7 @@ async function prepare(req: CutRequest, record = false): Promise<Prepared> {
456
466
  "Commit or stash them, or cut from a clean checkout of the commit.",
457
467
  );
458
468
  }
469
+ await req.stamp?.();
459
470
 
460
471
  let envs = req.environments;
461
472
  if (!envs) {
@@ -13,7 +13,6 @@ import { tmpdir } from "node:os";
13
13
  import { join } from "node:path";
14
14
  import { describe, expect, test } from "vitest";
15
15
  import { ChantConfigSchema } from "../config";
16
- import { NEXT_RELEASE } from "../release-floors";
17
16
  import {
18
17
  buildReleaseImages,
19
18
  checkReleaseImages,
@@ -46,6 +45,15 @@ describe("a release.images entry that names a Dockerfile (#4819)", () => {
46
45
  expect(own).toContain("mkdir -p out && ");
47
46
  });
48
47
 
48
+ test("under release.version the build passes the label as CHANT_RELEASE_LABEL, for the image's version label (#4840)", () => {
49
+ const entry = { name: "pulumi", dockerfile: "images/plywood-pulumi/Dockerfile" };
50
+ const plain = releaseImageBuildCommand(entry);
51
+ expect(plain).not.toContain("CHANT_RELEASE_LABEL");
52
+ expect(releaseImageBuildCommand(entry, { versionArg: true })).toBe(
53
+ plain.replace('--build-arg SOURCE_DATE_EPOCH="$SOURCE_DATE_EPOCH"', '--build-arg SOURCE_DATE_EPOCH="$SOURCE_DATE_EPOCH" --build-arg CHANT_RELEASE_LABEL="$CHANT_RELEASE_LABEL"'),
54
+ );
55
+ });
56
+
49
57
  test("the archive defaults to dist/images/<name>.tar, and a build entry is as it was", () => {
50
58
  const images: ReleaseImageDeclaration[] = [
51
59
  { name: "pulumi", dockerfile: "images/plywood-pulumi/Dockerfile" },
@@ -143,7 +151,7 @@ describe("a release.images entry that names a Dockerfile (#4819)", () => {
143
151
  expect(ok([{ name: "both", build: "x", archive: "a.tar", dockerfile: "D" }])).toBe(false);
144
152
  });
145
153
 
146
- test("the floor names the next release", () => expect(RELEASE_IMAGE_DOCKERFILE_FLOOR).toBe(NEXT_RELEASE));
154
+ test("the floor names the next release", () => expect(RELEASE_IMAGE_DOCKERFILE_FLOOR).toBe("0.124.78"));
147
155
  });
148
156
 
149
157
  describe("the digest table and the pins file (#4819)", () => {
@@ -38,7 +38,6 @@
38
38
  import { spawnSync } from "node:child_process";
39
39
  import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
40
40
  import { dirname, isAbsolute, posix, relative, resolve } from "node:path";
41
- import { NEXT_RELEASE } from "../release-floors";
42
41
  import type { PublishDeclaration } from "./publish-declaration";
43
42
  import type { Release, ReleaseArtifact } from "./release-store";
44
43
 
@@ -53,7 +52,7 @@ export const RELEASE_IMAGES_FLOOR = "0.124.71";
53
52
  * `releaseImagePins` and `writeReleaseImagePins` for a product's package
54
53
  * build (#4819).
55
54
  */
56
- export const RELEASE_IMAGE_DOCKERFILE_FLOOR = NEXT_RELEASE;
55
+ export const RELEASE_IMAGE_DOCKERFILE_FLOOR = "0.124.78";
57
56
 
58
57
  /** One image a release builds in its cut with a command of the product's. */
59
58
  export interface ReleaseImageBuild {
@@ -105,7 +104,7 @@ const archiveOf = (i: ReleaseImageDeclaration): string => i.archive ?? `dist/ima
105
104
  * `SOURCE_DATE_EPOCH` the cut sets passed as a build argument and used to
106
105
  * rewrite every timestamp, and every platform in one image index.
107
106
  */
108
- export function releaseImageBuildCommand(i: ReleaseImageDockerfile): string {
107
+ export function releaseImageBuildCommand(i: ReleaseImageDockerfile, o: { versionArg?: boolean } = {}): string {
109
108
  const archive = archiveOf(i);
110
109
  const b = RELEASE_IMAGE_BUILDER;
111
110
  return [
@@ -113,15 +112,15 @@ export function releaseImageBuildCommand(i: ReleaseImageDockerfile): string {
113
112
  `mkdir -p ${sh(posix.dirname(archive))}`,
114
113
  [
115
114
  `docker buildx build --builder ${b} --no-cache --platform ${sh((i.platforms ?? RELEASE_IMAGE_PLATFORMS).join(","))}`,
116
- `--provenance=false --sbom=false --build-arg SOURCE_DATE_EPOCH="$SOURCE_DATE_EPOCH"`,
115
+ `--provenance=false --sbom=false --build-arg SOURCE_DATE_EPOCH="$SOURCE_DATE_EPOCH"${o.versionArg ? ' --build-arg CHANT_RELEASE_LABEL="$CHANT_RELEASE_LABEL"' : ""}`,
117
116
  `--output ${sh(`type=oci,dest=${archive},rewrite-timestamp=true`)} -f ${sh(i.dockerfile)} ${sh(i.context ?? ".")} >&2`,
118
117
  ].join(" "),
119
118
  ].join(" && ");
120
119
  }
121
120
 
122
121
  /** Each entry as a command and an archive: a Dockerfile entry's command is {@link releaseImageBuildCommand}, its archive the default when it names none. */
123
- export function resolveReleaseImages(images: readonly ReleaseImageDeclaration[]): ReleaseImageBuild[] {
124
- return images.map((i) => (isDockerfile(i) ? { name: i.name, build: releaseImageBuildCommand(i), archive: archiveOf(i) } : i));
122
+ export function resolveReleaseImages(images: readonly ReleaseImageDeclaration[], o: { versionArg?: boolean } = {}): ReleaseImageBuild[] {
123
+ return images.map((i) => (isDockerfile(i) ? { name: i.name, build: releaseImageBuildCommand(i, o), archive: archiveOf(i) } : i));
125
124
  }
126
125
 
127
126
  export class ReleaseImageError extends Error {
@@ -169,6 +168,11 @@ export interface BuildImagesInput {
169
168
  label: string | null;
170
169
  env?: NodeJS.ProcessEnv;
171
170
  archiveDigest: ArchiveDigest;
171
+ /**
172
+ * `release.version` stamps the label (#4840): a Dockerfile entry gets it as
173
+ * the build argument `CHANT_RELEASE_LABEL`, for the image's version label.
174
+ */
175
+ versionArg?: boolean;
172
176
  /** Run one build command; the default runs it through the shell with its output on stderr. */
173
177
  run?: (command: string, o: { cwd: string; env: NodeJS.ProcessEnv }) => number | null;
174
178
  }
@@ -202,7 +206,7 @@ export function buildReleaseImages(i: BuildImagesInput): ReleaseArtifact[] {
202
206
  const status = run(image.prepare, { cwd: i.cwd, env });
203
207
  if (status !== 0) throw new ReleaseImageError("release-image-build-failed", `the prepare command of image "${image.name}" exited ${status ?? "with a signal"}: ${image.prepare}`);
204
208
  }
205
- for (const image of resolveReleaseImages(i.images)) {
209
+ for (const image of resolveReleaseImages(i.images, i.versionArg ? { versionArg: true } : {})) {
206
210
  const env = envFor();
207
211
  const status = run(image.build, { cwd: i.cwd, env });
208
212
  if (status !== 0) throw new ReleaseImageError("release-image-build-failed", `the build of image "${image.name}" exited ${status ?? "with a signal"}: ${image.build}`);
@@ -231,7 +235,7 @@ const SHA256 = /^sha256:[0-9a-f]{64}$/;
231
235
  export interface ReleaseImagePinsInput {
232
236
  /** Each image's name in `release.images`, to its reference at this version: `ghcr.io/intentius/plywood-pulumi:0.3.0-pulumi3.272.0`. */
233
237
  images: Record<string, string>;
234
- /** The package's version. A cut's label (`CHANT_RELEASE_LABEL`) must be it. */
238
+ /** The package's version. A cut's label (`CHANT_RELEASE_LABEL`) must be it, as it is when `release.version` stamps the package (#4840). */
235
239
  version: string;
236
240
  env?: NodeJS.ProcessEnv;
237
241
  }
@@ -41,6 +41,7 @@
41
41
 
42
42
  import { execFileSync } from "node:child_process";
43
43
  import type { Release } from "./release-store";
44
+ import { stampedChanges, type ReleaseVersionConfig } from "./release-version";
44
45
  import { createRedactor, type Redactor } from "./publish-credentials";
45
46
 
46
47
  /** Whether this run can sign provenance with an OIDC token, and why not when it can't. */
@@ -421,7 +422,10 @@ export async function preparePublish(req: {
421
422
  }
422
423
  // A target publishes files from this checkout, so they must be the release commit's (#4047).
423
424
  if (targets.length > 0) {
424
- const refused = checkCheckoutIsRelease(cwd, release.commit, name);
425
+ // #4840: the files release.version names may carry the label, as the publish job's `chant release stamp` writes them.
426
+ const { loadChantConfig } = await import("../config");
427
+ const version = (await loadChantConfig(cwd)).config.release?.version;
428
+ const refused = checkCheckoutIsRelease(cwd, release.commit, name, version ? { version, label } : {});
425
429
  if (refused) return { refusal: refused };
426
430
  }
427
431
 
@@ -455,8 +459,16 @@ export async function preparePublish(req: {
455
459
  * checkout is the release's commit with nothing changed, so a publish refuses
456
460
  * a `HEAD` that is another commit and a tree with changes git sees. A publish
457
461
  * with no target reads nothing and checks neither.
462
+ *
463
+ * Under `release.version` (#4840), a file it names that is exactly the
464
+ * commit's stamped with the release's label is the commit's too.
458
465
  */
459
- export function checkCheckoutIsRelease(cwd: string, commit: string, name: string): PublishRefusal | null {
466
+ export function checkCheckoutIsRelease(
467
+ cwd: string,
468
+ commit: string,
469
+ name: string,
470
+ o: { version?: ReleaseVersionConfig; label?: string | null } = {},
471
+ ): PublishRefusal | null {
460
472
  const head = tryGit(cwd, ["rev-parse", "HEAD"]);
461
473
  if (head !== commit) {
462
474
  return {
@@ -465,7 +477,8 @@ export function checkCheckoutIsRelease(cwd: string, commit: string, name: string
465
477
  fix: `Check out the release's commit, as a CI job on its tag does: git checkout ${commit}`,
466
478
  };
467
479
  }
468
- const status = tryGit(cwd, ["status", "--porcelain", "--untracked-files=normal"]);
480
+ let status = tryGit(cwd, ["status", "--porcelain", "--untracked-files=normal"]);
481
+ if (status && o.version) status = withoutStamps(cwd, commit, o.version, o.label ?? null, status);
469
482
  if (status) {
470
483
  const n = status.split("\n").length;
471
484
  return {
@@ -477,6 +490,24 @@ export function checkCheckoutIsRelease(cwd: string, commit: string, name: string
477
490
  return null;
478
491
  }
479
492
 
493
+ /** The porcelain status without the files {@link stampedChanges} takes as the commit's stamped with the label. */
494
+ function withoutStamps(cwd: string, commit: string, version: ReleaseVersionConfig, label: string | null, status: string): string {
495
+ let raw: string;
496
+ let top: string;
497
+ try {
498
+ raw = execFileSync("git", ["status", "--porcelain", "--untracked-files=normal"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
499
+ top = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
500
+ } catch {
501
+ return status;
502
+ }
503
+ const stamped = stampedChanges({ cwd, top, commit, config: version, label, status: raw });
504
+ return raw
505
+ .split("\n")
506
+ .filter((l) => l.length > 0 && !stamped.has(l.slice(3)))
507
+ .join("\n")
508
+ .trim();
509
+ }
510
+
480
511
  function tryGit(cwd: string, args: string[]): string | null {
481
512
  try {
482
513
  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -0,0 +1,155 @@
1
+ /**
2
+ * #4840: `release.version` stamps the release's label into package.json at
3
+ * the cut and the publish, so a product needs no version-bump commit.
4
+ */
5
+
6
+ import { afterAll, describe, expect, test } from "vitest";
7
+ import { readFileSync, rmSync } from "node:fs";
8
+ import { dirname, join } from "node:path";
9
+ import { cutRelease, ReleaseCutError } from "./release-cut";
10
+ import { checkCheckoutIsRelease } from "./release-publish";
11
+ import { checkVersionLabel, releaseVersionFiles, ReleaseVersionError, stampedChanges, stampReleaseVersion, stampText, type ReleaseVersionConfig } from "./release-version";
12
+ import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
13
+ import { TestRepo } from "../workspace/trust/test-repo";
14
+ import { ChantConfigSchema } from "../config";
15
+
16
+ const repos: TestRepo[] = [];
17
+ afterAll(() => {
18
+ for (const r of repos) rmSync(dirname(r.dir), { recursive: true, force: true });
19
+ });
20
+
21
+ const PKG = `{\n "name": "@acme/cli",\n "version": "0.4.52",\n "dependencies": {\n "@intentius/chant": "0.124.77"\n }\n}\n`;
22
+ const ROOT = `{\n "name": "acme",\n "private": true,\n "workspaces": ["packages/*"]\n}\n`;
23
+ const LOCK = `{\n "name": "acme",\n "lockfileVersion": 3,\n "requires": true,\n "packages": {\n "": {\n "name": "acme",\n "workspaces": [\n "packages/*"\n ]\n },\n "packages/cli": {\n "name": "@acme/cli",\n "version": "0.4.52"\n },\n "node_modules/@acme/cli": {\n "resolved": "packages/cli",\n "link": true\n }\n }\n}\n`;
24
+
25
+ /** A workspace with one package, as terragucci's is, committed and green. */
26
+ function workspace(label: string): { r: TestRepo; head: string } {
27
+ const r = new TestRepo(label);
28
+ repos.push(r);
29
+ r.write("chant.config.ts", `export default { environments: ["dev"] };\n`);
30
+ r.write("package.json", ROOT);
31
+ r.write("package-lock.json", LOCK);
32
+ r.write("packages/cli/package.json", PKG);
33
+ const head = r.commit("init");
34
+ r.git(["tag", `ci/green/${head}`]);
35
+ return { r, head };
36
+ }
37
+
38
+ const CONFIG: ReleaseVersionConfig = { packages: ["packages/cli"] };
39
+
40
+ describe("stamping the label (#4840)", () => {
41
+ test("a package.json changes in its version alone, and a lockfile in the package's entry", () => {
42
+ expect(stampText(PKG, "0.4.53", "package")).toBe(PKG.replace(`"version": "0.4.52"`, `"version": "0.4.53"`));
43
+ expect(stampText(LOCK, "0.4.53", "lockfile", ["packages/cli"])).toBe(LOCK.replace(`"version": "0.4.52"`, `"version": "0.4.53"`));
44
+ // The member's own package: the root entry and the lockfile's top-level version.
45
+ const rootLock = `{\n "name": "yodel",\n "version": "0.12.1",\n "lockfileVersion": 3,\n "packages": {\n "": {\n "name": "yodel",\n "version": "0.12.1"\n }\n }\n}\n`;
46
+ expect(stampText(rootLock, "0.13.0", "lockfile", ["."])).toBe(rootLock.replaceAll("0.12.1", "0.13.0"));
47
+ // A tab-indented file keeps its tabs.
48
+ expect(stampText(`{\n\t"name": "a",\n\t"version": "1.0.0"\n}\n`, "1.0.1", "package")).toBe(`{\n\t"name": "a",\n\t"version": "1.0.1"\n}\n`);
49
+ });
50
+
51
+ test("the files are each package's package.json and the lockfile when there is one", () => {
52
+ const { r } = workspace("release-version-files");
53
+ expect(releaseVersionFiles(r.dir, CONFIG)).toEqual(["packages/cli/package.json", "package-lock.json"]);
54
+ expect(releaseVersionFiles(r.dir, { packages: ["."], lockfile: false })).toEqual(["package.json"]);
55
+ });
56
+
57
+ test("stamp, then restore, puts every file back byte for byte", () => {
58
+ const { r } = workspace("release-version-restore");
59
+ const s = stampReleaseVersion({ cwd: r.dir, config: CONFIG, label: "0.4.53" });
60
+ expect(JSON.parse(readFileSync(join(r.dir, "packages/cli/package.json"), "utf-8")).version).toBe("0.4.53");
61
+ expect(JSON.parse(readFileSync(join(r.dir, "package-lock.json"), "utf-8")).packages["packages/cli"].version).toBe("0.4.53");
62
+ s.restore();
63
+ expect(readFileSync(join(r.dir, "packages/cli/package.json"), "utf-8")).toBe(PKG);
64
+ expect(readFileSync(join(r.dir, "package-lock.json"), "utf-8")).toBe(LOCK);
65
+ expect(r.git(["status", "--porcelain"])).toBe("");
66
+ });
67
+
68
+ test("a label npm can't take as a version, no label, and a missing package are refused before anything is written", () => {
69
+ expect(() => checkVersionLabel(null)).toThrow(ReleaseVersionError);
70
+ expect(() => checkVersionLabel("v1.4.0")).toThrow(/"v1.4.0" is not a version npm takes/);
71
+ expect((() => { try { checkVersionLabel("v1.4.0"); } catch (e) { return (e as ReleaseVersionError).fix; } })()).toBe("Label the release MAJOR.MINOR.PATCH, such as 1.4.0, with no v.");
72
+ expect(() => checkVersionLabel("1.4")).toThrow(/not a version/);
73
+ expect(() => checkVersionLabel("1.4.0-rc.1")).not.toThrow();
74
+ const { r } = workspace("release-version-refuse");
75
+ expect(() => stampReleaseVersion({ cwd: r.dir, config: { packages: ["packages/cli", "packages/nope"] }, label: "0.4.53" })).toThrow(/packages\/nope\/package.json, which does not exist/);
76
+ expect(r.git(["status", "--porcelain"])).toBe("");
77
+ expect(() => stampReleaseVersion({ cwd: r.dir, config: { packages: ["../other"] }, label: "0.4.53" })).toThrow(/not a path inside the member/);
78
+ });
79
+
80
+ test("chant.config.ts takes release.version, and refuses a misspelt key", () => {
81
+ expect(ChantConfigSchema.safeParse({ release: { version: { packages: ["packages/cli"], lockfile: false } } }).success).toBe(true);
82
+ expect(ChantConfigSchema.safeParse({ release: { version: { package: ["packages/cli"] } } }).success).toBe(false);
83
+ expect(ChantConfigSchema.safeParse({ release: { version: { packages: [] } } }).success).toBe(false);
84
+ });
85
+ });
86
+
87
+ describe("the publish takes a stamped tree as the commit's (#4840)", () => {
88
+ test("only the named files, stamped with this release's label, pass the checkout check", () => {
89
+ const { r, head } = workspace("release-version-publish");
90
+ // Today's check, with no release.version: a stamped tree is dirty.
91
+ stampReleaseVersion({ cwd: r.dir, config: CONFIG, label: "0.4.53" });
92
+ expect(checkCheckoutIsRelease(r.dir, head, "0.4.53")?.code).toBe("release-worktree-dirty");
93
+ expect(checkCheckoutIsRelease(r.dir, head, "0.4.53", { version: CONFIG, label: "0.4.53" })).toBeNull();
94
+ // Another release's label is not this one's.
95
+ expect(checkCheckoutIsRelease(r.dir, head, "0.4.54", { version: CONFIG, label: "0.4.54" })?.code).toBe("release-worktree-dirty");
96
+ // Any other change in a stamped file, or another file changed, is still dirty.
97
+ r.write("README.md", "changed\n");
98
+ expect(checkCheckoutIsRelease(r.dir, head, "0.4.53", { version: CONFIG, label: "0.4.53" })?.code).toBe("release-worktree-dirty");
99
+ r.git(["checkout", "--", "."]);
100
+ r.git(["clean", "-fdq"]);
101
+ r.write("packages/cli/package.json", PKG.replace("0.4.52", "0.4.53").replace("0.124.77", "0.124.78"));
102
+ expect(stampedChanges({ cwd: r.dir, top: r.dir, commit: head, config: CONFIG, label: "0.4.53", status: r.git(["status", "--porcelain"]) }).size).toBe(0);
103
+ });
104
+ });
105
+
106
+ describe("the cut stamps after its clean-tree check and before it builds (#4840)", () => {
107
+ test("the images and the compile read the label from package.json, and the tree is the commit's after", async () => {
108
+ const { r } = workspace("release-version-cut");
109
+ const seen: string[] = [];
110
+ const version = () => JSON.parse(readFileSync(join(r.dir, "packages/cli/package.json"), "utf-8")).version as string;
111
+ const compiler: TargetCompiler = {
112
+ async compile(env): Promise<CompiledTarget> {
113
+ seen.push(`compile ${version()}`);
114
+ return { env, params: [], components: [], buildSteps: {}, buildInputs: {}, componentFiles: {}, templates: [{ component: null, path: "dist/out.json", content: "{}\n" }] };
115
+ },
116
+ async buildArtifacts() {
117
+ return [];
118
+ },
119
+ };
120
+ let stamped: ReturnType<typeof stampReleaseVersion> | null = null;
121
+ try {
122
+ await cutRelease({
123
+ cwd: r.dir,
124
+ compiler,
125
+ label: "0.4.53",
126
+ actor: "alice",
127
+ env: {},
128
+ now: () => new Date("2026-11-08T10:00:00.000Z"),
129
+ stamp: () => {
130
+ seen.push(`stamp ${version()}`);
131
+ stamped = stampReleaseVersion({ cwd: r.dir, config: CONFIG, label: "0.4.53" });
132
+ },
133
+ buildImages: () => {
134
+ seen.push(`images ${version()}`);
135
+ return [];
136
+ },
137
+ });
138
+ } finally {
139
+ (stamped as ReturnType<typeof stampReleaseVersion> | null)?.restore();
140
+ }
141
+ expect(seen).toEqual(["stamp 0.4.52", "images 0.4.53", "compile 0.4.53"]);
142
+ expect(r.git(["status", "--porcelain"])).toBe("");
143
+ });
144
+
145
+ test("a dirty tree is refused before anything is stamped", async () => {
146
+ const { r } = workspace("release-version-cut-dirty");
147
+ r.write("packages/cli/package.json", PKG.replace("0.4.52", "9.9.9"));
148
+ let called = false;
149
+ const compiler: TargetCompiler = { async compile(env) { return { env, params: [], components: [], buildSteps: {}, buildInputs: {}, componentFiles: {}, templates: [] }; }, async buildArtifacts() { return []; } };
150
+ const err = await cutRelease({ cwd: r.dir, compiler, label: "0.4.53", actor: "alice", env: {}, stamp: () => { called = true; } }).catch((e: unknown) => e);
151
+ expect(err).toBeInstanceOf(ReleaseCutError);
152
+ expect((err as ReleaseCutError).code).toBe("release-worktree-dirty");
153
+ expect(called).toBe(false);
154
+ });
155
+ });