@intentius/chant 0.124.26 → 0.124.28

package/src/cli/handlers/promote.ts

@@ -17,9 +17,12 @@
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { loadChantConfig, type ChantConfig } from "../../config";
+import { promotionOrder } from "../../workspace/promotion-order";
+import { resolvePromotionSource } from "../../components/promote-order";
 import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git";
 import {
   appendReleaseRecord,
+  latestPerComponent,
   readReleaseLedger,
   resolveRunId,
   type ReleaseRecord,
@@ -30,6 +33,7 @@ import { applyConfigDefaults } from "../../components/config-defaults";
 import { fanOutRegistry } from "../../components/fan-out-support";
 import { renderDriverHuman } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
+import { openCliRunEvents, refusesBothStreams } from "../run-events";
 import {
   parseDigestPins,
   planPromotion,
@@ -41,20 +45,23 @@ import {
   rollbackRecord,
   redeployRecord,
   gateApprover,
+  gateAdmission,
   type DeployRunInfo,
   type PromotionItem,
   type PromotionPlan,
 } from "../../components/promote";
 import type { DriverComponent } from "../../components/driver";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
-import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate";
+import { approveCommand, describeGateMismatch, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../../op/gate";
+import type { ReleaseGateBinding } from "../../components/driver";
+import type { ChangeSetDocument } from "../../change-set";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { GATED_EXIT_CODE } from "./run";
 import type { CommandContext } from "../registry";
 
 const PROMOTE_USAGE =
-  "chant components promote --from <env> --to <env> [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
+  "chant components promote --to <env> [--from <env>] [--allow-skip] [--release <label|digest>] [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
 const ROLLBACK_USAGE =
   "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 const REDEPLOY_USAGE =
@@ -62,6 +69,13 @@ const REDEPLOY_USAGE =
 
 type Verb = "promote" | "rollback" | "redeploy";
 
+/** The release a promote deploys under (#4026), and its target for the environment promoted to. */
+interface UnderRelease {
+  release: import("../../lifecycle/release-store").Release;
+  label: string | null;
+  target: import("../../lifecycle/release-store").ReleaseTarget;
+}
+
 function renderPlan(verb: Verb, plan: PromotionPlan, removed: Map<string, string[]>): void {
   console.error(formatBold(verb === "promote" ? `promote ${plan.from} -> ${plan.to}` : `${verb} ${plan.to}`));
   for (const item of plan.items) {
@@ -129,6 +143,115 @@ async function readLedger(env: string): Promise<ReleaseRecord[]> {
   return ledger.records;
 }
 
+/**
+ * Plan, store and bind the release gate for a promote under a release
+ * (#4045, ws-104 questions 2 and 6). Undefined when no promoted composition
+ * declares a gate, so there is nothing to bind. A number is the exit code of
+ * a refusal already printed: a provisional member, or a member that failed
+ * to plan. On an empty change set, each gate gets an `empty: true`
+ * resolution the run then counts once it reads the stored document back.
+ */
+async function bindReleaseGate(input: {
+  plan: PromotionPlan;
+  prepared: DriverComponent[];
+  under: UnderRelease;
+  registry: Awaited<ReturnType<typeof fanOutRegistry>>;
+  port: GateLedgerPort;
+  seededOutputs: Record<string, Record<string, unknown>>;
+  actor: string;
+  projectPath: string;
+  head: string | undefined;
+}): Promise<{ binding: ReleaseGateBinding; doc: ChangeSetDocument; empty: boolean } | number | undefined> {
+  const { plan, under, port } = input;
+  const gate = await import("../../components/release-gate");
+  const gates = gate.gateNamesOf(input.prepared);
+  if (gates.length === 0) return undefined;
+  const env = plan.to;
+  const releaseDigest = under.release.releaseDigest;
+
+  // What the environment runs now, to compare each component with.
+  const { readRelease } = await import("../../lifecycle/release-store");
+  const latest = latestPerComponent((await readLedger(env)).filter((r) => r.env === env));
+  const releases = new Map<string, import("../../lifecycle/release-store").Release | null>();
+  const current = new Map<string, import("../../components/release-gate").CurrentDeploy>();
+  for (const item of plan.items) {
+    const record = latest.get(item.component);
+    if (!record) continue;
+    const named = record.releaseDigest;
+    if (named !== undefined && !releases.has(named)) releases.set(named, await readRelease(named).catch(() => null));
+    current.set(item.component, { record, release: named !== undefined ? (releases.get(named) ?? null) : null });
+  }
+
+  const doc = await gate.planReleaseChangeSet({
+    release: under.release,
+    env,
+    components: input.prepared,
+    digests: new Map(plan.items.map((i) => [i.component, i.digest])),
+    registry: input.registry,
+    current,
+    seededOutputs: input.seededOutputs,
+  });
+  const provisional = gate.provisionalMembers(doc);
+  if (provisional.length > 0) {
+    console.error(formatError({
+      message: `the change set of release ${under.label ?? releaseDigest} for "${env}" has provisional members (${provisional.join(", ")}), which no approval covers; nothing was deployed`,
+      hint: "Deploy what they read first, so they plan against real values.",
+    }));
+    return 1;
+  }
+  const failed = doc.members.filter((m) => m.status === "failed");
+  if (failed.length > 0) {
+    for (const m of failed) console.error(formatError({ message: `${m.member} failed to plan for "${env}"${m.error ? `: ${m.error}` : ""}` }));
+    console.error(formatError({ message: "nothing was deployed" }));
+    return 1;
+  }
+
+  // The document is stored before the gate is decided, so the plan a pending
+  // gate waits on can be read, and an empty pass can be checked.
+  const { storeGateChangeSet } = await import("../../lifecycle/gate-change-set");
+  try {
+    const stored = await storeGateChangeSet({ doc, cwd: input.projectPath, at: input.head ?? null });
+    if (stored.warning) console.error(formatWarning({ message: stored.warning }));
+  } catch (err) {
+    console.error(formatWarning({ message: `could not store the change set ${doc.digest}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+  const { isEmptyChangeSet } = await import("../../change-set");
+  const empty = isEmptyChangeSet(doc);
+  console.error(formatInfo(
+    `release gate: change set ${doc.digest} for "${env}"` +
+      (empty ? ", empty: its gates pass without an approval" : `, ${doc.summary.entries} entr${doc.summary.entries === 1 ? "y" : "ies"}, ${doc.summary.holes} hole(s)`) +
+      ` (chant change-set show ${doc.digest})`,
+  ));
+
+  if (empty) {
+    if (!port.appendResolution) throw new Error("the gate ledger can't record a resolution, so an empty change set can't pass its gates");
+    const { resolutions } = await port.read(gate.RELEASE_GATE_OP);
+    const timestamp = new Date().toISOString();
+    for (const name of gates) {
+      const standing = resolutions.some(
+        (r) => r.empty === true && r.gate === name && r.environment === env && r.releaseDigest === releaseDigest && r.planDigest === doc.digest,
+      );
+      if (standing) continue;
+      // Pushed with the resolution; the deploy records the promote writes push the same branch.
+      await port.appendResolution(
+        gate.emptyResolution({ gate: name, doc, actor: input.actor, timestamp, ...(input.head ? { gitSha: input.head } : {}) }),
+      );
+    }
+  }
+
+  const { readStoredChangeSet } = await import("../../lifecycle/change-set-store");
+  return {
+    doc,
+    empty,
+    binding: {
+      op: gate.RELEASE_GATE_OP,
+      planDigest: doc.digest,
+      releaseDigest,
+      verifyEmpty: gate.emptyVerifier((digest) => readStoredChangeSet(digest, { cwd: input.projectPath }), { releaseDigest, environment: env }),
+    },
+  };
+}
+
 /**
  * Prepare, run and record a plan. Shared by promote, rollback and redeploy,
  * which differ only in how the plan was chosen, whether the publish step runs,
@@ -141,8 +264,10 @@ async function deployPlan(
   project: { projectPath: string; config: ChantConfig; targets: DriverComponent[] },
   actor: string | undefined,
   record: (item: PromotionItem, env: string, run: DeployRunInfo) => ReleaseRecordInput,
+  under?: UnderRelease,
 ): Promise<number> {
   const { args } = ctx;
+  if (refusesBothStreams(args)) return 1;
   const byName = new Map(project.targets.map((c) => [c.name, applyConfigDefaults(c, project.config)]));
   const prepared: DriverComponent[] = [];
   const removed = new Map<string, string[]>();
@@ -166,6 +291,37 @@ async function deployPlan(
     return 1;
   }
 
+  // #4026: under a release, the deploy reads the templates the release
+  // recorded for this environment, checked against their digests.
+  let pinnedFiles: import("../../components/release-promote").PinnedTemplate[] = [];
+  if (under) {
+    const { pinReleaseTemplates } = await import("../../components/release-promote");
+    const { readReleaseTemplate } = await import("../../lifecycle/release-store");
+    const pinned = await pinReleaseTemplates(prepared, under.release, under.target, (digest) => readReleaseTemplate(digest));
+    if ("errors" in pinned) {
+      for (const message of pinned.errors) console.error(formatError({ message }));
+      console.error(formatError({ message: `nothing was deployed` }));
+      return 1;
+    }
+    prepared.splice(0, prepared.length, ...pinned.components);
+    pinnedFiles = pinned.files;
+    for (const item of plan.items) {
+      const named = item.source.releaseDigest;
+      if (named !== undefined && named !== under.release.releaseDigest) {
+        console.error(formatWarning({ message: `${item.component}: the ${plan.from} deploy being promoted came from release ${named}, not ${under.release.releaseDigest}` }));
+      }
+    }
+    // #4045: the artifact deployed against the artifacts the release built.
+    const { releaseArtifactMismatches } = await import("../../components/release-promote");
+    const { readBuildManifest } = await import("../../lifecycle/build-ledger-store");
+    const mismatches = await releaseArtifactMismatches(
+      under.release,
+      plan.items.map((i) => ({ component: i.component, source: i.source })),
+      (digest) => readBuildManifest(digest).catch(() => null),
+    );
+    for (const message of mismatches) console.error(formatWarning({ message }));
+  }
+
   // The composition deployed is this checkout's. Say so when it is not the
   // commit the artifact was built from.
   const head = await getHeadCommit().catch(() => undefined);
@@ -178,12 +334,24 @@ async function deployPlan(
     }
   }
 
+  const releaseJson: { release?: { releaseDigest: string; label: string | null; templates: unknown[] } } = under
+    ? { release: { releaseDigest: under.release.releaseDigest, label: under.label, templates: under.target.templates } }
+    : {};
   if (args.dryRun) {
-    if (args.json) console.log(JSON.stringify(planJson(plan, removed), null, 2));
-    else renderPlan(verb, plan, removed);
+    if (args.json) console.log(JSON.stringify({ ...planJson(plan, removed), ...releaseJson }, null, 2));
+    else {
+      renderPlan(verb, plan, removed);
+      if (under) console.error(`  under release ${under.label ?? under.release.releaseDigest}: ${under.target.templates.length} template(s) from its "${plan.to}" target`);
+    }
     return 0;
   }
   if (!args.json) renderPlan(verb, plan, removed);
+  // #4045: the pinned templates are written for this run and removed after it.
+  const { writePinnedTemplates, removePinnedTemplates } = await import("../../components/release-promote");
+  const tidy = () => {
+    if (pinnedFiles.length > 0) removePinnedTemplates(project.projectPath, pinnedFiles);
+  };
+  if (pinnedFiles.length > 0) writePinnedTemplates(project.projectPath, pinnedFiles);
 
   const seededOutputs: Record<string, Record<string, unknown>> = {};
   for (const file of args.seedOutputs ?? []) {
@@ -191,35 +359,78 @@ async function deployPlan(
       Object.assign(seededOutputs, JSON.parse(readFileSync(resolve(file), "utf8")));
     } catch (err) {
       console.error(formatError({ message: `--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` }));
+      tidy();
       return 1;
     }
   }
 
   const registry = await fanOutRegistry(project.projectPath, project.config);
-  const run = await runPromotion({
-    plan,
-    components: prepared,
-    registry,
-    componentOutputs: seededOutputs,
-    ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+  const port = gitGateLedgerPort();
+  // #4045: under a release, every gate binds the release's change set for this environment.
+  let releaseGate: ReleaseGateBinding | undefined;
+  let changeSetJson: { changeSet: string; empty: boolean } | undefined;
+  if (under) {
+    try {
+      const bound = await bindReleaseGate({ plan, prepared, under, registry, port, seededOutputs, actor: actor!, projectPath: project.projectPath, head });
+      if (typeof bound === "number") {
+        tidy();
+        return bound;
+      }
+      if (bound) {
+        releaseGate = bound.binding;
+        changeSetJson = { changeSet: bound.doc.digest, empty: bound.empty };
+      }
+    } catch (err) {
+      tidy();
+      throw err;
+    }
+  }
+  // The run id the release records carry, chosen before the run so that
+  // `--events-json` (#4041) names the run by it too.
+  const { runId, runOrigin } = resolveRunId(args.runId);
+  const events = await openCliRunEvents(args, {
+    kind: "component",
+    name: `${verb} ${plan.items.map((i) => i.component).join(",")} in ${plan.to}`,
+    runId,
+    cwd: project.projectPath,
   });
+  let run: Awaited<ReturnType<typeof runPromotion>>;
+  try {
+    run = await runPromotion({
+      plan,
+      components: prepared,
+      registry,
+      componentOutputs: seededOutputs,
+      gates: port,
+      ...(releaseGate ? { releaseGate } : {}),
+      ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+      ...(events ? { onRunEvent: events.emit } : {}),
+    });
+  } catch (err) {
+    events?.settle("failed", err instanceof Error ? err.message : String(err));
+    throw err;
+  } finally {
+    tidy();
+  }
+  // The driver settles the stream; this only ends one it left open.
+  events?.settle(run.status === "fail" ? "failed" : run.status);
   if (!args.json) renderDriverHuman(run);
 
   // Record every component that deployed, whatever happened to the rest: a
   // component that reached the environment and is missing from its ledger
   // would be exactly the unrecorded deploy the ledger exists to rule out.
   const deployed = plan.items.filter((item) => run.results.some((r) => r.component === item.component && r.status === "ok"));
-  const { runId, runOrigin } = resolveRunId(args.runId);
   const timestamp = new Date().toISOString();
   const recorded: ReleaseRecord[] = [];
   let recordError: string | undefined;
   if (deployed.length > 0) {
     try {
       for (const item of deployed) {
-        const approver = gateApprover(run.results.find((r) => r.component === item.component));
-        const { record: written } = await appendReleaseRecord(
-          record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor!, timestamp, ...(approver ? { approver } : {}) }),
-        );
+        const result = run.results.find((r) => r.component === item.component);
+        const approver = gateApprover(result);
+        const admission = gateAdmission(result);
+        const input = record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor!, timestamp, ...(approver ? { approver } : {}), ...(admission ? { admission } : {}) });
+        const { record: written } = await appendReleaseRecord(under ? { ...input, releaseDigest: under.release.releaseDigest } : input);
         recorded.push(written);
       }
       await pushLifecycle();
@@ -229,7 +440,8 @@ async function deployPlan(
   }
 
   if (args.json) {
-    console.log(JSON.stringify({ ...planJson(plan, removed), run, recorded }, null, 2));
+    const withChangeSet = under && changeSetJson ? { release: { ...releaseJson.release!, ...changeSetJson } } : releaseJson;
+    console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, run, recorded }, null, 2));
   } else {
     for (const r of recorded) {
       console.error(formatSuccess(
@@ -296,10 +508,9 @@ function actorOrRefuse(ctx: CommandContext): { actor: string | undefined } | num
 
 export async function runComponentsPromote(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
-  const from = args.migrateFrom;
   const to = args.migrateTo;
-  if (!from || !to) {
-    console.error(formatError({ message: "--from <env> and --to <env> are required", hint: PROMOTE_USAGE }));
+  if (!to) {
+    console.error(formatError({ message: "--to <env> is required", hint: PROMOTE_USAGE }));
     return 1;
   }
   const who = actorOrRefuse(ctx);
@@ -308,6 +519,25 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
   const project = await loadProject(ctx, args.component ?? "all");
   if (typeof project === "number") return project;
 
+  // The member's `environments` array is its promotion order (#4030). It
+  // defaults --from and refuses a skipped step; a member that declares none
+  // has no order, so --from is required and nothing is refused.
+  const resolved = resolvePromotionSource({
+    order: promotionOrder(project.config.environments),
+    to,
+    ...(args.migrateFrom ? { from: args.migrateFrom } : {}),
+    ...(args.allowSkip ? { allowSkip: true } : {}),
+  });
+  if ("error" in resolved) {
+    console.error(formatError({ message: `${resolved.error.message} [${resolved.error.code}]`, hint: resolved.error.fix }));
+    return 1;
+  }
+  const from = resolved.from;
+  if (!from) {
+    console.error(formatError({ message: "--from <env> is required: this member declares no environments, so there is no promotion order to default it from", hint: PROMOTE_USAGE }));
+    return 1;
+  }
+
   // Without --component, each --digest is <component>=<digest> (#2602): a
   // generated promote job pins every component to the release its own
   // pipeline run recorded, rather than whatever is latest in --from.
@@ -326,6 +556,35 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
   }
 
   await fetchLifecycle().catch(() => false);
+
+  // #4026: --release names the release this promote deploys, by label or digest.
+  let under: UnderRelease | undefined;
+  if (args.release) {
+    const { resolveRelease } = await import("../../lifecycle/release-store");
+    const { targetFor, isImplicitRelease } = await import("../../components/release-promote");
+    const found = await resolveRelease(args.release);
+    if (!found) {
+      console.error(formatError({ message: `no release is labelled or digested "${args.release}" in this member`, hint: "List them with: chant release list" }));
+      return 1;
+    }
+    const target = targetFor(found.release, to);
+    if ("error" in target) {
+      console.error(formatError({ message: target.error }));
+      return 1;
+    }
+    // #4046: a release of a project with no components records build output
+    // and no component, so there is no deploy step here to point at it.
+    if (isImplicitRelease(found.release)) {
+      const name = found.label ?? found.release.releaseDigest;
+      console.error(formatError({
+        message: `release ${name} is of a project with no components, so promote has no component to deploy`,
+        hint: `Write its "${to}" build output with \`chant release export ${name} --env ${to}\`, then run the project's own deploy against those files.`,
+      }));
+      return 1;
+    }
+    under = { release: found.release, label: found.label, target: target.target };
+  }
+
   const plan = planPromotion({
     from,
     to,
@@ -339,7 +598,7 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: plan.error, hint: PROMOTE_USAGE }));
     return 1;
   }
-  return deployPlan(ctx, "promote", plan, project, who.actor, promotionRecord);
+  return deployPlan(ctx, "promote", plan, project, who.actor, promotionRecord, under);
 }
 
 export async function runComponentsRollback(ctx: CommandContext): Promise<number> {

package/src/cli/handlers/release-implicit.e2e.test.ts

@@ -0,0 +1,153 @@
+/**
+ * An implicit release of a project with no components, end to end (#4046):
+ * the getting-started example, given two environments and a build parameter
+ * set per environment, is cut from the same commit in two clones. Each
+ * environment's build output must come out byte for byte the same, and the
+ * two cuts must give one release digest. No cluster is touched: the release
+ * is exported to files and never deployed.
+ */
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { contract, REPO } from "../../workspace/__fixtures__/contract-repo";
+import releasesSchema from "../../workspace/releases.schema.json";
+import { contentDigest } from "../../content-digest";
+
+const CHANT = [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")];
+const EXAMPLE = join(REPO, "examples", "getting-started");
+
+function chant(cwd: string, ...args: string[]): { code: number; stdout: string; stderr: string } {
+  const env: NodeJS.ProcessEnv = { ...process.env, USER: "tester" };
+  for (const k of ["GITHUB_RUN_ID", "CI_PIPELINE_ID", "GITHUB_ACTOR", "GITLAB_USER_LOGIN", "CHANT_ENV", "GITHUB_SHA", "CI"]) delete env[k];
+  const r = spawnSync(CHANT[0], [...CHANT.slice(1), ...args], { cwd, encoding: "utf-8", env, timeout: 180_000 });
+  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(r.stderr);
+  return r.stdout.trim();
+}
+
+/** Every file under `dir`, by its path relative to `dir`, as bytes. */
+function filesUnder(dir: string): Map<string, Buffer> {
+  const out = new Map<string, Buffer>();
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else out.set(relative(dir, p), readFileSync(p));
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** The example as a project of its own with two environments and a parameter that differs between them. */
+function writeProject(dir: string): void {
+  cpSync(join(EXAMPLE, "src"), join(dir, "src"), { recursive: true });
+  // The deploy Op goes under the build root, so the build writes src/dist/ops/deploy/op.json too: an Op's output goes under its build root.
+  cpSync(join(EXAMPLE, "deploy.op.ts"), join(dir, "src", "deploy.op.ts"));
+  const web = readFileSync(join(dir, "src", "web.ts"), "utf-8");
+  writeFileSync(
+    join(dir, "src", "web.ts"),
+    `import { params } from "@intentius/chant/params";\n${web.replace("replicas: 2,", "replicas: params.replicas as number,")}`,
+  );
+  writeFileSync(
+    join(dir, "chant.config.ts"),
+    `export default {\n  lexicons: ["k8s"],\n  sourceDir: "src",\n  environments: ["dev", "prod"],\n  buildParams: { replicas: { type: "number", default: 2 } },\n};\n`,
+  );
+  writeFileSync(join(dir, "params.dev.json"), `{ "replicas": 1 }\n`);
+  writeFileSync(join(dir, "params.prod.json"), `{ "replicas": 3 }\n`);
+  writeFileSync(join(dir, ".gitignore"), "node_modules\ndist/\nout/\n");
+}
+
+describe("an implicit release of a project with no components", () => {
+  test(
+    "two cuts of one commit, in two clones, give byte-identical build output per environment and one release digest",
+    () => {
+      const root = mkdtempSync(join(tmpdir(), "chant-release-implicit-"));
+      try {
+        const a = join(root, "a");
+        const b = join(root, "b");
+        mkdirSync(a);
+        writeProject(a);
+        git(a, "init", "-q", "-b", "main");
+        git(a, "config", "user.email", "t@chant.dev");
+        git(a, "config", "user.name", "T");
+        git(a, "add", ".");
+        git(a, "commit", "-q", "-m", "init");
+        const sha = git(a, "rev-parse", "HEAD");
+        git(a, "tag", `ci/green/${sha}`);
+        git(root, "clone", "-q", a, b);
+        git(b, "remote", "remove", "origin");
+        for (const d of [a, b]) symlinkSync(join(REPO, "node_modules"), join(d, "node_modules"), "dir");
+
+        const cuts = [a, b].map((d, i) => {
+          const r = chant(d, "release", "cut", ...(i === 0 ? ["v1"] : []), "--params-file", "params.{env}.json", "--json");
+          expect(r.code, r.stderr).toBe(0);
+          return JSON.parse(r.stdout);
+        });
+        const [first, second] = cuts;
+        expect(second.release.releaseDigest).toBe(first.release.releaseDigest);
+        expect(second.release).toEqual(first.release);
+        expect(first.stored && second.stored).toBe(true);
+
+        const release = first.release;
+        expect(release.commit).toBe(sha);
+        expect(release.artifactDigests).toEqual([]);
+        expect(release.targets.map((t: { env: string }) => t.env)).toEqual(["dev", "prod"]);
+        for (const t of release.targets) {
+          expect(t.templates.map((x: { component: unknown; path: string }) => [x.component, x.path])).toEqual([
+            [null, "dist/build.yaml"],
+            [null, "src/dist/ops/deploy/op.json"],
+          ]);
+          expect(t.params).toEqual([{ name: "replicas", value: t.env === "prod" ? 3 : 1, source: "params-file" }]);
+        }
+        // The parameter reaches the output, so the two environments' manifests differ.
+        expect(release.targets[0].templates[0].digest).not.toBe(release.targets[1].templates[0].digest);
+        // Nothing was written into the member's directory by the cut.
+        expect(existsSync(join(a, "dist")) || existsSync(join(a, "src", "dist"))).toBe(false);
+
+        // Each clone's stored bytes, written out per environment, are the same bytes.
+        for (const env of ["dev", "prod"]) {
+          const [fromA, fromB] = [a, b].map((d) => {
+            const ref = d === a ? "v1" : release.releaseDigest;
+            const r = chant(d, "release", "export", ref, "--env", env, "-o", `out/${env}`);
+            expect(r.code, r.stderr).toBe(0);
+            return filesUnder(join(d, "out", env));
+          });
+          expect([...fromA.keys()].sort()).toEqual(["dist/build.yaml", "src/dist/ops/deploy/op.json"]);
+          expect([...fromB.keys()].sort()).toEqual([...fromA.keys()].sort());
+          for (const [path, bytes] of fromA) {
+            expect(fromB.get(path)!.equals(bytes), `${env} ${path}`).toBe(true);
+            const recorded = release.targets.find((t: { env: string }) => t.env === env).templates.find((x: { path: string }) => x.path === path);
+            expect(contentDigest(bytes.toString("utf-8"))).toBe(recorded.digest);
+          }
+          expect(fromA.get("dist/build.yaml")!.toString("utf-8")).toContain(`replicas: ${env === "prod" ? 3 : 1}`);
+        }
+
+        // `release list --json` shows it as it shows any release.
+        const list = chant(a, "release", "list", "--json");
+        expect(list.code, list.stderr).toBe(0);
+        const doc = JSON.parse(list.stdout);
+        contract(releasesSchema).expectValid(doc);
+        expect(doc.releases).toHaveLength(1);
+        expect(doc.releases[0]).toMatchObject({ releaseDigest: release.releaseDigest, label: "v1", artifactDigests: [], environments: [] });
+
+        // Promote has no component to deploy, and says what to run instead.
+        const promote = chant(a, "components", "promote", "--from", "dev", "--to", "prod", "--release", "v1");
+        expect(promote.code).toBe(1);
+        expect(promote.stderr).toMatch(/release v1 is of a project with no components/);
+        expect(promote.stderr).toMatch(/chant release export v1 --env prod/);
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+    480_000,
+  );
+});

package/src/cli/handlers/release.e2e.test.ts

@@ -0,0 +1,85 @@
+/**
+ * `chant release cut` and `chant release list` end to end (#4026): the cut
+ * compiles each environment in a child chant with CHANT_ENV set, in a temp
+ * repo, and the list prints the read contract's `releases` document. No
+ * cloud is touched: the fixture's deploy is never run.
+ */
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { contract, REPO } from "../../workspace/__fixtures__/contract-repo";
+import releasesSchema from "../../workspace/releases.schema.json";
+import { contentDigest } from "../../content-digest";
+
+const CHANT = [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")];
+
+function chant(cwd: string, ...args: string[]): { code: number; stdout: string; stderr: string } {
+  const env: NodeJS.ProcessEnv = { ...process.env, USER: "tester" };
+  for (const k of ["GITHUB_RUN_ID", "CI_PIPELINE_ID", "GITHUB_ACTOR", "GITLAB_USER_LOGIN", "CHANT_ENV"]) delete env[k];
+  const r = spawnSync(CHANT[0], [...CHANT.slice(1), ...args], { cwd, encoding: "utf-8", env, timeout: 120_000 });
+  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(r.stderr);
+  return r.stdout.trim();
+}
+
+const BUILD = `mkdir -p dist && printf '{"env":"%s"}' "$CHANT_ENV" > dist/api.template.json`;
+
+describe("chant release cut and list", () => {
+  test(
+    "cuts a green commit once per environment's compile, refuses a commit that isn't green, and lists the release",
+    () => {
+      const dir = mkdtempSync(join(tmpdir(), "chant-release-cut-"));
+      try {
+        git(dir, "init", "-q", "-b", "main");
+        git(dir, "config", "user.email", "t@chant.dev");
+        git(dir, "config", "user.name", "T");
+        writeFileSync(join(dir, "chant.config.ts"), `export default { environments: ["dev", "prod", "pr-*"] };\n`);
+        writeFileSync(
+          join(dir, "api.component.ts"),
+          `export const api = { name: "api", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "dist/api.template.json" }] }] };\n`,
+        );
+        writeFileSync(join(dir, ".gitignore"), "dist/\n");
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "init");
+        const sha = git(dir, "rev-parse", "HEAD");
+
+        const refused = chant(dir, "release", "cut", "v1", "--build", BUILD);
+        expect(refused.code).toBe(1);
+        expect(refused.stderr).toMatch(/has no ci\/green tag.*\[release-commit-not-green\]/);
+
+        git(dir, "tag", `ci/green/${sha}`);
+        const cut = chant(dir, "release", "cut", "v1", "--build", BUILD, "--json");
+        expect(cut.code, cut.stderr).toBe(0);
+        const result = JSON.parse(cut.stdout);
+        expect(result.label).toBe("v1");
+        expect(result.release.commit).toBe(sha);
+        expect(result.release.targets).toEqual([
+          { env: "dev", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"dev"}`) }] },
+          { env: "prod", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"prod"}`) }] },
+        ]);
+
+        const again = chant(dir, "release", "cut", "--build", BUILD, "--json");
+        expect(again.code, again.stderr).toBe(0);
+        expect(JSON.parse(again.stdout)).toMatchObject({ label: "v1", cut: null, release: { releaseDigest: result.release.releaseDigest } });
+
+        const list = chant(dir, "release", "list", "--json");
+        expect(list.code, list.stderr).toBe(0);
+        const doc = JSON.parse(list.stdout);
+        contract(releasesSchema).expectValid(doc);
+        expect(doc.releases).toHaveLength(1);
+        expect(doc.releases[0]).toMatchObject({ releaseDigest: result.release.releaseDigest, label: "v1", environments: [] });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+    240_000,
+  );
+});