@intentius/chant 0.124.63 → 0.124.65

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 (185) hide show
  1. package/dist/cli/handlers/approve.d.ts +8 -0
  2. package/dist/cli/handlers/approve.d.ts.map +1 -1
  3. package/dist/cli/handlers/approve.js +27 -4
  4. package/dist/cli/handlers/pr.d.ts.map +1 -1
  5. package/dist/cli/handlers/pr.js +2 -1
  6. package/dist/cli/handlers/release.d.ts +6 -4
  7. package/dist/cli/handlers/release.d.ts.map +1 -1
  8. package/dist/cli/handlers/release.js +101 -16
  9. package/dist/cli/handlers/run.d.ts +30 -1
  10. package/dist/cli/handlers/run.d.ts.map +1 -1
  11. package/dist/cli/handlers/run.js +108 -7
  12. package/dist/cli/main.d.ts.map +1 -1
  13. package/dist/cli/main.js +34 -7
  14. package/dist/cli/parse-args.d.ts.map +1 -1
  15. package/dist/cli/parse-args.js +19 -0
  16. package/dist/cli/registry.d.ts +10 -2
  17. package/dist/cli/registry.d.ts.map +1 -1
  18. package/dist/components/cli-support.d.ts +19 -1
  19. package/dist/components/cli-support.d.ts.map +1 -1
  20. package/dist/components/cli-support.js +11 -3
  21. package/dist/components/component.d.ts +19 -0
  22. package/dist/components/component.d.ts.map +1 -1
  23. package/dist/components/component.schema.json +17 -0
  24. package/dist/components/index.d.ts +1 -1
  25. package/dist/components/index.d.ts.map +1 -1
  26. package/dist/components/release-run.d.ts +48 -0
  27. package/dist/components/release-run.d.ts.map +1 -0
  28. package/dist/components/release-run.js +166 -0
  29. package/dist/components/starter-plugin.d.ts +1 -0
  30. package/dist/components/starter-plugin.d.ts.map +1 -1
  31. package/dist/components/starter-plugin.js +5 -1
  32. package/dist/components/unchanged-inputs.d.ts +81 -0
  33. package/dist/components/unchanged-inputs.d.ts.map +1 -0
  34. package/dist/components/unchanged-inputs.js +122 -0
  35. package/dist/components/verbs/index.d.ts +1 -0
  36. package/dist/components/verbs/index.d.ts.map +1 -1
  37. package/dist/components/verbs/index.js +1 -0
  38. package/dist/components/verbs/release-image.d.ts +36 -0
  39. package/dist/components/verbs/release-image.d.ts.map +1 -0
  40. package/dist/components/verbs/release-image.js +33 -0
  41. package/dist/config.d.ts +18 -0
  42. package/dist/config.d.ts.map +1 -1
  43. package/dist/config.js +1 -0
  44. package/dist/gate-statement.schema.json +4 -2
  45. package/dist/lifecycle/delivery-metrics.d.ts.map +1 -1
  46. package/dist/lifecycle/delivery-metrics.js +4 -2
  47. package/dist/lifecycle/gate-ledger.d.ts +11 -2
  48. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  49. package/dist/lifecycle/gate-ledger.js +6 -0
  50. package/dist/lifecycle/gate-seal.d.ts +20 -4
  51. package/dist/lifecycle/gate-seal.d.ts.map +1 -1
  52. package/dist/lifecycle/gate-seal.js +18 -5
  53. package/dist/lifecycle/gate-statement.d.ts +27 -2
  54. package/dist/lifecycle/gate-statement.d.ts.map +1 -1
  55. package/dist/lifecycle/gate-statement.js +37 -2
  56. package/dist/lifecycle/git.d.ts.map +1 -1
  57. package/dist/lifecycle/git.js +6 -1
  58. package/dist/lifecycle/ledger-read.js +1 -1
  59. package/dist/lifecycle/plan-stale.d.ts.map +1 -1
  60. package/dist/lifecycle/plan-stale.js +1 -2
  61. package/dist/lifecycle/publish-declaration.d.ts +20 -0
  62. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  63. package/dist/lifecycle/publish-declaration.js +24 -1
  64. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  65. package/dist/lifecycle/publish-forge.js +1 -2
  66. package/dist/lifecycle/publish-git-ssh.d.ts +82 -0
  67. package/dist/lifecycle/publish-git-ssh.d.ts.map +1 -0
  68. package/dist/lifecycle/publish-git-ssh.js +180 -0
  69. package/dist/lifecycle/publish-homebrew.d.ts +11 -0
  70. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -1
  71. package/dist/lifecycle/publish-homebrew.js +96 -5
  72. package/dist/lifecycle/publish-marketplace.d.ts +36 -2
  73. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -1
  74. package/dist/lifecycle/publish-marketplace.js +173 -30
  75. package/dist/lifecycle/publish-tauri.d.ts.map +1 -1
  76. package/dist/lifecycle/publish-tauri.js +1 -2
  77. package/dist/lifecycle/query.d.ts +2 -2
  78. package/dist/lifecycle/query.d.ts.map +1 -1
  79. package/dist/lifecycle/query.js +3 -3
  80. package/dist/lifecycle/release-cut.d.ts +82 -6
  81. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  82. package/dist/lifecycle/release-cut.js +209 -20
  83. package/dist/lifecycle/release-ledger.d.ts +11 -0
  84. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  85. package/dist/lifecycle/release-publish.d.ts +13 -0
  86. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  87. package/dist/lifecycle/release-publish.js +5 -0
  88. package/dist/lifecycle/release-revocation.d.ts +4 -3
  89. package/dist/lifecycle/release-revocation.d.ts.map +1 -1
  90. package/dist/lifecycle/release-revocation.js +5 -4
  91. package/dist/lifecycle/release-store.d.ts +49 -3
  92. package/dist/lifecycle/release-store.d.ts.map +1 -1
  93. package/dist/lifecycle/release-store.js +22 -3
  94. package/dist/op/gate.d.ts +1 -1
  95. package/dist/op/gate.d.ts.map +1 -1
  96. package/dist/op/gate.js +2 -1
  97. package/dist/op/op-waves-run.js +5 -3
  98. package/dist/pr-forge.d.ts.map +1 -1
  99. package/dist/pr-forge.js +26 -6
  100. package/dist/release-floors.d.ts +1 -1
  101. package/dist/release-floors.js +1 -1
  102. package/dist/wave-runtime.mjs +284 -283
  103. package/dist/workspace/ci-green.d.ts.map +1 -1
  104. package/dist/workspace/ci-green.js +1 -2
  105. package/dist/workspace/ci-quarantine-report.d.ts.map +1 -1
  106. package/dist/workspace/ci-quarantine-report.js +1 -2
  107. package/dist/workspace/ci-quarantine.d.ts.map +1 -1
  108. package/dist/workspace/ci-quarantine.js +1 -2
  109. package/dist/workspace/delivery-metrics.schema.json +1 -1
  110. package/dist/workspace/intent.d.ts.map +1 -1
  111. package/dist/workspace/intent.js +1 -2
  112. package/dist/workspace/release-candidates.d.ts +9 -1
  113. package/dist/workspace/release-candidates.d.ts.map +1 -1
  114. package/dist/workspace/release-candidates.js +16 -5
  115. package/dist/workspace/release-candidates.schema.json +7 -0
  116. package/dist/workspace/releases.schema.json +54 -2
  117. package/package.json +1 -1
  118. package/src/cli/handlers/approve-external-signature.test.ts +105 -3
  119. package/src/cli/handlers/approve.ts +34 -4
  120. package/src/cli/handlers/pr.ts +2 -1
  121. package/src/cli/handlers/release.ts +91 -16
  122. package/src/cli/handlers/run-unchanged.e2e.test.ts +112 -0
  123. package/src/cli/handlers/run.ts +117 -7
  124. package/src/cli/main.ts +34 -7
  125. package/src/cli/parse-args.ts +15 -0
  126. package/src/cli/registry.ts +10 -2
  127. package/src/components/cli-support.test.ts +53 -0
  128. package/src/components/cli-support.ts +26 -4
  129. package/src/components/component.schema.json +17 -0
  130. package/src/components/component.ts +20 -0
  131. package/src/components/index.ts +1 -0
  132. package/src/components/registry.test.ts +1 -1
  133. package/src/components/release-run.test.ts +127 -0
  134. package/src/components/release-run.ts +188 -0
  135. package/src/components/starter-plugin.ts +5 -0
  136. package/src/components/unchanged-inputs.test.ts +98 -0
  137. package/src/components/unchanged-inputs.ts +151 -0
  138. package/src/components/verbs/index.ts +1 -0
  139. package/src/components/verbs/release-image.ts +52 -0
  140. package/src/config.ts +8 -0
  141. package/src/gate-statement.schema.json +4 -2
  142. package/src/lifecycle/delivery-metrics.ts +4 -2
  143. package/src/lifecycle/gate-ledger.ts +17 -2
  144. package/src/lifecycle/gate-seal.ts +24 -6
  145. package/src/lifecycle/gate-statement.ts +40 -4
  146. package/src/lifecycle/git.test.ts +15 -0
  147. package/src/lifecycle/git.ts +5 -1
  148. package/src/lifecycle/ledger-read.ts +1 -1
  149. package/src/lifecycle/plan-stale.test.ts +3 -4
  150. package/src/lifecycle/plan-stale.ts +1 -2
  151. package/src/lifecycle/publish-declaration.ts +24 -1
  152. package/src/lifecycle/publish-forge.ts +1 -2
  153. package/src/lifecycle/publish-git-ssh.ts +202 -0
  154. package/src/lifecycle/publish-homebrew.test.ts +181 -2
  155. package/src/lifecycle/publish-homebrew.ts +101 -6
  156. package/src/lifecycle/publish-marketplace.test.ts +158 -6
  157. package/src/lifecycle/publish-marketplace.ts +192 -31
  158. package/src/lifecycle/publish-resume.test.ts +40 -0
  159. package/src/lifecycle/publish-tauri.ts +1 -2
  160. package/src/lifecycle/query.ts +3 -3
  161. package/src/lifecycle/release-cut-lane.test.ts +195 -0
  162. package/src/lifecycle/release-cut-override.test.ts +225 -0
  163. package/src/lifecycle/release-cut.test.ts +45 -0
  164. package/src/lifecycle/release-cut.ts +262 -21
  165. package/src/lifecycle/release-ledger.ts +11 -0
  166. package/src/lifecycle/release-publish.ts +18 -0
  167. package/src/lifecycle/release-revocation.ts +5 -4
  168. package/src/lifecycle/release-store.ts +73 -5
  169. package/src/op/gate.ts +2 -1
  170. package/src/op/op-waves-run.ts +4 -2
  171. package/src/pr-forge.ts +25 -6
  172. package/src/pr-requires.test.ts +9 -0
  173. package/src/release-floors.ts +1 -1
  174. package/src/workspace/ci-green.ts +1 -2
  175. package/src/workspace/ci-quarantine-report.test.ts +2 -3
  176. package/src/workspace/ci-quarantine-report.ts +1 -2
  177. package/src/workspace/ci-quarantine.test.ts +2 -3
  178. package/src/workspace/ci-quarantine.ts +1 -2
  179. package/src/workspace/delivery-metrics.schema.json +1 -1
  180. package/src/workspace/delivery-metrics.test.ts +8 -0
  181. package/src/workspace/intent.ts +1 -2
  182. package/src/workspace/release-candidates.schema.json +7 -0
  183. package/src/workspace/release-candidates.ts +19 -5
  184. package/src/workspace/releases.schema.json +54 -2
  185. package/src/workspace/trust/gate-seal.test.ts +44 -0
