@intentius/chant 0.124.70 → 0.124.72

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 (169) hide show
  1. package/dist/ci-agent.d.ts +12 -1
  2. package/dist/ci-agent.d.ts.map +1 -1
  3. package/dist/ci-agent.js +13 -8
  4. package/dist/ci-commit.d.ts +326 -0
  5. package/dist/ci-commit.d.ts.map +1 -0
  6. package/dist/ci-commit.js +725 -0
  7. package/dist/ci-estate/delivery.d.ts +75 -2
  8. package/dist/ci-estate/delivery.d.ts.map +1 -1
  9. package/dist/ci-estate/delivery.js +129 -0
  10. package/dist/ci-estate.d.ts +3 -1
  11. package/dist/ci-estate.d.ts.map +1 -1
  12. package/dist/ci-estate.js +4 -1
  13. package/dist/ci-product-words.d.ts +6 -1
  14. package/dist/ci-product-words.d.ts.map +1 -1
  15. package/dist/ci-product-words.js +3 -1
  16. package/dist/ci-product.d.ts +1 -1
  17. package/dist/ci-product.d.ts.map +1 -1
  18. package/dist/ci-product.js +1 -1
  19. package/dist/cli/handlers/approve.d.ts.map +1 -1
  20. package/dist/cli/handlers/approve.js +7 -2
  21. package/dist/cli/handlers/commit.d.ts +26 -0
  22. package/dist/cli/handlers/commit.d.ts.map +1 -0
  23. package/dist/cli/handlers/commit.js +145 -0
  24. package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
  25. package/dist/cli/handlers/notify-relay.js +22 -2
  26. package/dist/cli/handlers/pr.d.ts +6 -0
  27. package/dist/cli/handlers/pr.d.ts.map +1 -1
  28. package/dist/cli/handlers/pr.js +16 -7
  29. package/dist/cli/handlers/release.d.ts +9 -0
  30. package/dist/cli/handlers/release.d.ts.map +1 -1
  31. package/dist/cli/handlers/release.js +114 -5
  32. package/dist/cli/main.d.ts.map +1 -1
  33. package/dist/cli/main.js +17 -0
  34. package/dist/components/product-pipeline.d.ts +33 -0
  35. package/dist/components/product-pipeline.d.ts.map +1 -1
  36. package/dist/components/product-pipeline.js +34 -1
  37. package/dist/components/release-compile.d.ts +2 -0
  38. package/dist/components/release-compile.d.ts.map +1 -1
  39. package/dist/components/release-compile.js +8 -4
  40. package/dist/config.d.ts +60 -0
  41. package/dist/config.d.ts.map +1 -1
  42. package/dist/config.js +16 -0
  43. package/dist/lexicon.d.ts +54 -0
  44. package/dist/lexicon.d.ts.map +1 -1
  45. package/dist/lexicon.js +28 -0
  46. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +4 -0
  47. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  48. package/dist/lifecycle/__fixtures__/publish-fakes.js +6 -2
  49. package/dist/lifecycle/gated-request.d.ts +3 -1
  50. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  51. package/dist/lifecycle/gated-request.js +5 -2
  52. package/dist/lifecycle/git.d.ts.map +1 -1
  53. package/dist/lifecycle/git.js +57 -0
  54. package/dist/lifecycle/publish-declaration.d.ts +16 -0
  55. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  56. package/dist/lifecycle/publish-declaration.js +35 -3
  57. package/dist/lifecycle/publish-forge.d.ts +12 -0
  58. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  59. package/dist/lifecycle/publish-forge.js +102 -19
  60. package/dist/lifecycle/publish-npm.d.ts +15 -0
  61. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  62. package/dist/lifecycle/publish-npm.js +28 -1
  63. package/dist/lifecycle/publish-oci.d.ts +2 -0
  64. package/dist/lifecycle/publish-oci.d.ts.map +1 -1
  65. package/dist/lifecycle/publish-oci.js +10 -0
  66. package/dist/lifecycle/release-cut.d.ts +7 -1
  67. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  68. package/dist/lifecycle/release-cut.js +8 -1
  69. package/dist/lifecycle/release-images.d.ts +87 -0
  70. package/dist/lifecycle/release-images.d.ts.map +1 -0
  71. package/dist/lifecycle/release-images.js +138 -0
  72. package/dist/lifecycle/release-publish.d.ts +2 -0
  73. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  74. package/dist/notify-relay.d.ts +41 -1
  75. package/dist/notify-relay.d.ts.map +1 -1
  76. package/dist/notify-relay.js +40 -0
  77. package/dist/notify.d.ts +16 -3
  78. package/dist/notify.d.ts.map +1 -1
  79. package/dist/notify.js +16 -10
  80. package/dist/op/activities/review-agent.d.ts.map +1 -1
  81. package/dist/op/activities/review-agent.js +4 -2
  82. package/dist/op/gate.d.ts +5 -1
  83. package/dist/op/gate.d.ts.map +1 -1
  84. package/dist/op/gate.js +7 -2
  85. package/dist/op/op-waves-notify.d.ts +1 -1
  86. package/dist/op/op-waves-notify.d.ts.map +1 -1
  87. package/dist/op/op-waves-notify.js +2 -1
  88. package/dist/op/op-waves-run.d.ts.map +1 -1
  89. package/dist/op/op-waves-run.js +12 -8
  90. package/dist/op/op-waves.d.ts +9 -0
  91. package/dist/op/op-waves.d.ts.map +1 -1
  92. package/dist/op/op-waves.js +11 -0
  93. package/dist/pr-forge-base.d.ts +18 -0
  94. package/dist/pr-forge-base.d.ts.map +1 -0
  95. package/dist/pr-forge-base.js +29 -0
  96. package/dist/release-floors.d.ts +1 -1
  97. package/dist/release-floors.js +1 -1
  98. package/dist/wave-runtime.mjs +315 -315
  99. package/dist/workspace/ci-green.d.ts.map +1 -1
  100. package/dist/workspace/ci-green.js +1 -2
  101. package/dist/workspace/release-workflow.d.ts +47 -0
  102. package/dist/workspace/release-workflow.d.ts.map +1 -1
  103. package/dist/workspace/release-workflow.js +258 -14
  104. package/package.json +1 -1
  105. package/src/ci-agent.ts +13 -8
  106. package/src/ci-commit.test.ts +415 -0
  107. package/src/ci-commit.ts +901 -0
  108. package/src/ci-estate/__fixtures__/terragucci-dora.json +1305 -0
  109. package/src/ci-estate/delivery.ts +186 -2
  110. package/src/ci-estate/records-delivery.test.ts +55 -0
  111. package/src/ci-estate.ts +10 -0
  112. package/src/ci-product-words.ts +6 -2
  113. package/src/ci-product.ts +1 -0
  114. package/src/cli/handlers/approve.ts +6 -2
  115. package/src/cli/handlers/commit.ts +155 -0
  116. package/src/cli/handlers/notify-relay.ts +21 -2
  117. package/src/cli/handlers/operator.test.ts +2 -0
  118. package/src/cli/handlers/pr-wave-approve-lines.test.ts +32 -0
  119. package/src/cli/handlers/pr.ts +17 -7
  120. package/src/cli/handlers/release.ts +110 -5
  121. package/src/cli/main.ts +17 -0
  122. package/src/components/product-pipeline.test.ts +28 -1
  123. package/src/components/product-pipeline.ts +54 -1
  124. package/src/components/release-compile.ts +9 -3
  125. package/src/config.ts +31 -0
  126. package/src/lexicon.ts +72 -0
  127. package/src/lifecycle/__fixtures__/publish-fakes.ts +11 -5
  128. package/src/lifecycle/gated-request-spend.test.ts +115 -0
  129. package/src/lifecycle/gated-request.ts +5 -2
  130. package/src/lifecycle/git.ts +53 -0
  131. package/src/lifecycle/ledger-two-clones.test.ts +132 -0
  132. package/src/lifecycle/publish-declaration.ts +35 -3
  133. package/src/lifecycle/publish-forge-notes.test.ts +193 -0
  134. package/src/lifecycle/publish-forge.ts +100 -22
  135. package/src/lifecycle/publish-npm.ts +31 -2
  136. package/src/lifecycle/publish-oci.ts +10 -0
  137. package/src/lifecycle/publish-targets.test.ts +2 -1
  138. package/src/lifecycle/release-cut.ts +17 -1
  139. package/src/lifecycle/release-images.test.ts +242 -0
  140. package/src/lifecycle/release-images.ts +174 -0
  141. package/src/lifecycle/release-publish.ts +2 -0
  142. package/src/notify-relay.test.ts +55 -1
  143. package/src/notify-relay.ts +49 -1
  144. package/src/notify.ts +25 -12
  145. package/src/op/activities/review-agent.test.ts +20 -1
  146. package/src/op/activities/review-agent.ts +5 -2
  147. package/src/op/gate.ts +7 -2
  148. package/src/op/op-waves-approve-target.test.ts +108 -0
  149. package/src/op/op-waves-notify.ts +2 -2
  150. package/src/op/op-waves-run.ts +12 -7
  151. package/src/op/op-waves.ts +12 -0
  152. package/src/pr-forge-base.test.ts +37 -0
  153. package/src/pr-forge-base.ts +36 -0
  154. package/src/release-floors.ts +1 -1
  155. package/src/workspace/__fixtures__/release-workflow/forgejo-plain-member.yml +26 -0
  156. package/src/workspace/__fixtures__/release-workflow/forgejo-plain.yml +23 -0
  157. package/src/workspace/__fixtures__/release-workflow/forgejo-secure-member.yml +27 -0
  158. package/src/workspace/__fixtures__/release-workflow/forgejo-secure.yml +24 -0
  159. package/src/workspace/__fixtures__/release-workflow/github-plain-member.yml +26 -0
  160. package/src/workspace/__fixtures__/release-workflow/github-plain.yml +23 -0
  161. package/src/workspace/__fixtures__/release-workflow/github-secure-member.yml +27 -0
  162. package/src/workspace/__fixtures__/release-workflow/github-secure.yml +24 -0
  163. package/src/workspace/__fixtures__/release-workflow/gitlab-plain-member.yml +13 -0
  164. package/src/workspace/__fixtures__/release-workflow/gitlab-plain.yml +12 -0
  165. package/src/workspace/__fixtures__/release-workflow/gitlab-secure-member.yml +14 -0
  166. package/src/workspace/__fixtures__/release-workflow/gitlab-secure.yml +13 -0
  167. package/src/workspace/ci-green.ts +1 -2
  168. package/src/workspace/release-workflow.test.ts +199 -0
  169. package/src/workspace/release-workflow.ts +356 -14
