@intentius/chant 0.124.32 → 0.124.33

package/src/cli/handlers/promote.ts

@@ -315,7 +315,7 @@ async function deployPlan(
   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));
+    const pinned = await pinReleaseTemplates(prepared, under.release, under.target, (digest, encoding) => readReleaseTemplate(digest, undefined, encoding));
     if ("errors" in pinned) {
       for (const message of pinned.errors) console.error(formatError({ message }));
       console.error(formatError({ message: `nothing was deployed` }));
@@ -595,6 +595,21 @@ async function resolveUnderRelease(ref: string, env: string, verb: "promote" | "
     console.error(formatError(revokedRefusal({ releaseDigest: found.release.releaseDigest, label: found.label }, revocation, await fix(found.release))));
     return 1;
   }
+  // #4168: under verified-releases a release deploys only once `chant release verify` passes for it.
+  const { securityGroupsAt } = await import("../../workspace/security");
+  if (securityGroupsAt(process.cwd()).has("verified-releases")) {
+    const { verifyRelease, verificationCode } = await import("../../lifecycle/release-verify");
+    const name = found.label ?? found.release.releaseDigest;
+    const v = await verifyRelease({ cwd: process.cwd(), ref: found.release.releaseDigest });
+    const code = "error" in v ? v.error.code : verificationCode(v);
+    if (code) {
+      console.error(formatError({
+        message: `${code}: release ${name} does not verify (${"error" in v ? v.error.message : v.reason}), and the workspace opts into verified-releases, so ${verb} deploys only a verified release`,
+        hint: `Check it with: chant release verify ${name}`,
+      }));
+      return 1;
+    }
+  }
   return { release: found.release, label: found.label, target: target.target };
 }
 

package/src/cli/handlers/release-cut-at.e2e.test.ts