@@ -28,7 +28,7 @@ import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git
28
28
  import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
29
29
  import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
30
30
  import { checkGateSignature, gateSealPayload, gateSealVersion, WEBAUTHN_SEAL_KIND, type SealedGateApproval } from "../../lifecycle/gate-seal";
31
- import { gateStatement, readExternalSignature, type GateStatement } from "../../lifecycle/gate-statement";
31
+ import { gateBindingProblem, gateStatement, readExternalSignature, type GateStatement } from "../../lifecycle/gate-statement";
32
32
  import type { GateApprovalSeal } from "../../lifecycle/gate-ledger";
33
33
  import type { TrustPolicy } from "../../workspace/trust/policy";
34
34
  import { readFileSync } from "node:fs";
@@ -176,6 +176,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
176
176
  ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
177
177
  ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
178
178
  ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
179
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
179
180
  allowSameOrigin: ctx.args.allowSameOrigin,
180
181
  };
181
182
  const statement = await gateApprovalStatement(opName, gate, shared);
@@ -187,6 +188,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
187
188
  (statement.relayedBy !== null ? ` --relayed-by ${statement.relayedBy}` : "") +
188
189
  (statement.planDigest !== null ? ` --plan ${statement.planDigest}` : "") +
189
190
  (statement.environment !== null ? ` --env ${statement.environment}` : "") +
