@intentius/chant 0.124.96 → 0.124.98

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 (237) hide show
  1. package/dist/audit/core.d.ts +29 -0
  2. package/dist/audit/core.d.ts.map +1 -1
  3. package/dist/audit/core.js +48 -11
  4. package/dist/audit/identity.d.ts +27 -0
  5. package/dist/audit/identity.d.ts.map +1 -0
  6. package/dist/audit/identity.js +36 -0
  7. package/dist/audit/report-html.d.ts +3 -1
  8. package/dist/audit/report-html.d.ts.map +1 -1
  9. package/dist/audit/report-html.js +1 -1
  10. package/dist/audit/report-model.d.ts +16 -0
  11. package/dist/audit/report-model.d.ts.map +1 -1
  12. package/dist/audit/report-model.js +5 -1
  13. package/dist/change-set-graph.d.ts +3 -1
  14. package/dist/change-set-graph.d.ts.map +1 -1
  15. package/dist/change-set-graph.js +7 -1
  16. package/dist/change-set.d.ts +5 -2
  17. package/dist/change-set.d.ts.map +1 -1
  18. package/dist/change-set.js +6 -3
  19. package/dist/ci-agent.d.ts +17 -0
  20. package/dist/ci-agent.d.ts.map +1 -1
  21. package/dist/ci-agent.js +32 -0
  22. package/dist/ci-comment-allow.d.ts +88 -0
  23. package/dist/ci-comment-allow.d.ts.map +1 -0
  24. package/dist/ci-comment-allow.js +178 -0
  25. package/dist/ci-comment-commands.d.ts +12 -0
  26. package/dist/ci-comment-commands.d.ts.map +1 -1
  27. package/dist/ci-comment-commands.js +22 -0
  28. package/dist/ci-control.d.ts +6 -1
  29. package/dist/ci-control.d.ts.map +1 -1
  30. package/dist/ci-control.js +6 -1
  31. package/dist/ci-product.d.ts +3 -0
  32. package/dist/ci-product.d.ts.map +1 -1
  33. package/dist/ci-product.js +3 -0
  34. package/dist/cli/commands/audit.d.ts +3 -1
  35. package/dist/cli/commands/audit.d.ts.map +1 -1
  36. package/dist/cli/commands/audit.js +23 -6
  37. package/dist/cli/commands/import.d.ts +8 -1
  38. package/dist/cli/commands/import.d.ts.map +1 -1
  39. package/dist/cli/commands/import.js +31 -6
  40. package/dist/cli/handlers/agent.d.ts.map +1 -1
  41. package/dist/cli/handlers/agent.js +12 -2
  42. package/dist/cli/handlers/pr-comment.d.ts +6 -0
  43. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  44. package/dist/cli/handlers/pr-comment.js +12 -0
  45. package/dist/cli/handlers/promote.d.ts.map +1 -1
  46. package/dist/cli/handlers/promote.js +53 -6
  47. package/dist/cli/main.d.ts.map +1 -1
  48. package/dist/cli/main.js +29 -6
  49. package/dist/cli/parse-args.d.ts.map +1 -1
  50. package/dist/cli/parse-args.js +23 -0
  51. package/dist/cli/registry.d.ts +8 -0
  52. package/dist/cli/registry.d.ts.map +1 -1
  53. package/dist/cloud-lister/mask.d.ts +30 -1
  54. package/dist/cloud-lister/mask.d.ts.map +1 -1
  55. package/dist/cloud-lister/mask.js +66 -3
  56. package/dist/components/driver.d.ts +8 -1
  57. package/dist/components/driver.d.ts.map +1 -1
  58. package/dist/components/driver.js +1 -0
  59. package/dist/components/product-pipeline.d.ts +23 -1
  60. package/dist/components/product-pipeline.d.ts.map +1 -1
  61. package/dist/components/product-pipeline.js +40 -7
  62. package/dist/components/product-plan.d.ts +20 -0
  63. package/dist/components/product-plan.d.ts.map +1 -1
  64. package/dist/components/product-plan.js +11 -1
  65. package/dist/control/applied.d.ts +8 -1
  66. package/dist/control/applied.d.ts.map +1 -1
  67. package/dist/control/applied.js +18 -2
  68. package/dist/control/dispatch.d.ts +52 -0
  69. package/dist/control/dispatch.d.ts.map +1 -1
  70. package/dist/control/dispatch.js +140 -4
  71. package/dist/control/train.d.ts +198 -0
  72. package/dist/control/train.d.ts.map +1 -0
  73. package/dist/control/train.js +294 -0
  74. package/dist/deep-observation.js +2 -2
  75. package/dist/floor-table.data.d.ts.map +1 -1
  76. package/dist/floor-table.data.js +7 -1
  77. package/dist/graph-detail.d.ts +9 -0
  78. package/dist/graph-detail.d.ts.map +1 -1
  79. package/dist/graph-detail.js +38 -13
  80. package/dist/graph-refs.d.ts +233 -3
  81. package/dist/graph-refs.d.ts.map +1 -1
  82. package/dist/graph-refs.js +106 -15
  83. package/dist/lint/post-synth.d.ts +22 -0
  84. package/dist/lint/post-synth.d.ts.map +1 -1
  85. package/dist/lint/rules/declarable-naming-convention.d.ts +12 -0
  86. package/dist/lint/rules/declarable-naming-convention.d.ts.map +1 -1
  87. package/dist/lint/rules/declarable-naming-convention.js +38 -8
  88. package/dist/lint/rules/imported-source.d.ts +20 -0
  89. package/dist/lint/rules/imported-source.d.ts.map +1 -0
  90. package/dist/lint/rules/imported-source.js +27 -0
  91. package/dist/lint/rules/no-unused-declarable.d.ts.map +1 -1
  92. package/dist/lint/rules/no-unused-declarable.js +3 -0
  93. package/dist/op/gate.d.ts +2 -0
  94. package/dist/op/gate.d.ts.map +1 -1
  95. package/dist/op/gate.js +8 -1
  96. package/dist/pr-forge-reads.d.ts +17 -0
  97. package/dist/pr-forge-reads.d.ts.map +1 -1
  98. package/dist/pr-forge-reads.js +55 -0
  99. package/dist/reconcile.d.ts +9 -0
  100. package/dist/reconcile.d.ts.map +1 -1
  101. package/dist/release-floors.d.ts +9 -1
  102. package/dist/release-floors.d.ts.map +1 -1
  103. package/dist/release-floors.js +10 -2
  104. package/dist/repo-path.d.ts +29 -0
  105. package/dist/repo-path.d.ts.map +1 -0
  106. package/dist/repo-path.js +81 -0
  107. package/dist/sensitive-key.d.ts +23 -0
  108. package/dist/sensitive-key.d.ts.map +1 -1
  109. package/dist/sensitive-key.js +37 -0
  110. package/dist/terraform/hcl2json.d.ts +7 -0
  111. package/dist/terraform/hcl2json.d.ts.map +1 -1
  112. package/dist/terraform/hcl2json.js +7 -0
  113. package/dist/wave-runtime.mjs +352 -345
  114. package/dist/workspace/catalog-edges.d.ts +147 -0
  115. package/dist/workspace/catalog-edges.d.ts.map +1 -0
  116. package/dist/workspace/catalog-edges.js +461 -0
  117. package/dist/workspace/compose-graph.d.ts +73 -3
  118. package/dist/workspace/compose-graph.d.ts.map +1 -1
  119. package/dist/workspace/declaration.d.ts +2 -0
  120. package/dist/workspace/declaration.d.ts.map +1 -1
  121. package/dist/workspace/declaration.js +1 -0
  122. package/dist/workspace/declaration.schema.json +6 -0
  123. package/dist/workspace/discover.d.ts +134 -0
  124. package/dist/workspace/discover.d.ts.map +1 -0
  125. package/dist/workspace/discover.js +372 -0
  126. package/dist/workspace/graph-cli.d.ts +20 -0
  127. package/dist/workspace/graph-cli.d.ts.map +1 -1
  128. package/dist/workspace/graph-cli.js +178 -20
  129. package/dist/workspace/graph.schema.json +195 -2
  130. package/dist/workspace/release-train.d.ts +214 -3
  131. package/dist/workspace/release-train.d.ts.map +1 -1
  132. package/dist/workspace/release-train.js +552 -16
  133. package/dist/workspace/repo-ref.d.ts +14 -0
  134. package/dist/workspace/repo-ref.d.ts.map +1 -1
  135. package/dist/workspace/repo-ref.js +26 -1
  136. package/dist/workspace/workspace-gates.d.ts +24 -0
  137. package/dist/workspace/workspace-gates.d.ts.map +1 -1
  138. package/dist/workspace/workspace-gates.js +29 -5
  139. package/dist/workspace/workspace-ledger.d.ts +31 -5
  140. package/dist/workspace/workspace-ledger.d.ts.map +1 -1
  141. package/dist/workspace/workspace-ledger.js +2 -1
  142. package/dist/workspace/workspace-run.d.ts +14 -0
  143. package/dist/workspace/workspace-run.d.ts.map +1 -1
  144. package/dist/workspace/workspace-run.js +2 -2
  145. package/dist/yaml.d.ts.map +1 -1
  146. package/dist/yaml.js +33 -8
  147. package/package.json +1 -1
  148. package/src/audit/core.test.ts +64 -1
  149. package/src/audit/core.ts +75 -10
  150. package/src/audit/identity.test.ts +31 -0
  151. package/src/audit/identity.ts +43 -0
  152. package/src/audit/report-html.ts +4 -2
  153. package/src/audit/report-model.ts +21 -1
  154. package/src/change-set-graph.test.ts +33 -1
  155. package/src/change-set-graph.ts +7 -1
  156. package/src/change-set.ts +6 -3
  157. package/src/ci-agent.test.ts +32 -0
  158. package/src/ci-agent.ts +42 -0
  159. package/src/ci-comment-allow.test.ts +380 -0
  160. package/src/ci-comment-allow.ts +184 -0
  161. package/src/ci-comment-commands.ts +25 -0
  162. package/src/ci-control.ts +42 -0
  163. package/src/ci-product.ts +3 -0
  164. package/src/cli/commands/audit-parser-notice.test.ts +74 -0
  165. package/src/cli/commands/audit.test.ts +12 -0
  166. package/src/cli/commands/audit.ts +25 -7
  167. package/src/cli/commands/import-layout.test.ts +2 -1
  168. package/src/cli/commands/import.ts +29 -6
  169. package/src/cli/handlers/agent.ts +13 -2
  170. package/src/cli/handlers/pr-before-merge.test.ts +18 -0
  171. package/src/cli/handlers/pr-comment.ts +12 -0
  172. package/src/cli/handlers/promote.test.ts +68 -0
  173. package/src/cli/handlers/promote.ts +52 -6
  174. package/src/cli/main.test.ts +5 -0
  175. package/src/cli/main.ts +29 -6
  176. package/src/cli/parse-args.ts +18 -0
  177. package/src/cli/registry.ts +8 -0
  178. package/src/cloud-lister/kubernetes.k3d.e2e.test.ts +104 -0
  179. package/src/cloud-lister/mask-references.test.ts +132 -0
  180. package/src/cloud-lister/mask.ts +68 -3
  181. package/src/components/driver.ts +9 -1
  182. package/src/components/product-pipeline.ts +57 -7
  183. package/src/components/product-plan.ts +27 -2
  184. package/src/control/applied.ts +33 -3
  185. package/src/control/dispatch.ts +156 -5
  186. package/src/control/train.test.ts +215 -0
  187. package/src/control/train.ts +413 -0
  188. package/src/deep-observation.ts +2 -2
  189. package/src/floor-table.data.ts +7 -1
  190. package/src/graph-detail.ts +37 -12
  191. package/src/graph-refs.test.ts +45 -1
  192. package/src/graph-refs.ts +321 -14
  193. package/src/lint/post-synth.ts +20 -0
  194. package/src/lint/rules/declarable-naming-convention.test.ts +35 -1
  195. package/src/lint/rules/declarable-naming-convention.ts +35 -8
  196. package/src/lint/rules/imported-source.test.ts +22 -0
  197. package/src/lint/rules/imported-source.ts +31 -0
  198. package/src/lint/rules/no-unused-declarable.test.ts +16 -0
  199. package/src/lint/rules/no-unused-declarable.ts +7 -0
  200. package/src/op/gate.ts +10 -2
  201. package/src/pr-forge-reads.ts +62 -0
  202. package/src/reconcile.ts +9 -0
  203. package/src/release-floors.ts +14 -2
  204. package/src/repo-path.test.ts +72 -0
  205. package/src/repo-path.ts +103 -0
  206. package/src/sensitive-key.ts +38 -0
  207. package/src/terraform/hcl2json.ts +8 -0
  208. package/src/workspace/application-set.e2e.test.ts +405 -0
  209. package/src/workspace/catalog-edges.ts +507 -0
  210. package/src/workspace/ci-green-workflow.test.ts +2 -2
  211. package/src/workspace/cluster-join.e2e.test.ts +150 -0
  212. package/src/workspace/compose-graph.ts +74 -5
  213. package/src/workspace/declaration.schema.json +6 -0
  214. package/src/workspace/declaration.ts +3 -0
  215. package/src/workspace/discover.e2e.test.ts +122 -0
  216. package/src/workspace/discover.test.ts +225 -0
  217. package/src/workspace/discover.ts +406 -0
  218. package/src/workspace/drift-reader.test.ts +3 -3
  219. package/src/workspace/external-secret-catalog.e2e.test.ts +98 -0
  220. package/src/workspace/external-secret-catalog.test.ts +142 -0
  221. package/src/workspace/graph-cli.ts +207 -21
  222. package/src/workspace/graph-contract.test.ts +92 -0
  223. package/src/workspace/graph.schema.json +195 -2
  224. package/src/workspace/helm-references.e2e.test.ts +135 -0
  225. package/src/workspace/identity-annotation-catalog.e2e.test.ts +91 -0
  226. package/src/workspace/identity-annotation-catalog.test.ts +139 -0
  227. package/src/workspace/release-train-repos.test.ts +304 -0
  228. package/src/workspace/release-train.test.ts +296 -0
  229. package/src/workspace/release-train.ts +631 -16
  230. package/src/workspace/repo-ref.ts +26 -1
  231. package/src/workspace/runs-on.test.ts +45 -0
  232. package/src/workspace/workspace-gates.ts +48 -5
  233. package/src/workspace/workspace-ledger.ts +28 -5
  234. package/src/workspace/workspace-run.test.ts +1 -1
  235. package/src/workspace/workspace-run.ts +2 -2
  236. package/src/yaml.test.ts +96 -8
  237. package/src/yaml.ts +36 -8
