@intentius/chant 0.124.70 → 0.124.71

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 (144) 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 +297 -0
  5. package/dist/ci-commit.d.ts.map +1 -0
  6. package/dist/ci-commit.js +696 -0
  7. package/dist/ci-product-words.d.ts +6 -1
  8. package/dist/ci-product-words.d.ts.map +1 -1
  9. package/dist/ci-product-words.js +3 -1
  10. package/dist/cli/handlers/approve.d.ts.map +1 -1
  11. package/dist/cli/handlers/approve.js +7 -2
  12. package/dist/cli/handlers/commit.d.ts +26 -0
  13. package/dist/cli/handlers/commit.d.ts.map +1 -0
  14. package/dist/cli/handlers/commit.js +142 -0
  15. package/dist/cli/handlers/pr.d.ts +6 -0
  16. package/dist/cli/handlers/pr.d.ts.map +1 -1
  17. package/dist/cli/handlers/pr.js +16 -7
  18. package/dist/cli/handlers/release.d.ts +9 -0
  19. package/dist/cli/handlers/release.d.ts.map +1 -1
  20. package/dist/cli/handlers/release.js +114 -5
  21. package/dist/cli/main.d.ts.map +1 -1
  22. package/dist/cli/main.js +17 -0
  23. package/dist/components/product-pipeline.d.ts +33 -0
  24. package/dist/components/product-pipeline.d.ts.map +1 -1
  25. package/dist/components/product-pipeline.js +34 -1
  26. package/dist/components/release-compile.d.ts +2 -0
  27. package/dist/components/release-compile.d.ts.map +1 -1
  28. package/dist/components/release-compile.js +8 -4
  29. package/dist/config.d.ts +46 -0
  30. package/dist/config.d.ts.map +1 -1
  31. package/dist/config.js +9 -0
  32. package/dist/lexicon.d.ts +37 -0
  33. package/dist/lexicon.d.ts.map +1 -1
  34. package/dist/lexicon.js +28 -0
  35. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +4 -0
  36. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  37. package/dist/lifecycle/__fixtures__/publish-fakes.js +6 -2
  38. package/dist/lifecycle/gated-request.d.ts +3 -1
  39. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  40. package/dist/lifecycle/gated-request.js +5 -2
  41. package/dist/lifecycle/git.d.ts.map +1 -1
  42. package/dist/lifecycle/git.js +57 -0
  43. package/dist/lifecycle/publish-declaration.d.ts +16 -0
  44. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  45. package/dist/lifecycle/publish-declaration.js +35 -3
  46. package/dist/lifecycle/publish-forge.d.ts +12 -0
  47. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  48. package/dist/lifecycle/publish-forge.js +103 -19
  49. package/dist/lifecycle/publish-npm.d.ts +15 -0
  50. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  51. package/dist/lifecycle/publish-npm.js +28 -1
  52. package/dist/lifecycle/publish-oci.d.ts +2 -0
  53. package/dist/lifecycle/publish-oci.d.ts.map +1 -1
  54. package/dist/lifecycle/publish-oci.js +10 -0
  55. package/dist/lifecycle/release-cut.d.ts +7 -1
  56. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  57. package/dist/lifecycle/release-cut.js +8 -1
  58. package/dist/lifecycle/release-images.d.ts +87 -0
  59. package/dist/lifecycle/release-images.d.ts.map +1 -0
  60. package/dist/lifecycle/release-images.js +139 -0
  61. package/dist/lifecycle/release-publish.d.ts +2 -0
  62. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  63. package/dist/op/activities/activity-contracts.d.ts +4 -4
  64. package/dist/op/activities/review-agent.d.ts.map +1 -1
  65. package/dist/op/activities/review-agent.js +4 -2
  66. package/dist/op/gate.d.ts +5 -1
  67. package/dist/op/gate.d.ts.map +1 -1
  68. package/dist/op/gate.js +7 -2
  69. package/dist/op/op-waves-notify.d.ts +1 -1
  70. package/dist/op/op-waves-notify.d.ts.map +1 -1
  71. package/dist/op/op-waves-notify.js +2 -1
  72. package/dist/op/op-waves-run.d.ts.map +1 -1
  73. package/dist/op/op-waves-run.js +12 -8
  74. package/dist/op/op-waves.d.ts +9 -0
  75. package/dist/op/op-waves.d.ts.map +1 -1
  76. package/dist/op/op-waves.js +11 -0
  77. package/dist/pr-forge-base.d.ts +18 -0
  78. package/dist/pr-forge-base.d.ts.map +1 -0
  79. package/dist/pr-forge-base.js +29 -0
  80. package/dist/release-floors.d.ts +1 -1
  81. package/dist/release-floors.js +1 -1
  82. package/dist/wave-runtime.mjs +315 -315
  83. package/dist/workspace/ci-green.d.ts.map +1 -1
  84. package/dist/workspace/ci-green.js +1 -2
  85. package/dist/workspace/release-workflow.d.ts +23 -0
  86. package/dist/workspace/release-workflow.d.ts.map +1 -1
  87. package/dist/workspace/release-workflow.js +203 -12
  88. package/package.json +1 -1
  89. package/src/ci-agent.ts +13 -8
  90. package/src/ci-commit.test.ts +415 -0
  91. package/src/ci-commit.ts +857 -0
  92. package/src/ci-product-words.ts +6 -2
  93. package/src/cli/handlers/approve.ts +6 -2
  94. package/src/cli/handlers/commit.ts +152 -0
  95. package/src/cli/handlers/operator.test.ts +2 -0
  96. package/src/cli/handlers/pr-wave-approve-lines.test.ts +32 -0
  97. package/src/cli/handlers/pr.ts +17 -7
  98. package/src/cli/handlers/release.ts +110 -5
  99. package/src/cli/main.ts +17 -0
  100. package/src/components/product-pipeline.test.ts +28 -1
  101. package/src/components/product-pipeline.ts +54 -1
  102. package/src/components/release-compile.ts +9 -3
  103. package/src/config.ts +24 -0
  104. package/src/lexicon.ts +56 -0
  105. package/src/lifecycle/__fixtures__/publish-fakes.ts +11 -5
  106. package/src/lifecycle/gated-request-spend.test.ts +115 -0
  107. package/src/lifecycle/gated-request.ts +5 -2
  108. package/src/lifecycle/git.ts +53 -0
  109. package/src/lifecycle/ledger-two-clones.test.ts +132 -0
  110. package/src/lifecycle/publish-declaration.ts +35 -3
  111. package/src/lifecycle/publish-forge-notes.test.ts +193 -0
  112. package/src/lifecycle/publish-forge.ts +101 -22
  113. package/src/lifecycle/publish-npm.ts +31 -2
  114. package/src/lifecycle/publish-oci.ts +10 -0
  115. package/src/lifecycle/publish-targets.test.ts +2 -1
  116. package/src/lifecycle/release-cut.ts +17 -1
  117. package/src/lifecycle/release-images.test.ts +242 -0
  118. package/src/lifecycle/release-images.ts +175 -0
  119. package/src/lifecycle/release-publish.ts +2 -0
  120. package/src/op/activities/review-agent.test.ts +20 -1
  121. package/src/op/activities/review-agent.ts +5 -2
  122. package/src/op/gate.ts +7 -2
  123. package/src/op/op-waves-approve-target.test.ts +108 -0
  124. package/src/op/op-waves-notify.ts +2 -2
  125. package/src/op/op-waves-run.ts +12 -7
  126. package/src/op/op-waves.ts +12 -0
  127. package/src/pr-forge-base.test.ts +37 -0
  128. package/src/pr-forge-base.ts +36 -0
  129. package/src/release-floors.ts +1 -1
  130. package/src/workspace/__fixtures__/release-workflow/forgejo-plain-member.yml +26 -0
  131. package/src/workspace/__fixtures__/release-workflow/forgejo-plain.yml +23 -0
  132. package/src/workspace/__fixtures__/release-workflow/forgejo-secure-member.yml +27 -0
  133. package/src/workspace/__fixtures__/release-workflow/forgejo-secure.yml +24 -0
  134. package/src/workspace/__fixtures__/release-workflow/github-plain-member.yml +26 -0
  135. package/src/workspace/__fixtures__/release-workflow/github-plain.yml +23 -0
  136. package/src/workspace/__fixtures__/release-workflow/github-secure-member.yml +27 -0
  137. package/src/workspace/__fixtures__/release-workflow/github-secure.yml +24 -0
  138. package/src/workspace/__fixtures__/release-workflow/gitlab-plain-member.yml +13 -0
  139. package/src/workspace/__fixtures__/release-workflow/gitlab-plain.yml +12 -0
  140. package/src/workspace/__fixtures__/release-workflow/gitlab-secure-member.yml +14 -0
  141. package/src/workspace/__fixtures__/release-workflow/gitlab-secure.yml +13 -0
  142. package/src/workspace/ci-green.ts +1 -2
  143. package/src/workspace/release-workflow.test.ts +151 -0
  144. package/src/workspace/release-workflow.ts +270 -12
