@intentius/chant 0.124.64 → 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 (105) hide show
  1. package/dist/cli/handlers/release.d.ts.map +1 -1
  2. package/dist/cli/handlers/release.js +20 -2
  3. package/dist/cli/handlers/run.d.ts +30 -1
  4. package/dist/cli/handlers/run.d.ts.map +1 -1
  5. package/dist/cli/handlers/run.js +108 -7
  6. package/dist/cli/main.d.ts.map +1 -1
  7. package/dist/cli/main.js +17 -2
  8. package/dist/cli/parse-args.d.ts.map +1 -1
  9. package/dist/cli/parse-args.js +7 -0
  10. package/dist/cli/registry.d.ts +5 -1
  11. package/dist/cli/registry.d.ts.map +1 -1
  12. package/dist/components/cli-support.d.ts +19 -1
  13. package/dist/components/cli-support.d.ts.map +1 -1
  14. package/dist/components/cli-support.js +11 -3
  15. package/dist/components/component.d.ts +19 -0
  16. package/dist/components/component.d.ts.map +1 -1
  17. package/dist/components/component.schema.json +17 -0
  18. package/dist/components/index.d.ts +1 -1
  19. package/dist/components/index.d.ts.map +1 -1
  20. package/dist/components/release-run.d.ts +48 -0
  21. package/dist/components/release-run.d.ts.map +1 -0
  22. package/dist/components/release-run.js +166 -0
  23. package/dist/components/starter-plugin.d.ts +1 -0
  24. package/dist/components/starter-plugin.d.ts.map +1 -1
  25. package/dist/components/starter-plugin.js +5 -1
  26. package/dist/components/unchanged-inputs.d.ts +81 -0
  27. package/dist/components/unchanged-inputs.d.ts.map +1 -0
  28. package/dist/components/unchanged-inputs.js +122 -0
  29. package/dist/components/verbs/index.d.ts +1 -0
  30. package/dist/components/verbs/index.d.ts.map +1 -1
  31. package/dist/components/verbs/index.js +1 -0
  32. package/dist/components/verbs/release-image.d.ts +36 -0
  33. package/dist/components/verbs/release-image.d.ts.map +1 -0
  34. package/dist/components/verbs/release-image.js +33 -0
  35. package/dist/lifecycle/delivery-metrics.d.ts.map +1 -1
  36. package/dist/lifecycle/delivery-metrics.js +4 -2
  37. package/dist/lifecycle/gate-statement.d.ts.map +1 -1
  38. package/dist/lifecycle/gate-statement.js +1 -2
  39. package/dist/lifecycle/git.d.ts.map +1 -1
  40. package/dist/lifecycle/git.js +6 -1
  41. package/dist/lifecycle/ledger-read.js +1 -1
  42. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -1
  43. package/dist/lifecycle/publish-homebrew.js +1 -2
  44. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -1
  45. package/dist/lifecycle/publish-marketplace.js +2 -3
  46. package/dist/lifecycle/query.d.ts +2 -2
  47. package/dist/lifecycle/query.d.ts.map +1 -1
  48. package/dist/lifecycle/query.js +3 -3
  49. package/dist/lifecycle/release-cut.d.ts +32 -2
  50. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  51. package/dist/lifecycle/release-cut.js +47 -7
  52. package/dist/lifecycle/release-ledger.d.ts +11 -0
  53. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  54. package/dist/lifecycle/release-store.d.ts +17 -3
  55. package/dist/lifecycle/release-store.d.ts.map +1 -1
  56. package/dist/lifecycle/release-store.js +11 -3
  57. package/dist/op/activities/activity-contracts.d.ts +4 -4
  58. package/dist/op/op-waves-run.js +5 -3
  59. package/dist/release-floors.d.ts +1 -1
  60. package/dist/release-floors.js +1 -1
  61. package/dist/wave-runtime.mjs +237 -237
  62. package/dist/workspace/delivery-metrics.schema.json +1 -1
  63. package/dist/workspace/release-candidates.d.ts.map +1 -1
  64. package/dist/workspace/release-candidates.js +1 -2
  65. package/dist/workspace/releases.schema.json +7 -2
  66. package/package.json +1 -1
  67. package/src/cli/handlers/release.ts +18 -2
  68. package/src/cli/handlers/run-unchanged.e2e.test.ts +112 -0
  69. package/src/cli/handlers/run.ts +117 -7
  70. package/src/cli/main.ts +17 -2
  71. package/src/cli/parse-args.ts +6 -0
  72. package/src/cli/registry.ts +5 -1
  73. package/src/components/cli-support.test.ts +53 -0
  74. package/src/components/cli-support.ts +26 -4
  75. package/src/components/component.schema.json +17 -0
  76. package/src/components/component.ts +20 -0
  77. package/src/components/index.ts +1 -0
  78. package/src/components/registry.test.ts +1 -1
  79. package/src/components/release-run.test.ts +127 -0
  80. package/src/components/release-run.ts +188 -0
  81. package/src/components/starter-plugin.ts +5 -0
  82. package/src/components/unchanged-inputs.test.ts +98 -0
  83. package/src/components/unchanged-inputs.ts +151 -0
  84. package/src/components/verbs/index.ts +1 -0
  85. package/src/components/verbs/release-image.ts +52 -0
  86. package/src/lifecycle/delivery-metrics.ts +4 -2
  87. package/src/lifecycle/gate-statement.ts +1 -2
  88. package/src/lifecycle/git.test.ts +15 -0
  89. package/src/lifecycle/git.ts +5 -1
  90. package/src/lifecycle/ledger-read.ts +1 -1
  91. package/src/lifecycle/publish-homebrew.ts +1 -2
  92. package/src/lifecycle/publish-marketplace.ts +2 -3
  93. package/src/lifecycle/query.ts +3 -3
  94. package/src/lifecycle/release-cut-lane.test.ts +18 -0
  95. package/src/lifecycle/release-cut-override.test.ts +12 -0
  96. package/src/lifecycle/release-cut.test.ts +45 -0
  97. package/src/lifecycle/release-cut.ts +67 -7
  98. package/src/lifecycle/release-ledger.ts +11 -0
  99. package/src/lifecycle/release-store.ts +29 -5
  100. package/src/op/op-waves-run.ts +4 -2
  101. package/src/release-floors.ts +1 -1
  102. package/src/workspace/delivery-metrics.schema.json +1 -1
  103. package/src/workspace/delivery-metrics.test.ts +8 -0
  104. package/src/workspace/release-candidates.ts +1 -2
  105. package/src/workspace/releases.schema.json +7 -2
