@intentius/chant 0.124.32 → 0.124.34

package/dist/cli/handlers/promote.js

@@ -20,8 +20,8 @@
  * environment: every component of the release at the digest the environment
  * ran from it, through the release gate `promote --release` binds (#4045).
  */
-import { resolve } from "node:path";
-import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { loadChantConfig } from "../../config.js";
 import { promotionOrder } from "../../workspace/promotion-order.js";
 import { resolvePromotionSource } from "../../components/promote-order.js";
@@ -41,7 +41,7 @@ import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format.js";
 import { GATED_EXIT_CODE } from "./run.js";
 import { redeployLine, releaseRollbackLine, rollbackTarget, unsettledComponents } from "../../lifecycle/mixed-environment.js";
-const PROMOTE_USAGE = "chant components promote --to <env> [--from <env>] [--allow-skip] [--release <label|digest>] [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--dry-run] [--json]";
+const PROMOTE_USAGE = "chant components promote --to <env> [--from <env>] [--allow-skip] [--release <label|digest>] [--component <name> [--digest <sha256:...>] | --digest <component>=<sha256:...> ...] [--wave-gate <gate>] [--resume <file>] [--dry-run] [--json]";
 const ROLLBACK_USAGE = "chant components rollback <env> (--component <name> [--digest <sha256:...>] | --release <label|digest>) [--dry-run] [--json]";
 const REDEPLOY_USAGE = "chant components redeploy <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 function renderPlan(verb, plan, removed) {
@@ -115,6 +115,11 @@ async function readLedger(env) {
  * 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.
+ *
+ * A dependent is planned against what a promoted upstream's plan says it will
+ * expose (#4168 step 4). With a resume record, only what is left is planned,
+ * against the outputs the record kept, and the approval the record names
+ * carries on when it covers that plan.
  */
 async function bindReleaseGate(input) {
     const { plan, under, port } = input;
@@ -145,71 +150,157 @@ async function bindReleaseGate(input) {
     for (const [component, u] of unsettledComponents(envRecords, await readDeployOutcomes(env).catch(() => []))) {
         unsettled.set(component, `the ${u.outcome.verb} run ${u.outcome.runId} left ${component} ${u.state} in "${env}" and nothing has been recorded for it since, so what it runs is not known`);
     }
-    const doc = await gate.planReleaseChangeSet({
+    const digests = new Map(plan.items.map((i) => [i.component, i.digest]));
+    const planSet = (only, outputs) => gate.planReleaseSet({
         release: under.release,
         env,
         components: input.prepared,
-        digests: new Map(plan.items.map((i) => [i.component, i.digest])),
+        digests,
         registry: input.registry,
         current,
         unsettled,
-        seededOutputs: input.seededOutputs,
+        seededOutputs: outputs,
+        ...(only ? { only } : {}),
     });
-    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.js");
-    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 { readStoredChangeSet } = await import("../../lifecycle/change-set-store.js");
     const { isEmptyChangeSet } = await import("../../change-set.js");
-    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 verifyEmpty = gate.emptyVerifier((digest) => readStoredChangeSet(digest, { cwd: input.projectPath }), { releaseDigest, environment: env });
+    /** Refuse, store, and pass the gates of an empty plan; the binding, or the exit code of a refusal already printed. */
+    const bindDoc = async (doc, names, what) => {
+        const provisional = gate.provisionalMembers(doc);
+        if (provisional.length > 0) {
+            console.error(formatError({
+                message: `${what} of release ${under.label ?? releaseDigest} for "${env}" has provisional members (${provisional.join(", ")}), which no approval covers; nothing more was deployed`,
+                hint: "Deploy what they read first, so they plan against real values.",
+            }));
+            return 1;
         }
-    }
-    const { readStoredChangeSet } = await import("../../lifecycle/change-set-store.js");
-    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 }),
+        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 more 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.
+        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 empty = isEmptyChangeSet(doc);
+        console.error(formatInfo(`release gate: ${what} ${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 names) {
+                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 } : {}) }));
+            }
+        }
+        return { binding: { op: gate.RELEASE_GATE_OP, planDigest: doc.digest, releaseDigest, verifyEmpty }, empty };
+    };
+    const later = {
+        replan: async (only, outputs) => (await planSet(only, outputs)).doc,
+        bind: async (doc, names) => {
+            const bound = await bindDoc(doc, names, "a later plan");
+            if (typeof bound === "number")
+                throw new PromoteStageRefused();
+            return bound.binding;
         },
     };
+    // #4168 step 4: a resume plans what is left against the outputs it kept.
+    if (input.resume) {
+        const done = new Set(input.resume.completed);
+        const left = new Set(plan.items.map((i) => i.component).filter((c) => !done.has(c)));
+        const fresh = await planSet(left, { ...input.seededOutputs, ...input.resume.outputs });
+        const stored = await readStoredChangeSet(input.resume.approvedDigest, { cwd: input.projectPath });
+        if (stored.status === "found") {
+            const { waveNotCovered } = await import("../../components/pr-run.js");
+            const notCovered = waveNotCovered(stored.document, fresh.doc);
+            if (notCovered.length === 0) {
+                console.error(formatInfo(`resuming: ${done.size} component(s) applied earlier; what is left is covered by change set ${stored.document.digest}`));
+                return {
+                    doc: stored.document,
+                    empty: isEmptyChangeSet(stored.document),
+                    binding: { op: gate.RELEASE_GATE_OP, planDigest: stored.document.digest, releaseDigest, verifyEmpty },
+                    reads: fresh.reads,
+                    resumedFrom: stored.document.digest,
+                    ...(fresh.plannedOutputs ? { plannedOutputs: fresh.plannedOutputs } : {}),
+                    ...(fresh.unknownInputs ? { unknownInputs: fresh.unknownInputs } : {}),
+                    ...later,
+                };
+            }
+            for (const line of notCovered)
+                console.error(formatWarning({ message: `resume: ${line}` }));
+        }
+        const bound = await bindDoc(fresh.doc, gates, "change set");
+        if (typeof bound === "number")
+            return bound;
+        return { doc: fresh.doc, ...bound, reads: fresh.reads, ...(fresh.plannedOutputs ? { plannedOutputs: fresh.plannedOutputs } : {}), ...(fresh.unknownInputs ? { unknownInputs: fresh.unknownInputs } : {}), ...later };
+    }
+    const first = await planSet(undefined, input.seededOutputs);
+    const bound = await bindDoc(first.doc, gates, "change set");
+    if (typeof bound === "number")
+        return bound;
+    for (const [component, refs] of Object.entries(first.unknownInputs ?? {})) {
+        console.error(formatInfo(`${component} reads ${refs.join(", ")}, known only once its upstream applies; it is planned again then, and needs its own approval if its plan moves`));
+    }
+    return { doc: first.doc, ...bound, reads: first.reads, ...(first.plannedOutputs ? { plannedOutputs: first.plannedOutputs } : {}), ...(first.unknownInputs ? { unknownInputs: first.unknownInputs } : {}), ...later };
+}
+/** A later round's or wave's plan was refused (provisional or failed members); the refusal is already printed. */
+class PromoteStageRefused extends Error {
+    constructor() {
+        super("a later round's plan was refused");
+        this.name = "PromoteStageRefused";
+    }
+}
+/**
+ * The pull requests a release carries into `env` and how each was approved
+ * on merge (#4168 decision 2): shown beside the release gate, never counted
+ * by it. The commits are the release commit's first-parent history since
+ * the commits `env` runs, at most 200, read from the merge records.
+ */
+async function pullRequestApprovals(release, since, cwd) {
+    const { execFileSync } = await import("node:child_process");
+    const { readMergeRecord } = await import("../../lifecycle/merge-record.js");
+    let commits = [];
+    try {
+        const out = execFileSync("git", ["rev-list", "--first-parent", "--max-count=200", release.commit, ...since.map((c) => `^${c}`)], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        commits = out.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const commit of commits) {
+        const record = await readMergeRecord(commit, { cwd }).catch(() => null);
+        if (record)
+            records.push(record);
+    }
+    return records;
+}
+/** One line per merge record: where it came from and how its plan stood against its approval. */
+function approvalLine(r) {
+    const from = r.source.kind === "pull-request" ? `#${r.source.pr}` : r.source.kind === "work-item" ? r.source.records.map((x) => `${x.kind}:${x.id}`).join(", ") : "direct push";
+    const how = r.plan === "approved"
+        ? `approved by ${r.approvedBy.join(", ") || "nobody named"}${r.authorApproved?.length ? ` (by its author: ${r.authorApproved.join(", ")})` : ""}`
+        : r.plan === "changed"
+            ? `its plan moved after the approval of ${r.approvedDigest ?? "another digest"}`
+            : r.plan;
+    return `${r.commit.slice(0, 12)} ${from}: ${how}`;
 }
 /**
  * Prepare, run and record a plan. Shared by promote, rollback and redeploy,
@@ -247,7 +338,7 @@ async function deployPlan(ctx, verb, plan, project, actor, record, under) {
     if (under) {
         const { pinReleaseTemplates } = await import("../../components/release-promote.js");
         const { readReleaseTemplate } = await import("../../lifecycle/release-store.js");
-        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 }));
@@ -319,16 +410,43 @@ async function deployPlan(ctx, verb, plan, project, actor, record, under) {
     // #4045: under a release, every gate binds the release's change set for this environment.
     let releaseGate;
     let changeSetJson;
+    let bound;
+    // #4168 step 4: a promote that stopped at a round's or a wave's gate left a resume record.
+    const rounds = await import("../../components/promote-rounds.js");
+    const resumePath = resolve(project.projectPath, args.resume ?? join(".chant", "promote", `${plan.to}.resume.json`));
+    let resume;
+    if (under && existsSync(resumePath)) {
+        try {
+            const record = JSON.parse(readFileSync(resumePath, "utf8"));
+            if (record.schema === rounds.PROMOTE_RESUME_SCHEMA && record.env === plan.to && record.releaseDigest === under.release.releaseDigest)
+                resume = record;
+            else if (args.resume)
+                console.error(formatWarning({ message: `--resume ${args.resume} is for another release or environment; planning from the start` }));
+        }
+        catch (err) {
+            console.error(formatWarning({ message: `could not read the resume record ${resumePath}: ${err instanceof Error ? err.message : String(err)}` }));
+        }
+    }
+    let pullRequests = [];
     if (under) {
         try {
-            const bound = await bindReleaseGate({ plan, prepared, under, registry, port, seededOutputs, actor: actor, projectPath: project.projectPath, head });
-            if (typeof bound === "number") {
+            const result = await bindReleaseGate({ plan, prepared, under, registry, port, seededOutputs, actor: actor, projectPath: project.projectPath, head, ...(resume ? { resume } : {}) });
+            if (typeof result === "number") {
                 tidy();
-                return bound;
+                return result;
             }
-            if (bound) {
-                releaseGate = bound.binding;
-                changeSetJson = { changeSet: bound.doc.digest, empty: bound.empty };
+            if (result) {
+                bound = result;
+                releaseGate = result.binding;
+                changeSetJson = { changeSet: result.doc.digest, empty: result.empty };
+                // #4168 decision 2: the pull requests' own approvals, shown beside the gate.
+                const since = [...new Set((await readLedger(plan.to)).filter((r) => r.env === plan.to).map((r) => r.gitSha))];
+                pullRequests = await pullRequestApprovals(under.release, since, project.projectPath);
+                if (pullRequests.length > 0 && !args.json) {
+                    console.error(formatInfo(`pull requests this release carries into "${plan.to}" (shown, not counted by the release gate):`));
+                    for (const r of pullRequests)
+                        console.error(`  ${approvalLine(r)}`);
+                }
             }
         }
         catch (err) {
@@ -336,6 +454,11 @@ async function deployPlan(ctx, verb, plan, project, actor, record, under) {
             throw err;
         }
     }
+    if (args.waveGate && !bound) {
+        console.error(formatError({ message: "--wave-gate needs a promote under --release whose compositions declare a gate", hint: PROMOTE_USAGE }));
+        tidy();
+        return 1;
+    }
     // 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);
@@ -346,25 +469,88 @@ async function deployPlan(ctx, verb, plan, project, actor, record, under) {
         cwd: project.projectPath,
     });
     let run;
+    let staged;
+    // #4168 step 4: a wave at a time when a dependent read an upstream's plan,
+    // under --wave-gate, or on a resume; one run otherwise.
+    const inPlan = new Set(plan.items.map((i) => i.component));
+    const readsPlanned = bound?.plannedOutputs !== undefined && Object.keys(bound.plannedOutputs).some((d) => inPlan.has(d));
+    const inRounds = bound !== undefined && (readsPlanned || args.waveGate !== undefined || resume !== undefined);
     try {
-        run = await runPromotion({
-            plan,
-            components: prepared,
-            registry,
-            componentOutputs: seededOutputs,
-            gates: port,
-            ...(releaseGate ? { releaseGate } : {}),
-            ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
-            ...(events ? { onRunEvent: events.emit } : {}),
-        });
+        if (inRounds && bound) {
+            staged = await rounds.runPromotionInRounds({
+                components: prepared,
+                outputs: { ...seededOutputs, ...(resume?.outputs ?? {}) },
+                binding: bound.binding,
+                approved: bound.doc,
+                reads: bound.reads,
+                ...(resume ? { completed: resume.completed } : {}),
+                ...(args.waveGate ? { waveGate: args.waveGate } : {}),
+                replan: bound.replan,
+                bind: bound.bind,
+                run: (components, outputs, binding) => runPromotion({
+                    plan: { ...plan, items: plan.items.filter((i) => components.some((c) => c.name === i.component)) },
+                    components,
+                    registry,
+                    componentOutputs: outputs,
+                    gates: port,
+                    releaseGate: binding,
+                    ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+                    ...(events ? { onRunEvent: events.emit } : {}),
+                }),
+            });
+            run = staged.run;
+        }
+        else {
+            run = await runPromotion({
+                plan,
+                components: prepared,
+                registry,
+                componentOutputs: seededOutputs,
+                gates: port,
+                ...(releaseGate ? { releaseGate } : {}),
+                ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+                ...(events ? { onRunEvent: events.emit } : {}),
+            });
+        }
     }
     catch (err) {
+        if (err instanceof PromoteStageRefused) {
+            events?.settle("failed", err.message);
+            return 1;
+        }
         events?.settle("failed", err instanceof Error ? err.message : String(err));
         throw err;
     }
     finally {
         tidy();
     }
+    if (staged && bound) {
+        for (const stage of staged.stages) {
+            const label = stage.kind === "round" ? `round ${stage.number}` : `wave ${stage.number}`;
+            console.error(formatInfo(`${label} (${stage.components.join(", ")}): planned again as ${stage.digest}, ${stage.status}`));
+            for (const line of stage.notCovered)
+                console.error(`  not covered by ${bound.doc.digest}: ${line}`);
+            if (stage.message)
+                console.error(formatError({ message: stage.message }));
+        }
+        if (run.status === "ok") {
+            rmSync(resumePath, { force: true });
+        }
+        else if (staged.completed.length > 0) {
+            const record = {
+                schema: rounds.PROMOTE_RESUME_SCHEMA,
+                env: plan.to,
+                releaseDigest: under.release.releaseDigest,
+                approvedDigest: resume?.approvedDigest ?? bound.resumedFrom ?? bound.doc.digest,
+                completed: staged.completed,
+                outputs: staged.outputs,
+                at: new Date().toISOString(),
+            };
+            mkdirSync(dirname(resumePath), { recursive: true });
+            writeFileSync(resumePath, `${JSON.stringify(record, null, 2)}\n`);
+            console.error(formatInfo(`resume record: ${resumePath}; the same promote carries on from here`));
+        }
+    }
     // The driver settles the stream; this only ends one it left open.
     events?.settle(run.status === "fail" ? "failed" : run.status);
     if (!args.json)
@@ -400,7 +586,9 @@ async function deployPlan(ctx, verb, plan, project, actor, record, under) {
     }
     if (args.json) {
         const withChangeSet = under && changeSetJson ? { release: { ...releaseJson.release, ...changeSetJson } } : releaseJson;
-        console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, run, recorded, ...(outcome ? { outcome } : {}) }, null, 2));
+        const stagedJson = staged ? { stages: staged.stages, ...(bound?.plannedOutputs ? { plannedOutputs: bound.plannedOutputs } : {}), ...(bound?.unknownInputs ? { unknownInputs: bound.unknownInputs } : {}) } : {};
+        const prJson = pullRequests.length > 0 ? { pullRequests: pullRequests.map((r) => ({ commit: r.commit, source: r.source, plan: r.plan, digest: r.digest, approvedBy: r.approvedBy, ...(r.authorApproved ? { authorApproved: r.authorApproved } : {}) })) } : {};
+        console.log(JSON.stringify({ ...planJson(plan, removed), ...withChangeSet, ...stagedJson, ...prJson, run, recorded, ...(outcome ? { outcome } : {}) }, null, 2));
     }
     else {
         for (const r of recorded) {
@@ -526,6 +714,21 @@ async function resolveUnderRelease(ref, env, verb, fix) {
         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.js");
+    if (securityGroupsAt(process.cwd()).has("verified-releases")) {
+        const { verifyRelease, verificationCode } = await import("../../lifecycle/release-verify.js");
+        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/dist/cli/handlers/release.d.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
@@ -49,6 +52,11 @@ export declare function sameWithYes(argv: readonly string[]): string;
  * 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 declare function runReleaseCut(ctx: CommandContext): Promise<number>;
 /**
@@ -76,6 +84,13 @@ export declare function runReleasePublish(ctx: CommandContext): Promise<number>;
  * verifies and 1 when it does not or can't be checked.
  */
 export declare function runReleaseVerify(ctx: CommandContext): Promise<number>;
+/**
+ * `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 declare function runReleaseCandidates(ctx: CommandContext): Promise<number>;
 export declare function runReleaseList(ctx: CommandContext): Promise<number>;
 /**
  * `release export <label|digest> --env <env> [-o <dir>]` (#4046): write each

package/dist/cli/handlers/release.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAmBlD,0HAA0H;AAC1H,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;CACvB,GAAG,MAAM,EAAE,CASX;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAG3D;AAiBD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyMxE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2G5E;AAQD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC3E;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BzE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC3E;AAED,gHAAgH;AAChH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB5E;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5E"}
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAyBlD,0HAA0H;AAC1H,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;CACvB,GAAG,MAAM,EAAE,CASX;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAG3D;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwNxE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2G5E;AAQD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC3E;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC/E;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BzE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC3E;AAED,gHAAgH;AAChH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB5E;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5E"}