@@ -39,6 +39,7 @@ import type { DriverComponent } from "./driver";
39
39
  import type { ScheduledOpSpec } from "../lexicon";
40
40
  import type { CiRunner } from "../ci-jobs";
41
41
  import { resolveAgentSpec, type OpAgentSpec } from "../ci-agent";
42
+ import { resolveCommitSpec, type OpCommitSpec } from "../ci-commit";
42
43
  import type { CiResponses } from "../ci-respond";
43
44
 
44
45
  /** Where the generator writes a product's waves spec, which chant reads at base (#4550). */
@@ -70,6 +71,15 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
70
71
  * scheduled Ops.
71
72
  */
72
73
  agent?: boolean | ProductAgentOptions;
74
+ /**
75
+ * The product's commit jobs (#4722) that answer a comment: each one's
76
+ * `word` maps onto `commit` in the words, and `/<product> <word>` runs its
77
+ * command on the pull request's head and pushes the change. The pipeline
78
+ * returns each one's Op spec, which the product writes and generates as
79
+ * it does the agent's. A commit job after a check rides on the check's own
80
+ * Op spec instead ({@link productCheckCommit}).
81
+ */
82
+ commits?: ProductCommitOptions[];
73
83
  /**
74
84
  * The product answers its `action` command (#4654) from a workflow of its
75
85
  * own, such as terragucci's action workflow: `true` counts the command as
@@ -152,6 +162,8 @@ export interface ProductPipelineJobs {
152
162
  * job with the write token.
153
163
  */
154
164
  agent?: { comment: string; name: string; spec: ScheduledOpSpec };