@@ -26,7 +26,7 @@ import { UnknownCanaryError } from "../gated-waves";
26
26
  import { lexiconModulePath, lexiconNames, importLexiconPackage } from "../lexicon-module";
27
27
  import { discoverComponents } from "./discover";
28
28
  import type { BuildParamProvenance } from "../provenance";
29
- import { inferArchetype, projectToJson, type Archetype, type ComponentEnvironmentDeclaration } from "./component";
29
+ import { inferArchetype, projectToJson, type Archetype, type ComponentEnvironmentDeclaration, type ComponentInputs } from "./component";
30
30
  import {
31
31
  deployContext,
32
32
  resolveComponentGraph,
@@ -495,6 +495,19 @@ export interface RunComponentsOptions {
495
495
  * a checkout. `null` passes none.
496
496
  */
497
497
  revision?: string | null;
498
+ /**
499
+ * Rewrites the selected compositions before anything runs, or refuses the
500
+ * run (#4694): `chant run --components --release` takes out the build steps
501
+ * of a component the release recorded an artifact for and hands its
502
+ * `release-image` steps the image (./release-run.ts). Called once, with the
503
+ * components in run order, after their config defaults are applied, and
504
+ * the inputs each declares (#4695), by which a run under a release skips
505
+ * a component whose inputs did not change.
506
+ */
507
+ prepare?: (
508
+ components: DriverComponent[],
509
+ declared: { inputs: Readonly<Record<string, ComponentInputs>> },
510
+ ) => Promise<{ components: DriverComponent[] } | { error: string }>;
498
511
  }
499
512
 
500
513
  /** The resolved order of a list run (#3950), reported through `RunComponentsOptions.onPlan`. */
@@ -573,6 +586,8 @@ export interface ResolvedComponentTargets {
573
586
  list?: { named: string[]; enabled: DriverComponent[] };
574
587
  /** Component name to the environments it declares (#3153), for the components that declare any (#4330). */
575
588
  sites?: Record<string, ComponentEnvironmentDeclaration[]>;
589
+ /** Component name to the inputs it declares (#4695), for the components that declare them. */
590
+ inputs?: Record<string, ComponentInputs>;
576
591
  error?: string;
577
592
  }
578
593
 
@@ -602,12 +617,14 @@ export async function resolveComponentTargets(
602
617
 
603
618
  const discovered = [...result.components.values()].map(({ component }) => component);
604
619
  const all = discovered.map((component) => toDriverComponent(component));
620
+ const inputs = Object.fromEntries(discovered.filter((c) => c.inputs !== undefined).map((c) => [c.name, c.inputs!]));
621
+ const declared = Object.keys(inputs).length > 0 ? { inputs } : {};
605
622
 
606
- if (isComponentList(selector)) return resolveComponentList(selector, discovered, all);
623
+ if (isComponentList(selector)) return { ...resolveComponentList(selector, discovered, all), ...declared };
607
624
 
608
625
  if (selector === "all") {
609
626
  const sites = Object.fromEntries(discovered.filter((c) => c.environments && c.environments.length > 0).map((c) => [c.name, c.environments!.map((e) => ({ ...e }))]));
610
- return { success: true, targets: withoutDisabled(discovered, all), ...(Object.keys(sites).length > 0 ? { sites } : {}) };
627
+ return { success: true, targets: withoutDisabled(discovered, all), ...(Object.keys(sites).length > 0 ? { sites } : {}), ...declared };
611
628
  }
612
629
 
613
630
  const found = all.find((c) => c.name === selector);
@@ -629,7 +646,7 @@ export async function resolveComponentTargets(
629
646
  error: `Component "${selector}" not found.${known ? ` Known components: ${known}` : " No components discovered."}`,
630
647
  };
631
648
  }
632
- return { success: true, targets: [found] };
649
+ return { success: true, targets: [found], ...declared };
633
650
  }