@@ -8,17 +8,48 @@
8
8
  * the one `--pin <member>=<label|digest>` picks. It refuses unless every
9
9
  * `chant` member of the declaration has a release, so a train never leaves a
10
10
  * member out. It is written to `_members/_workspace/<env>/trains.jsonl`.
11
+ *
12
+ * A train's digest (#4037) is over the member release digests and nothing
13
+ * else, so the same picks always give the same train digest, whatever the
14
+ * environment, actor or time. The member releases are named, never copied
15
+ * or changed.
16
+ *
17
+ * `chant workspace train promote <env>` (#4037) promotes a train: each
18
+ * member's `chant components promote --to <env> --release <its digest>`,
19
+ * under the member's own chant, producers first. With `--gate <name>`,
20
+ * every member plans first (`--plan-only`), one workspace gate fact covers
21
+ * each member's release gates with its change set and release, and nothing
22
+ * deploys until `chant workspace run approve <name>` approves it. The
23
+ * promote is a workspace run record that names the train.
24
+ *
25
+ * A train can pin `repo` members too (#5119): each one's releases are read
26
+ * at its pinned revision through that repository's own `chant release list
27
+ * --json`. A train of `repo` members is promoted from the control repo, one
28
+ * member repository at a time: each call dispatches a member, or moves on
29
+ * from its answer in `_control/applied.jsonl` (`--continue`). Each member
30
+ * keeps its own gate (../control/train.ts has the jobs on both sides).
11
31
  */
12
32
 
33
+ import { spawn } from "node:child_process";
13
34
  import { randomUUID } from "node:crypto";
14
35
  import { resolve } from "node:path";
15
36
  import { formatError } from "../cli/format";
16
37
  import type { CommandContext } from "../cli/registry";
38
+ import { CHANT_EXIT } from "../exit-codes";
39
+ import { computePlanDigest } from "../lifecycle/plan-digest";
17
40
  import { readAllReleases, readCuts } from "../lifecycle/release-store";
18
- import { readDeclaration, WorkspaceReadError } from "./declaration";
41
+ import { WORKSPACE_GATE_ENV, WORKSPACE_RUN_ENV } from "../op/workspace-run-env";
42
+ import type { WorkspaceGraph } from "./compose-graph";
43
+ import { readDeclaration, WorkspaceReadError, type RepoRef } from "./declaration";
44
+ import { REPO_KIND } from "./kinds";
19
45
  import { locateWorkspace } from "./which-chant";
20
- import { appendWorkspaceLine, readWorkspaceLines } from "./workspace-ledger";
46
+ import { appendWorkspaceLine, appendWorkspaceRun, readWorkspaceLines, readWorkspaceRuns, type WorkspaceRunRecord, type WorkspaceRunStep } from "./workspace-ledger";
47
+ import { appendWorkspaceGatePending, readWorkspaceGate, workspaceGateDigest, type WorkspaceGateCover, type WorkspaceGatePending } from "./workspace-gates";
48
+ import type { MemberOpResult } from "./workspace-run";
49
+ import type { ControlAppliedRecord } from "../control/applied";
50
+ import type { TrainDispatch } from "../control/train";
21
51
  import { actorFromEnv } from "../actor";
52
+ import { NEXT_RELEASE } from "../release-floors";
22
53
 
23
54
  export interface TrainMember {
24
55
  member: string;
@@ -27,6 +58,12 @@ export interface TrainMember {
27
58
  commit: string;
28
59
  /** The label its newest cut gave it, or null. */
29
60
  label: string | null;
61
+ /**
62
+ * For a member of kind `repo` (#5119): the other repository, its URL with
63
+ * any credential removed, and the revision its releases were read at.
64
+ * Absent for a `chant` member.
65
+ */
66
+ repo?: { url: string; rev: string };
30
67
  }
31
68
 
32
69
  export interface ReleaseTrainRecord {
@@ -37,6 +74,27 @@ export interface ReleaseTrainRecord {
37
74
  actor: string;
38
75
  /** Every `chant` member, by name. */
39
76
  members: TrainMember[];
77
+ /**
78
+ * {@link trainDigest} over `members` (#4037). Absent on a line written
79
+ * before {@link TRAIN_PROMOTE_FLOOR}; {@link readReleaseTrains} computes it then.
80
+ */
81
+ trainDigest?: string;
82
+ }
83
+
84
+ /** A train as read back: its digest is always there. */
85
+ export type ReadTrain = ReleaseTrainRecord & { trainDigest: string };
86
+
87
+ /**
88
+ * The digest of a train (#4037): over each member's name and release digest,
89
+ * sorted by member. The commit and the label are the release's own, and the
90
+ * release digest already covers the commit, so they stay out, as do the
91
+ * environment, the id, the actor and the time.
92
+ */
93
+ export function trainDigest(members: readonly Pick<TrainMember, "member" | "releaseDigest">[]): string {
94
+ const subject = [...members]
95
+ .map((m) => ({ member: m.member, releaseDigest: m.releaseDigest }))
96
+ .sort((a, b) => (a.member < b.member ? -1 : a.member > b.member ? 1 : 0));
97
+ return computePlanDigest("release-train", { members: subject });
40
98
  }
41
99
 
42
100
  const TRAINS_FILE = "trains.jsonl";
@@ -45,6 +103,10 @@ const TRAINS_FILE = "trains.jsonl";
45
103
  export interface MemberReleases {
46
104
  member: string;
47
105
  releases: TrainMember[];
106
+ /** Why the member's releases could not be read (#5119), which stops the train. */
107
+ problem?: string;
108
+ /** For a `repo` member: where its releases are cut, for the message when it has none. */
109
+ repo?: string;
48
110
  }
49
111
 
50
112
  /**
@@ -56,26 +118,44 @@ export function pickTrain(members: readonly MemberReleases[], pins: ReadonlyMap<
56
118
  const problems: string[] = [];
57
119
  const picked: TrainMember[] = [];
58
120
  for (const name of pins.keys()) {
59
- if (!members.some((m) => m.member === name)) problems.push(`--pin ${name}: not a chant member of the workspace`);
121
+ if (!members.some((m) => m.member === name)) problems.push(`--pin ${name}: not a chant or repo member of the workspace`);
60
122
  }
61
123
  for (const m of members) {
124
+ if (m.problem !== undefined) {
125
+ problems.push(`member ${m.member}: ${m.problem}`);
126
+ continue;
127
+ }
62
128
  const pin = pins.get(m.member);
63
129
  const r = pin === undefined ? m.releases[0] : m.releases.find((x) => x.releaseDigest === pin || x.label === pin);
64
130
  if (!r) {
65
- problems.push(pin === undefined ? `member ${m.member} has no release; cut one with chant release cut in its directory` : `member ${m.member} has no release ${pin}`);
131
+ const where = m.repo !== undefined ? `in ${m.repo}` : "in its directory";
132
+ problems.push(pin === undefined ? `member ${m.member} has no release; cut one with chant release cut ${where}` : `member ${m.member} has no release ${pin}`);
66
133
  continue;
67
134
  }
68
135
  picked.push(r);
69
136
  }
137
+ // #4037: a train names at least one release, so its digest never covers nothing.
138
+ if (members.length === 0) problems.push("the workspace declares no chant or repo member, so a train has nothing to pin");
70
139
  return problems.length > 0 ? { problems } : { members: picked };
71
140
  }
72
141
 
73
- /** Every `chant` member's releases, newest cut first, read from its ledger. */
74
- export async function readMemberReleases(cwd: string): Promise<MemberReleases[]> {
142
+ /** Reads one `repo` member's releases (#5119); {@link readRepoReleases} unless a test passes its own. */
143
+ export type RepoReleasesReader = (member: string, ref: RepoRef, workspaceRoot: string) => Promise<MemberReleases>;
144
+
145
+ /**
146
+ * Every `chant` member's releases, newest cut first, read from its ledger,
147
+ * and every `repo` member's, read through that repository's own
148
+ * `chant release list --json` at its pinned revision (#5119).
149
+ */
150
+ export async function readMemberReleases(cwd: string, opts: { readRepo?: RepoReleasesReader } = {}): Promise<MemberReleases[]> {
75
151
  const located = locateWorkspace(cwd);
76
152
  const declaration = readDeclaration(located.tree, "", { rootChant: true });
77
153
  const out: MemberReleases[] = [];
78
154
  for (const m of declaration.members) {
155
+ if (m.kind === REPO_KIND && m.repo !== null) {
156
+ out.push(await (opts.readRepo ?? readRepoReleases)(m.name, m.repo, located.rootOnDisk));
157
+ continue;
158
+ }
79
159
  if (m.kind !== "chant") continue;
80
160
  const loc = { cwd: located.rootOnDisk, member: m.dir === "." ? "." : m.name };
81
161
  const { releases } = await readAllReleases(loc);
@@ -91,24 +171,473 @@ export async function readMemberReleases(cwd: string): Promise<MemberReleases[]>
91
171
  return out;
92
172
  }
93
173
 
174
+ /** Starts one chant command in `cwd` and gives back what it printed. */
175
+ function spawnChant(command: readonly string[], argv: string[], cwd: string): Promise<{ exitCode: number; stdout: string; stderr: string }> {
176
+ const [bin, ...pre] = command;
177
+ return new Promise((done) => {
178
+ const child = spawn(bin!, [...pre, ...argv], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
179
+ const out: Buffer[] = [];
180
+ const err: Buffer[] = [];
181
+ child.stdout.on("data", (b: Buffer) => out.push(b));
182
+ child.stderr.on("data", (b: Buffer) => err.push(b));
183
+ child.on("error", (e) => done({ exitCode: 127, stdout: "", stderr: `could not start ${bin}: ${e.message}` }));
184
+ child.on("close", (code) => done({ exitCode: code ?? 1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));
185
+ });
186
+ }
187
+
188
+ /**
189
+ * The releases of a `repo` member (#5119), read the way its graph is read
190
+ * (#3168): chant fetches the pinned revision into the user's cache, brings
191
+ * that repository's `chant/lifecycle` into the cache clone, and runs
192
+ * `chant release list --json` in the workspace root at the revision, under
193
+ * the chant that resolves there. Nothing is written in the other
194
+ * repository. A read that fails says why, and stops the train.
195
+ */
196
+ export async function readRepoReleases(member: string, ref: RepoRef, workspaceRoot: string, opts: { env?: NodeJS.ProcessEnv; command?: readonly string[] } = {}): Promise<MemberReleases> {
197
+ const { fetchRepoAt, fetchRepoLifecycle, redactUrl } = await import("./repo-ref");
198
+ const url = redactUrl(ref.url);
199
+ const base = { member, releases: [] as TrainMember[], repo: url };
200
+ const fetched = fetchRepoAt(ref, workspaceRoot, opts.env);
201
+ if (!fetched.ok) return { ...base, problem: fetched.message };
202
+ const lifecycle = fetchRepoLifecycle(ref, workspaceRoot, opts.env);
203
+ if (!lifecycle.ok) return { ...base, problem: lifecycle.message };
204
+ const { resolveToolchain } = await import("./member-commands");
205
+ const command = opts.command ?? resolveToolchain(fetched.dir, fetched.worktree).command;
206
+ const r = await spawnChant(command, ["release", "list", "--json"], fetched.dir);
207
+ type Printed = { $schema?: unknown; error?: { code?: unknown; message?: unknown }; releases?: unknown };
208
+ let doc: Printed | null;
209
+ try {
210
+ doc = JSON.parse(r.stdout) as Printed;
211
+ } catch {
212
+ doc = null;
213
+ }
214
+ const { RELEASES_SCHEMA_ID } = await import("./releases");
215
+ if (!doc || doc.$schema !== RELEASES_SCHEMA_ID) {
216
+ const tail = r.stderr.trim().split("\n").slice(-3).join("; ");
217
+ return { ...base, problem: `chant release list in ${url} at ${ref.rev.slice(0, 12)} exited ${r.exitCode} and printed no releases document${tail ? `: ${tail}` : ""}` };
218
+ }
219
+ if (doc.error) return { ...base, problem: `chant release list in ${url} at ${ref.rev.slice(0, 12)}: ${String(doc.error.code)}: ${String(doc.error.message)}` };
220
+ const entries = Array.isArray(doc.releases) ? (doc.releases as Array<{ releaseDigest?: unknown; commit?: unknown; label?: unknown; cuts?: unknown }>) : [];
221
+ const releases: TrainMember[] = [];
222
+ // The document lists the newest cut first; a release no cut names comes last and is not one a train takes.
223
+ for (const e of entries) {
224
+ if (typeof e.releaseDigest !== "string" || typeof e.commit !== "string" || !Array.isArray(e.cuts) || e.cuts.length === 0) continue;
225
+ releases.push({ member, releaseDigest: e.releaseDigest, commit: e.commit, label: typeof e.label === "string" ? e.label : null, repo: { url, rev: ref.rev } });
226
+ }
227
+ return { ...base, releases };
228
+ }
229
+
94
230
  function isTrain(v: unknown): v is ReleaseTrainRecord {
95
231
  const t = v as ReleaseTrainRecord;
96
232
  return typeof t === "object" && t !== null && t.version === 1 && typeof t.id === "string" && typeof t.env === "string" && Array.isArray(t.members);
97
233
  }
98
234
 
99
- export async function readReleaseTrains(cwd: string, env: string): Promise<{ records: ReleaseTrainRecord[]; malformed: number }> {
100
- return readWorkspaceLines(cwd, env, TRAINS_FILE, isTrain);
235
+ export async function readReleaseTrains(cwd: string, env: string): Promise<{ records: ReadTrain[]; malformed: number }> {
236
+ const { records, malformed } = await readWorkspaceLines(cwd, env, TRAINS_FILE, isTrain);
237
+ return { records: records.map((t) => ({ ...t, trainDigest: t.trainDigest ?? trainDigest(t.members) })), malformed };
238
+ }
239
+
240
+ /** The train `ref` names, by id or digest, else the newest. Null when there is none. */
241
+ export function findTrain(trains: readonly ReadTrain[], ref?: string): ReadTrain | null {
242
+ if (ref === undefined) return trains.at(-1) ?? null;
243
+ return trains.filter((t) => t.id === ref || t.trainDigest === ref).at(-1) ?? null;
101
244
  }
102
245
 
103
246
  export async function appendReleaseTrain(cwd: string, record: ReleaseTrainRecord): Promise<string> {
104
247
  return appendWorkspaceLine(cwd, record.env, TRAINS_FILE, record, `Release train: ${record.env} ${record.id}`);
105
248
  }
106
249
 
107
- const USAGE = "chant workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json] | chant workspace train list <env> [--json]";
250
+ /** The first chant that writes {@link ReleaseTrainRecord.trainDigest} and has `chant workspace train promote` (#4037). */
251
+ export const TRAIN_PROMOTE_FLOOR = NEXT_RELEASE;
252
+
253
+ // ── Promote ──────────────────────────────────────────────────────────────────
254
+
255
+ /** What a step of a train's promote runs in each member: `chant components promote`. */
256
+ export const TRAIN_STEP_OP = "components promote";
257
+
258
+ /** What `components promote --plan-only --json` prints (#4037). */
259
+ export interface MemberReleasePlan {
260
+ env: string;
261
+ releaseDigest: string;
262
+ label: string | null;
263
+ /** The ledger the member's release gates are recorded in. */
264
+ op: string;
265
+ /** The release gates the promoted compositions declare; empty when none does. */
266
+ gates: string[];
267
+ /** The change-set document's digest, or null when there is no gate to bind it. */
268
+ changeSet: string | null;
269
+ empty: boolean | null;
270
+ components: string[];
271
+ }
272
+
273
+ function isMemberReleasePlan(v: unknown): v is MemberReleasePlan {
274
+ const p = v as MemberReleasePlan;
275
+ return typeof p === "object" && p !== null && typeof p.releaseDigest === "string" && typeof p.op === "string" && Array.isArray(p.gates) && (p.changeSet === null || typeof p.changeSet === "string");
276
+ }
277
+
278
+ /**
279
+ * The covers a workspace gate needs for one member's release (#4037): one
280
+ * per release gate, bound to the member's change set, the environment and
281
+ * the release. None for an empty change set, which passes without an
282
+ * approval, nor for a promote that declares no gate.
283
+ */
284
+ export function releaseCovers(member: string, env: string, plan: MemberReleasePlan): WorkspaceGateCover[] {
285
+ if (plan.changeSet === null || plan.empty === true) return [];
286
+ return plan.gates.map((gate) => ({ member, op: plan.op, gate, planDigest: plan.changeSet!, environment: env, releaseDigest: plan.releaseDigest }));
287
+ }
288
+
289
+ export interface TrainPromoteQuery {
290
+ /** The workspace root. */
291
+ cwd: string;
292
+ env: string;
293
+ /** The train, by id or digest; the newest for `env` when absent. */
294
+ train?: string;
295
+ /** The workspace gate every member's release gates wait on together. */
296
+ gate?: string;
297
+ dryRun?: boolean;
298
+ /** Overrides, for tests. */
299
+ readGraph?: (cwd: string) => Promise<{ graph: WorkspaceGraph; failed: boolean } | { error: string }>;
300
+ runMember?: (member: { name: string; dir: string }, argv: string[], env: Record<string, string>) => Promise<MemberOpResult>;
301
+ now?: () => string;
302
+ onOutput?: (target: string, result: MemberOpResult) => void;
303
+ /**
304
+ * A train of `repo` members (#5119): advance the promote in flight from
305
+ * the answers the control repo recorded, and start nothing new.
306
+ */
307
+ continue?: boolean;
308
+ /** Sends one dispatch into a member repository (#5119); {@link defaultTrainDispatcher} unless a test passes its own. */
309
+ dispatch?: TrainDispatcher;
310
+ /** The control repo's apply records (#5119), read from `_control/applied.jsonl` unless a test passes its own. */
311
+ readAnswers?: (cwd: string) => Promise<ControlAppliedRecord[]>;
312
+ /** The member links a train across repositories orders by (#5119), from the declaration unless a test passes its own. */
313
+ readLinks?: (cwd: string) => Promise<WorkspaceGraph["links"]>;
314
+ }
315
+
316
+ /** Sends one dispatch into a member repository: the member, its repository's URL, and what the dispatch carries. Throws when it was not taken. */
317
+ export type TrainDispatcher = (member: { name: string; repo: string }, d: TrainDispatch) => Promise<void>;
318
+
319
+ export type TrainPromoteOutcome =
320
+ | { kind: "refused"; message: string }
321
+ | { kind: "planned"; train: ReadTrain; order: string[] }
322
+ | { kind: "ran"; train: ReadTrain; record: WorkspaceRunRecord; pending: WorkspaceGatePending | null; approved: string | null; ledgerError: string | null }
323
+ /** #5119: the promote in flight waits on `member`'s answer, and nothing was written. */
324
+ | { kind: "waiting"; train: ReadTrain; record: WorkspaceRunRecord; member: string }
325
+ /** #5119: `--continue` found no promote of the train in flight. */
326
+ | { kind: "idle"; train: ReadTrain; message: string };
327
+
328
+ const promoteArgv = (env: string, m: TrainMember, extra: string[] = []) => ["components", "promote", "--to", env, "--release", m.releaseDigest, ...extra, "--json"];
329
+
330
+ /** The JSON a member's promote printed, or null. */
331
+ function parseJson(stdout: string): unknown {
332
+ const at = stdout.indexOf("{");
333
+ if (at < 0) return null;
334
+ try {
335
+ return JSON.parse(stdout.slice(at)) as unknown;
336
+ } catch {
337
+ return null;
338
+ }
339
+ }
340
+
341
+ /** The member run and the gate a member's `promote --json` output names. */
342
+ function promoteOutcome(stdout: string): { run: string | null; gate?: WorkspaceRunStep["gate"] } {
343
+ const doc = parseJson(stdout) as { recorded?: Array<{ runId?: unknown }>; run?: { gate?: { op?: unknown; gate?: unknown; planDigest?: unknown; environment?: unknown } } } | null;
344
+ const runId = doc?.recorded?.find((r) => typeof r.runId === "string")?.runId;
345
+ const g = doc?.run?.gate;
346
+ return {
347
+ run: typeof runId === "string" ? runId : null,
348
+ ...(g && typeof g.gate === "string"
349
+ ? { gate: { op: typeof g.op === "string" ? g.op : TRAIN_STEP_OP, name: g.gate, planDigest: typeof g.planDigest === "string" ? g.planDigest : null, environment: typeof g.environment === "string" ? g.environment : null } }
350
+ : {}),
351
+ };
352
+ }
353
+
354
+ /**
355
+ * Promote a release train (#4037). Each member's release is promoted with
356
+ * `chant components promote --to <env> --release <digest>` under its own
357
+ * chant, producers first, stopping at the first member that does not pass.
358
+ *
359
+ * With a workspace gate, each member plans first and deploys nothing; the
360
+ * covers of every member's release gates are recorded as one pending fact
361
+ * naming the train, and the run ends gated. Once an approval of exactly
362
+ * those covers stands, the same call promotes every member under the gate,
363
+ * so each release gate takes the approval in place of its own where the
364
+ * member opts in at base. A member whose plan moved since then plans a
365
+ * change set the approval does not cover, and stops at its own gate.
366
+ */
367
+ export async function promoteTrain(query: TrainPromoteQuery): Promise<TrainPromoteOutcome> {
368
+ const now = query.now ?? (() => new Date().toISOString());
369
+ const { records } = await readReleaseTrains(query.cwd, query.env);
370
+ const train = findTrain(records, query.train);
371
+ if (!train) {
372
+ return {
373
+ kind: "refused",
374
+ message: query.train === undefined ? `no release train is recorded for ${query.env}; record one with chant workspace train ${query.env}` : `no release train ${query.train} is recorded for ${query.env}`,
375
+ };
376
+ }
377
+ if (train.members.length === 0) return { kind: "refused", message: `release train ${train.id} pins no member, so there is nothing to promote` };
378
+ const across = train.members.filter((m) => m.repo !== undefined);
379
+ if (across.length > 0) {
380
+ if (across.length < train.members.length) {
381
+ return { kind: "refused", message: `release train ${train.id} pins repo members (${across.map((m) => m.member).join(", ")}) and chant members (${train.members.filter((m) => !m.repo).map((m) => m.member).join(", ")}); a promote runs chant members here and dispatches repo members, so record a train of one kind` };
382
+ }
383
+ return promoteAcrossRepos(query, train, now);
384
+ }
385
+ if (query.continue) return { kind: "refused", message: "--continue advances a train of repo members, and this train pins chant members" };
386
+
387
+ const { defaultReadGraph, defaultRunMember, orderTargets } = await import("./workspace-run");
388
+ const read = await (query.readGraph ?? defaultReadGraph)(query.cwd);
389
+ if ("error" in read) return { kind: "refused", message: `the workspace graph could not be read: ${read.error}` };
390
+ const { graph } = read;
391
+ const missing = train.members.filter((m) => !graph.members.some((g) => g.name === m.member && g.status === "composed"));
392
+ if (missing.length > 0) return { kind: "refused", message: `release train ${train.id} pins ${missing.map((m) => m.member).join(", ")}, which the workspace graph does not compose` };
393
+
394
+ const order = orderTargets(train.members.map((m) => ({ member: m.member, op: TRAIN_STEP_OP })), graph.links).map((t) => train.members.find((m) => m.member === t.member)!);
395
+ if (query.dryRun) return { kind: "planned", train, order: order.map((m) => m.member) };
396
+
397
+ const id = `ws-${randomUUID()}`;
398
+ const started = now();
399
+ const citation = { id: train.id, digest: train.trainDigest };
400
+ const steps: WorkspaceRunStep[] = order.map((m) => ({ target: `${m.member}/${TRAIN_STEP_OP}`, member: m.member, op: TRAIN_STEP_OP, status: "not-run", exitCode: null, memberRun: null }));
401
+ const runMember = query.runMember ?? ((m, argv, e) => defaultRunMember(query.cwd, m, argv, e));
402
+ const dirOf = (member: string) => graph.members.find((g) => g.name === member)!.dir;
403
+ const finish = async (status: WorkspaceRunRecord["status"], pending: WorkspaceGatePending | null, approved: string | null, gatherCovers?: WorkspaceGateCover[]): Promise<TrainPromoteOutcome> => {
404
+ const record: WorkspaceRunRecord = { version: 1, id, started, ended: now(), status, env: query.env, gate: query.gate ?? null, dependentsOf: null, steps, train: citation };
405
+ let written = pending;
406
+ let ledgerError: string | null = null;
407
+ try {
408
+ if (gatherCovers && query.gate && !written) written = await appendWorkspaceGatePending(query.cwd, { gate: query.gate, run: id, timestamp: record.ended, covers: gatherCovers, train: citation });
409
+ await appendWorkspaceRun(query.cwd, record);
410
+ } catch (err) {
411
+ ledgerError = err instanceof Error ? err.message : String(err);
412
+ }
413
+ return { kind: "ran", train, record, pending: written, approved, ledgerError };
414
+ };
415
+
416
+ // With a workspace gate: every member plans before any deploys.
417
+ let approved: string | null = null;
418
+ if (query.gate) {
419
+ const covers: WorkspaceGateCover[] = [];
420
+ for (let i = 0; i < order.length; i++) {
421
+ const m = order[i]!;
422
+ const step = steps[i]!;
423
+ const result = await runMember({ name: m.member, dir: dirOf(m.member) }, promoteArgv(query.env, m, ["--plan-only"]), { [WORKSPACE_RUN_ENV]: id });
424
+ query.onOutput?.(`${step.target} --plan-only`, result);
425
+ const plan = parseJson(result.stdout);
426
+ if (result.exitCode !== 0 || !isMemberReleasePlan(plan) || plan.releaseDigest !== m.releaseDigest) {
427
+ step.status = "fail";
428
+ step.exitCode = result.exitCode;
429
+ return finish("fail", null, null);
430
+ }
431
+ covers.push(...releaseCovers(m.member, query.env, plan));
432
+ }
433
+ if (covers.length > 0) {
434
+ const digest = workspaceGateDigest(covers);
435
+ const { pending, approvals } = await readWorkspaceGate(query.cwd, query.gate);
436
+ if (approvals.some((a) => a.digest === digest && workspaceGateDigest(a.covers) === digest)) {
437
+ approved = digest;
438
+ } else {
439
+ // Nothing deployed; each member with a cover waits on the workspace gate.
440
+ for (const step of steps) {
441
+ const c = covers.find((x) => x.member === step.member);
442
+ if (c) step.gate = { op: c.op, name: c.gate, planDigest: c.planDigest, environment: c.environment ?? null };
443
+ step.status = c ? "gated" : "not-run";
444
+ }
445
+ const standing = pending.filter((p) => p.digest === digest).at(-1) ?? null;
446
+ return finish("gated", standing, null, covers);
447
+ }
448
+ }
449
+ }
450
+
451
+ const env: Record<string, string> = { [WORKSPACE_RUN_ENV]: id, ...(query.gate ? { [WORKSPACE_GATE_ENV]: query.gate } : {}) };
452
+ let status: WorkspaceRunRecord["status"] = "ok";
453
+ for (let i = 0; i < order.length; i++) {
454
+ const m = order[i]!;
455
+ const step = steps[i]!;
456
+ const result = await runMember({ name: m.member, dir: dirOf(m.member) }, promoteArgv(query.env, m), env);
457
+ query.onOutput?.(step.target, result);
458
+ step.exitCode = result.exitCode;
459
+ step.status = result.exitCode === 0 ? "ok" : result.exitCode === CHANT_EXIT.waiting ? "gated" : "fail";
460
+ const found = promoteOutcome(result.stdout);
461
+ step.memberRun = found.run;
462
+ if (found.gate) step.gate = found.gate;
463
+ if (step.status !== "ok") {
464
+ status = step.status;
465
+ break;
466
+ }
467
+ }
468
+ return finish(status, null, approved);
469
+ }
470
+
471
+ // ── Across repositories (#5119) ──────────────────────────────────────────────
472
+
473
+ /** What a step of a train's promote across repositories runs in the member repository: its train job's `chant run --release`. */
474
+ export const TRAIN_REPO_STEP_OP = "run --release";
475
+
476
+ /** The answers after which the next member is dispatched. */
477
+ const TRAIN_PASSES: readonly string[] = ["applied", "unchanged"];
478
+
479
+ /** The member links in the declaration: producer to consumer, which a promote across repositories orders by. */
480
+ async function declarationLinks(cwd: string): Promise<WorkspaceGraph["links"]> {
481
+ const declaration = readDeclaration(locateWorkspace(cwd).tree, "", { rootChant: true });
482
+ return declaration.members.flatMap((m) => m.links.map((l) => ({ consumer: m.name, producer: l.member, status: "declared" }))) as unknown as WorkspaceGraph["links"];
483
+ }
484
+
485
+ /** Dispatches with the forge's API and the member's token from the environment ({@link trainTokenEnv}). */
486
+ export const defaultTrainDispatcher: TrainDispatcher = async (member, d) => {
487
+ const { dispatchTrainMember, trainMemberTarget, trainProductOf } = await import("../control/train");
488
+ await dispatchTrainMember(trainMemberTarget(member.repo), d, { words: trainProductOf() });
489
+ };
490
+
491
+ async function defaultReadAnswers(cwd: string): Promise<ControlAppliedRecord[]> {
492
+ const { gitControlAppliedLedger, parseControlApplied } = await import("../control/applied");
493
+ return parseControlApplied(await gitControlAppliedLedger({ cwd }).read()).records;
494
+ }
495
+
496
+ /** Each run's newest line: a promote across repositories appends its run again as each member answers. */
497
+ export function latestRuns(runs: readonly WorkspaceRunRecord[]): WorkspaceRunRecord[] {
498
+ const at = new Map<string, number>();
499
+ runs.forEach((r, i) => at.set(r.id, i));
500
+ return runs.filter((r, i) => at.get(r.id) === i);
501
+ }
502
+
503
+ /**
504
+ * Promote a train of `repo` members (#5119) from the control repo, one
505
+ * member repository at a time, producers first. Each call does one step and
506
+ * returns:
507
+ *
508
+ * - With no promote of the train in flight, it starts one: a workspace run
509
+ * record citing the train, and a dispatch into the first member
510
+ * repository, whose step is `dispatched`. `--continue` starts nothing.
511
+ * - With one in flight, `--continue` reads the control repo's apply records
512
+ * for the member it waits on. `applied` or `unchanged` passes the step
513
+ * and dispatches the next member, or ends the run `ok`. `waiting` ends it
514
+ * `gated` at the member's own gate, and `failed` or `partial` ends it
515
+ * `fail`, the step saying why. An answer for another release fails the
516
+ * step. With no answer yet nothing is written. Without `--continue` it
517
+ * refuses, naming the member it waits on.
518
+ *
519
+ * Each member keeps its own gate: no workspace gate covers members in other
520
+ * repositories, so `--gate` is refused.
521
+ */
522
+ async function promoteAcrossRepos(query: TrainPromoteQuery, train: ReadTrain, now: () => string): Promise<TrainPromoteOutcome> {
523
+ if (query.gate) return { kind: "refused", message: `release train ${train.id} pins repo members, and each keeps its own gate: a workspace gate covers members of this repository only, so drop --gate` };
524
+ const { orderTargets } = await import("./workspace-run");
525
+ const links = await (query.readLinks ?? declarationLinks)(query.cwd);
526
+ const order = orderTargets(train.members.map((m) => ({ member: m.member, op: TRAIN_REPO_STEP_OP })), links).map((t) => train.members.find((m) => m.member === t.member)!);
527
+ if (query.dryRun) return { kind: "planned", train, order: order.map((m) => m.member) };
528
+
529
+ const runs = latestRuns((await readWorkspaceRuns(query.cwd, query.env)).records).filter((r) => r.train?.id === train.id);
530
+ const inFlight = runs.filter((r) => r.status === "dispatched").at(-1) ?? null;
531
+ if (!inFlight && query.continue) return { kind: "idle", train, message: `no promote of release train ${train.id} to ${query.env} is in flight, so there is nothing to continue` };
532
+ if (inFlight && !query.continue) {
533
+ const waiting = inFlight.steps.find((s) => s.status === "dispatched")?.member ?? "a member";
534
+ return { kind: "refused", message: `promote ${inFlight.id} of release train ${train.id} is in flight and waits on ${waiting}; it continues when that member answers (chant workspace train promote ${query.env} ${train.id} --continue)` };
535
+ }
536
+
537
+ const dispatch = query.dispatch ?? defaultTrainDispatcher;
538
+ const record: WorkspaceRunRecord = inFlight
539
+ ? { ...inFlight, steps: inFlight.steps.map((s) => ({ ...s })) }
540
+ : {
541
+ version: 1,
542
+ id: `ws-${randomUUID()}`,
543
+ started: now(),
544
+ ended: now(),
545
+ status: "dispatched",
546
+ env: query.env,
547
+ gate: null,
548
+ dependentsOf: null,
549
+ steps: order.map((m) => ({ target: `${m.member}/${TRAIN_REPO_STEP_OP}`, member: m.member, op: TRAIN_REPO_STEP_OP, status: "not-run", exitCode: null, memberRun: null, repo: m.repo!.url })),
550
+ train: { id: train.id, digest: train.trainDigest },
551
+ };
552
+ const memberOf = (name: string) => train.members.find((m) => m.member === name)!;
553
+
554
+ /** Dispatch the first step not run yet, or end the run ok when none is left. */
555
+ const next = async (): Promise<void> => {
556
+ const step = record.steps.find((s) => s.status === "not-run");
557
+ if (!step) {
558
+ record.status = "ok";
559
+ return;
560
+ }
561
+ const m = memberOf(step.member);
562
+ try {
563
+ await dispatch({ name: m.member, repo: m.repo!.url }, { member: m.member, env: query.env, train: train.id, run: record.id, releaseDigest: m.releaseDigest, commit: m.commit });
564
+ step.status = "dispatched";
565
+ record.status = "dispatched";
566
+ } catch (err) {
567
+ step.status = "fail";
568
+ step.reason = `the dispatch into ${m.repo!.url} was not taken: ${err instanceof Error ? err.message : String(err)}`;
569
+ record.status = "fail";
570
+ }
571
+ };
572
+
573
+ if (!inFlight) await next();
574
+ else {
575
+ const step = record.steps.find((s) => s.status === "dispatched");
576
+ if (!step) return { kind: "idle", train, message: `promote ${record.id} of release train ${train.id} waits on no member` };
577
+ const answers = (await (query.readAnswers ?? defaultReadAnswers)(query.cwd)).filter((a) => a.member === step.member && a.train?.train === train.id && a.train.run === record.id);
578
+ const answer = answers.sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).at(-1);
579
+ if (!answer) return { kind: "waiting", train, record: inFlight!, member: step.member };
580
+ const m = memberOf(step.member);
581
+ step.outcome = answer.outcome;
582
+ if (answer.train!.releaseDigest !== m.releaseDigest || answer.train!.env !== query.env) {
583
+ step.status = "fail";
584
+ step.reason = `${step.member} answered for release ${answer.train!.releaseDigest} in ${answer.train!.env}, and the train pins ${m.releaseDigest} in ${query.env}`;
585
+ record.status = "fail";
586
+ } else if (TRAIN_PASSES.includes(answer.outcome)) {
587
+ step.status = "ok";
588
+ await next();
589
+ } else {
590
+ step.status = answer.outcome === "waiting" ? "gated" : "fail";
591
+ step.reason = answer.outcome === "waiting" ? `${step.member}'s run waits at its own gate; approve it there, then promote the train again` : `${step.member}'s run ended ${answer.outcome} at ${answer.sha.slice(0, 12)}`;
592
+ record.status = answer.outcome === "waiting" ? "gated" : "fail";
593
+ }
594
+ }
595
+ record.ended = now();
596
+ let ledgerError: string | null = null;
597
+ try {
598
+ await appendWorkspaceRun(query.cwd, record);
599
+ } catch (err) {
600
+ ledgerError = err instanceof Error ? err.message : String(err);
601
+ }
602
+ return { kind: "ran", train, record, pending: null, approved: null, ledgerError };
603
+ }
604
+
605
+ const USAGE =
606
+ "chant workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json] | chant workspace train list <env> [--json] | chant workspace train promote <env> [<train id|digest>] [--gate <name>] [--continue] [--dry-run] [--json]";
607
+
608
+ /** The workspace runs that promoted each train, as `train list --json` gives them (#4037). */
609
+ export interface TrainPromotion {
610
+ run: string;
611
+ started: string;
612
+ ended: string;
613
+ status: WorkspaceRunRecord["status"];
614
+ gate: string | null;
615
+ /** Each member's step; a step in another repository (#5119) names it, with the member's answer and why a step did not pass. */
616
+ members: Array<{ member: string; status: WorkspaceRunStep["status"]; memberRun: string | null; repo?: string; outcome?: string; reason?: string }>;
617
+ }
618
+
619
+ /** Each train with the runs that promoted it, oldest first. */
620
+ export function trainsWithPromotions(trains: readonly ReadTrain[], runs: readonly WorkspaceRunRecord[]): Array<ReadTrain & { promotions: TrainPromotion[] }> {
621
+ const latest = latestRuns(runs);
622
+ return trains.map((t) => ({
623
+ ...t,
624
+ promotions: latest
625
+ .filter((r) => r.train?.id === t.id)
626
+ .map((r) => ({
627
+ run: r.id,
628
+ started: r.started,
629
+ ended: r.ended,
630
+ status: r.status,
631
+ gate: r.gate,
632
+ members: r.steps.map((s) => ({ member: s.member, status: s.status, memberRun: s.memberRun, ...(s.repo !== undefined ? { repo: s.repo } : {}), ...(s.outcome !== undefined ? { outcome: s.outcome } : {}), ...(s.reason !== undefined ? { reason: s.reason } : {}) })),
633
+ })),
634
+ }));
635
+ }
108
636
 
109
637
  export async function runWorkspaceTrain(ctx: CommandContext): Promise<number> {
110
638
  const words = ctx.args.positionals ?? [];
111
639
  const rest = words[0] === "train" ? words.slice(1) : words;
640
+ if (rest[0] === "promote") return runTrainPromote(ctx, rest.slice(1));
112
641
  const listing = rest[0] === "list";
113
642
  const env = listing ? rest[1] : rest[0];
114
643
  if (!env) {
@@ -120,9 +649,15 @@ export async function runWorkspaceTrain(ctx: CommandContext): Promise<number> {
120
649
  if (listing) {
121
650
  const root = locateWorkspace(cwd).rootOnDisk;
122
651
  const { records } = await readReleaseTrains(root, env);
123
- if (ctx.args.json) console.log(JSON.stringify({ env, trains: records }, null, 2));
124
- else if (records.length === 0) console.log(`No release train recorded for ${env}.`);
125
- else for (const t of records) console.log(`${t.timestamp} ${t.id} ${t.members.map((m) => `${m.member}@${m.label ?? m.releaseDigest.slice(0, 19)}`).join(" ")}`);
652
+ const listed = trainsWithPromotions(records, (await readWorkspaceRuns(root, env)).records);
653
+ if (ctx.args.json) console.log(JSON.stringify({ env, trains: listed }, null, 2));
654
+ else if (listed.length === 0) console.log(`No release train recorded for ${env}.`);
655
+ else {
656
+ for (const t of listed) {
657
+ const last = t.promotions.at(-1);
658
+ console.log(`${t.timestamp} ${t.id} ${t.trainDigest} ${t.members.map((m) => `${m.member}@${m.label ?? m.releaseDigest.slice(0, 19)}`).join(" ")}${last ? ` promoted: ${last.status}` : ""}`);
659
+ }
660
+ }
126
661
  return 0;
127
662
  }
128
663
  const pins = new Map<string, string>();
@@ -137,17 +672,17 @@ export async function runWorkspaceTrain(ctx: CommandContext): Promise<number> {
137
672
  const root = locateWorkspace(cwd).rootOnDisk;
138
673
  const picked = pickTrain(await readMemberReleases(root), pins);
139
674
  if ("problems" in picked) {
140
- console.error(formatError({ message: `no release train for ${env}: every chant member needs a release`, hint: USAGE }));
675
+ console.error(formatError({ message: `no release train for ${env}: every chant and repo member needs a release`, hint: USAGE }));
141
676
  for (const p of picked.problems) console.error(` ${p}`);
142
677
  return 1;
143
678
  }
144
679
  const actor = ctx.args.actor ?? actorFromEnv();
145
- const record: ReleaseTrainRecord = { version: 1, id: `train-${randomUUID()}`, env, timestamp: new Date().toISOString(), actor, members: picked.members };
680
+ const record: ReleaseTrainRecord = { version: 1, id: `train-${randomUUID()}`, env, timestamp: new Date().toISOString(), actor, members: picked.members, trainDigest: trainDigest(picked.members) };
146
681
  if (!ctx.args.dryRun) await appendReleaseTrain(root, record);
147
682
  if (ctx.args.json) console.log(JSON.stringify({ ...record, written: !ctx.args.dryRun }, null, 2));
148
683
  else {
149
- console.log(`${ctx.args.dryRun ? "Would record" : "Recorded"} release train ${record.id} for ${env}:`);
150
- for (const m of record.members) console.log(` ${m.member.padEnd(24)} ${m.label ?? "(no label)"} ${m.releaseDigest} ${m.commit.slice(0, 12)}`);
684
+ console.log(`${ctx.args.dryRun ? "Would record" : "Recorded"} release train ${record.id} for ${env}, digest ${record.trainDigest}:`);
685
+ for (const m of record.members) console.log(` ${m.member.padEnd(24)} ${m.label ?? "(no label)"} ${m.releaseDigest} ${m.commit.slice(0, 12)}${m.repo ? ` ${m.repo.url}` : ""}`);
151
686
  }
152
687
  return 0;
153
688
  } catch (err) {
@@ -156,3 +691,83 @@ export async function runWorkspaceTrain(ctx: CommandContext): Promise<number> {
156
691
  return 1;
157
692
  }
158
693
  }
694
+
695
+ async function runTrainPromote(ctx: CommandContext, words: string[]): Promise<number> {
696
+ const [env, ref] = words;
697
+ if (!env) {
698
+ console.error(formatError({ message: "chant workspace train promote needs an environment", hint: USAGE }));
699
+ return 1;
700
+ }
701
+ const cwd = resolve(".");
702
+ // The root's chant promotes the train (ws-021), as it runs a workspace run.
703
+ const { handToRootChant } = await import("./which-chant");
704
+ const handed = await handToRootChant(cwd, undefined);
705
+ if (handed !== undefined) return handed;
706
+ const { args } = ctx;
707
+ let outcome: TrainPromoteOutcome;
708
+ try {
709
+ outcome = await promoteTrain({
710
+ cwd: locateWorkspace(cwd).rootOnDisk,
711
+ env,
712
+ ...(ref !== undefined ? { train: ref } : {}),
713
+ ...(args.gate !== undefined ? { gate: args.gate } : {}),
714
+ ...(args.dryRun ? { dryRun: true } : {}),
715
+ ...(args.continueTrain ? { continue: true } : {}),
716
+ onOutput: args.json
717
+ ? undefined
718
+ : (target, r) => {
719
+ process.stderr.write(`── ${target} (exit ${r.exitCode})\n`);
720
+ if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
721
+ },
722
+ });
723
+ } catch (err) {
724
+ if (!(err instanceof WorkspaceReadError)) throw err;
725
+ console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: USAGE }));
726
+ return 1;
727
+ }
728
+ if (outcome.kind === "refused") {
729
+ if (args.json) console.log(JSON.stringify({ status: "refused", message: outcome.message }, null, 2));
730
+ console.error(formatError({ message: outcome.message, hint: USAGE }));
731
+ return 1;
732
+ }
733
+ if (outcome.kind === "idle") {
734
+ if (args.json) console.log(JSON.stringify({ status: "idle", train: outcome.train.id, message: outcome.message }, null, 2));
735
+ else console.log(outcome.message);
736
+ return 0;
737
+ }
738
+ if (outcome.kind === "waiting") {
739
+ if (args.json) console.log(JSON.stringify({ ...outcome.record, waitingOn: outcome.member }, null, 2));
740
+ else console.log(`release train ${outcome.train.id} to ${env}: promote ${outcome.record.id} waits on ${outcome.member}, which has not answered yet`);
741
+ return 0;
742
+ }
743
+ if (outcome.kind === "planned") {
744
+ if (args.json) console.log(JSON.stringify({ status: "planned", train: outcome.train, order: outcome.order }, null, 2));
745
+ else {
746
+ console.log(`chant workspace train promote would promote ${outcome.train.id} (${outcome.train.trainDigest}) to ${env}, in order:`);
747
+ for (const member of outcome.order) {
748
+ const m = outcome.train.members.find((x) => x.member === member)!;
749
+ console.log(` ${member.padEnd(24)} ${m.label ?? "(no label)"} ${m.releaseDigest}`);
750
+ }
751
+ }
752
+ return 0;
753
+ }
754
+ const { record, pending, approved, ledgerError } = outcome;
755
+ if (args.json) console.log(JSON.stringify({ ...record, pending, approved, ledgerError }, null, 2));
756
+ else {
757
+ console.log(`release train ${outcome.train.id} to ${env}: ${record.status}${approved ? ` (workspace gate "${record.gate}" approved ${approved})` : ""}`);
758
+ for (const s of record.steps) console.log(` ${s.member.padEnd(24)} ${s.status}${s.memberRun ? ` (run ${s.memberRun})` : ""}${s.gate ? ` gate ${s.gate.name}` : ""}${s.repo ? ` ${s.repo}` : ""}${s.reason ? ` ${s.reason}` : ""}`);
759
+ if (record.status === "dispatched") {
760
+ const at = record.steps.find((s) => s.status === "dispatched");
761
+ if (at) console.log(`Dispatched ${at.member}. The control repo continues the train when it answers: chant workspace train promote ${env} ${outcome.train.id} --continue`);
762
+ }
763
+ if (record.status === "gated" && pending) {
764
+ console.log(`Workspace gate "${pending.gate}" is pending over ${pending.covers.length} release gate(s) of ${new Set(pending.covers.map((c) => c.member)).size} member(s), digest ${pending.digest}. Nothing was deployed.`);
765
+ console.log(` Approve: chant workspace run approve ${pending.gate} --plan ${pending.digest}`);
766
+ console.log(` Then run the same chant workspace train promote again. The approval stands in only for members that set acceptWorkspaceGates: true at base.`);
767
+ }
768
+ if (ledgerError) console.error(formatError({ message: `the workspace run record was not written: ${ledgerError}` }));
769
+ }
770
+ if (record.status === "fail") return 1;
771
+ if (record.status === "gated") return CHANT_EXIT.waiting;
772
+ return 0;
773
+ }