@@ -0,0 +1,115 @@
+/**
+ * `chant release cut --at <sha>` and `chant release candidates` end to end
+ * (#4168 4.2): a cut of a chosen green commit of trunk from a temporary
+ * worktree, while the checkout sits elsewhere with uncommitted changes, with
+ * the label reaching the build as CHANT_RELEASE_LABEL (decision 5). A temp
+ * repo with a temp bare remote; no cloud, no push of tags.
+ */
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, 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 candidatesSchema from "../../workspace/release-candidates.schema.json";
+
+const CHANT = [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")];
+const CI_VARS = ["CI", "GITHUB_ACTIONS", "GITHUB_RUN_ID", "GITHUB_SHA", "GITHUB_ACTOR", "GITLAB_CI", "CI_PIPELINE_ID", "CHANT_ENV", "CHANT_RELEASE_LABEL"];
+const { expectValid } = contract(candidatesSchema);
+
+function chant(cwd: string, args: string[], extra: Record<string, string> = {}): { code: number; stdout: string; stderr: string } {
+  const env: NodeJS.ProcessEnv = { ...process.env, USER: "tester" };
+  for (const k of CI_VARS) delete env[k];
+  Object.assign(env, extra);
+  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();
+}
+
+// The template records the environment, the label, and which commit's file the build read.
+const BUILD = `mkdir -p dist && printf '{"env":"%s","label":"%s","marker":"%s"}' "$CHANT_ENV" "$CHANT_RELEASE_LABEL" "$(cat marker.txt)" > dist/api.template.json`;
+
+describe("chant release cut --at and release candidates", () => {
+  test(
+    "cuts a chosen green commit from a temporary worktree with the label in the build, and lists candidates",
+    () => {
+      const root = mkdtempSync(join(tmpdir(), "chant-release-cut-at-"));
+      try {
+        const dir = join(root, "work");
+        const remote = join(root, "origin.git");
+        git(root, "init", "-q", "--bare", "-b", "main", remote);
+        git(root, "init", "-q", "-b", "main", dir);
+        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"] };\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");
+        writeFileSync(join(dir, "marker.txt"), "one");
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "one (#11)");
+        const one = git(dir, "rev-parse", "HEAD");
+        writeFileSync(join(dir, "marker.txt"), "two");
+        git(dir, "commit", "-q", "-am", "two (#12)");
+        const two = git(dir, "rev-parse", "HEAD");
+        git(dir, "remote", "add", "origin", remote);
+        git(dir, "push", "-q", "origin", "main");
+        git(dir, "fetch", "-q", "origin");
+        git(dir, "tag", `ci/green/${one}`);
+        // The checkout is at two, not green, with an uncommitted change.
+        writeFileSync(join(dir, "marker.txt"), "dirty");
+
+        const unknown = chant(dir, ["release", "cut", "v1", "--at", "nope", "--build", BUILD]);
+        expect(unknown.code).toBe(1);
+        expect(unknown.stderr).toContain("[release-at-unknown]");
+        const notGreen = chant(dir, ["release", "cut", "v1", "--at", two, "--build", BUILD]);
+        expect(notGreen.code).toBe(1);
+        expect(notGreen.stderr).toContain("[release-commit-not-green]");
+
+        const candidates = chant(dir, ["release", "candidates", "--json"]);
+        expect(candidates.code, candidates.stderr).toBe(0);
+        const doc = JSON.parse(candidates.stdout);
+        expectValid(doc);
+        expect(doc.candidates.map((c: { commit: string }) => c.commit)).toEqual([one]);
+        expect(doc.candidates[0]).toMatchObject({ newFor: ["dev", "prod"], cut: [] });
+        expect(doc.candidates[0].changes[0]).toMatchObject({ commit: one, pr: 11 });
+        expect(doc.pending.map((c: { commit: string }) => c.commit)).toEqual([two]);
+
+        const dry = chant(dir, ["release", "cut", "v1", "--at", one, "--build", BUILD, "--json"]);
+        expect(dry.code, dry.stderr).toBe(0);
+        expect(JSON.parse(dry.stdout)).toMatchObject({ dryRun: true, commit: one, at: { ref: one, commit: one } });
+
+        const cut = chant(dir, ["release", "cut", "v1", "--at", one, "--build", BUILD, "--yes", "--json"]);
+        expect(cut.code, cut.stderr).toBe(0);
+        const result = JSON.parse(cut.stdout);
+        expect(result.release.commit).toBe(one);
+        expect(result.tag).toEqual({ name: "release/v1", created: true });
+        expect(git(dir, "rev-parse", "release/v1^{commit}")).toBe(one);
+
+        // The recorded template is commit one's, built with the label, and the checkout is untouched.
+        const out = join(root, "export");
+        const exported = chant(dir, ["release", "export", "v1", "--env", "prod", "-o", out]);
+        expect(exported.code, exported.stderr).toBe(0);
+        expect(JSON.parse(readFileSync(join(out, "dist", "api.template.json"), "utf-8"))).toEqual({ env: "prod", label: "v1", marker: "one" });
+        expect(readFileSync(join(dir, "marker.txt"), "utf-8")).toBe("dirty");
+        expect(git(dir, "rev-parse", "HEAD")).toBe(two);
+        expect(git(dir, "worktree", "list").split("\n")).toHaveLength(1);
+
+        const after = JSON.parse(chant(dir, ["release", "candidates", "--json"]).stdout);
+        expect(after.candidates[0].cut).toEqual(["v1"]);
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+    240_000,
+  );
+});

package/src/cli/handlers/release-publish-targets.e2e.test.ts

@@ -199,10 +199,10 @@ describe("chant release publish with targets", () => {
       }
       expect(pub.stderr).toContain("npm notice token [redacted]");
 
-      // From a workstation the publish warns that it carries no provenance, and the plan offers none.
+      // From a workstation the plan offers no provenance, and with no supply-chain group says nothing about it (#4168).
       const asJson = await chant(dir, ["release", "publish", "v1", "--json"], { ...path, ...secrets });
       expect(asJson.code, asJson.stderr).toBe(0);
-      expect(asJson.stderr).toContain("this publish runs without OIDC");
+      expect(asJson.stderr).not.toContain("this publish runs without OIDC");
       const doc = JSON.parse(asJson.stdout);
       expect(doc).toMatchObject({ dryRun: true, label: "v1", provenance: { oidc: false } });
       expect(doc.targets.map((t: { kind: string }) => t.kind)).toEqual(["npm", "oci"]);

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

@@ -3,8 +3,10 @@
  * (#4049), in a temp repo with a temp bare remote and throwaway ssh keys. A
  * release cut signed with a key `.chant/allowed_signers` lists verifies, and a
  * publish takes it; an unsigned one and one signed by a key the file does not
- * list fail `release verify`, and a publish refuses them unless
- * `--allow-unsigned`. Nothing is published: the member declares no target.
+ * list fail `release verify`. With no release gate or verified-releases
+ * group a publish takes them and records their status (#4168);
+ * release-publish.test.ts covers the refusals under the group. Nothing is
+ * published: the member declares no target.
  */
 
 import { describe, expect, test } from "vitest";
@@ -42,7 +44,7 @@ const BUILD = `mkdir -p dist && printf '{"env":"%s"}' "$CHANT_ENV" > dist/api.te
 
 describe("chant release verify", () => {
   test.skipIf(!hasSshKeygen)(
-    "passes for a signed release, fails for an unsigned one and for one signed by an unlisted key; a publish refuses both unless --allow-unsigned",
+    "passes for a signed release, fails for an unsigned one and for one signed by an unlisted key; a publish with no security group takes both and records their status",
     () => {
       const root = mkdtempSync(join(tmpdir(), "chant-release-verify-"));
       try {
@@ -89,10 +91,10 @@ describe("chant release verify", () => {
         expect(unsigned.code).toBe(1);
         expect(unsigned.stderr).toMatch(/v2.* does not verify: no cut of the release carries a signature \[release-unsigned\]/);
         expect(JSON.parse(chant(dir, ["release", "verify", "v2", "--json"]).stdout)).toMatchObject({ status: "unsigned", error: { code: "release-unsigned" } });
-        const pubUnsigned = chant(dir, ["release", "publish", "v2"]);
-        expect(pubUnsigned.code).toBe(1);
-        expect(pubUnsigned.stderr).toMatch(/\[release-unsigned\]/);
-        expect(chant(dir, ["release", "publish", "v2", "--allow-unsigned"]).code).toBe(0);
+        // #4168: with no release gate or verified-releases group, a publish takes it and records it unsigned.
+        const pubUnsigned = chant(dir, ["release", "publish", "v2", "--json"]);
+        expect(pubUnsigned.code, pubUnsigned.stderr).toBe(0);
+        expect(JSON.parse(pubUnsigned.stdout)).toMatchObject({ signature: { status: "unsigned" }, warnings: [] });
 
         // v3: signed by mallory, whom the signers file does not list.
         next("v3");
@@ -101,9 +103,9 @@ describe("chant release verify", () => {
         const unlisted = chant(dir, ["release", "verify", "v3"]);
         expect(unlisted.code).toBe(1);
         expect(unlisted.stderr).toMatch(/mallory has no key in \.chant\/allowed_signers at [0-9a-f]{12}.*\[release-signature-unverified\]/);
-        const pubUnlisted = chant(dir, ["release", "publish", "v3"]);
-        expect(pubUnlisted.code).toBe(1);
-        expect(pubUnlisted.stderr).toMatch(/\[release-signature-unverified\]/);
+        const pubUnlisted = chant(dir, ["release", "publish", "v3", "--json"]);
+        expect(pubUnlisted.code, pubUnlisted.stderr).toBe(0);
+        expect(JSON.parse(pubUnlisted.stdout)).toMatchObject({ signature: { status: "unverified" }, warnings: [] });
 
         const missing = chant(dir, ["release", "verify", "v9"]);
         expect(missing.code).toBe(1);

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

@@ -128,8 +128,8 @@ describe("chant release cut, publish and list", () => {
         expect(result.release.releaseDigest).toBe(dryJson.releaseDigest);
         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"}`) }] },