@@ -15,10 +15,22 @@
15
15
  * The OIDC permission (`id-token: write`, or GitLab's `id_tokens`) is always
16
16
  * there: it costs nothing, and with it what the job uploads carries
17
17
  * provenance whether or not the group requires it.
18
+ *
19
+ * `release.workflow` in the root's `chant.config.ts` (#4656) renders the
20
+ * rest of the release from the same file. `trigger: "dispatch"` starts it by
21
+ * hand with a label, and four jobs follow: the gate names the commit to cut
22
+ * (`chant ci last-green`, or the dispatched commit itself under `gate:
23
+ * "head"`), the cut runs `chant release cut <label> --at <commit>` and pushes
24
+ * the release's tag, the publish job publishes it, and the post-release job
25
+ * runs `after`. No tag exists until the gate has passed. With
26
+ * `release.images` (#4657) the publish job builds the images again with
27
+ * `chant release images` before the build. A config with only `publish`
28
+ * renders the tag-triggered file it always did.
18
29
  */
19
30
  import { ACTION_PINS, tagComments, usesRef } from "../action-pins";
20
31
  import { GENERATED_MARKER } from "../discovery/files";
21
32
  import type { SecurityGroup } from "./security";
33
+ import type { OpSetupStep } from "../lexicon";
22
34
 
23
35
  export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"] as const;
24
36
  export type ReleaseWorkflowForge = (typeof RELEASE_WORKFLOW_FORGES)[number];
@@ -31,6 +43,45 @@ export const RELEASE_WORKFLOW_FILES: Record<ReleaseWorkflowForge, string> = {
31
43
  gitlab: ".gitlab/chant-release.yml",
32
44
  };
33
45
 
46
+ /** `release.workflow` in `chant.config.ts` (#4656): how the release pipeline starts and what it runs. */
47
+ export interface ReleasePipelineConfig {
48
+ /** `tag` (default): the publish job runs on a `release/**` tag. `dispatch`: the whole release starts by hand with a label. */
49
+ trigger?: "tag" | "dispatch";
50
+ /** For `dispatch`: the commit to cut. `last-green` (default) is the newest green commit at or below the dispatched one; `head` is the dispatched commit, which must be green. */
51
+ gate?: "last-green" | "head";
52
+ /** The command that installs what the build needs. Default `npm ci`. */
53
+ install?: string;
54
+ /** The command that builds what the targets upload, run by the cut (as its `--build`) and the publish job. `false` for none. Default `npm run build`. */
55
+ build?: string | false;
56
+ /** What runs chant. Default `npx chant`. */
57
+ chant?: string;
58
+ /** Shell lines run after the publish, with `CHANT_RELEASE_LABEL` set: steps that need a published release. */
59
+ after?: string[];
60
+ /**
61
+ * Scopes added to the workflow's `contents: write` and `id-token: write`
62
+ * (#4751), such as `{ packages: "write" }` for an `oci` target that pushes to
63
+ * GHCR with the run's token. A scope already granted is refused. GitHub and
64
+ * Forgejo only; GitLab has no `permissions:` and refuses it by name.
65
+ */
66
+ permissions?: Record<string, "read" | "write">;
67
+ /**
68
+ * Variables for the cut and publish jobs (#4751), such as an `oci` target's
69
+ * `OCI_USERNAME: "${{ github.actor }}"` and `OCI_PASSWORD: "${{ github.token }}"`.
70
+ * A value may be a forge expression: it goes in the job's `env:` (GitLab:
71
+ * `variables:`), never on a `run:` line.
72
+ */
73
+ env?: Record<string, string>;
74
+ /**
75
+ * Steps the cut and publish jobs run after the install (#4751): `{ run }`,
76
+ * or `{ uses, with }` on GitHub and Forgejo, such as QEMU's binfmt handlers
77
+ * for a two-platform image build, or a newer npm. GitLab takes `run` steps
78
+ * as script lines and refuses `uses` by name.
79
+ */
80
+ setup?: OpSetupStep[];
81
+ /** Where the workflow is written, from the repository root, such as `.github/workflows/publish.yml` for an npm trusted publisher that names that file. Default {@link RELEASE_WORKFLOW_FILES}. */
82
+ file?: string;
83
+ }
84
+
34
85
  export interface ReleaseWorkflowInput {
35
86
  forge: ReleaseWorkflowForge;
36
87
  /** The security groups the workspace opts into at its root. */
@@ -43,6 +94,12 @@ export interface ReleaseWorkflowInput {
43
94
  chant?: string;
44
95
  /** The workspace root relative to the repository root, `.` at the top. */
45
96
  workspaceRoot?: string;
97
+ /** `release.workflow` (#4656). A flag above wins over the field it names. */
98
+ pipeline?: ReleasePipelineConfig;
99
+ /** The config declares `release.images` (#4657): the publish job builds them again first. */
100
+ images?: boolean;
101
+ /** `release.lane` (#4692): the gate's green lane. */
102
+ lane?: string;
46
103
  }
47
104
 
48
105
  /** The flags `chant release publish` gets under the groups. */
@@ -50,16 +107,35 @@ export function publishFlags(groups: ReadonlySet<SecurityGroup>): string[] {
50
107
  return [...(groups.has("supply-chain") ? ["--require-provenance"] : []), "--yes"];
51
108
  }
52
109
 
110
+ /** Where `chant release images` writes the digests the publish job's build reads (#4657). */
111
+ export const RELEASE_DIGESTS_FILE = ".chant/release-digests.json";
112
+
113
+ /** A string as a single-quoted shell word. */
114
+ function sq(s: string): string {
115
+ return `'${s.replaceAll("'", "'\\''")}'`;
116
+ }
117
+
53
118
  /** The workflow file's text, without the generated-by header. */
54
119
  export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
55
- const chant = input.chant ?? "npx chant";
56
- const install = input.install ?? "npm ci";
57
- const build = input.build === undefined ? "npm run build" : input.build;
120
+ const p = input.pipeline ?? {};
121
+ const chant = input.chant ?? p.chant ?? "npx chant";
122
+ const install = input.install ?? p.install ?? "npm ci";
123
+ const build = input.build !== undefined ? input.build : p.build === false ? null : (p.build ?? "npm run build");
58
124
  const root = input.workspaceRoot && input.workspaceRoot !== "." ? input.workspaceRoot : null;
59
125
  const verify = input.groups.has("verified-releases");
60
126
  const flags = publishFlags(input.groups).join(" ");
127
+ const after = p.after ?? [];
128
+ const images = input.images === true;
129
+ const extra = jobExtras(p, input.forge);
130
+ if (p.trigger === "dispatch") {
131
+ const o = { chant, install, build, root, verify, flags, after, images, extra, gate: p.gate ?? "last-green", ...(input.lane ? { lane: input.lane } : {}) };
132
+ return input.forge === "gitlab" ? renderGitlabDispatch(o) : renderGithubDispatch(o);
133
+ }
134
+ // #4657: the images are built from the release, so chant/lifecycle is fetched before them and the build after.
135
+ const imageLines = (label: string, env: string): string[] => [`${chant} release images ${label} -o ${RELEASE_DIGESTS_FILE}`, env];
61
136
  if (input.forge === "gitlab") {
62
137
  const label = '"${CI_COMMIT_TAG#release/}"';
138
+ const fetches = [" - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'", " - git fetch origin chant/lifecycle:chant/lifecycle"];
63
139
  const lines = [
64
140
  "chant-release-publish:",
65
141
  " rules:",
@@ -67,18 +143,35 @@ export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
67
143
  " id_tokens:",
68
144
  " SIGSTORE_ID_TOKEN:",
69
145
  " aud: sigstore",
146
+ ...(extra.gitlabVariables.length > 0 ? [" variables:", ...extra.gitlabVariables] : []),
70
147
  " script:",
71
148
  ...(root ? [` - cd ${root}`] : []),
72
149
  ` - ${install}`,
150
+ ...extra.gitlabScript.map((l) => ` - ${l}`),
151
+ ...(images ? [...fetches, ...imageLines(label, `export CHANT_RELEASE_DIGESTS="$PWD/${RELEASE_DIGESTS_FILE}"`).map((l) => ` - ${l}`)] : []),
73
152
  ...(build ? [` - ${build}`] : []),
74
- " - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
75
- " - git fetch origin chant/lifecycle:chant/lifecycle",
153
+ ...(images ? [] : fetches),
76
154
  ...(verify ? [` - ${chant} release verify ${label}`] : []),
77
155
  ` - ${chant} release publish ${label} ${flags}`,
78
156
  ];
157
+ if (after.length > 0) {
158
+ lines.push(
159
+ "",
160
+ "chant-release-after:",
161
+ " rules:",
162
+ " - if: $CI_COMMIT_TAG =~ /^release\\//",
163
+ " needs: [chant-release-publish]",
164
+ " script:",
165
+ ' - export CHANT_RELEASE_LABEL="${CI_COMMIT_TAG#release/}"',
166
+ ...(root ? [` - cd ${root}`] : []),
167
+ ` - ${install}`,
168
+ ...after.map((l) => ` - ${l}`),
169
+ );
170
+ }
79
171
  return `${lines.join("\n")}\n`;
80
172
  }
81
173
  const label = '"${GITHUB_REF_NAME#release/}"';
174
+ const fetches = [" - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'", " - run: git fetch origin chant/lifecycle:chant/lifecycle"];
82
175
  const lines = [
83
176
  "name: chant release publish",
84
177
  "on:",
@@ -87,28 +180,262 @@ export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
87
180
  "permissions:",
88
181
  " contents: write",
89
182
  " id-token: write",
183
+ ...extra.permissions,
90
184
  "jobs:",
91
185
  " publish:",
92
186
  " runs-on: ubuntu-latest",
93
187
  ...(root ? [" defaults:", " run:", ` working-directory: ${root}`] : []),
188
+ ...extra.githubEnv([]),
94
189
  " steps:",
190
+ ...githubSetup(),
191
+ ` - run: ${install}`,
192
+ ...extra.githubSteps,
193
+ ...(images ? [...fetches, ...imageLines(label, `echo "CHANT_RELEASE_DIGESTS=$PWD/${RELEASE_DIGESTS_FILE}" >> "$GITHUB_ENV"`).map((l) => ` - run: ${l}`)] : []),
194
+ ...(build ? [` - run: ${build}`] : []),
195
+ ...(images ? [] : fetches),
196
+ ...(verify ? [` - run: ${chant} release verify ${label}`] : []),
197
+ ` - run: ${chant} release publish ${label} ${flags}`,
198
+ ];
199
+ if (after.length > 0) {
200
+ lines.push(
201
+ " after-release:",
202
+ " needs: publish",
203
+ " runs-on: ubuntu-latest",
204
+ ...(root ? [" defaults:", " run:", ` working-directory: ${root}`] : []),
205
+ " steps:",
206
+ ...githubSetup(),
207
+ ' - run: echo "CHANT_RELEASE_LABEL=${GITHUB_REF_NAME#release/}" >> "$GITHUB_ENV"',
208
+ ` - run: ${install}`,
209
+ ...after.map((l) => ` - run: ${l}`),
210
+ );
211
+ }
212
+ return tagComments(`${lines.join("\n")}\n`);
213
+ }
214
+
215
+ interface JobExtras {
216
+ /** Lines added under the workflow's `permissions:`. */
217
+ permissions: string[];
218
+ /** The job's `env:` block with `base` entries first, or nothing when there is neither. */
219
+ githubEnv: (base: string[]) => string[];
220
+ /** Steps after the install. */
221
+ githubSteps: string[];
222
+ /** GitLab: the job's `variables:` entries, under a `variables:` key of their own. */
223
+ gitlabVariables: string[];
224
+ /** GitLab: script lines after the install. */
225
+ gitlabScript: string[];
226
+ }
227
+
228
+ /** `release.workflow`'s `permissions`, `env` and `setup` (#4751) as lines of the forge's file. Empty for a config without them, so its file is what it was. */
229
+ function jobExtras(p: ReleasePipelineConfig, forge: ReleaseWorkflowForge): JobExtras {
230
+ const permissions = Object.entries(p.permissions ?? {});
231
+ const env = Object.entries(p.env ?? {});
232
+ const setup = p.setup ?? [];
233
+ const where = "release.workflow";
234
+ for (const [k, v] of env) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k) || typeof v !== "string") throw new Error(`${where}.env: ${JSON.stringify(k)} is not a variable name with a string value`);
235
+ if (forge === "gitlab") {
236
+ if (permissions.length > 0) throw new Error(`${where}.permissions: GitLab has no permissions: block; a GitLab job's token scopes are the project's`);
237
+ const uses = setup.find((s) => "uses" in s);
238
+ if (uses) throw new Error(`${where}.setup: "${(uses as { uses: string }).uses}" is an action, and a GitLab job runs script lines; give it as { run }`);
239
+ } else {
240
+ for (const [k, v] of permissions) {
241
+ if (k === "contents" || k === "id-token") throw new Error(`${where}.permissions: ${k} is already granted (contents: write, id-token: write)`);
242
+ if (!/^[a-z][a-z-]*$/.test(k) || (v !== "read" && v !== "write")) throw new Error(`${where}.permissions: ${k}: ${String(v)} is not a scope and read or write`);
243
+ }
244
+ for (const s of setup) if (!("uses" in s) && s.run.trim() === "") throw new Error(`${where}.setup: a run step is empty`);
245
+ }
246
+ const q = (v: string | number | boolean): string => JSON.stringify(v);
247
+ const map = (indent: string, entries: Array<[string, string | number | boolean]>): string[] => entries.map(([k, v]) => `${indent}${k}: ${q(v)}`);
248
+ const githubSteps = setup.flatMap((s) => [
249
+ "uses" in s ? ` - uses: ${s.uses}` : ` - run: ${q(s.run)}`,
250
+ ...("uses" in s && s.with && Object.keys(s.with).length > 0 ? [" with:", ...map(" ", Object.entries(s.with))] : []),
251
+ ...(s.env && Object.keys(s.env).length > 0 ? [" env:", ...map(" ", Object.entries(s.env))] : []),
252
+ ]);
253
+ return {
254
+ permissions: permissions.map(([k, v]) => ` ${k}: ${v}`),
255
+ githubEnv: (base) => (base.length + env.length > 0 ? [" env:", ...base, ...map(" ", env)] : []),
256
+ githubSteps,
257
+ gitlabVariables: map(" ", env),
258
+ gitlabScript: setup.flatMap((s) => ("uses" in s ? [] : [...Object.entries(s.env ?? {}).map(([k, v]) => `export ${k}=${q(v)}`), s.run])),
259
+ };
260
+ }
261
+
262
+ /** The checkout and node setup a GitHub or Forgejo job starts with; `ref` checks out that commit. */
263
+ function githubSetup(ref?: string): string[] {
264
+ return [
95
265
  ` - uses: ${usesRef(ACTION_PINS.checkout4)}`,
96
266
  " with:",
267
+ ...(ref ? [` ref: ${ref}`] : []),
97
268
  " fetch-depth: 0",
98
269
  ` - uses: ${usesRef(ACTION_PINS.setupNode4)}`,
99
270
  " with:",
100
271
  " node-version: 24",
101
272
  " registry-url: https://registry.npmjs.org",
102
- ` - run: ${install}`,
103
- ...(build ? [` - run: ${build}`] : []),
104
- " - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
105
- " - run: git fetch origin chant/lifecycle:chant/lifecycle",
106
- ...(verify ? [` - run: ${chant} release verify ${label}`] : []),
107
- ` - run: ${chant} release publish ${label} ${flags}`,
108
273
  ];
274
+ }
275
+
276
+ interface DispatchInput {
277
+ chant: string;
278
+ install: string;
279
+ build: string | null;
280
+ root: string | null;
281
+ verify: boolean;
282
+ flags: string;
283
+ after: string[];
284
+ images: boolean;
285
+ gate: "last-green" | "head";
286
+ lane?: string;
287
+ extra: JobExtras;
288
+ }
289
+
290
+ /** The node one-liner that prints a JSON document's field from stdin, or from the file its argument names. */
291
+ const field = (path: string): string =>
292
+ `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}??""))'`;
293
+
294
+ /** 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. */
295
+ function gateScript(o: DispatchInput, dispatched: string): string[] {
296
+ return [
297
+ `commit="$(${o.chant} ci last-green --from "${dispatched}"${o.lane ? ` --lane ${o.lane}` : ""} --json | ${field("d.commit?.sha")})"`,
298
+ `if [ -z "$commit" ]; then echo "no green commit at or below ${dispatched}, so no release is cut" >&2; exit 1; fi`,
299
+ ...(o.gate === "head" ? [`if [ "$commit" != "${dispatched}" ]; then echo "${dispatched} is not green (the newest green commit below it is $commit), so no release is cut" >&2; exit 1; fi`] : []),
300
+ ];
301
+ }
302
+
303
+ /** The cut's shell: cut the label at the gate's commit, then push the tag the cut made. */
304
+ function cutScript(o: DispatchInput, out: string): string[] {
305
+ return [
306
+ 'git config user.name "chant release"',
307
+ 'git config user.email "chant-release@localhost"',
308
+ `${o.chant} release cut "$CHANT_RELEASE_LABEL" --at "$CHANT_RELEASE_COMMIT" --yes${o.build ? ` --build ${sq(o.build)}` : ""}${o.lane ? ` --lane ${o.lane}` : ""} --json > ${out}`,
309
+ `tag="$(${field("d.tag?.name")} ${out})"`,
310
+ 'if [ -n "$tag" ]; then git push origin "refs/tags/$tag"; fi',
311
+ ];
312
+ }
313
+
314
+ /** GitHub and Forgejo: the release started by hand with a label (#4656). */
315
+ function renderGithubDispatch(o: DispatchInput): string {
316
+ const defaults = o.root ? [" defaults:", " run:", ` working-directory: ${o.root}`] : [];
317
+ const commit = "${{ needs.gate.outputs.commit }}";
318
+ const fetches = [" - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'", " - run: git fetch origin chant/lifecycle:chant/lifecycle"];
319
+ const block = (lines: string[]): string[] => [" - run: |", ...lines.map((l) => ` ${l}`)];
320
+ const lines = [
321
+ "name: chant release",
322
+ "on:",
323
+ " workflow_dispatch:",
324
+ " inputs:",
325
+ " label:",
326
+ " description: The release's label, such as v1.4.0",
327
+ " required: true",
328
+ " type: string",
329
+ "permissions:",
330
+ " contents: write",
331
+ " id-token: write",
332
+ ...o.extra.permissions,
333
+ "concurrency:",
334
+ " group: chant-release",
335
+ " cancel-in-progress: false",
336
+ "env:",
337
+ " CHANT_RELEASE_LABEL: ${{ inputs.label }}",
338
+ "jobs:",
339
+ " gate:",
340
+ " runs-on: ubuntu-latest",
341
+ ...defaults,
342
+ " outputs:",
343
+ " commit: ${{ steps.green.outputs.commit }}",
344
+ " steps:",
345
+ ...githubSetup(),
346
+ ` - run: ${o.install}`,
347
+ fetches[0]!,
348
+ " - id: green",
349
+ " run: |",
350
+ ...[...gateScript(o, "$GITHUB_SHA"), 'echo "commit=$commit" >> "$GITHUB_OUTPUT"'].map((l) => ` ${l}`),
351
+ " cut:",
352
+ " needs: gate",
353
+ " runs-on: ubuntu-latest",
354
+ ...defaults,
355
+ ...o.extra.githubEnv([` CHANT_RELEASE_COMMIT: ${commit}`]),
356
+ " steps:",
357
+ ...githubSetup(commit),
358
+ ` - run: ${o.install}`,
359
+ ...o.extra.githubSteps,
360
+ ...fetches,
361
+ ...block(cutScript(o, '"$RUNNER_TEMP/chant-cut.json"')),
362
+ " publish:",
363
+ " needs: [gate, cut]",
364
+ " runs-on: ubuntu-latest",
365
+ ...defaults,
366
+ ...o.extra.githubEnv([]),
367
+ " steps:",
368
+ ...githubSetup(commit),
369
+ ` - run: ${o.install}`,
370
+ ...o.extra.githubSteps,
371
+ ...fetches,
372
+ ...(o.images ? [` - run: ${o.chant} release images "$CHANT_RELEASE_LABEL" -o ${RELEASE_DIGESTS_FILE}`, ` - run: echo "CHANT_RELEASE_DIGESTS=$PWD/${RELEASE_DIGESTS_FILE}" >> "$GITHUB_ENV"`] : []),
373
+ ...(o.build ? [` - run: ${o.build}`] : []),
374
+ ...(o.verify ? [` - run: ${o.chant} release verify "$CHANT_RELEASE_LABEL"`] : []),
375
+ ` - run: ${o.chant} release publish "$CHANT_RELEASE_LABEL" ${o.flags}`,
376
+ ];
377
+ if (o.after.length > 0) {
378
+ lines.push(" after-release:", " needs: [gate, publish]", " runs-on: ubuntu-latest", ...defaults, " steps:", ...githubSetup(commit), ` - run: ${o.install}`, ...o.after.map((l) => ` - run: ${l}`));
379
+ }
109
380
  return tagComments(`${lines.join("\n")}\n`);
110
381
  }