165
+ /** The comment commit jobs (#4722), with `commits`: each one's comment, `/<product> <word>`, and the Op spec whose generated workflow runs it. */
166
+ commits?: Array<{ comment: string; name: string; spec: ScheduledOpSpec }>;
155
167
  /**
156
168
  * The action job (#4654), with `actionJob`: the comment and the dispatch
157
169
  * inputs it answers, and the product's action verb it runs. The GitHub and
@@ -168,6 +180,39 @@ export interface ProductAgentOptions extends Omit<OpAgentSpec, "on" | "comment"
168
180
  runner?: CiRunner;
169
181
  }
170
182
 
183
+ /** A comment commit job as a product passes it (#4722): {@link OpCommitSpec} without the trigger, with the word it answers. */
184
+ export interface ProductCommitOptions extends Omit<OpCommitSpec, "on" | "comment" | "findings" | "gitlabCheck"> {
185
+ /** The word after `/<product>`, which the words map onto `commit`: `fmt` for `/terragucci fmt`. */
186
+ word: string;
187
+ /** The job's name: its workflow, its jobs and its runs on the ledger. Default `<product>-<word>`. */
188
+ name?: string;
189
+ runner?: CiRunner;
190
+ }
191
+
192
+ /** A comment commit job's Op spec (#4722). The settings are checked here, so a product finds a bad one when it generates. */
193
+ export function productCommitSpec(wordsIn: CiProductWordsInput | CiProductWords, options: ProductCommitOptions): ScheduledOpSpec {
194
+ const words = assertProductWords(wordsIn);
195
+ const { word, name: given, runner, ...settings } = options;
196
+ if (words.commands[word] !== "commit") throw new Error(`the commit job's word ${JSON.stringify(word)} is not a command the words map onto commit`);
197
+ const name = given ?? `${words.product}-${word}`;
198
+ const commit: OpCommitSpec = { on: "comment", comment: `/${words.product} ${word}`, ...settings };
199
+ resolveCommitSpec(name, commit, words.product);
200
+ return { name, trigger: { kind: "pull_request" }, commit, ...(runner !== undefined ? { runner } : {}) };
201
+ }
202
+
203
+ /**
204
+ * The `commit` of a check's Op spec (#4722): after the check's run exits
205
+ * with one of `findings` on a pull request, the command runs on the head
206
+ * and its change is pushed to the pull request's branch. The check's spec
207
+ * needs a `pull_request` trigger.
208
+ */
209
+ export function productCheckCommit(wordsIn: CiProductWordsInput | CiProductWords, op: string, options: Omit<OpCommitSpec, "on" | "comment">): OpCommitSpec {
210
+ const words = assertProductWords(wordsIn);
211
+ const commit: OpCommitSpec = { on: "check", ...options };
212
+ resolveCommitSpec(op, commit, words.product);
213
+ return commit;
214
+ }
215
+
171
216
  /** The agent's Op spec for `/<product> agent <ask>` (#4616). The settings are checked here, so a product finds a bad one when it generates. */
172
217
  export function productAgentSpec(wordsIn: CiProductWordsInput | CiProductWords, comment: string, options: ProductAgentOptions = {}): ScheduledOpSpec {
173
218
  const words = assertProductWords(wordsIn);
@@ -219,6 +264,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
219
264
  if (options.applyBeforeMerge || options.waves || options.componentWaves) jobs.push("apply");
220
265
  if (options.locks === "plan") jobs.push("lock", "unlock");
221
266
  if (options.agent) jobs.push("agent");
267
+ if (options.commits?.length) jobs.push("commit");
222
268
  // #4654: the action command, answered by the product's own workflow (`actions`) or by the pipeline's action job.
223
269
  if (options.actions || options.actionJob) jobs.push("action");
224
270
  // #4601: the note's merge sentence follows the jobs built here: waves on merge, an apply before merge, else a record for a release.
@@ -226,7 +272,7 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
226
272
  const built: CiProductApplyMode = options.waves || options.componentWaves ? "on-merge" : options.applyBeforeMerge ? "before-merge" : "release";
227
273
  const applyMode: CiProductApplyMode = options.words.applyMode === "before-merge" && options.applyBeforeMerge ? "before-merge" : built;
228
274
  const words = assertProductWords({ ...options.words, applyMode }, { jobs });
229
- const { waves: given, wavesSpecFile, member, agent: _agent, actions: _actions, componentWaves, ...loop } = options;
275
+ const { waves: given, wavesSpecFile, member, agent: _agent, commits: _commits, actions: _actions, componentWaves, ...loop } = options;
230
276
  const { respond } = options;
231
277
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
232
278
  const prLoop: PrLoopPipelineOptions = { ...loop, words, gate: options.gate ?? words.prGate };
@@ -263,6 +309,13 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
263
309
  const spec = productAgentSpec(words, agentComment, options.agent === true ? {} : options.agent);
264
310
  out.agent = { comment: agentComment, name: spec.name, spec };
265
311
  }
312
+ // #4722: each comment commit job answers its own word from a workflow of its own.
313
+ if (options.commits?.length) {
314
+ out.commits = options.commits.map((c) => {
315
+ const spec = productCommitSpec(words, c);
316
+ return { comment: spec.commit!.comment!, name: spec.name, spec };
317
+ });
318
+ }
266
319
  // #4588: without a spec of the product's own, the component graph's waves on op waves.
267
320
  const op = words.op ?? componentWaves?.waveGate ?? words.prGate;