+          { env: "dev", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"dev"}`) }], trees: [] },
+          { env: "prod", params: [], templates: [{ component: "api", path: "dist/api.template.json", digest: contentDigest(`{"env":"prod"}`) }], trees: [] },
         ]);
         expect(result.cut).toMatchObject({ actor: "t@chant.dev", runId: expect.stringMatching(/^local-\d+$/), runOrigin: { forge: "local" }, signature: null });
         expect(result.next).toEqual(["git push origin release/v1", "chant release publish v1", "chant components promote --release v1 --to dev"]);
@@ -151,41 +151,32 @@ describe("chant release cut, publish and list", () => {
         expect(doc.releases[0]).toMatchObject({ releaseDigest: result.release.releaseDigest, label: "v1", environments: [] });
         expect(doc.releases[0].cuts[0]).toMatchObject({ runId: result.cut.runId, runOrigin: { forge: "local" } });
 
-        // #4049: the cut is not signed, so a publish refuses it unless --allow-unsigned.
-        const unsignedPub = chant(dir, ["release", "publish", "v1"]);
-        expect(unsignedPub.code).toBe(1);
-        expect(unsignedPub.stderr).toMatch(/v1 has no signed cut.*\[release-unsigned\]/);
-        expect(unsignedPub.stderr).toContain("pass --allow-unsigned");
-
+        // #4168: the cut is not signed, and with no release gate or verified-releases group a publish takes it quietly.
         // A publish is a dry run without --yes, as a cut is.
-        const dryPub = chant(dir, ["release", "publish", "v1", "--allow-unsigned"]);
+        const dryPub = chant(dir, ["release", "publish", "v1"]);
         expect(dryPub.code, dryPub.stderr).toBe(0);
-        expect(dryPub.stderr).toContain("v1 has no signed cut; publishing it anyway under --allow-unsigned");
+        expect(dryPub.stderr).not.toContain("release-unsigned");
+        expect(dryPub.stderr).not.toContain("no signed cut");
         expect(dryPub.stdout).toContain("What would be published where:\n  nothing: this member declares no publish target (release.publish in chant.config.ts)");
-        expect(dryPub.stderr).toContain("Dry run: nothing was published. Run again with --yes to publish: chant release publish v1 --allow-unsigned --yes");
+        expect(dryPub.stderr).toContain("Dry run: nothing was published. Run again with --yes to publish: chant release publish v1 --yes");
 
-        // Publish from the workstation: the warning comes before anything else is said about publishing.
-        const pub = chant(dir, ["release", "publish", "v1", "--allow-unsigned", "--yes"]);
+        // Publish from the workstation: with no supply-chain group there is no OIDC warning either.
+        const pub = chant(dir, ["release", "publish", "v1", "--yes"]);
         expect(pub.code, pub.stderr).toBe(0);
-        const warning = pub.stderr.indexOf("this publish runs without OIDC, so what it publishes carries no provenance");
-        const nothing = pub.stderr.indexOf("Nothing was published: this member declares no publish target (release.publish in chant.config.ts).");
-        expect(warning).toBeGreaterThan(-1);
-        expect(nothing).toBeGreaterThan(warning);
+        expect(pub.stderr).not.toContain("without OIDC");
+        expect(pub.stderr).toContain("Nothing was published: this member declares no publish target (release.publish in chant.config.ts).");
         expect(pub.stderr).toContain("chant components promote --release v1 --to dev");
 
-        // In GitHub Actions with id-token: write there is no warning.
+        // The --json document records what is missing: no signature and no OIDC provenance.
+        const asJson = chant(dir, ["release", "publish", "v1", "--json"]);
+        expect(asJson.code, asJson.stderr).toBe(0);
+        expect(JSON.parse(asJson.stdout)).toMatchObject({ dryRun: true, label: "v1", signature: { status: "unsigned" }, provenance: { oidc: false }, warnings: [], targets: [], published: [] });
+
+        // In GitHub Actions with id-token: write the provenance is OIDC.
         const oidc = { GITHUB_ACTIONS: "true", ACTIONS_ID_TOKEN_REQUEST_URL: "https://token.example", ACTIONS_ID_TOKEN_REQUEST_TOKEN: "t" };
-        const fromCi = chant(dir, ["release", "publish", "v1", "--allow-unsigned", "--json"], oidc);
+        const fromCi = chant(dir, ["release", "publish", "v1", "--json"], oidc);
         expect(fromCi.code, fromCi.stderr).toBe(0);
-        expect(fromCi.stderr).not.toContain("without OIDC");
-        expect(JSON.parse(fromCi.stdout)).toMatchObject({
-          dryRun: true,
-          label: "v1",
-          provenance: { oidc: true, ci: "github" },
-          warnings: ["v1 has no signed cut; publishing it anyway under --allow-unsigned, so chant release verify v1 will fail for it"],
-          targets: [],
-          published: [],
-        });
+        expect(JSON.parse(fromCi.stdout)).toMatchObject({ dryRun: true, label: "v1", provenance: { oidc: true, ci: "github" }, warnings: [], targets: [], published: [] });
 
         const unknown = chant(dir, ["release", "publish", "v9"]);
         expect(unknown.code).toBe(1);

package/src/cli/handlers/release.ts

@@ -1,7 +1,7 @@
 /**
  * `chant release` (#4026, ws-104): the release is what graduates.
  *
- *   release cut [<label>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
+ *   release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
  *       a dry run of a cut of this member from the checkout's HEAD, which must be
  *       clean, on trunk and pushed, and green (#4027); `--yes` cuts, records,
  *       and tags the commit `release/<label>` locally;
@@ -17,6 +17,9 @@
  *   release verify <label|digest> [--json]
  *       check the release's signature offline against .chant/allowed_signers
  *       at the release's commit (#4049)
+ *   release candidates [--env <env>] [--json]
+ *       the green commits of trunk a release can be cut from, each with what it
+ *       would ship, and what each environment runs (#4168 4.2)
  *   release list [--json]
  *       every release of this member with its targets, its cuts and where it runs;
  *       `--json` prints the read contract's `releases` document
@@ -39,13 +42,19 @@ import { parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 
 const USAGE =
-  "chant release cut [<label>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
+  "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
 
 /** The build inputs `release cut` and `release compile` share. */
-function compileInputs(ctx: CommandContext, params: Record<string, string> | undefined): import("../../components/release-compile").CompileInputs {
+function compileInputs(
+  ctx: CommandContext,
+  params: Record<string, string> | undefined,
+  projectDir: string = resolve("."),
+  releaseLabel?: string | null,
+): import("../../components/release-compile").CompileInputs {
   const { args } = ctx;
   return {
-    projectDir: resolve("."),
+    projectDir,
+    ...(releaseLabel ? { releaseLabel } : {}),
     ...(args.buildCommand ? { buildCommand: args.buildCommand } : {}),
     ...(params ? { params } : {}),
     ...(args.paramsFile ? { paramsFile: args.paramsFile } : {}),
@@ -102,6 +111,11 @@ function describeActorSource(source: import("../../lifecycle/release-workstation
  * would record, build and tag, and what publishes where. With `--yes` it
  * cuts, signs with `--sign`, records the cut with its actor and run id,
  * tags the commit locally and prints the next command.
+ *
+ * `--at <sha>` (#4168 4.2) cuts that commit instead of `HEAD`, from a
+ * temporary worktree (../../lifecycle/release-at.ts), so the checkout need
+ * not be clean or at the commit. The label reaches every compile and
+ * artifact build as `CHANT_RELEASE_LABEL` (decision 5).
  */
 export async function runReleaseCut(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
@@ -124,6 +138,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: `${message} [${code}]`, ...(fix ? { hint: fix } : {}) }));
     return 1;
   };
+  const at = await import("../../lifecycle/release-at");
+  let checkout: import("../../lifecycle/release-at").CommitCheckout | null = null;
 
   try {
     // The workstation checks come first, in the order #4027 lists them; the
@@ -139,9 +155,16 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     let trunk: import("../../lifecycle/release-workstation").Trunk | null = null;
     let signers: readonly import("../../workspace/trust/trust-files").Signer[] = [];
     let member: string | null = null;
+    if (args.at !== undefined && !top) {
+      return fail("not-a-git-repository", "--at names a commit, and this directory is not in a git repository");
+    }
     if (top) {
-      commit = await getHeadCommit({ cwd });
-      ws.checkCleanTree(top, commit);
+      if (args.at !== undefined) {
+        commit = at.resolveCutCommit(top, args.at);
+      } else {
+        commit = await getHeadCommit({ cwd });
+        ws.checkCleanTree(top, commit);
+      }
       const { scopeSource } = await import("../../workspace/write-scope");
       const { releaseRuleFrom } = await import("../../workspace/identity");
       const source = scopeSource(cwd);
@@ -179,8 +202,11 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     const tag = label !== null && commit !== null && top ? { name: ws.releaseTagName(member, label), state: ws.checkReleaseTag(top, ws.releaseTagName(member, label), commit) } : null;
     const ci = resolveCiRun(process.env);
     const params = parseParamFlags(args.param);
-    const compiler = spawnTargetCompiler(compileInputs(ctx, params));
-    const request = { cwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) };
+    // --at: the cut reads, compiles and builds the commit's tree, not the checkout's.
+    if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
+    const cutCwd = checkout?.memberDir ?? cwd;
+    const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
+    const request = { cwd: cutCwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) };
 
     if (dryRun) {
       const plan = await planRelease(request);
@@ -195,7 +221,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const ref = plan.label ?? plan.alreadyCut ?? plan.releaseDigest;
       const provenance = detectProvenance();
       // The targets release publish would run, as the config here declares them; their files are read at publish.
-      const publishTargets = await releasePublishTargets(cwd).then(
+      const publishTargets = await releasePublishTargets(cutCwd).then(
         (ts) => ts.map((t) => `${t.name} to ${t.destination}`),
         (err: unknown) => (err instanceof Error ? err : new Error(String(err))),
       );
@@ -207,6 +233,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
         actorSource: who.source,
         run: ci ? { runId: ci.runId, runOrigin: ci.runOrigin } : { runId: null, runOrigin: { forge: "local" as const } },
         trunk,
+        at: args.at !== undefined ? { ref: args.at, commit } : null,
         sign: args.sign !== undefined ? { key: publicKey !== null ? publicKey.split(" ")[0] : null, readable: publicKey !== null } : null,
         tag: tag ? { name: tag.name, exists: tag.state === "present" } : null,
         publish: { targets: Array.isArray(publishTargets) ? publishTargets : [], provenance },
@@ -294,7 +321,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     if (tagWarning) console.error(formatWarning({ message: tagWarning }));
     return 0;
   } catch (err) {
-    if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError) {
+    if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError || err instanceof at.CutAtError) {
       return fail(err.code, err.message, err.fix);
     }
     if (err instanceof ReleaseLabelError) return fail(err.code, err.message);
@@ -303,6 +330,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       return 1;
     }
     throw err;
+  } finally {
+    checkout?.remove();
   }
 }
 
@@ -480,6 +509,47 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * `release candidates [--env <env>] [--json]` (#4168 4.2): the green commits
+ * of trunk a release can be cut from, newest first, each with what it would
+ * ship since the previous one, and what each environment runs. `--json`
+ * prints the read contract's `release-candidates` document.
+ */
+export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
+  const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
+  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}) });
+  if (ctx.args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.message} [${doc.error.code}]`, hint: USAGE }));
+    return 1;
+  }
+  for (const e of doc.environments) {
+    const runs = e.running.map((r) => `${r.label ?? r.releaseDigest.slice(0, 19)}${r.commit ? ` at ${r.commit.slice(0, 12)}` : ""}`).join(", ");
+    console.log(`${e.env}: ${runs || "runs no release yet"}`);
+  }
+  if (!doc.tip) {
+    console.error(`No candidates: this clone knows no ${doc.branch}. Fetch it: git fetch origin ${doc.branch} --tags`);
+    return 0;
+  }
+  if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not green yet`);
+  if (doc.candidates.length === 0) console.log(`No green commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
+  for (const c of doc.candidates) {
+    const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
+    console.log(`${c.commit.slice(0, 12)}  ${c.subject}${tags.length > 0 ? `  (${tags.join("; ")})` : ""}`);
+    for (const ch of c.changes) {
+      const links = [...(ch.pr !== null ? [`#${ch.pr}`] : []), ...ch.work.map((w) => `work:${w}`)];
+      console.log(`    ${ch.commit.slice(0, 12)}  ${ch.subject}${links.length > 0 ? `  [${links.join(", ")}]` : ""}`);
+    }
+    for (const f of c.flags) console.log(`    flag ${f.id} (${f.member} ${f.param}) changed`);
+  }
+  for (const sk of doc.skipped) console.log(`skipped ${sk.commit.slice(0, 12)}  ${sk.subject}  (revoked)`);
+  if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>`);
+  return 0;
+}
+
 export async function runReleaseList(ctx: CommandContext): Promise<number> {
   const { releasesDocument } = await import("../../workspace/releases");
   const doc = await releasesDocument({ cwd: resolve(".") });
@@ -540,7 +610,7 @@ export async function runReleaseExport(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: target.error }));
     return 1;
   }
-  const read = await targetFiles(found.release, target.target, (digest) => readReleaseTemplate(digest));
+  const read = await targetFiles(found.release, target.target, (digest, encoding) => readReleaseTemplate(digest, undefined, encoding));
   if ("errors" in read) {
     for (const e of read.errors) console.error(formatError({ message: e }));
     return 1;