634
651
 
635
652
  /**
@@ -741,6 +758,11 @@ export async function runComponents(
741
758
  const defaulted = resolved.targets.map((component) => applyConfigDefaults(component, config));
742
759
  resolvedTargets = selector === "all" ? await withDeclaredReads(defaulted, registry, path) : defaulted;
743
760
  }
761
+ if (options.prepare) {
762
+ const prepared = await options.prepare(resolvedTargets, { inputs: resolved.inputs ?? {} });
763
+ if ("error" in prepared) return { success: false, selected: [], error: prepared.error };
764
+ resolvedTargets = prepared.components;
765
+ }
744
766
  const selected = resolvedTargets.map((c) => c.name);
745
767
  const narrowed = options.targets ?? {};
746
768
  const outside = Object.keys(narrowed).filter((name) => !selected.includes(name));
@@ -77,6 +77,23 @@
77
77
  "lifecycle": { "type": "string", "minLength": 1, "description": "The git remote this environment's approvals, effect receipts and ledger records are pushed to." }
78
78
  }
79
79
  }
80
+ },
81
+ "inputs": {
82
+ "type": "object",
83
+ "description": "Optional: what a deploy of this component is made from (#4695). A run under a release (chant run --components --release) skips the component when these are the same as in the release the environment runs it from, and records the skip; --deploy-unchanged deploys it anyway. Omitted, the component deploys with every release. Read by chant 0.124.65 and newer.",
84
+ "additionalProperties": false,
85
+ "properties": {
86
+ "paths": {
87
+ "type": "array",
88
+ "description": "Git pathspecs, relative to the member's directory, that the component is built and deployed from. A change to any file they match between the two releases' commits deploys it. Magic such as :(exclude) and :(top) is git's.",
89
+ "items": { "type": "string", "minLength": 1 }
90
+ },
91
+ "params": {
92
+ "type": "array",
93
+ "description": "Build parameters, by name, whose values in the environment's target the component deploys from. A value that differs between the two releases deploys it.",
94
+ "items": { "type": "string", "minLength": 1 }
95
+ }
96
+ }
80
97
  }
81
98
  },
82
99
  "$defs": {
@@ -194,6 +194,26 @@ export interface Component {
194
194
  * environments are its member's, as before.
195
195
  */
196
196
  environments?: ComponentEnvironmentDeclaration[];
197
+ /**
198
+ * Optional: what a deploy of this component is made from (#4695). A run
199
+ * under a release (`chant run --components --release`) skips the component
200
+ * when these are the same as in the release the environment runs it from,
201
+ * and records the skip; `--deploy-unchanged` deploys it anyway. Omitted, the
202
+ * component deploys with every release. See ./unchanged-inputs.ts.
203
+ */
204
+ inputs?: ComponentInputs;
205
+ }
206
+
207
+ /** What a component's deploy is made from (#4695), compared between two releases. */
208
+ export interface ComponentInputs {
209
+ /**
210
+ * Git pathspecs, relative to the member's directory, such as
211
+ * `../crates/control` or `:(exclude)../web/e2e`. A change between the two
212
+ * releases' commits to a file they match deploys the component.
213
+ */
214
+ paths?: string[];
215
+ /** Build parameters, by name. A value that differs between the two releases' targets for the environment deploys the component. */
216
+ params?: string[];
197
217
  }
198
218
 
199
219
  /** One environment a component declares it deploys to (#3153). */