268
321
  const spec = given ?? (componentWaves
@@ -52,6 +52,7 @@ import { DriverRunFailure, runInterpretDriver, type DriverComponent, type Driver
52
52
  import type { CapabilityRegistry, ReleaseInputs, ReleaseInputsUnbound } from "./capability";
53
53
  import { memoryGateLedgerPort } from "../op/gate";
54
54
  import type { ReleaseArtifact, ReleaseParam } from "../lifecycle/release-store";
55
+ import { RELEASE_DIGESTS_ENV } from "../lifecycle/release-images";
55
56
 
56
57
  /** The deploy step fields whose literal file paths are a component's templates. */
57
58
  export { TEMPLATE_FIELDS } from "./deploy-inputs";
@@ -297,6 +298,8 @@ export interface CompileInputs {
297
298
  * reads the variable. Unset for a cut with no label.
298
299
  */
299
300
  releaseLabel?: string;
301
+ /** The digests file of the images the cut built (#4657), passed to the build command as `CHANT_RELEASE_DIGESTS`. */
302
+ releaseDigests?: string;
300
303
  }
301
304
 
302
305
  /** The variable a cut's label reaches the build through (#4168). */
@@ -359,7 +362,7 @@ export async function compileEnvironment(inputs: CompileInputs, env: string): Pr
359
362
  cwd: inputs.projectDir,
360
363
  shell: true,
361
364
  stdio: ["ignore", 2, 2],
362
- env: { ...process.env, CHANT_ENV: env },
365
+ env: { ...process.env, CHANT_ENV: env, ...(inputs.releaseDigests ? { [RELEASE_DIGESTS_ENV]: inputs.releaseDigests } : {}) },
363
366
  });
364
367
  if (run.status !== 0) throw new ReleaseCompileError(`the build command for "${env}" exited ${run.status ?? "with a signal"}: ${inputs.buildCommand}`);
365
368
  }