111
382
 
383
+ /**
384
+ * GitLab: the release started from "Run pipeline" with `CHANT_RELEASE_LABEL`
385
+ * set (#4656). The jobs follow each other by `needs`, in the file's default
386
+ * stage, so the including `.gitlab-ci.yml` keeps its own `stages`. A job
387
+ * token cannot push, so the cut and publish jobs push with
388
+ * `CHANT_RELEASE_TOKEN`, a project access token with `write_repository`.
389
+ */
390
+ function renderGitlabDispatch(o: DispatchInput): string {
391
+ const cd = o.root ? [`cd ${o.root}`] : [];
392
+ const fetches = ["git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'", "git fetch origin chant/lifecycle:chant/lifecycle"];
393
+ const auth = [
394
+ `chant_auth="$(printf 'oauth2:%s' "$CHANT_RELEASE_TOKEN" | base64 | tr -d '\\n')"`,
395
+ 'export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"',
396
+ "unset chant_auth",
397
+ ];
398
+ const job = (name: string, needs: string[], script: string[], extra: string[] = [], vars: string[] = []): string[] => [
399
+ `${name}:`,
400
+ " rules:",
401
+ ' - if: $CHANT_RELEASE_LABEL && $CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/',
402
+ " variables:",
403
+ ' GIT_DEPTH: "0"',
404
+ ...vars,
405
+ ...(needs.length > 0 ? [` needs: [${needs.join(", ")}]`] : []),
406
+ ...extra,
407
+ " script:",
408
+ ...script.map((l) => ` - ${JSON.stringify(l)}`),
409
+ ];
410
+ const checkout = ['git checkout --detach "$CHANT_RELEASE_COMMIT"'];
411
+ const lines = [
412
+ ...job("chant-release-gate", [], [...cd, o.install, fetches[0]!, ...gateScript(o, "$CI_COMMIT_SHA"), 'echo "CHANT_RELEASE_COMMIT=$commit" > "$CI_PROJECT_DIR/chant-release-gate.env"'], [" artifacts:", " reports:", " dotenv: chant-release-gate.env"]),
413
+ "",
414
+ ...job("chant-release-cut", ["chant-release-gate"], [...checkout, ...cd, o.install, ...o.extra.gitlabScript, ...fetches, ...auth, ...cutScript(o, "/tmp/chant-cut.json")], [], o.extra.gitlabVariables),
415
+ "",
416
+ ...job(
417
+ "chant-release-publish",
418
+ ["chant-release-gate", "chant-release-cut"],
419
+ [
420
+ ...checkout,
421
+ ...cd,
422
+ o.install,
423
+ ...o.extra.gitlabScript,
424
+ ...fetches,
425
+ ...auth,
426
+ ...(o.images ? [`${o.chant} release images "$CHANT_RELEASE_LABEL" -o ${RELEASE_DIGESTS_FILE}`, `export CHANT_RELEASE_DIGESTS="$PWD/${RELEASE_DIGESTS_FILE}"`] : []),
427
+ ...(o.build ? [o.build] : []),
428
+ ...(o.verify ? [`${o.chant} release verify "$CHANT_RELEASE_LABEL"`] : []),
429
+ `${o.chant} release publish "$CHANT_RELEASE_LABEL" ${o.flags}`,
430
+ ],
431
+ [" id_tokens:", " SIGSTORE_ID_TOKEN:", " aud: sigstore"],
432
+ o.extra.gitlabVariables,
433
+ ),
434
+ ];
435
+ if (o.after.length > 0) lines.push("", ...job("chant-release-after", ["chant-release-gate", "chant-release-publish"], [...checkout, ...cd, o.install, ...o.after]));
436
+ return `${lines.join("\n")}\n`;
437
+ }
438
+
112
439
  /** The header that marks the file generated, naming the command that regenerates it. */