191
+ (statement.binding !== null ? ` --binding ${shellQuote(statement.binding)}` : "") +
190
192
  ` --at ${statement.timestamp} --signature <file>`,
191
193
  ));
192
194
  return 0;
@@ -218,6 +220,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
218
220
  ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
219
221
  ...(ctx.args.signature !== undefined ? { signature: ctx.args.signature } : {}),
220
222
  ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
223
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
221
224
  ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
222
225
  });
223
226
  if (!outcome.ok) return 1;
@@ -313,6 +316,14 @@ export interface GateApprovalOptions {
313
316
  signature?: string;
314
317
  /** `--at <timestamp>` (#4646): the statement's time, which `--statement` fixes and `--signature` records. */
315
318
  at?: string;
319
+ /**
320
+ * `--binding <text>` (#4697): a line the relay sets for the approver's
321
+ * signature to cover as well, such as a platform's deploy id and an
322
+ * expiry. Signed last (seal version 3) and recorded as `binding`. It goes
323
+ * with `--statement`, `--signature` or `--sign`, and must be the same on
324
+ * `--statement` and `--signature`.
325
+ */
326
+ binding?: string;
316
327
  /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
317
328
  cwd?: string;
318
329
  /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
@@ -643,6 +654,13 @@ async function approveGate(
643
654
  `Pass the timestamp \`chant approve ${opName} ${gate} --statement\` printed.`,
644
655
  );
645
656
  }
657
+ if (opts.binding !== undefined) {
658
+ if (!statementOnly && opts.signature === undefined && opts.sign === undefined) {
659
+ return refuse("--binding is a line the approver's signature covers, so it goes with --statement, --signature or --sign");
660
+ }
661
+ const problem = gateBindingProblem(opts.binding);
662
+ if (problem !== null) return refuse(`--binding takes one line of printable text, and ${problem}`);
663
+ }
646
664
  let timestamp = new Date().toISOString();