@@ -571,13 +574,16 @@ function runChild(
571
574
  cwd: string,
572
575
  env: string,
573
576
  releaseLabel?: string,
577
+ releaseDigests?: string,
574
578
  ): Promise<{ code: number; stdout: string; stderr: string }> {
575
579
  return new Promise((resolvePromise, reject) => {
576
580
  const [bin, ...lead] = command;
577
581
  const childEnv: NodeJS.ProcessEnv = { ...process.env, CHANT_ENV: env };
578
- // A label never leaks in from the caller's shell: only the cut sets it.
582
+ // A label never leaks in from the caller's shell: only the cut sets it. Nor do the digests (#4657).
579
583
  delete childEnv[RELEASE_LABEL_ENV];
584
+ delete childEnv[RELEASE_DIGESTS_ENV];
580
585
  if (releaseLabel !== undefined) childEnv[RELEASE_LABEL_ENV] = releaseLabel;
586
+ if (releaseDigests !== undefined) childEnv[RELEASE_DIGESTS_ENV] = releaseDigests;
581
587
  const child = spawn(bin, [...lead, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: childEnv });
582
588
  const out: Buffer[] = [];
583
589
  const err: Buffer[] = [];
@@ -607,7 +613,7 @@ export function spawnTargetCompiler(inputs: CompileInputs, command: readonly str
607
613
  return args;
608
614
  };
609
615
  const call = async (env: string, extra: string[]): Promise<unknown> => {
610
- const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env, inputs.releaseLabel);
616
+ const run = await runChild(command, ["release", "compile", "--env", env, ...common(), ...extra, "--json"], inputs.projectDir, env, inputs.releaseLabel, inputs.releaseDigests);
611
617
  if (run.code !== 0) throw new ReleaseCompileError(`compiling "${env}" failed (exit ${run.code})`);
612
618
  try {
613
619
  return JSON.parse(run.stdout);
package/src/config.ts CHANGED
@@ -109,7 +109,16 @@ export const ChantConfigSchema = z.object({
109
109
  release: z.object({
110
110
  autoRecord: z.boolean().optional(),
111
111
  publish: z.array(PublishDeclarationSchema).optional(),
112
+ images: z.array(z.object({ name: z.string().min(1), build: z.string().min(1), archive: z.string().min(1) }).strict()).optional(),
112
113
  lane: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "a ci.green lane name: lowercase letters, digits and dashes").optional(),
114
+ workflow: z.object({
115
+ trigger: z.enum(["tag", "dispatch"]).optional(),
116
+ gate: z.enum(["last-green", "head"]).optional(),
117
+ install: z.string().min(1).optional(),
118
+ build: z.union([z.string().min(1), z.literal(false)]).optional(),
119
+ chant: z.string().min(1).optional(),
120
+ after: z.array(z.string().min(1)).optional(),
121
+ }).strict().optional(),
113
122
  }).optional(),
114
123
  // Strict: a misspelt key here would leave Ops on the local runtime with
115
124
  // nothing said (#2523).
@@ -372,6 +381,14 @@ export interface ChantConfig {
372
381
  * the order given. See ./lifecycle/publish-declaration.ts.
373
382
  */
374
383
  publish?: PublishDeclaration[];
384
+ /**
385
+ * Images the cut builds before the release's build command (#4657): each
386
+ * `build` writes the OCI archive at `archive`, and the cut records its
387
+ * digest and hands every digest to the build through `CHANT_RELEASE_DIGESTS`,
388
+ * so a package can pin the images it ships with. An `oci` target pushes
389
+ * the archive. See ./lifecycle/release-images.ts.
390
+ */
391
+ images?: Array<{ name: string; build: string; archive: string }>;
375
392
  /**
376
393
  * The green lane `chant release cut` and `chant release candidates` check
377
394
  * when `--lane` is not given (#4692): one `ci.green.lanes` declares in
@@ -379,6 +396,13 @@ export interface ChantConfig {
379
396
  * rather than `ci/green/<sha>`.
380
397
  */
381
398
  lane?: string;
399
+ /**
400
+ * The release pipeline `chant release workflow` writes (#4656): a
401
+ * dispatched release with gate, cut, publish and post-release jobs, the
402
+ * install and build commands, and the steps after the publish. See
403
+ * {@link import("./workspace/release-workflow").ReleasePipelineConfig}.
404
+ */
405
+ workflow?: import("./workspace/release-workflow").ReleasePipelineConfig;
382
406
  };
383
407
 
384
408
  /** Defaults for `chant run` and its subcommands (#2523). */
package/src/lexicon.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { InstanceObservation } from "./instance-nodes";
2
2
  import type { CiRunner } from "./ci-jobs";
3
3
  import type { OpAgentSpec } from "./ci-agent";
4
+ import type { OpCommitSpec } from "./ci-commit";
4
5
  import type { CloudTradeSpec } from "./ci-identity";
5
6
  import type { EngineFacts } from "./engine-facts";
6
7
  import type { CapabilityPack } from "./capabilities/view";
@@ -78,6 +79,7 @@ export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
78
79
  // edge type from the same entry it imports the plugin contract from.
79
80
  export type { IREdge } from "./graph-ir";
80
81
  export type { OpAgentSpec } from "./ci-agent";
82
+ export type { OpCommitSpec } from "./ci-commit";
81
83
 
82
84
  // The observation contract (#1089), re-exported from the same entry so a
83
85
  // lexicon's `describeResources` can report NOT-OBSERVED without a second
@@ -935,6 +937,16 @@ export interface ScheduledOpSpec {
935
937
  * branch. The model's job holds no write token; the push job does.
936
938
  */
937
939
  agent?: OpAgentSpec;
940
+ /**
941
+ * The commit jobs (#4722, ../ci-commit.ts): the product's fixed command run
942
+ * on a pull request's head, its change pushed to the pull request's branch.
943
+ * `on: "comment"`: this spec is the commit job's own workflow, answering
944
+ * `/<product> <word>`, and `trigger` is not read. `on: "check"`: the jobs
945
+ * follow this Op's job on a pull request and run when its run exits with
946
+ * one of `findings`. The command's job holds no forge token; the push job
947
+ * holds `tokenEnv`.
948
+ */
949
+ commit?: OpCommitSpec;
938
950
  /**
939
951
  * The job's cloud identities (#4631), as an op wave's `cloud` (#4332,
940
952
  * #4549): the three generators trade the job's OIDC token for them in a
@@ -952,6 +964,50 @@ export interface ScheduledOpSpec {
952
964
  * check. A cron or pull_request trigger only.
953
965
  */
954
966
  update?: ScheduledOpUpdate;
967
+ /**
968
+ * Files the Op's job keeps after its run (#4622), such as a drift report
969
+ * for a repository with no bucket to put it in. Kept whether the run
970
+ * passed, failed or found drift. GitHub and Forgejo upload each entry as
971
+ * its own artifact; GitLab keeps one archive per job, so the entries' paths
972
+ * join the job's `artifacts:` under the entry's name when there is one.
973
+ * Not on a `reviewAgent` split or a comment agent's workflow.
974
+ */
975
+ artifacts?: ScheduledOpArtifact[];
976
+ }
977
+
978
+ /** A named set of files a scheduled Op's job keeps after its run (#4622). */
979
+ export interface ScheduledOpArtifact {
980
+ /** The artifact's name, unique among the Op's artifacts. */
981
+ name: string;
982
+ /** Files or directories, relative to the job's directory (the member's, in a workspace). */
983
+ paths: string[];
984
+ /** How many days the forge keeps it. Default: the forge's own. */
985
+ retentionDays?: number;
986
+ }
987
+
988
+ /**
989
+ * Check a scheduled Op's `artifacts` (#4622) and return them, or `[]` when it
990
+ * has none. Throws naming the Op on an empty or repeated name, an empty
991
+ * `paths`, an absolute path or one that leaves the job's directory, or a
992
+ * retention that is not a positive whole number of days.
993
+ */
994
+ export function scheduledOpArtifacts(spec: Pick<ScheduledOpSpec, "name" | "artifacts">): ScheduledOpArtifact[] {
995
+ const list = spec.artifacts ?? [];
996
+ const seen = new Set<string>();
997
+ for (const a of list) {
998
+ const where = `Scheduled Op "${spec.name}" artifact "${a.name}"`;
999
+ if (!a.name || !/^[A-Za-z0-9._-]+$/.test(a.name)) throw new Error(`Scheduled Op "${spec.name}": an artifact's name is letters, digits, ".", "_" and "-", and "${a.name}" is not.`);
1000
+ if (seen.has(a.name)) throw new Error(`Scheduled Op "${spec.name}" names the artifact "${a.name}" twice.`);
1001
+ seen.add(a.name);
1002
+ if (a.paths.length === 0) throw new Error(`${where} lists no paths.`);
1003
+ for (const p of a.paths) {
1004
+ if (p === "" || p.startsWith("/") || p.split("/").includes("..")) throw new Error(`${where}: "${p}" is not a path inside the job's directory.`);
1005
+ }
1006
+ if (a.retentionDays !== undefined && (!Number.isInteger(a.retentionDays) || a.retentionDays < 1)) {
1007
+ throw new Error(`${where}: retentionDays is a whole number of days, 1 or more.`);
1008
+ }
1009
+ }
1010
+ return list;
955
1011
  }
956
1012
 
957
1013
  /** A scheduled Op's update on drift (#4631). */
@@ -254,6 +254,10 @@ export interface FakeForgeRelease {
254
254
  name?: string;
255
255
  /** GitHub: the `make_latest` the release was published with. */
256
256
  make_latest?: string;
257
+ /** The release's notes: GitHub's and Forgejo's `body`, GitLab's `description` (#4658). */
258
+ body?: string;
259
+ /** Forgejo: published as a prerelease. */
260
+ prerelease?: boolean;
257
261
  }
258
262
 
259
263
  /** A forge fake answering through `fetch`: GitHub or Forgejo with draft releases, or GitLab with releases, links and a generic package registry. */
@@ -307,9 +311,9 @@ export function startFakeForge(forge: "github" | "forgejo" | "gitlab", api: stri
307
311
  return r ? json(200, view(r)) : json(404, { message: "404 Not Found" });
308
312
  }
309
313
  if (init.method === "POST" && path === `${root}/releases`) {
310
- const b = JSON.parse(text(init.body)) as { tag_name: string; ref: string; assets?: { links?: Array<{ name: string; url: string }> } };
314
+ const b = JSON.parse(text(init.body)) as { tag_name: string; ref: string; description?: string; assets?: { links?: Array<{ name: string; url: string }> } };
311
315
  if (releases.some((x) => x.tag_name === b.tag_name)) return json(409, { message: "Release already exists" });
312
- const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: false, target: b.ref, assets: (b.assets?.links ?? []).map((l) => ({ name: l.name, digest: null, bytes: packages.get(l.url) ?? "" })) };
316
+ const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: false, target: b.ref, assets: (b.assets?.links ?? []).map((l) => ({ name: l.name, digest: null, bytes: packages.get(l.url) ?? "" })), ...(b.description !== undefined ? { body: b.description } : {}) };
313
317
  releases.push(r);
314
318
  return json(201, view(r));
315
319
  }
@@ -322,8 +326,8 @@ export function startFakeForge(forge: "github" | "forgejo" | "gitlab", api: stri
322
326
  }
323
327
  if (init.method === "GET" && path === `${root}/releases`) return json(200, releases.map(view));
324
328
  if (init.method === "POST" && path === `${root}/releases`) {
325
- const b = JSON.parse(text(init.body)) as { tag_name: string; target_commitish: string; draft?: boolean; name?: string };
326
- const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: b.draft === true, target: b.target_commitish, assets: [], ...(b.name ? { name: b.name } : {}) };
329
+ const b = JSON.parse(text(init.body)) as { tag_name: string; target_commitish: string; draft?: boolean; name?: string; body?: string };
330
+ const r: FakeForgeRelease = { id: nextId++, tag_name: b.tag_name, draft: b.draft === true, target: b.target_commitish, assets: [], ...(b.name ? { name: b.name } : {}), ...(b.body !== undefined ? { body: b.body } : {}) };
327
331
  releases.push(r);
328
332
  return json(201, view(r));
329
333
  }
@@ -342,7 +346,9 @@ export function startFakeForge(forge: "github" | "forgejo" | "gitlab", api: stri
342
346
  if (init.method === "PATCH" && edit) {
343
347
  const r = releases.find((x) => x.id === Number(edit[1]));
344
348
  if (!r) return json(404, { message: "Not Found" });
345
- const b = JSON.parse(text(init.body)) as { draft?: boolean; make_latest?: string };
349
+ const b = JSON.parse(text(init.body)) as { draft?: boolean; make_latest?: string; body?: string; prerelease?: boolean };
350
+ if (b.body !== undefined) r.body = b.body;
351
+ if (b.prerelease !== undefined) r.prerelease = b.prerelease;
346
352
  if (b.draft === false && r.draft) {
347
353
  if (releases.some((x) => x !== r && !x.draft && x.tag_name === r.tag_name)) return json(422, { message: "Validation Failed", errors: [{ code: "already_exists", field: "tag_name" }] });
348
354
  r.draft = false;
@@ -0,0 +1,115 @@
1
+ /**
2
+ * #4720: spending a gated request's approval in a checkout with no remote for
3
+ * `chant/lifecycle`. The local branch is the whole ledger there, so the
4
+ * applied line written to it spends the approval. A push that fails still
5
+ * refuses, as before.
6
+ */
7
+ import { afterEach, describe, expect, test } from "vitest";
8
+ import { execFileSync } from "node:child_process";
9
+ import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
10
+ import { tmpdir } from "node:os";
11
+ import { join } from "node:path";
12
+ import { pushLifecycleStatus, readBlobFromPath, writeBlobToPath } from "./git";
13
+ import { spendGatedRequest } from "./gated-request";
14
+ import { appliedGatePath, parseAppliedGateFile } from "./gate-applied";
15
+
16
+ const dirs: string[] = [];
17
+
18
+ afterEach(() => {
19
+ for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
20
+ });
21
+
22
+ function git(args: string[], cwd: string): string {
23
+ return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
24
+ }
25
+
26
+ function tmp(name: string): string {
27
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), `gated-spend-${name}-`)));
28
+ dirs.push(dir);
29
+ return dir;
30
+ }
31
+
32
+ function identity(dir: string): void {
33
+ git(["config", "user.email", "test@chant.dev"], dir);
34
+ git(["config", "user.name", "Test"], dir);
35
+ }
36
+
37
+ function repo(dir: string): void {
38
+ git(["init", "-q", "-b", "main"], dir);
39
+ identity(dir);
40
+ writeFileSync(join(dir, "README.md"), "fixture\n");
41
+ git(["add", "README.md"], dir);
42
+ git(["commit", "-q", "-m", "init"], dir);
43
+ }
44
+
45
+ const spend = (cwd: string) => ({
46
+ op: "tf-export",
47
+ gate: "network",
48
+ digest: "sha256:" + "a".repeat(64),
49
+ approval: { resolvedBy: "github:bob", timestamp: "2026-11-02T10:00:00Z" },
50
+ now: "2026-11-02T10:05:00Z",
51
+ cwd,
52
+ });
53
+
54
+ async function appliedLines(cwd: string) {
55
+ const { dir, file } = appliedGatePath("tf-export");
56
+ const text = await readBlobFromPath(dir, file, { cwd });
57
+ return text ? parseAppliedGateFile(text).applied : [];
58
+ }
59
+
60
+ describe("spendGatedRequest (#4720)", () => {
61
+ test("with no remote, the applied line on the local branch spends the approval", async () => {
62
+ const dir = tmp("local");
63
+ repo(dir);
64
+ expect(git(["remote"], dir)).toBe("");
65
+
66
+ const record = await spendGatedRequest(spend(dir));
67
+ expect(record).toMatchObject({ kind: "applied", gate: "network", approvedBy: "github:bob" });
68
+ expect(await appliedLines(dir)).toEqual([expect.objectContaining({ gate: "network", planDigest: spend(dir).digest })]);
69
+ });
70
+
71
+ test("with a remote the push cannot reach, the spend still throws and nothing may apply", async () => {
72
+ const remote = tmp("remote");
73
+ git(["init", "-q", "--bare", "-b", "main"], remote);
74
+ const dir = tmp("checkout");
75
+ git(["clone", "-q", remote, dir], tmpdir());
76
+ identity(dir);
77
+ writeFileSync(join(dir, "README.md"), "fixture\n");
78
+ git(["add", "README.md"], dir);
79
+ git(["commit", "-q", "-m", "init"], dir);
80
+ git(["push", "-q", "origin", "main"], dir);
81
+ await writeBlobToPath("prod", "releases.jsonl", '{"seed":true}\n', "seed", { cwd: dir });
82
+ expect((await pushLifecycleStatus({ cwd: dir })).status).toBe("pushed");
83
+
84
+ git(["remote", "set-url", "origin", join(remote, "gone")], dir);
85
+ await expect(spendGatedRequest(spend(dir))).rejects.toThrow(/recorded as spent and not pushed .*failed.*so nothing may apply under it/);
86
+ });
87
+
88
+ test("with a remote another writer pushed to first, the spend still throws", async () => {
89
+ const remote = tmp("remote");
90
+ git(["init", "-q", "--bare", "-b", "main"], remote);
91
+ const dir = tmp("checkout");
92
+ git(["clone", "-q", remote, dir], tmpdir());
93
+ identity(dir);
94
+ writeFileSync(join(dir, "README.md"), "fixture\n");
95
+ git(["add", "README.md"], dir);
96
+ git(["commit", "-q", "-m", "init"], dir);
97
+ git(["push", "-q", "origin", "main"], dir);
98
+ await writeBlobToPath("prod", "releases.jsonl", '{"seed":true}\n', "seed", { cwd: dir });
99
+ expect((await pushLifecycleStatus({ cwd: dir })).status).toBe("pushed");
100
+
101
+ // A second checkout records and pushes, and the first never fetches it:
102
+ // the fetch before the spend is pointed somewhere unreadable, the push
103
+ // back at the real remote.
104
+ const other = tmp("other");
105
+ git(["clone", "-q", remote, other], tmpdir());
106
+ identity(other);
107
+ git(["fetch", "-q", "origin", "chant/lifecycle:chant/lifecycle"], other);
108
+ await writeBlobToPath("prod", "releases.jsonl", '{"seed":true}\n{"other":true}\n', "other", { cwd: other });
109
+ expect((await pushLifecycleStatus({ cwd: other })).status).toBe("pushed");
110
+
111
+ git(["remote", "set-url", "origin", join(remote, "gone")], dir);
112
+ git(["remote", "set-url", "--push", "origin", remote], dir);
113
+ await expect(spendGatedRequest(spend(dir))).rejects.toThrow(/recorded as spent and not pushed .*stale info.*so nothing may apply under it/s);
114
+ });
115
+ });
@@ -32,6 +32,7 @@ import { readGateLedger, type GateResolutionRecord, type PendingGateRecord } fro
32
32
  import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, requireLifecycleLedger, writeBlobToPath, type LedgerLocation } from "./git";