@@ -15,6 +15,7 @@ export {
15
15
  type Phase,
16
16
  type Component,
17
17
  type ComponentEnvironmentDeclaration,
18
+ type ComponentInputs,
18
19
  phase,
19
20
  gate,
20
21
  stackOutput,
@@ -99,7 +99,7 @@ describe("createCapabilityRegistry", () => {
99
99
  // for them to live in instead.
100
100
  test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
101
101
  expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
102
- ["build", "cloudflare", "engineOutputs", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
102
+ ["build", "cloudflare", "engineOutputs", "escapeHatch", "publish", "release", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
103
103
  );
104
104
  });
105
105
 
@@ -0,0 +1,127 @@
1
+ /**
2
+ * A run of a release's own artifacts (#4694): build steps out, a handed image
3
+ * into `release-image` and in place of a publish, refusals before anything runs.
4
+ */
5
+ import { describe, test, expect } from "vitest";
6
+ import { withTestDir } from "@intentius/chant-test-utils";
7
+ import { mkdirSync, writeFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { releaseRunComponents } from "./release-run";
10
+ import { releaseImageCapability } from "./verbs/release-image";
11
+ import type { DriverComponent } from "./driver";
12
+ import type { ReleaseArtifact } from "../lifecycle/release-store";
13
+
14
+ const IMAGE = `registry.fly.io/control@sha256:${"b".repeat(64)}`;
15
+ const handed: ReleaseArtifact = { component: "control", kind: "image", path: "", digest: `sha256:${"b".repeat(64)}`, ref: IMAGE };
16
+ const release = (artifactDigests: ReleaseArtifact[]) => ({ releaseDigest: "jcs1-sha256:r", artifactDigests });
17
+
18
+ const control: DriverComponent = {
19
+ name: "control",
20
+ dependsOn: [],
21
+ deploy: [
22
+ { phase: "Approve", steps: [{ kind: "gate", gate: "prod-release" }] },
23
+ { phase: "Image", steps: [{ kind: "release-image" }] },
24
+ { phase: "Release", steps: [{ kind: "fly-release", plan: "dist/fly.json", image: "@Image.uri", digest: "@Image.digest" }] },
25
+ ],
26
+ };
27
+
28
+ const api: DriverComponent = {
29
+ name: "api",
30
+ dependsOn: [],
31
+ deploy: [
32
+ { phase: "Build", steps: [{ kind: "docker-build", context: "api", into: "out/api.tar" }] },
33
+ { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:out/api.tar", to: "r.io/api" }] },
34
+ { phase: "Apply", steps: [{ kind: "ecs-update-service", image: "@Publish.uri" }] },
35
+ ],
36
+ };
37
+
38
+ const plain: DriverComponent = { name: "db", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "db.json" }] }] };
39
+
40
+ describe("releaseRunComponents", () => {
41
+ test("a release-image step gets the image handed to the cut, and the gate and deploy steps stay", () => {
42
+ const result = releaseRunComponents([control, plain], release([handed]), "/nowhere", "v1");
43
+ expect("components" in result).toBe(true);
44
+ if (!("components" in result)) return;
45
+ expect(result.components[0].deploy).toEqual([
46
+ control.deploy[0],
47
+ { phase: "Image", steps: [{ kind: "release-image", uri: IMAGE, digest: handed.digest }] },
48
+ control.deploy[2],
49
+ ]);
50
+ expect(result.components[1]).toBe(plain);
51
+ expect(result.notes).toEqual([{ component: "control", removed: [], image: IMAGE }]);
52
+ });
53
+
54
+ test("fly-release's images for the plan's other Machines can wire the same image, and are left as written (#4696)", async () => {
55
+ const withCron: DriverComponent = {
56
+ ...control,
57
+ deploy: [
58
+ control.deploy[1],
59
+ { phase: "Release", steps: [{ kind: "fly-release", plan: "dist/fly.json", image: "@Image.uri", images: { controlCron: "@Image.uri" }, digest: "@Image.digest" }] },
60
+ ],
61
+ };
62
+ const result = releaseRunComponents([withCron], release([handed]), "/nowhere");
63
+ if (!("components" in result)) throw new Error(JSON.stringify(result));
64
+ expect(result.components[0].deploy[1]).toEqual(withCron.deploy[1]);
65
+ const { resolveStepInput } = await import("./driver");
66
+ const step = withCron.deploy[1].steps[0] as Record<string, unknown>;
67
+ expect(resolveStepInput({ image: step.image, images: step.images }, { Image: { uri: IMAGE, digest: handed.digest } }, {})).toEqual({ image: IMAGE, images: { controlCron: IMAGE } });
68
+ });
69
+
70
+ test("a handed image replaces the build and the publish, so @Publish.uri reads the image", () => {
71
+ const result = releaseRunComponents([api], release([{ ...handed, component: "api" }]), "/nowhere");
72
+ if (!("components" in result)) throw new Error(JSON.stringify(result));
73
+ expect(result.components[0].deploy).toEqual([
74
+ { phase: "Publish", steps: [{ kind: "release-image", uri: IMAGE, digest: handed.digest, replaces: "publish-image" }] },
75
+ api.deploy[2],
76
+ ]);
77
+ expect(result.notes[0].removed).toEqual(["docker-build"]);
78
+ });
79
+
80
+ test("an archive the cut built is published from where the cut wrote it, without building", async () => {
81
+ await withTestDir(async (dir) => {
82
+ const built: ReleaseArtifact = { component: "api", kind: "image", path: "out/api.tar", digest: `sha256:${"a".repeat(64)}` };
83
+ const missing = releaseRunComponents([api], release([built]), dir, "v1");
84
+ expect(missing).toEqual({ errors: [expect.stringMatching(/release v1 built out\/api\.tar, which is not here/)] });
85
+
86
+ mkdirSync(join(dir, "out"));
87
+ writeFileSync(join(dir, "out", "api.tar"), "tar");
88
+ const result = releaseRunComponents([api], release([built]), dir, "v1");
89
+ if (!("components" in result)) throw new Error(JSON.stringify(result));
90
+ expect(result.components[0].deploy).toEqual([api.deploy[1], api.deploy[2]]);
91
+ });
92
+ });
93
+
94
+ test("refuses a component whose artifact or image the release did not record, naming each", () => {
95
+ const result = releaseRunComponents([control, api, plain], release([]), "/nowhere", "v1");
96
+ expect(result).toEqual({
97
+ errors: [
98
+ expect.stringMatching(/"control" runs the image release v1 recorded for it .* recorded none; .*--image control=/),
99
+ expect.stringMatching(/"api" builds an artifact, and release v1 recorded none for it, so the run would build it again/),
100
+ ],
101
+ });
102
+ });
103
+
104
+ test("refuses a step that reads the output of a build step the run takes out", () => {
105
+ const reads: DriverComponent = {
106
+ name: "api",
107
+ dependsOn: [],
108
+ deploy: [
109
+ { phase: "Build", steps: [{ kind: "docker-build", context: "api", into: "out/api.tar" }] },
110
+ { phase: "Apply", steps: [{ kind: "ecs-update-service", image: "@Build.imageRef" }] },
111
+ ],
112
+ };
113
+ expect(releaseRunComponents([reads], release([{ ...handed, component: "api" }]), "/nowhere")).toEqual({
114
+ errors: [expect.stringMatching(/reads "@Build\.imageRef", an output of a build step a run under a release does not run/)],
115
+ });
116
+ });
117
+ });
118
+
119
+ describe("release-image", () => {
120
+ const ctx = { env: "prod", component: "control" };
121
+ test("hands on the image a run under a release filled in", async () => {
122
+ expect(await releaseImageCapability.run(ctx, { uri: IMAGE, digest: handed.digest })).toEqual({ uri: IMAGE, digest: handed.digest });
123
+ });
124
+ test("fails a run that names no release", async () => {
125
+ await expect(releaseImageCapability.run(ctx, {})).rejects.toThrow(/--release <label>/);
126
+ });
127
+ });
@@ -0,0 +1,188 @@
1
+ /**
2
+ * A run of a release's own artifacts (#4694): `chant run --components <c>
3
+ * --env <e> --release <label>` deploys what the cut recorded, without
4
+ * building it again.
5
+ *
6
+ * The run is at the release's commit (`resolveRunRelease`, ../cli/handlers/run.ts),
7
+ * so each component's composition is the one the cut compiled. Before
8
+ * anything runs, each component the release recorded an artifact for has its
9
+ * build steps (`BUILD_STEP_KINDS`) taken out, as a promote takes them out
10
+ * (`withoutBuildSteps`, ./promote.ts), and a step that reads the output of
11
+ * one is refused:
12
+ *
13
+ * - an image handed to the cut (`chant release cut --image`, the artifact's
14
+ * `ref`) is already in its registry. Each `release-image` step of the
15
+ * component is given it, and each publish step is replaced by a
16
+ * `release-image` step that hands on the same image, since there is no
17
+ * archive to publish from;
18
+ * - an archive the cut built is published from where the cut wrote it, so the
19
+ * publish step stays and reads that file. A run where the file is not there
20
+ * is refused.
21
+ *
22
+ * A component with build steps whose artifact the release did not record, and
23
+ * one with a `release-image` step when the release recorded no image for it,
24
+ * are refused: the first would build again, the second has no image to run.
25
+ * A component with neither build steps nor a `release-image` step runs as
26
+ * declared. Every refusal is returned before anything runs.
27
+ */
28
+
29
+ import { existsSync } from "node:fs";
30
+ import { isAbsolute, resolve } from "node:path";
31
+ import type { DriverComponent, DriverGate, DriverPhase, DriverStep } from "./driver";
32
+ import type { Release, ReleaseArtifact } from "../lifecycle/release-store";
33
+ import { BUILD_STEP_KINDS, PUBLISH_STEP_KINDS } from "./promote";
34
+ import { parseWiringRef } from "../lint/rules/comp/support";
35
+ import { RELEASE_IMAGE_KIND } from "./verbs/release-image";
36
+
37
+ const isGate = (s: DriverStep | DriverGate | DriverPhase): s is DriverGate => (s as { kind?: unknown }).kind === "gate";
38
+ const isPhase = (s: DriverStep | DriverGate | DriverPhase): s is DriverPhase =>
39
+ typeof (s as { phase?: unknown }).phase === "string" && Array.isArray((s as DriverPhase).steps);
40
+
41
+ /** Every step of a composition, nested phases included. */
42
+ function stepsOf(phases: readonly DriverPhase[]): DriverStep[] {
43
+ const out: DriverStep[] = [];
44
+ const walk = (phase: DriverPhase): void => {
45
+ for (const s of phase.steps) {
46
+ if (isPhase(s)) walk(s);
47
+ else if (!isGate(s)) out.push(s);
48
+ }
49
+ };
50
+ phases.forEach(walk);
51
+ return out;
52
+ }
53
+
54
+ /** The same phases with every step `fn` maps, nested phases included. */
55
+ function mapSteps(phases: readonly DriverPhase[], fn: (step: DriverStep) => DriverStep): DriverPhase[] {
56
+ const map = (phase: DriverPhase): DriverPhase => ({
57
+ ...phase,
58
+ steps: phase.steps.map((s) => (isPhase(s) ? map(s) : isGate(s) ? s : fn(s))),
59
+ });
60
+ return phases.map(map);
61
+ }
62
+
63
+ /** Every `@Phase.field` a step's fields read. */
64
+ function priorStepReads(step: DriverStep): Array<{ phase: string; field: string }> {
65
+ const out: Array<{ phase: string; field: string }> = [];
66
+ const walk = (v: unknown): void => {
67
+ if (typeof v === "string") {
68
+ const ref = parseWiringRef(v);
69
+ if (ref?.kind === "prior-step") out.push({ phase: ref.phaseName, field: ref.field });
70
+ } else if (Array.isArray(v)) v.forEach(walk);
71
+ else if (v && typeof v === "object" && !("stackOutput" in v)) Object.values(v as Record<string, unknown>).forEach(walk);
72
+ };
73
+ const { kind: _kind, ...fields } = step;
74
+ walk(fields);
75
+ return out;
76
+ }
77
+
78
+ /**
79
+ * `component` without its build steps, a phase left with nothing dropped, or
80
+ * why it can't be: a step left reads an output of a phase that held only
81
+ * build steps.
82
+ */
83
+ function withoutBuilds(component: DriverComponent): { component: DriverComponent; removed: string[] } | { error: string } {
84
+ const removed: string[] = [];
85
+ const emptied = new Set<string>();
86
+ const strip = (phase: DriverPhase): DriverPhase | undefined => {
87
+ const steps: DriverPhase["steps"] = [];
88
+ let lost = false;
89
+ for (const s of phase.steps) {
90
+ if (isPhase(s)) {
91
+ const nested = strip(s);
92
+ if (nested) steps.push(nested);
93
+ } else if (!isGate(s) && BUILD_STEP_KINDS.includes(s.kind)) {
94
+ removed.push(s.kind);
95
+ lost = true;
96
+ } else steps.push(s);
97
+ }
98
+ if (lost && !steps.some((s) => !isGate(s))) emptied.add(phase.phase);
99
+ return steps.length > 0 ? { ...phase, steps } : undefined;
100
+ };
101
+ const deploy = component.deploy.map(strip).filter((p): p is DriverPhase => p !== undefined);
102
+ for (const step of stepsOf(deploy)) {
103
+ const read = priorStepReads(step).find((r) => emptied.has(r.phase));
104
+ if (read) {
105
+ return { error: `component "${component.name}" reads "@${read.phase}.${read.field}", an output of a build step a run under a release does not run` };
106
+ }
107
+ }
108
+ return { component: { ...component, deploy }, removed };
109
+ }
110
+
111
+ /** What a component's run under a release will do, for the run to print. */
112
+ export interface ReleaseRunNote {
113
+ component: string;
114
+ /** The build step kinds taken out. */
115
+ removed: string[];
116
+ /** The image the component runs, when one was handed to the cut. */
117
+ image?: string;
118
+ }
119
+
120
+ /**
121
+ * The compositions to run under `release`, or every reason a component can't
122
+ * be run from it. `memberDir` is where the cut's archive paths are read from.
123
+ */
124
+ export function releaseRunComponents(
125
+ components: readonly DriverComponent[],
126
+ release: Pick<Release, "releaseDigest" | "artifactDigests">,
127
+ memberDir: string,
128
+ label: string | null = null,
129
+ ): { components: DriverComponent[]; notes: ReleaseRunNote[] } | { errors: string[] } {
130
+ const name = label ?? release.releaseDigest;
131
+ const errors: string[] = [];
132
+ const out: DriverComponent[] = [];
133
+ const notes: ReleaseRunNote[] = [];
134
+ for (const component of components) {
135
+ const artifacts = release.artifactDigests.filter((a) => a.component === component.name);
136
+ const handed = artifacts.find((a): a is ReleaseArtifact & { ref: string } => typeof a.ref === "string");
137
+ const steps = stepsOf(component.deploy);
138
+ const builds = steps.some((s) => BUILD_STEP_KINDS.includes(s.kind));
139
+ const wantsImage = steps.some((s) => s.kind === RELEASE_IMAGE_KIND);
140
+
141
+ if (wantsImage && !handed) {
142
+ errors.push(
143
+ `component "${component.name}" runs the image release ${name} recorded for it (a release-image step), and the release recorded none; ` +
144
+ `hand the cut its image: chant release cut <label> --image ${component.name}=<repository>@sha256:<hex>`,
145
+ );
146
+ continue;
147
+ }
148
+ if (!builds && !handed) {
149
+ out.push(component);
150
+ continue;
151
+ }
152
+ if (artifacts.length === 0) {
153
+ errors.push(
154
+ `component "${component.name}" builds an artifact, and release ${name} recorded none for it, so the run would build it again; ` +
155
+ `cut a release that builds it, or hand the cut its image with --image`,
156
+ );
157
+ continue;
158
+ }
159
+ if (!handed) {
160
+ const missing = artifacts.filter((a) => a.path === "" || !existsSync(isAbsolute(a.path) ? a.path : resolve(memberDir, a.path)));
161
+ if (missing.length > 0) {
162
+ errors.push(
163
+ `component "${component.name}": release ${name} built ${missing.map((a) => a.path || a.kind).join(", ")}, which is not here, so the run can't publish the release's own artifact; ` +
164
+ `run where the cut built it, or push the image and hand the cut its digest with --image`,
165
+ );
166
+ continue;
167
+ }
168
+ }
169
+ // An image handed to the cut is in its registry already: a publish step hands it on rather than pushing an archive.
170
+ const filled = handed
171
+ ? mapSteps(component.deploy, (s) =>
172
+ s.kind === RELEASE_IMAGE_KIND
173
+ ? { ...s, uri: handed.ref, digest: handed.digest }
174
+ : PUBLISH_STEP_KINDS.includes(s.kind)
175
+ ? { kind: RELEASE_IMAGE_KIND, uri: handed.ref, digest: handed.digest, replaces: s.kind }
176
+ : s,
177
+ )
178
+ : component.deploy;
179
+ const stripped = withoutBuilds({ ...component, deploy: filled });
180
+ if ("error" in stripped) {
181
+ errors.push(stripped.error);
182
+ continue;
183
+ }
184
+ out.push(stripped.component);
185
+ notes.push({ component: component.name, removed: stripped.removed, ...(handed ? { image: handed.ref } : {}) });
186
+ }
187
+ return errors.length > 0 ? { errors } : { components: out, notes };
188
+ }
@@ -48,6 +48,7 @@ import {
48
48
  wranglerVersionsPromoteCapability,
49
49
  r2SyncCapability,
50
50
  memberOutputsStarterCapability,
51
+ releaseImageCapability,
51
52
  } from "./verbs/index";