647
665
  if (opts.at !== undefined) {
648
666
  const at = Date.parse(opts.at);
@@ -667,6 +685,7 @@ async function approveGate(
667
685
  ...(relayedBy ? { relayedBy } : {}),
668
686
  timestamp,
669
687
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
688
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
670
689
  };
671
690
  if (statementOnly) {
672
691
  const { CHANT_VERSION } = await import("../../chant-version");
@@ -697,8 +716,9 @@ async function approveGate(
697
716
  try {
698
717
  const key = resolveSigningKey(opts.sign, cwd);
699
718
  try {
700
- // #3947: a seal over a checkpoint digest is seal version 2.
701
- seal = { ...sealGateApproval(key.file, sealed), ...(gateSealVersion(sealed) === 2 ? { version: 2 as const } : {}) };
719
+ // #3947, #4697: a seal over a checkpoint digest is seal version 2, and one over a binding 3.
720
+ const version = gateSealVersion(sealed);
721
+ seal = { ...sealGateApproval(key.file, sealed), ...(version !== 1 ? { version } : {}) };
702
722
  } finally {
703
723
  key.cleanup();
704
724
  }
@@ -718,6 +738,7 @@ async function approveGate(
718
738
  ...(relayedBy ? { relayedBy } : {}),
719
739
  timestamp,
720
740
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
741
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
721
742
  seal,
722
743
  });
723
744
  if (why !== null) {
@@ -748,6 +769,7 @@ async function approveGate(
748
769
  ...(relayedBy ? { relayedBy } : {}),
749
770
  timestamp,
750
771
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
772
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
751
773
  ...(seal ? { seal } : {}),
752
774
  }).roles;
753
775
  let policyDecision: GatePolicyDecision | undefined;
@@ -797,6 +819,7 @@ async function approveGate(
797
819
  ...(url ? { url } : {}),
798
820
  ...(planDigest !== undefined ? { planDigest } : {}),
799
821
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
822
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
800
823
  ...(environment !== undefined ? { environment } : {}),
801
824
  ...(releaseDigest !== undefined ? { releaseDigest } : {}),
802
825
  ...(changeSet !== undefined ? { changeSet } : {}),
@@ -819,6 +842,7 @@ async function approveGate(
819
842
  (record.seal ? `, signed with ${record.seal.kind === WEBAUTHN_SEAL_KIND ? "passkey " : ""}${record.seal.key}` : "") +
820
843
  push.suffix,
821
844
  ));
845
+ if (record.binding !== undefined) console.error(formatInfo(`The signature also binds ${JSON.stringify(record.binding)} (--binding).`));
822
846
  if (record.planDigest) {
823
847
  console.error(formatInfo(
824
848
  `This approves the plan ${record.planDigest}` +
@@ -891,7 +915,13 @@ function externalSeal(
891
915
  : `the ${sig.kind === "ssh" ? "ssh signature" : "passkey's assertion"} does not verify for ${sealed.resolvedBy} over this approval's statement: ${r.reason}`,
892
916
  };
893
917
  }
894
- return { seal: { ...candidate, key: r.key, ...(gateSealVersion(sealed) === 2 ? { version: 2 as const } : {}) } };
918
+ const version = gateSealVersion(sealed);
919
+ return { seal: { ...candidate, key: r.key, ...(version !== 1 ? { version } : {}) } };
920
+ }
921
+
922
+ /** `text` quoted for a POSIX shell, for a command line a hint prints. */
923
+ function shellQuote(text: string): string {
924
+ return /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
895
925
  }
896
926
 
897
927
  /**
@@ -1496,8 +1496,9 @@ async function beforeMergeChecks(ctx: CommandContext): Promise<PrBeforeMerge | n
1496
1496
  );
1497
1497
  }
1498
1498
  // The apply's own statuses never hold it back: chant ci run's, and the report's.
1499
+ // Nor does the plan's: a policy denial fails it, and the denial is only recorded when the apply judges it (plywood#66).
1499
1500
  // #4550: under a product's words its own prefix too.
1500
- const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member)])];
1501
+ const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member), prStatusContext("plan"), `${prStatusContext("plan")}/`])];
1501
1502
  // ws-106 gives the declaration no way to leave a check out, so with no --requires all four are asked (#4336, #4607).
1502
1503
  const requires = await checkPrRequires(forge, args.pr, head, { ignore, ...(only ? { only: only.checks } : {}) });
1503
1504
  for (const r of requires) console.error(formatInfo(`${r.name}: ${r.passed ? "passed" : r.pending ? "pending" : "unmet"}, ${r.reason}`));
@@ -1,11 +1,13 @@
1
1
  /**
2
2
  * `chant release` (#4026, ws-104): the release is what graduates.
3
3
  *
4
- * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
4
+ * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--lane <name>] [--json]
5
5
  * a dry run of a cut of this member from the checkout's HEAD, which must be
6
- * clean, on trunk and pushed, and green (#4027); `--yes` cuts, records,
6
+ * clean, on trunk and pushed, and green (#4027), or green in a lane with
7
+ * `--lane` or `release.lane` (#4692); `--yes` cuts, records,
7
8
  * and tags the commit `release/<label>` locally;
8
- * --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
9
+ * --sign signs the cut with the actor's ssh key (#4031); `--override-green`
10
+ * cuts a commit that is not green under a person's override (#4693); `--src`, `-o` and
9
11
  * `--lexicon` shape the build of a project with no components (#4046)
10
12
  * release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json]
11
13
  * publish a cut release (#4027) to the targets release.publish declares
@@ -17,7 +19,7 @@
17
19
  * release verify <label|digest> [--json]
18
20
  * check the release's signature offline against .chant/allowed_signers
19
21
  * at the release's commit (#4049)
20
- * release candidates [--env <env>] [--forge-issues] [--json]
22
+ * release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json]
21
23
  * the green commits of trunk a release can be cut from, each with what it
22
24
  * would ship, and what each environment runs (#4168 4.2)
23
25
  * release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json]
@@ -47,7 +49,7 @@ import { parseParamFlags } from "../build-params-cli";
47
49
  import type { CommandContext } from "../registry";
48
50
 
49
51
  const USAGE =
50
- "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--forge-issues] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
52
+ "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--image <component>=<repository>@sha256:<hex>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--lane <name>] [--override-green] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
51
53
 
52
54
  /** The build inputs `release cut` and `release compile` share. */
53
55
  function compileInputs(
@@ -94,6 +96,23 @@ export function sameWithYes(argv: readonly string[]): string {
94
96
  return ["chant", ...argv.filter((a) => a !== "--json" && a !== "--yes"), "--yes"].map(quote).join(" ");
95
97
  }
96
98
 
99
+ /**
100
+ * The green lane a cut or a candidates read checks (#4692): `--lane`, else
101
+ * `release.lane` in the member's chant.config.ts at `cwd`, else none. A
102
+ * config that can't be loaded is warned about and read as naming none, so the
103
+ * full green tag is checked.
104
+ */
105
+ async function laneOf(ctx: CommandContext, cwd: string): Promise<string | undefined> {
106
+ if (ctx.args.lane !== undefined) return ctx.args.lane;
107
+ try {
108
+ const { loadChantConfig } = await import("../../config");
109
+ return (await loadChantConfig(cwd)).config.release?.lane;
110
+ } catch (err) {
111
+ if (!ctx.args.json) console.error(formatWarning({ message: `release.lane was not read, so the full green tag is checked: ${err instanceof Error ? err.message : String(err)}` }));
112
+ return undefined;
113
+ }
114
+ }
115
+
97
116
  function describeActorSource(source: import("../../lifecycle/release-workstation").ActorSource): string {
98
117
  switch (source) {
99
118
  case "flag":
@@ -130,6 +149,14 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
130
149
  return 1;
131
150
  }
132
151
  const label = positional ?? args.label ?? null;
152
+ // #4693: the reason is the override's, written by the person who overrides.
153
+ if (args.reason !== undefined) {
154
+ console.error(formatError({
155
+ message: "release cut takes no --reason: an override's reason is on the override itself",
156
+ hint: "Cut with --override-green: it names the chant approve policy-override command that records the override and its reason.",
157
+ }));
158
+ return 1;
159
+ }
133
160
  const dryRun = args.yes !== true;
134
161
  const cwd = resolve(".");
135
162
  const { spawnTargetCompiler, ReleaseCompileError } = await import("../../components/release-compile");
@@ -222,10 +249,25 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
222
249
  const tag = label !== null && commit !== null && top ? { name: ws.releaseTagName(member, label), state: ws.checkReleaseTag(top, ws.releaseTagName(member, label), commit) } : null;
223
250
  const ci = resolveCiRun(process.env);
224
251
  const params = parseParamFlags(args.param);
252
+ // #4694: images built elsewhere, handed to the cut by digest, one per component.
253
+ const images: Record<string, string> = {};
254
+ for (const value of args.images ?? []) {
255
+ const eq = value.indexOf("=");
256
+ const component = eq > 0 ? value.slice(0, eq) : "";
257
+ if (!component || eq === value.length - 1) {
258
+ return fail("release-image-invalid", `--image ${value}: name the component and the image, as --image <component>=<repository>@sha256:<hex>`);
259
+ }
260
+ if (images[component] !== undefined && images[component] !== value.slice(eq + 1)) {
261
+ return fail("release-image-invalid", `--image names two images for "${component}"; a release records one image per component`);
262
+ }
263
+ images[component] = value.slice(eq + 1);
264
+ }
225
265
  // --at: the cut reads, compiles and builds the commit's tree, not the checkout's.
226
266
  if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
227
267
  const cutCwd = checkout?.memberDir ?? cwd;
228
268
  const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
269
+ // #4692: the lane is the commit's own config's under --at.
270
+ const lane = await laneOf(ctx, cutCwd);
229
271
  const request = {
230
272
  cwd: cutCwd,
231
273
  compiler,
@@ -234,6 +276,9 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
234
276
  ...(args.sign !== undefined ? { sign: args.sign } : {}),
235
277
  ...(composed ? { composed } : {}),
236
278
  ...(args.channel ? { channel: args.channel } : {}),
279
+ ...(lane !== undefined ? { lane } : {}),
280
+ ...(args.overrideGreen ? { overrideGreen: true } : {}),
281
+ ...(Object.keys(images).length > 0 ? { images } : {}),
237
282
  };
238
283
 
239
284
  if (dryRun) {
@@ -274,13 +319,19 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
274
319
  return 0;
275
320
  }
276
321
  const name = plan.label ? formatBold(plan.label) : "an unlabelled release";
322
+ const greenIn = plan.override
323
+ ? `not green: no ${plan.override.tag.slice(0, plan.override.tag.lastIndexOf("/"))} tag`
324
+ : plan.lane !== null
325
+ ? `green in lane ${plan.lane}`
326
+ : "green";
277
327
  const where = composed
278
- ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), green)`
328
+ ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), ${greenIn})`
279
329
  : trunk
280
- ? ` (on ${trunk.remote}/${trunk.branch}, green)`
330
+ ? ` (on ${trunk.remote}/${trunk.branch}, ${greenIn})`
281
331
  : "";
282
332
  console.log(`Dry run: cut ${name} from commit ${plan.commit.slice(0, 12)}${where}`);
283
333
  if (args.channel) console.log(` channel ${args.channel}: a publish moves ${args.channel}, not latest`);
334
+ if (plan.override) console.log(` under the override by ${plan.override.by} at ${plan.override.at}${plan.override.sealed ? ", sealed" : ""}: ${plan.override.reason}; the cut spends it`);
284
335
  if (plan.alreadyCut) console.log(` already cut as ${plan.alreadyCut}: the cut would record nothing new`);
285
336
  console.log(` actor ${actor} (from ${describeActorSource(who.source)})`);
286
337
  console.log(` run ${ci ? `${ci.runId} (${ci.runOrigin.forge})` : "minted on this machine at the cut (local)"}`);
@@ -296,6 +347,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
296
347
  }
297
348
  for (const b of plan.build) console.log(` ${b.component}: artifacts built in ${b.env}`);
298
349
  for (const r of plan.reused) console.log(` ${r.component}: artifacts unchanged, carried from ${r.from}`);
350
+ for (const h of plan.handed) console.log(` ${h.component}: image ${h.ref}, handed to the cut, not built`);
299
351
  console.log(` digest ${plan.releaseDigest ?? "decided when the artifacts are built"}`);
300
352
  console.log("What will be published where:");
301
353
  if (plan.publishSteps.length === 0) console.log(" no component declares a publish step");
@@ -337,7 +389,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
337
389
  if (args.json) {
338
390
  console.log(
339
391
  JSON.stringify(
340
- { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, next },
392
+ { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, handed: result.handed, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, lane: lane ?? null, next },
341
393
  null,
342
394
  2,
343
395
  ),
@@ -346,11 +398,13 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
346
398
  const name = result.label ? formatBold(result.label) : "unlabelled release";
347
399
  if (result.cut) console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
348
400
  else console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
349
- console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}`);
401
+ console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}${lane !== undefined ? `, green in lane ${lane}` : ""}`);
350
402
  if (args.channel) console.error(` channel ${args.channel}`);
403
+ if (result.cut?.override) console.error(` not green: cut under the override by ${result.cut.override.by}: ${result.cut.override.reason}`);
351
404
  if (result.cut) console.error(` ${result.cut.signature ? `signed by ${result.cut.actor}` : `not signed; actor ${result.cut.actor}`}, run ${result.cut.runId}`);
352
405
  console.error(` artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
353
406
  for (const r of result.reused) console.error(` ${r.component}: artifacts unchanged, carried from ${r.from}`);
407
+ for (const h of result.handed) console.error(` ${h.component}: image ${h.ref}, handed to the cut`);
354
408
  if (tagged) console.error(` tag ${tagged.name}${tagged.created ? "" : " (already there)"}, not pushed`);
355
409
  console.error(`Next: ${next[0]}`);
356
410
  for (const n of next.slice(1)) console.error(` or: ${n}`);
@@ -361,6 +415,12 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
361
415
  return 0;
362
416
  } catch (err) {
363
417
  if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError || err instanceof at.CutAtError) {
418
+ // #4693: a request for an override goes where the person who answers it reads.
419
+ if (err instanceof ReleaseCutError && err.recorded) {
420
+ const { pushLifecycleReport } = await import("../../lifecycle/git");
421
+ const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
422
+ if (push.pushWarning) console.error(formatWarning({ message: push.pushWarning }));
423
+ }
364
424
  return fail(err.code, err.message, err.fix);
365
425
  }
366
426
  if (err instanceof ReleaseLabelError) return fail(err.code, err.message);
@@ -495,8 +555,9 @@ export async function runReleasePublish(ctx: CommandContext): Promise<number> {
495
555
  const hint = promoteHint();
496
556
  if (hint) say(hint);
497
557
  } else {
498
- for (const p of published) for (const i of p.items) say(` ${i.present ? "already there" : "published"}: ${describeItem(i)}`);
499
- console.error(formatSuccess(`Published ${name} to ${published.length} target(s)`));
558
+ for (const p of published) for (const i of p.items) say(` ${i.refused ? "refused" : i.present ? "already there" : "published"}: ${describeItem(i)}`);
559
+ const refused = published.filter((p) => p.warning);
560
+ console.error(formatSuccess(`Published ${name} to ${published.length - refused.length} target(s)${refused.length > 0 ? `; ${refused.length} refused it, with a warning` : ""}`));
500
561
  }
501
562
  return 0;
502
563
  }
@@ -559,7 +620,14 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
559
620
  */
560
621
  export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
561
622
  const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
562
- const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}), ...(ctx.args.branch ? { branch: ctx.args.branch } : {}), ...(ctx.args.forgeIssues ? { forgeIssues: {} } : {}) });
623
+ const lane = await laneOf(ctx, resolve("."));
624
+ const doc = await releaseCandidatesDocument({
625
+ cwd: resolve("."),
626
+ ...(ctx.args.env ? { env: ctx.args.env } : {}),
627
+ ...(ctx.args.branch ? { branch: ctx.args.branch } : {}),
628
+ ...(lane !== undefined ? { lane } : {}),
629
+ ...(ctx.args.forgeIssues ? { forgeIssues: {} } : {}),
630
+ });
563
631
  if (ctx.args.json) {
564
632
  console.log(JSON.stringify(doc, null, 2));
565
633
  return "error" in doc ? 1 : 0;
@@ -576,8 +644,10 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
576
644
  console.error(`No candidates: this clone knows no ${doc.branch}. Fetch it: git fetch origin ${doc.branch} --tags`);
577
645
  return 0;
578
646
  }
579
- if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not green yet`);
580
- if (doc.candidates.length === 0) console.log(`No green commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
647
+ const greenIn = doc.lane !== null ? `green in lane ${doc.lane}` : "green";
648
+ if (doc.lane !== null) console.log(`Lane ${doc.lane}: candidates carry ci/green-${doc.lane}/<sha>`);
649
+ if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not ${greenIn} yet`);
650
+ if (doc.candidates.length === 0) console.log(`No ${greenIn} commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
581
651
  for (const c of doc.candidates) {
582
652
  const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
583
653
  console.log(`${c.commit.slice(0, 12)} ${c.subject}${tags.length > 0 ? ` (${tags.join("; ")})` : ""}`);
@@ -596,7 +666,7 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
596
666
  // --forge-issues: why a pull request's issues were not read, once per reason.
597
667
  const unread = new Set([...doc.candidates.flatMap((c) => c.changes), ...doc.pending].map((ch) => ch.closes?.reason).filter((r): r is string => typeof r === "string"));
598
668
  for (const r of unread) console.error(`Issues not read from the forge: ${r}`);
599
- if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>`);
669
+ if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>${doc.lane !== null && ctx.args.lane !== undefined ? ` --lane ${doc.lane}` : ""}`);
600
670
  return 0;
601
671
  }
602
672
 
@@ -622,8 +692,13 @@ export async function runReleaseList(ctx: CommandContext): Promise<number> {
622
692
  const newest = r.cuts.at(-1);
623
693
  const signature = newest ? (newest.signatureCheck.status === "verified" ? `signed by ${newest.actor}` : newest.signatureCheck.status) : "-";
624
694
  // #4033: a release cut from a revoked commit says so at the end of its line, and why on stderr.
625
- console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${r.revoked ? " revoked" : ""}`);
695
+ // #4692: a release cut from a lane's green tag names the lane.
696
+ const lane = r.cuts.find((c) => c.lane !== undefined)?.lane;
697
+ const overridden = r.cuts.some((c) => c.override !== undefined);
698
+ console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${lane !== undefined ? ` lane ${lane}` : ""}${overridden ? " not green" : ""}${r.revoked ? " revoked" : ""}`);
626
699
  if (newest?.signatureCheck.status === "unverified") console.error(` ${r.label ?? r.releaseDigest}: ${newest.signatureCheck.reason}`);
700
+ // #4693: a release cut under an override says the commit was not green.
701
+ for (const c of r.cuts) if (c.override) console.error(` ${r.label ?? r.releaseDigest}: not green (no ${c.override.tag}), cut under the override by ${c.override.by}: ${c.override.reason}`);
627
702
  if (r.revoked) {
628
703
  const { describeRevocation } = await import("../../lifecycle/release-revocation");
629
704
  console.error(` ${r.label ?? r.releaseDigest}: revoked by ${r.revoked.tag}, ${describeRevocation(r.revoked)}`);
@@ -0,0 +1,112 @@
1
+ /**
2
+ * A run under a release skips a component whose declared inputs did not
3
+ * change since the release the environment runs it from, and records the
4
+ * skip (#4695). A temp repo with no remote, real cuts and a real ledger.
5
+ */
6
+ import { describe, expect, test } from "vitest";
7
+ import { withTestDir } from "@intentius/chant-test-utils";
8
+ import { spawnSync } from "node:child_process";
9
+ import { mkdirSync, writeFileSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { cutRelease } from "../../lifecycle/release-cut";
12
+ import { appendReleaseRecord, latestPerComponent, readReleaseLedger } from "../../lifecycle/release-ledger";
13
+ import type { CompiledTarget, TargetCompiler } from "../../components/release-compile";
14
+ import type { DriverComponent } from "../../components/driver";
15
+ import { recordSkips, releaseRunPrepare, type Skipped } from "./run";
16
+
17
+ function git(dir: string, ...args: string[]): string {
18
+ const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
19
+ if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
20
+ return r.stdout.trim();
21
+ }
22
+
23
+ function commit(dir: string, file: string, content: string): string {
24
+ mkdirSync(join(dir, file, ".."), { recursive: true });
25
+ writeFileSync(join(dir, file), content);
26
+ git(dir, "add", ".");
27
+ git(dir, "commit", "-q", "-m", `change ${file}`);
28
+ const sha = git(dir, "rev-parse", "HEAD");
29
+ git(dir, "tag", `ci/green/${sha}`, sha);
30
+ return sha;
31
+ }
32
+
33
+ const compiler: TargetCompiler = {
34
+ async compile(env): Promise<CompiledTarget> {
35
+ return {
36
+ env,
37
+ params: [],
38
+ components: ["control"],
39
+ buildSteps: {},
40
+ buildInputs: {},
41
+ componentFiles: { control: "control.component.ts" },
42
+ templates: [{ component: "control", path: "dist/fly.json", content: `{"app":"illogical-control"}\n` }],
43
+ };
44
+ },
45
+ async buildArtifacts() {
46
+ return [];
47
+ },
48
+ };
49
+
50
+ const image = (c: string) => `registry.fly.io/illogical-control@sha256:${c.repeat(64)}`;
51
+ const cut = (dir: string, label: string, digest: string) => cutRelease({ cwd: dir, compiler, label, actor: "ci", env: {}, images: { control: image(digest) } });
52
+
53
+ const control: DriverComponent = {
54
+ name: "control",
55
+ dependsOn: [],
56
+ deploy: [
57
+ { phase: "Image", steps: [{ kind: "release-image" }] },
58
+ { phase: "Release", steps: [{ kind: "fly-release", plan: "dist/fly.json", image: "@Image.uri", digest: "@Image.digest" }] },
59
+ ],
60
+ };
61
+ const declared = { inputs: { control: { paths: ["crates/control"] } } };
62
+
63
+ describe("run --components --release with declared inputs (#4695)", () => {
64
+ test("skips and records a component whose inputs are unchanged; deploys one whose inputs changed, or with --deploy-unchanged", async () => {
65
+ await withTestDir(async (dir) => {
66
+ git(dir, "init", "-q", "-b", "main");
67
+ git(dir, "config", "user.email", "test@chant.dev");
68
+ git(dir, "config", "user.name", "Test");
69
+ writeFileSync(join(dir, "chant.config.ts"), `export default { environments: ["prod"] };\n`);
70
+ commit(dir, "crates/control/main.rs", "fn main() {}\n");
71
+ const r1 = await cut(dir, "v1", "a");
72
+ await appendReleaseRecord(
73
+ { component: "control", env: "prod", digest: `sha256:${"a".repeat(64)}`, gitSha: r1.release.commit, runId: "run-1", timestamp: "2026-11-01T10:00:00.000Z", actor: "ci", releaseDigest: r1.release.releaseDigest },
74
+ { cwd: dir },
75
+ );
76
+
77
+ // A commit outside the hub's inputs: the next release leaves it alone.
78
+ commit(dir, "web/index.html", "<p>hi</p>\n");
79
+ const r2 = await cut(dir, "v2", "b");
80
+ const skipped: Skipped = new Map();
81
+ const prepare = releaseRunPrepare({ releaseDigest: r2.release.releaseDigest, label: "v2", release: r2.release }, dir, "prod", { deployUnchanged: false, skipped });
82
+ const prepared = await prepare([control], declared);
83
+ expect(prepared).toEqual({ components: [{ ...control, deploy: [] }] });
84
+ expect([...skipped.keys()]).toEqual(["control"]);
85
+
86
+ const written = await recordSkips(skipped, r2.release.releaseDigest, { runId: "run-2" }, dir);
87
+ expect(written).toHaveLength(1);
88
+ const latest = latestPerComponent((await readReleaseLedger("prod", { cwd: dir })).records).get("control")!;
89
+ expect(latest).toMatchObject({
90
+ digest: `sha256:${"a".repeat(64)}`,
91
+ gitSha: r1.release.commit,
92
+ runId: "run-2",
93
+ releaseDigest: r2.release.releaseDigest,
94
+ unchangedSince: { env: "prod", runId: "run-1", timestamp: "2026-11-01T10:00:00.000Z" },
95
+ });
96
+
97
+ // --deploy-unchanged deploys it with the image v2 recorded.
98
+ const forced: Skipped = new Map();
99
+ const deployed = await releaseRunPrepare({ releaseDigest: r2.release.releaseDigest, label: "v2", release: r2.release }, dir, "prod", { deployUnchanged: true, skipped: forced })([control], declared);
100
+ expect(forced.size).toBe(0);
101
+ expect(deployed).toMatchObject({ components: [{ deploy: [{ phase: "Image", steps: [{ kind: "release-image", uri: image("b") }] }, control.deploy[1]] }] });
102
+
103
+ // A change to an input deploys it, compared against v2, which the skip record names.
104
+ commit(dir, "crates/control/main.rs", "fn main() { println!(); }\n");
105
+ const r3 = await cut(dir, "v3", "c");
106
+ const again: Skipped = new Map();
107
+ const changed = await releaseRunPrepare({ releaseDigest: r3.release.releaseDigest, label: "v3", release: r3.release }, dir, "prod", { deployUnchanged: false, skipped: again })([control], declared);
108
+ expect(again.size).toBe(0);
109
+ expect(changed).toMatchObject({ components: [{ deploy: [{ phase: "Image", steps: [{ kind: "release-image", uri: image("c") }] }, control.deploy[1]] }] });
110
+ });
111
+ });
112
+ });