33
33
  import { samePlanDigest } from "./plan-digest";
34
34
  import { gatedRequestAttachmentPath, gatedRequestDigest, type GatedRequest } from "./gated-request-digest";
35
+ import { isLifecycleLocalNote } from "./local-note";
35
36
 
36
37
  export { gatedRequestAttachmentPath, gatedRequestDigest, gatedRequestOf, type GatedRequest } from "./gated-request-digest";
37
38
 
@@ -183,7 +184,9 @@ export async function requestGate(input: RequestGateInput): Promise<RequestGateR
183
184
  /**
184
185
  * Record that the request applies under `approval`, which spends it. Throws
185
186
  * unless the line was pushed, so two jobs never act on one approval; the
186
- * caller acts only after this returns.
187
+ * caller acts only after this returns. With no remote for `chant/lifecycle`
188
+ * the local branch is the whole ledger, so the line written to it spends the
189
+ * approval (#4720); a push that failed or that another writer beat still throws.
187
190
  */
188
191
  export async function spendGatedRequest(input: {
189
192
  op: string;
@@ -208,7 +211,7 @@ export async function spendGatedRequest(input: {
208
211
  ...(input.commit ? { commit: input.commit } : {}),
209
212
  };
210
213
  const pushed = await appendAppliedLine(input.op, record as unknown as Record<string, unknown>, `Applied under ${input.gate}`, input.cwd ? { cwd: input.cwd } : undefined);
211
- if (!pushed.pushed) throw new Error(`the approval of ${input.gate} was recorded as spent and not pushed (${pushed.pushWarning ?? "no remote"}), so nothing may apply under it`);
214
+ if (!pushed.pushed && !isLifecycleLocalNote(pushed.pushWarning)) throw new Error(`the approval of ${input.gate} was recorded as spent and not pushed (${pushed.pushWarning ?? "no remote"}), so nothing may apply under it`);
212
215
  return record;
213
216
  }
214
217
 
@@ -276,6 +276,11 @@ export async function writeLedgerFiles(
276
276
  await requireLifecycleLedger({ ...(cwd ? { cwd } : {}) });
277
277
  }
278
278
 
279
+ // #4637: start from the remote's records this checkout already fetched. A
280
+ // caller that read a tip (`expectTip`) keeps it, and a run that records
281
+ // nothing leaves the branch alone.
282
+ if (opts?.expectTip === undefined && !ledgerRecordingOff()) await catchUpLifecycle(cwd);
283
+
279
284
  // 2-5. Read the trees, build the commit, and CAS-update the branch ref —
280
285
  // retried on a conflict (#1959 finding 1). Before that retry existed a
281
286
  // conflict from step 5's `updateRefCAS` simply threw, breaking every caller
@@ -787,6 +792,40 @@ export type LifecyclePushStatus =
787
792
  | { status: "stale"; remote: string; expected: string | null; stderr: string }
788
793
  | { status: "failed"; remote: string; stderr: string };
789
794
 
795
+ /** Whether `ancestor` is in `descendant`'s history. */
796
+ async function isAncestor(ancestor: string, descendant: string, cwd?: string): Promise<boolean> {
797
+ const rt = getRuntime();
798
+ return (await rt.spawn(["git", "merge-base", "--is-ancestor", ancestor, descendant], { cwd, env: C_LOCALE_ENV })).exitCode === 0;
799
+ }
800
+
801
+ /**
802
+ * Fast-forward the local `chant/lifecycle` to the ledger remote's tip this
803
+ * checkout has already fetched, when it is behind it (#4637). A plain
804
+ * `git fetch` in a full clone moves `refs/remotes/<remote>/chant/lifecycle`
805
+ * and leaves the branch, so a write built on the branch would sit beside the
806
+ * records made elsewhere instead of after them. Nothing is fetched here, and a
807
+ * branch with commits the remote lacks is left for the push to replay. The
808
+ * move is a compare-and-swap, so a writer that moved the branch meanwhile is
809
+ * never undone, and a checked-out `chant/lifecycle` is left alone.
810
+ */
811
+ async function catchUpLifecycle(cwd?: string): Promise<void> {
812
+ const rt = getRuntime();
813
+ const found = await ledgerRemote(cwd);
814
+ if (found === null || "failed" in found) return;
815
+ const fetched = await getRemoteLifecycleBranchSha(found.remote, { cwd });
816
+ if (!fetched) return;
817
+ const local = await getStateBranchTip(cwd);
818
+ if (!local || local === fetched) return;
819
+ if (!(await isAncestor(local, fetched, cwd))) return;
820
+ const head = await rt.spawn(["git", "symbolic-ref", "-q", "HEAD"], { cwd, env: C_LOCALE_ENV });
821
+ if (head.exitCode === 0 && head.stdout.trim() === `refs/heads/${STATE_BRANCH}`) return;
822
+ try {
823
+ await updateRefCAS(`refs/heads/${STATE_BRANCH}`, fetched, local, { cwd });
824
+ } catch (err) {
825
+ if (!(err instanceof RefCASConflictError)) throw err;
826
+ }
827
+ }
828
+
790
829
  /**
791
830
  * Point `refs/remotes/<remote>/chant/lifecycle` at `sha`, the remote tip this
792
831
  * checkout has just seen (#3391).
@@ -830,6 +869,20 @@ export async function pushLifecycleStatus(opts?: { cwd?: string }): Promise<Life
830
869
  const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
831
870
  const tip = await getStateBranchTip(cwd);
832
871
 
872
+ // #4637: the lease only says the remote still holds `expected`. A plain
873
+ // `git fetch` moves that ref without moving the local branch, so a branch
874
+ // that does not contain it would pass the lease and push over every record
875
+ // made since (an approval from another clone). Refused as stale, so a
876
+ // rebasing caller replays its commits onto the remote's tip.
877
+ if (expected && tip && expected !== tip && !(await isAncestor(expected, tip, cwd))) {
878
+ return {
879
+ status: "stale",
880
+ remote,
881
+ expected,
882
+ stderr: `this checkout's ${STATE_BRANCH} does not contain ${expected.slice(0, 12)}, the tip it last fetched from "${remote}"; pushing it would drop the records made since`,
883
+ };
884
+ }
885
+
833
886
  const pushResult = await rt.spawn(
834
887
  ["git", "push", `--force-with-lease=${lease}`, remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
835
888
  { cwd, env: C_LOCALE_ENV },