52
53
  import { ownPackageVersion, type CapabilityPlugin } from "./capability-plugin";
53
54
 
@@ -87,6 +88,9 @@ export const STARTER_VERB_FAMILIES = {
87
88
  // (#4455). One agnostic verb; each engine's lexicon contributes a source
88
89
  // (`CapabilityPlugin.engineOutputSources`).
89
90
  engineOutputs: ["member-outputs"],
91
+ // The image a release recorded for the component, handed to the cut by
92
+ // digest (#4694); a run under the release fills it in.
93
+ release: ["release-image"],
90
94
  } as const;
91
95
 
92
96
  /**
@@ -118,6 +122,7 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
118
122
  wranglerVersionsPromoteCapability,
119
123
  r2SyncCapability,
120
124
  memberOutputsStarterCapability,
125
+ releaseImageCapability,
121
126
  ] as unknown as Array<Capability<never, unknown>>;
122
127
  }
123
128
 
@@ -0,0 +1,98 @@
1
+ /**
2
+ * A component a release leaves alone (#4695): its declared inputs compared with
3
+ * the release the environment runs it from.
4
+ */
5
+ import { describe, test, expect } from "vitest";
6
+ import { compareInputs, unchangedRecord, type ChangedPaths } from "./unchanged-inputs";
7
+ import { makeRelease, type Release } from "../lifecycle/release-store";
8
+ import type { ReleaseRecord } from "../lifecycle/release-ledger";
9
+
10
+ const release = (commit: string, opts: { region?: string; template?: string } = {}): Release =>
11
+ makeRelease({
12
+ member: null,
13
+ commit: commit.repeat(40),
14
+ artifactDigests: [],
15
+ targets: [
16
+ {
17
+ env: "prod",
18
+ templates: [{ component: "control", path: "dist/fly.json", digest: opts.template ?? "sha256:fly" }],
19
+ params: [{ name: "region", value: opts.region ?? "ewr", source: "default" }],
20
+ },
21
+ ],
22
+ });
23
+
24
+ const before = release("a");
25
+ const record = (over: Partial<ReleaseRecord> = {}): ReleaseRecord => ({
26
+ version: 1,
27
+ component: "control",
28
+ env: "prod",
29
+ digest: "sha256:image",
30
+ gitSha: "a".repeat(40),
31
+ runId: "run-1",
32
+ timestamp: "2026-11-01T10:00:00.000Z",
33
+ actor: "ci",
34
+ releaseDigest: before.releaseDigest,
35
+ ...over,
36
+ });
37
+
38
+ const noChange: ChangedPaths = () => [];
39
+ const compare = (now: Release, opts: { current?: ReleaseRecord | undefined; changedPaths?: ChangedPaths; params?: string[]; stored?: Release[] } = {}) =>
40
+ compareInputs({
41
+ component: "control",
42
+ inputs: { paths: ["../crates/control"], params: opts.params ?? ["region"] },
43
+ env: "prod",
44
+ release: now,
45
+ current: "current" in opts ? opts.current : record(),
46
+ readRelease: async (d) => (opts.stored ?? [before]).find((r) => r.releaseDigest === d) ?? null,
47
+ changedPaths: opts.changedPaths ?? noChange,
48
+ });
49
+
50
+ describe("compareInputs", () => {
51
+ test("unchanged when the paths, the params and the deploy files are the same", async () => {
52
+ const seen: unknown[] = [];
53
+ const verdict = await compare(release("b"), { changedPaths: (from, to, paths) => (seen.push([from, to, paths]), []) });
54
+ expect(verdict).toEqual({ unchanged: true, since: record(), recorded: false });
55
+ expect(seen).toEqual([["a".repeat(40), "b".repeat(40), ["../crates/control"]]]);
56
+ });
57
+
58
+ test("a changed path, param or deploy file deploys it, and says which", async () => {
59
+ expect(await compare(release("b"), { changedPaths: () => ["crates/control/src/main.rs"] })).toEqual({
60
+ unchanged: false,
61
+ reason: expect.stringMatching(/1 input file\(s\) changed since a{12}, such as crates\/control\/src\/main\.rs/),
62
+ });
63
+ expect(await compare(release("b", { region: "iad" }))).toEqual({ unchanged: false, reason: 'param region is "iad", was "ewr"' });
64
+ expect(await compare(release("b", { template: "sha256:other" }))).toEqual({ unchanged: false, reason: expect.stringMatching(/the files its deploy reads in the "prod" target changed/) });
65
+ });
66
+
67
+ test("anything it can't compare deploys it", async () => {
68
+ expect(await compare(release("b"), { current: undefined })).toMatchObject({ unchanged: false, reason: '"prod" has no deploy of it' });
69
+ expect(await compare(release("b"), { current: record({ releaseDigest: undefined }) })).toMatchObject({ unchanged: false, reason: expect.stringMatching(/was not made from a release/) });
70
+ expect(await compare(release("b"), { stored: [] })).toMatchObject({ unchanged: false, reason: expect.stringMatching(/is not stored here/) });
71
+ expect(await compare(release("b"), { changedPaths: () => null })).toMatchObject({ unchanged: false, reason: expect.stringMatching(/git can't compare/) });
72
+ const none = await compareInputs({ component: "control", inputs: {}, env: "prod", release: release("b"), current: record(), readRelease: async () => before, changedPaths: noChange });
73
+ expect(none).toMatchObject({ unchanged: false });
74
+ });
75
+
76
+ test("a record that already names this release is unchanged, with nothing new to record", async () => {
77
+ expect(await compare(before)).toEqual({ unchanged: true, since: record(), recorded: true });
78
+ });
79
+ });
80
+
81
+ describe("unchangedRecord", () => {
82
+ test("repeats the deploy that stays, under this release, naming it in unchangedSince", () => {
83
+ const since = record({ manifestDigest: "sha256:m", approver: "bob", admission: { op: "control", gate: "prod-release", resolvedAt: "2026-11-01T09:00:00.000Z" } });
84
+ const now = release("b");
85
+ expect(unchangedRecord(since, { releaseDigest: now.releaseDigest, runId: "run-2", timestamp: "2026-11-02T10:00:00.000Z", actor: "ci" })).toEqual({
86
+ component: "control",
87
+ env: "prod",
88
+ digest: "sha256:image",
89
+ gitSha: "a".repeat(40),
90
+ manifestDigest: "sha256:m",
91
+ runId: "run-2",
92
+ timestamp: "2026-11-02T10:00:00.000Z",
93
+ actor: "ci",
94
+ releaseDigest: now.releaseDigest,
95
+ unchangedSince: { env: "prod", runId: "run-1", timestamp: "2026-11-01T10:00:00.000Z" },
96
+ });
97
+ });
98
+ });