@intentius/chant 0.124.27 → 0.124.29

package/src/components/pr-run.ts

@@ -52,6 +52,7 @@ import { remainingFanOut, type ComponentChangeSignal, type FanOutPlan } from "./
 import type { PrApplyRecord } from "./fan-out-record";
 import type { CapabilityRegistry } from "./capability";
 import type { RunProgressEvent } from "./run-progress";
+import type { RunEventSink } from "../run-event-stream";
 import { planWaveComponent, readComponentOutputs } from "./wave-plan";
 
 export interface PrPlanSetOptions {
@@ -64,8 +65,17 @@ export interface PrPlanSetOptions {
   vars?: Record<string, unknown>;
   /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
   seededOutputs?: Record<string, Record<string, unknown>>;
+  /**
+   * Where the planning's events go (#4041): a `plan` phase with no
+   * component, and in it one `plan` step per component, started as its wave
+   * is planned and settled `ok` or `failed`.
+   */
+  onRunEvent?: RunEventSink;
 }
 
+/** The phase a pull request's planning is, in its run's events. */
+export const PR_PLAN_PHASE = "plan";
+
 /** Every member of a pull request, planned. */
 export interface PrPlanSet {
   /** The change-set document over every member. Its digest is what the gate binds. */
@@ -101,6 +111,8 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
   const componentOf = new Map<string, string>();
   const plans: Record<string, Record<string, unknown>> = {};
   let failed = false;
+  const emit = options.onRunEvent;
+  emit?.({ type: "phase-start", component: null, phase: PR_PLAN_PHASE });
 
   for (const wave of options.plan.waves) {
     // The dependencies' outputs first, each read once. A dependency that
@@ -115,7 +127,20 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
       }
     }
     const planned = await Promise.all(
-      wave.map((name) => planWaveComponent(byName.get(name)!, options.registry, deployContext(options, name), outputs)),
+      wave.map(async (name) => {
+        const at = { component: name, phase: PR_PLAN_PHASE, step: "plan" };
+        emit?.({ type: "step-start", ...at });
+        const start = Date.now();
+        const p = await planWaveComponent(byName.get(name)!, options.registry, deployContext(options, name), outputs);
+        emit?.({
+          type: "step-settle",
+          ...at,
+          status: "error" in p ? "failed" : "ok",
+          durationMs: Date.now() - start,
+          ...("error" in p ? { error: p.error } : {}),
+        });
+        return p;
+      }),
     );
     for (const p of planned) {
       const component = byName.get(p.component)!;
@@ -135,6 +160,7 @@ export async function planPrSet(options: PrPlanSetOptions): Promise<PrPlanSet> {
     }
   }
 
+  emit?.({ type: "phase-settle", component: null, phase: PR_PLAN_PHASE, status: failed ? "failed" : "ok" });
   const doc = composeChangeSet(parts);
   const members: PrMember[] = doc.members.map((m) => ({
     member: m.member,
@@ -206,6 +232,8 @@ export interface PrApplyOptions {
   /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
   set: PrPlanSet;
   onProgress?: (event: RunProgressEvent) => void;
+  /** Where the apply's events go (#4041): the fan-out's run events. */
+  onRunEvent?: RunEventSink;
   /**
    * What an earlier attempt at this approved set applied (#3464): its
    * components, which are reported applied and not run again, and the
@@ -230,6 +258,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<{ members: Pr
     plans: options.set.plans,
     componentOutputs: { ...before },
     ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+    ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
     ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
   });
   const completed = new Set(run.completed);

package/src/components/promote-order.test.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from "vitest";
+import { promotionOrder, staticPromotionOrder } from "../workspace/promotion-order";
+import { resolvePromotionSource } from "./promote-order";
+
+describe("promotionOrder (#4030)", () => {
+  test("is the literal entries in order, with canary read from the object form", () => {
+    expect(promotionOrder(["dev", { name: "staging", canary: true }, { name: "prod", endpoint: "http://x" }, "pr-*"])).toEqual([
+      { name: "dev", canary: false },
+      { name: "staging", canary: true },
+      { name: "prod", canary: false },
+    ]);
+  });
+
+  test("is empty without environments, and a repeated name keeps its first place", () => {
+    expect(promotionOrder(undefined)).toEqual([]);
+    expect(promotionOrder(null)).toEqual([]);
+    expect(promotionOrder(["a", "b", "a"]).map((s) => s.name)).toEqual(["a", "b"]);
+  });
+});
+
+describe("resolvePromotionSource (#4030)", () => {
+  const order = promotionOrder(["dev", "staging", "prod"]);
+
+  test("defaults from to the step before to", () => {
+    expect(resolvePromotionSource({ order, to: "prod" })).toEqual({ from: "staging" });
+    expect(resolvePromotionSource({ order, to: "staging" })).toEqual({ from: "dev" });
+  });
+
+  test("an adjacent from is accepted", () => {
+    expect(resolvePromotionSource({ order, to: "prod", from: "staging" })).toEqual({ from: "staging" });
+  });
+
+  test("a from that skips a step is refused, and allowSkip lifts it", () => {
+    const r = resolvePromotionSource({ order, to: "prod", from: "dev" });
+    expect(r).toMatchObject({ error: { code: "promote-skips-environment" } });
+    expect("error" in r && r.error.message).toContain("skips staging");
+    expect("error" in r && r.error.fix).toContain("--allow-skip");
+    expect(resolvePromotionSource({ order, to: "prod", from: "dev", allowSkip: true })).toEqual({ from: "dev" });
+  });
+
+  test("a step outside the order is not judged", () => {
+    expect(resolvePromotionSource({ order, to: "prod", from: "hotfix" })).toEqual({ from: "hotfix" });
+    expect(resolvePromotionSource({ order, to: "pr-42", from: "dev" })).toEqual({ from: "dev" });
+  });
+
+  test("going backwards is not a skip", () => {
+    expect(resolvePromotionSource({ order, to: "dev", from: "prod" })).toEqual({ from: "prod" });
+  });
+
+  test("no order leaves from as given", () => {
+    expect(resolvePromotionSource({ order: [], to: "prod" })).toEqual({ from: undefined });
+    expect(resolvePromotionSource({ order: [], to: "prod", from: "dev" })).toEqual({ from: "dev" });
+  });
+});
+
+describe("staticPromotionOrder (#4030)", () => {
+  test("reads literal strings and objects without running the config, comments left out", () => {
+    const src = `// environments: ["old"]
+import type { ChantConfig } from "@intentius/chant";
+export default {
+  lexicons: ["aws"],
+  /* the order */
+  environments: [
+    "dev",
+    { name: "staging", canary: true },
+    { name: 'prod', endpoint: "http://localhost:4566" },
+    "pr-*",
+  ],
+} satisfies ChantConfig;
+`;
+    expect(staticPromotionOrder(src)).toEqual([
+      { name: "dev", canary: false },
+      { name: "staging", canary: true },
+      { name: "prod", canary: false },
+    ]);
+  });
+
+  test("a config with no environments and no spread declares none", () => {
+    expect(staticPromotionOrder('export default { lexicons: ["aws"] };\n')).toEqual([]);
+  });
+
+  test("anything computed is left to the loader", () => {
+    expect(staticPromotionOrder('export default { environments: [...base, "prod"] };')).toBeUndefined();
+    expect(staticPromotionOrder('const envs = ["a"];\nexport default { environments: envs };')).toBeUndefined();
+    expect(staticPromotionOrder('export default { environments: ["a", `b${x}`] };')).toBeUndefined();
+    expect(staticPromotionOrder('export default { environments: ["a", { name: n }] };')).toBeUndefined();
+    expect(staticPromotionOrder('export default { a: { environments: ["x"] }, environments: ["y"] };')).toBeUndefined();
+    expect(staticPromotionOrder("export default makeConfig();")).toBeUndefined();
+  });
+});

package/src/components/promote-order.ts

@@ -0,0 +1,75 @@
+/**
+ * The environment `chant components promote` reads from, given the member's
+ * promotion order (#4030, see `../workspace/promotion-order.ts`). These
+ * refusals are promote's own and are not codes of the workspace read contract.
+ */
+
+import type { PromotionStep } from "../workspace/promotion-order";
+
+/** The refusals `components promote` gives for the declared order. Stable: scripts may match on them. */
+export const PROMOTE_ORDER_CODES = [
+  /** `--from` is more than one step behind `--to` in the declared order, and `--allow-skip` was not given. */
+  "promote-skips-environment",
+  /** `--to` is the first step of the declared order, so no environment comes before it to default `--from` to. */
+  "promote-no-previous-environment",
+  /** `--from` was left out and `--to` is not a step of the declared order, so there is nothing to default it from. */
+  "promote-to-not-in-order",
+] as const;
+export type PromoteOrderCode = (typeof PROMOTE_ORDER_CODES)[number];
+
+export interface PromotionRefusal {
+  error: { code: PromoteOrderCode; message: string; fix: string };
+}
+
+/**
+ * The environment a promote reads from. With an order declared, `--from`
+ * defaults to the step before `to`, and a `--from` that skips a step is
+ * refused unless `allowSkip`. Without an order, or when `to` or `from` is not
+ * a step of it, the order has nothing to say and `from` is returned as given
+ * (`undefined` is the caller's to refuse, as before).
+ */
+export function resolvePromotionSource(opts: {
+  order: readonly PromotionStep[];
+  to: string;
+  from?: string;
+  allowSkip?: boolean;
+}): { from: string | undefined } | PromotionRefusal {
+  const { order, to, from, allowSkip } = opts;
+  const names = order.map((s) => s.name);
+  const list = names.join(", ");
+  const toAt = names.indexOf(to);
+  if (from === undefined) {
+    if (order.length === 0) return { from: undefined };
+    if (toAt < 0) {
+      return {
+        error: {
+          code: "promote-to-not-in-order",
+          message: `--from was not given, and "${to}" is not a step of the declared promotion order (${list})`,
+          fix: `Pass --from <env>, or add "${to}" to the environments array of this member's chant.config.ts.`,
+        },
+      };
+    }
+    if (toAt === 0) {
+      return {
+        error: {
+          code: "promote-no-previous-environment",
+          message: `"${to}" is the first step of the declared promotion order (${list}), so there is no environment to promote from`,
+          fix: `Deploy "${to}" with chant run --env ${to}, or pass --from <env> to promote from an environment outside the order.`,
+        },
+      };
+    }
+    return { from: names[toAt - 1] };
+  }
+  const fromAt = names.indexOf(from);
+  if (toAt >= 0 && fromAt >= 0 && fromAt < toAt - 1 && !allowSkip) {
+    const skipped = names.slice(fromAt + 1, toAt);
+    return {
+      error: {
+        code: "promote-skips-environment",
+        message: `promoting ${from} to ${to} skips ${skipped.join(", ")} in the declared promotion order (${list})`,
+        fix: `Promote to ${skipped[0]} first, or pass --allow-skip to promote ${from} to ${to} anyway.`,
+      },
+    };
+  }
+  return { from };
+}