113
440
  export function releaseWorkflowHeader(command: string): string {
114
441
  return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the workspace root)\n`;
@@ -144,15 +471,28 @@ export async function runReleaseWorkflow(ctx: import("../cli/registry").CommandC
144
471
  }
145
472
  const groups = securityGroupsAt(root);
146
473
  const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
474
+ // #4656: release.workflow, release.images and release.lane in the root's chant.config.ts.
475
+ let release: import("../config").ChantConfig["release"];
476
+ try {
477
+ const { loadChantConfig } = await import("../config");
478
+ release = (await loadChantConfig(root)).config.release;
479
+ } catch (err) {
480
+ console.error(formatError({ message: `chant.config.ts at the workspace root could not be read: ${err instanceof Error ? err.message : String(err)}`, hint: usage }));
481
+ return 1;
482
+ }
147
483
  const text = renderReleaseWorkflow({
148
484
  forge,
149
485
  groups,
150
486
  workspaceRoot,
487
+ ...(release?.workflow ? { pipeline: release.workflow } : {}),
488
+ // release.images (#4657) is read loosely, so this file renders with a config of either shape.
489
+ ...(((release as { images?: unknown[] } | undefined)?.images?.length ?? 0) > 0 ? { images: true } : {}),
490
+ ...(release?.lane ? { lane: release.lane } : {}),
151
491
  ...(args.ciInstall ? { install: args.ciInstall } : {}),
152
492
  ...(args.buildCommand ? { build: args.buildCommand } : {}),
153
493
  ...(args.ciChant ? { chant: args.ciChant } : {}),
154
494
  });
155
- const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, RELEASE_WORKFLOW_FILES[forge]);
495
+ const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, release?.workflow?.file ?? RELEASE_WORKFLOW_FILES[forge]);
156
496
  const parts = ["chant", "release", "workflow", "--forge", forge];
157
497
  if (args.ciInstall) parts.push("--install", args.ciInstall);
158
498
  if (args.buildCommand) parts.push("--build", args.buildCommand);
@@ -162,7 +502,9 @@ export async function runReleaseWorkflow(ctx: import("../cli/registry").CommandC
162
502
  writeFileSync(target, releaseWorkflowHeader(parts.map(shellArg).join(" ")) + text);
163
503
  const shown = relative(process.cwd(), target).split(sep).join("/") || target;
164
504
  const extras = [groups.has("supply-chain") ? "requires OIDC provenance (supply-chain)" : null, groups.has("verified-releases") ? "verifies the release first (verified-releases)" : null].filter(Boolean);
165
- console.log(formatSuccess(`Wrote ${shown}: publishes the release a release/** tag names${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
166
- if (forge === "gitlab") console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${RELEASE_WORKFLOW_FILES.gitlab} }]`);
505
+ const what = release?.workflow?.trigger === "dispatch" ? "cuts and publishes a release started by hand with its label, from a green commit" : "publishes the release a release/** tag names";
506
+ console.log(formatSuccess(`Wrote ${shown}: ${what}${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
507
+ if (forge === "gitlab") console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${release?.workflow?.file ?? RELEASE_WORKFLOW_FILES.gitlab} }]`);
508
+ if (forge === "gitlab" && release?.workflow?.trigger === "dispatch") console.log("The cut and publish jobs push with CHANT_RELEASE_TOKEN: a project access token with write_repository, as a masked CI/CD variable.");
167
509
  return 0;
168
510
  }