package/src/components/promote.test.ts

@@ -2,7 +2,7 @@
  * Promote a release without rebuilding (#2530).
  */
 
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { describeGateMismatch, memoryGateLedgerPort, type GateLedgerPort } from "../op/gate";
 import { componentPlanDigest } from "./gate-plan";
@@ -20,6 +20,7 @@ import {
   runPromotion,
   promotionRecord,
   gateApprover,
+  gateAdmission,
   promoteArchivePaths,
   hasPublishStep,
   parseDigestPins,
@@ -282,10 +283,15 @@ describe("running a promotion", () => {
     const { registry, ran } = fakeRegistry({ api: "sha256:api" });
     const opts = { plan: planFor("api", "sha256:api"), components: [prepared(gated)], registry, gates };
 
+    vi.stubEnv("GITHUB_RUN_ID", "9001");
+    vi.stubEnv("GITHUB_SHA", "e".repeat(40));
     const first = await runPromotion({ ...opts, now: "2026-01-03T00:00:00Z" });
     expect(first.status).toBe("gated");
     expect(first.gate?.gate).toBe("prod-release");
     expect(ran).not.toContain("prod:api:apply");
+    // #4020: the pending fact of a component gate names the CI run, and a commit.
+    expect(first.gate?.runId).toBe("9001");
+    expect(first.gate?.gitSha).toMatch(/^[0-9a-f]{40}$/);
 
     // `chant approve` copies the pending fact's environment and plan (#2574).
     const bound = { planDigest: first.gate!.planDigest!, environment: first.gate!.environment! };
@@ -294,6 +300,9 @@ describe("running a promotion", () => {
     const second = await runPromotion({ ...opts, now: "2026-01-03T00:02:00Z" });
     expect(second.status).toBe("ok");
     expect(gateApprover(second.results[0])).toBe("alice");
+    // #4020: and the gate resolution that admitted the deploy.
+    expect(gateAdmission(second.results[0])).toEqual({ op: "api", gate: "prod-release", resolvedAt: "2026-01-03T00:01:00Z" });
+    vi.unstubAllEnvs();
 
     // The same approval does not pass a promote of another release (#2574).
     const other = await runPromotion({

package/src/components/promote.ts

@@ -39,7 +39,7 @@
  */
 
 import { parseWiringRef, type WiringRef } from "../lint/rules/comp/support";
-import { latestPerComponent, type ReleaseRecord, type ReleaseRecordInput, type RunOrigin } from "../lifecycle/release-ledger";
+import { latestPerComponent, type ReleaseRecord, type ReleaseRecordInput, type ReleaseAdmission, type RunOrigin } from "../lifecycle/release-ledger";
 import { CapabilityRegistry, type Capability } from "./capability";
 import {
   runInterpretDriver,
@@ -47,12 +47,15 @@ import {
   type DriverComponent,
   type DriverComponentResult,
   type DriverGate,
+  type ReleaseGateBinding,
   type DriverPhase,
   type DriverRunResult,
   type DriverStep,
 } from "./driver";
 import type { GateLedgerPort } from "../op/gate";
+import type { Release } from "../lifecycle/release-store";
 import type { RunProgressEvent } from "./run-progress";
+import type { RunEventSink } from "../run-event-stream";
 
 /**
  * Step kinds that produce an artifact at build time: the build family, and the
@@ -247,6 +250,66 @@ export function planRollback(input: {
   return { from: env, to: env, items: [{ component, digest: target.digest, source: target }], notPromoted: [] };
 }
 
+/**
+ * Decide what a rollback to a release restores (#4035): every component of
+ * `release`, each at the newest record in `env`'s ledger that names the
+ * release, so the digest restored is the one the environment ran from it. A
+ * component of the release this checkout does not declare is reported and
+ * left alone. One the environment never ran from the release has no recorded
+ * digest, and is refused. So is a release the environment already runs,
+ * unless one of its components is `unsettled` (a run left it failed or gated):
+ * then the rollback is what puts that component back too.
+ */
+export function planReleaseRollback(input: {
+  env: string;
+  records: ReleaseRecord[];
+  declared: string[];
+  release: Pick<Release, "releaseDigest" | "artifactDigests" | "targets">;
+  /** The release's label, or null; used in messages. */
+  label: string | null;
+  /** Components a run left failed or gated in `env` (../lifecycle/mixed-environment.ts). */
+  unsettled?: ReadonlySet<string>;
+}): PromotionPlan | { error: string } {
+  const { env, records, declared, release } = input;
+  const name = input.label ?? release.releaseDigest;
+  const target = release.targets.find((t) => t.env === env);
+  const inRelease = new Set<string>();
+  for (const t of target?.templates ?? []) if (t.component !== null) inRelease.add(t.component);
+  for (const a of release.artifactDigests) inRelease.add(a.component);
+  const items: PromotionItem[] = [];
+  const notPromoted: PromotionPlan["notPromoted"] = [];
+  const neverRan: string[] = [];
+  for (const component of [...inRelease].sort()) {
+    if (!declared.includes(component)) {
+      notPromoted.push({ component, reason: `in release ${name} but not declared in this checkout` });
+      continue;
+    }
+    const ran = records.filter((r) => r.component === component && r.releaseDigest === release.releaseDigest);
+    if (ran.length === 0) {
+      neverRan.push(component);
+      continue;
+    }
+    const record = latestPerComponent(ran).get(component)!;
+    items.push({ component, digest: record.digest, source: record });
+  }
+  if (neverRan.length > 0) {
+    return {
+      error: `release ${name} never deployed ${neverRan.map((c) => `"${c}"`).join(", ")} to "${env}", so no recorded digest can be restored; ` +
+        `promote it instead: chant components promote --to ${env} --release ${name}`,
+    };
+  }
+  if (items.length === 0) return { error: `release ${name} has no component declared in this checkout` };
+  const current = latestPerComponent(records);
+  const already = items.every((i) => {
+    const now = current.get(i.component);
+    return now !== undefined && now.releaseDigest === release.releaseDigest && now.digest === i.digest && !input.unsettled?.has(i.component);
+  });
+  if (already) {
+    return { error: `"${env}" already runs release ${name}; nothing to roll back. After a deploy that failed partway, chant components redeploy puts a component's release back` };
+  }
+  return { from: env, to: env, items, notPromoted };
+}
+
 /**
  * Decide what a redeploy deploys: the release of `component` the ledger in
  * `env` records as current. A deploy that fails partway records nothing, so
@@ -535,8 +598,12 @@ export interface RunPromotionOptions {
   registry: CapabilityRegistry;
   componentOutputs?: Record<string, Record<string, unknown>>;
   gates?: GateLedgerPort;
+  /** A promote under a release (#4045): what every gate it reaches binds. */
+  releaseGate?: ReleaseGateBinding;
   now?: string;
   onProgress?: (event: RunProgressEvent) => void;
+  /** Where the run's events go (#4041, `--events-json`). */
+  onRunEvent?: RunEventSink;
 }
 
 /**
@@ -566,7 +633,9 @@ export async function runPromotion(options: RunPromotionOptions): Promise<Driver
         return item ? { version: item.digest, revision: item.source.gitSha } : undefined;
       },
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+      ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
       ...(options.gates ? { gates: options.gates } : {}),
+      ...(options.releaseGate ? { releaseGate: options.releaseGate } : {}),
       ...(options.now ? { now: options.now } : {}),
     });
   } catch (err) {
@@ -584,6 +653,20 @@ export function gateApprover(result: DriverComponentResult | undefined): string
   return approver;
 }
 
+/**
+ * The gate resolution that admitted a component's last gate in this run (#4020):
+ * which gate, in the component's gate ledger, and when the resolution was
+ * recorded. Undefined for a component that passed no gate.
+ */
+export function gateAdmission(result: DriverComponentResult | undefined): ReleaseAdmission | undefined {
+  let admission: ReleaseAdmission | undefined;
+  for (const record of result?.records ?? []) {
+    // #4045: a release gate's resolution is in the release gate's ledger, not the component's.
+    if (record.approval) admission = { op: record.approval.op ?? result!.component, gate: record.approval.gate, resolvedAt: record.approval.timestamp };
+  }
+  return admission;
+}
+
 /** What a promote, rollback or redeploy knows about its own run, for the records it writes. */
 export interface DeployRunInfo {
   runId: string;
@@ -591,6 +674,8 @@ export interface DeployRunInfo {
   actor: string;
   timestamp: string;
   approver?: string;
+  /** The gate resolution that admitted the deploy (#4020), from {@link gateAdmission}. */
+  admission?: ReleaseAdmission;
 }
 
 /** The fields a promote, a rollback and a redeploy record share: the artifact is the earlier release's own. */
@@ -606,6 +691,7 @@ function sharedRecord(item: PromotionItem, env: string, run: DeployRunInfo): Rel
     timestamp: run.timestamp,
     actor: run.actor,
     ...(run.approver ? { approver: run.approver } : {}),
+    ...(run.admission ? { admission: run.admission } : {}),
     ...(source.manifestDigest ? { manifestDigest: source.manifestDigest } : {}),
     ...(source.inputDigest ? { inputDigest: source.inputDigest } : {}),
   };
@@ -616,6 +702,11 @@ function refTo(record: ReleaseRecord) {
   return { env: record.env, runId: record.runId, timestamp: record.timestamp };
 }
 
+/** A rollback and a redeploy put an earlier deploy back, so they name the release it came from (#4043). */
+function releaseOf(source: ReleaseRecord): { releaseDigest?: string } {
+  return source.releaseDigest !== undefined ? { releaseDigest: source.releaseDigest } : {};
+}
+
 /**
  * The release record a successful promotion appends to the target ledger.
  * The digest, git sha and archive identities are the source release's own,
@@ -632,7 +723,7 @@ export function promotionRecord(item: PromotionItem, to: string, run: DeployRunI
  * release.
  */
 export function rollbackRecord(item: PromotionItem, env: string, run: DeployRunInfo): ReleaseRecordInput {
-  return { ...sharedRecord(item, env, run), restores: refTo(item.source) };
+  return { ...sharedRecord(item, env, run), restores: refTo(item.source), ...releaseOf(item.source) };
 }
 
 /**
@@ -642,5 +733,5 @@ export function rollbackRecord(item: PromotionItem, env: string, run: DeployRunI
  * change, and the record says when it was last put back.
  */
 export function redeployRecord(item: PromotionItem, env: string, run: DeployRunInfo): ReleaseRecordInput {
-  return { ...sharedRecord(item, env, run), redeploys: refTo(item.source) };
+  return { ...sharedRecord(item, env, run), redeploys: refTo(item.source), ...releaseOf(item.source) };
 }

package/src/components/release-compile.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Compiling one environment of a release, and building its artifacts once
+ * (#4026, ws-104 question 5), against fixture projects in temp directories.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CapabilityRegistry, type DeployContext } from "./capability";
+import type { DriverComponent } from "./driver";
+import {
+  buildReleaseArtifacts,
+  buildStepsOf,
+  compileEnvironment,
+  ReleaseCompileError,
+  templateRefs,
+  withOnlyArchiveSteps,
+} from "./release-compile";
+
+const api: DriverComponent = {
+  name: "api",
+  dependsOn: ["db"],
+  deploy: [
+    { phase: "Build", steps: [{ kind: "docker-build", context: "api", into: "api.tar" }, { kind: "zip-package", source: "fn", into: "fn.zip" }] },
+    { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar", template: "not-a-template.json" }] },
+    {
+      phase: "Apply",
+      steps: [
+        { kind: "gate", gate: "prod" },
+        { kind: "cfn-deploy", template: "dist/api.template.json", imageRef: "@Publish.digest" },
+        { kind: "cfn-deploy", template: "archive:dist/edge.template.json" },
+        { kind: "helm-upgrade", chart: "charts/api", values: ["values/base.yaml", "$env.VALUES"] },
+        { kind: "kubectl-apply", manifest: "@Render.path" },
+        { phase: "Nested", steps: [{ kind: "kubectl-apply", manifest: "k8s/api.yaml" }] },
+      ],
+    },
+  ],
+};
+
+describe("templateRefs", () => {
+  test("lists the literal paths in template, manifest and values of deploy steps, without build or publish steps", () => {
+    expect(templateRefs(api).map((r) => [r.kind, r.field, r.path])).toEqual([
+      ["cfn-deploy", "template", "dist/api.template.json"],
+      ["cfn-deploy", "template", "dist/edge.template.json"],
+      ["helm-upgrade", "values", "values/base.yaml"],
+      ["kubectl-apply", "manifest", "k8s/api.yaml"],
+    ]);
+  });
+});
+
+describe("withOnlyArchiveSteps", () => {
+  test("keeps the archive steps alone, drops gates and every other step, and the dependencies", () => {
+    expect(withOnlyArchiveSteps(api)).toEqual({
+      name: "api",
+      dependsOn: [],
+      deploy: [{ phase: "Build", steps: [{ kind: "docker-build", context: "api", into: "api.tar" }, { kind: "zip-package", source: "fn", into: "fn.zip" }] }],
+    });
+    expect(withOnlyArchiveSteps({ name: "x", deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }] })).toBeUndefined();
+  });
+
+  test("buildStepsOf lists the build-time steps in order", () => {
+    expect(buildStepsOf(api).map((s) => s.kind)).toEqual(["docker-build", "zip-package"]);
+  });
+});
+
+function project(dir: string): void {
+  writeFileSync(
+    join(dir, "api.component.ts"),
+    `export const api = {
+      name: "api",
+      dependsOn: [],
+      deploy: [
+        { phase: "Build", steps: [{ kind: "docker-build", context: "svc", into: "api.tar" }] },
+        { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:api.tar" }] },
+        { phase: "Apply", steps: [{ kind: "gate", gate: "go" }, { kind: "cfn-deploy", template: "dist/api.template.json", imageRef: "@Publish.digest" }] },
+      ],
+    };
+    export const off = { name: "off", dependsOn: [], enabled: false, deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "dist/missing.json" }] }] };
+    `,
+  );
+  mkdirSync(join(dir, "svc"), { recursive: true });
+  writeFileSync(join(dir, "svc", "Dockerfile"), "FROM scratch\n");
+}
+
+describe("compileEnvironment", () => {
+  test("runs the build command with CHANT_ENV, then reads the templates the enabled components name", async () => {
+    await withTestDir(async (dir) => {
+      project(dir);
+      const target = await compileEnvironment(
+        { projectDir: dir, buildCommand: `mkdir -p dist && printf '{"env":"%s"}' "$CHANT_ENV" > dist/api.template.json` },
+        "staging",
+      );
+      expect(target.env).toBe("staging");
+      expect(target.components).toEqual(["api"]);
+      expect(target.templates).toEqual([{ component: "api", path: "dist/api.template.json", content: `{"env":"staging"}` }]);
+      expect(target.buildSteps).toEqual({ api: [{ kind: "docker-build", context: "svc", into: "api.tar" }] });
+      expect(target.buildInputs).toEqual({ api: ["svc", "svc/Dockerfile"] });
+      expect(target.componentFiles).toEqual({ api: "api.component.ts" });
+    });
+  });
+
+  test("refuses when a template a deploy names does not exist after the build", async () => {
+    await withTestDir(async (dir) => {
+      project(dir);
+      const err = await compileEnvironment({ projectDir: dir }, "dev").catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(ReleaseCompileError);
+      expect((err as Error).message).toMatch(/reads template "dist\/api.template.json", and no such file exists after the build for "dev"/);
+    });
+  });
+
+  test("refuses when the build command fails", async () => {
+    await withTestDir(async (dir) => {
+      project(dir);
+      await expect(compileEnvironment({ projectDir: dir, buildCommand: "exit 3" }, "dev")).rejects.toThrow(/the build command for "dev" exited 3/);
+    });
+  });
+});
+
+describe("buildReleaseArtifacts", () => {
+  test("runs only the archive steps, once, and names each image and asset with its digest", async () => {
+    await withTestDir(async (dir) => {
+      writeFileSync(
+        join(dir, "api.component.ts"),
+        `export const api = {
+          name: "api",
+          dependsOn: [],
+          deploy: [
+            { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: "api.tar" }, { kind: "zip-package", source: "fn", into: "fn.zip" }] },
+            { phase: "Apply", steps: [{ kind: "gate", gate: "go" }, { kind: "cfn-deploy", template: "t.json" }] },
+          ],
+        };`,
+      );
+      const ran: string[] = [];
+      const registry = new CapabilityRegistry();
+      registry.register({ kind: "docker-build", async run(ctx: DeployContext, input: { into: string }) { ran.push(`${ctx.env}:docker-build`); return { archivePath: input.into, digest: "sha256:img" }; } } as never);
+      registry.register({ kind: "zip-package", async run(ctx: DeployContext, input: { into: string }) { ran.push(`${ctx.env}:zip-package`); return { archivePath: input.into, digest: "sha256:zip" }; } } as never);
+      registry.register({ kind: "cfn-deploy", async run() { ran.push("cfn-deploy"); return {}; } } as never);
+      const artifacts = await buildReleaseArtifacts({ projectDir: dir }, "dev", ["api"], registry);
+      expect(ran).toEqual(["dev:docker-build", "dev:zip-package"]);
+      expect(artifacts).toEqual([
+        { component: "api", kind: "image", path: "api.tar", digest: "sha256:img" },
+        { component: "api", kind: "asset", path: "fn.zip", digest: "sha256:zip" },
+      ]);
+    });
+  });
+});