@intentius/chant 0.124.27 → 0.124.28

package/dist/cli/handlers/promote.js

@@ -16,20 +16,23 @@
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { loadChantConfig } from "../../config.js";
+import { promotionOrder } from "../../workspace/promotion-order.js";
+import { resolvePromotionSource } from "../../components/promote-order.js";
 import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git.js";
-import { appendReleaseRecord, readReleaseLedger, resolveRunId, } from "../../lifecycle/release-ledger.js";
+import { appendReleaseRecord, latestPerComponent, readReleaseLedger, resolveRunId, } from "../../lifecycle/release-ledger.js";
 import { isComponentList, resolveComponentTargets } from "../../components/cli-support.js";
 import { applyConfigDefaults } from "../../components/config-defaults.js";
 import { fanOutRegistry } from "../../components/fan-out-support.js";
 import { renderDriverHuman } from "../../components/driver-output.js";
 import { ndjsonProgressSink } from "../../components/run-progress.js";
-import { parseDigestPins, planPromotion, planRollback, planRedeploy, withoutBuildSteps, runPromotion, promotionRecord, rollbackRecord, redeployRecord, gateApprover, } from "../../components/promote.js";
+import { openCliRunEvents, refusesBothStreams } from "../run-events.js";
+import { parseDigestPins, planPromotion, planRollback, planRedeploy, withoutBuildSteps, runPromotion, promotionRecord, rollbackRecord, redeployRecord, gateApprover, gateAdmission, } from "../../components/promote.js";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary.js";
-import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate.js";
+import { approveCommand, describeGateMismatch, gateIsSealed, gitGateLedgerPort } from "../../op/gate.js";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format.js";
 import { GATED_EXIT_CODE } from "./run.js";
-const PROMOTE_USAGE = "chant components promote --from <env> --to <env> [--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:...> ...] [--dry-run] [--json]";
 const ROLLBACK_USAGE = "chant components rollback <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 const REDEPLOY_USAGE = "chant components redeploy <env> --component <name> [--digest <sha256:...>] [--dry-run] [--json]";
 function renderPlan(verb, plan, removed) {
@@ -96,13 +99,110 @@ async function readLedger(env) {
     }
     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) {
+    const { plan, under, port } = input;
+    const gate = await import("../../components/release-gate.js");
+    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.js");
+    const latest = latestPerComponent((await readLedger(env)).filter((r) => r.env === env));
+    const releases = new Map();
+    const current = new Map();
+    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.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 { 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 { 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 }),
+        },
+    };
+}
 /**
  * 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,
  * and which field names the earlier release on the new record.
  */
-async function deployPlan(ctx, verb, plan, project, actor, record) {
+async function deployPlan(ctx, verb, plan, project, actor, record, under) {
     const { args } = ctx;
+    if (refusesBothStreams(args))
+        return 1;
     const byName = new Map(project.targets.map((c) => [c.name, applyConfigDefaults(c, project.config)]));
     const prepared = [];
     const removed = new Map();
@@ -124,6 +224,34 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         console.error(formatError({ message: `nothing was deployed` }));
         return 1;
     }
+    // #4026: under a release, the deploy reads the templates the release
+    // recorded for this environment, checked against their digests.
+    let pinnedFiles = [];
+    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));
+        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.js");
+        const { readBuildManifest } = await import("../../lifecycle/build-ledger-store.js");
+        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);
@@ -135,15 +263,29 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
             }));
         }
     }
+    const releaseJson = 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
+            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.js");
+    const tidy = () => {
+        if (pinnedFiles.length > 0)
+            removePinnedTemplates(project.projectPath, pinnedFiles);
+    };
+    if (pinnedFiles.length > 0)
+        writePinnedTemplates(project.projectPath, pinnedFiles);
     const seededOutputs = {};
     for (const file of args.seedOutputs ?? []) {
         try {
@@ -151,32 +293,80 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         }
         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;
+    let changeSetJson;
+    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;
+    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 = [];
     let recordError;
     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();
@@ -186,7 +376,8 @@ async function deployPlan(ctx, verb, plan, project, actor, record) {
         }
     }
     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) {
@@ -247,10 +438,9 @@ function actorOrRefuse(ctx) {
 }
 export async function runComponentsPromote(ctx) {
     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);
@@ -259,6 +449,24 @@ export async function runComponentsPromote(ctx) {
     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.
@@ -277,6 +485,33 @@ export async function runComponentsPromote(ctx) {
         return 1;
     }
     await fetchLifecycle().catch(() => false);
+    // #4026: --release names the release this promote deploys, by label or digest.
+    let under;
+    if (args.release) {
+        const { resolveRelease } = await import("../../lifecycle/release-store.js");
+        const { targetFor, isImplicitRelease } = await import("../../components/release-promote.js");
+        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,
@@ -290,7 +525,7 @@ export async function runComponentsPromote(ctx) {
         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) {
     const { args } = ctx;

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

@@ -0,0 +1,34 @@
+/**
+ * `chant release` (#4026, ws-104): the release is what graduates.
+ *
+ *   release cut [<label>] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
+ *       cut a release of this member from the checkout's HEAD, which must be green;
+ *       --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
+ *       `--lexicon` shape the build of a project with no components (#4046)
+ *   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
+ *   release export <label|digest> --env <env> [-o <dir>] [--json]
+ *       write the files the release recorded for <env>, checked against their digests (#4046)
+ *   release compile --env <env> [--build <command>] [--artifacts --component <a,b>] --json
+ *       internal: what the cut runs in a child process per environment
+ *
+ * The workstation UX for `cut` grows in #4027. A declaration whose
+ * `identity.gates` names a `release` gate requires a signed cut by an actor
+ * in its class (#4031).
+ */
+import type { CommandContext } from "../registry.js";
+export declare function runReleaseCut(ctx: CommandContext): Promise<number>;
+export declare function runReleaseList(ctx: CommandContext): Promise<number>;
+/**
+ * `release export <label|digest> --env <env> [-o <dir>]` (#4046): write each
+ * file the release's target for <env> records, at the path it was compiled to,
+ * under <dir> (the member's directory by default), after checking each one's
+ * bytes against its digest. This is how a project with no components deploys
+ * a release: its own deploy reads these files instead of building again.
+ */
+export declare function runReleaseExport(ctx: CommandContext): Promise<number>;
+/** Internal: compile one environment, or build artifacts, in this process, and print the JSON the cut reads. */
+export declare function runReleaseCompile(ctx: CommandContext): Promise<number>;
+export declare function runReleaseUnknown(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=release.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAuBlD,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDxE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBzE;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"}

package/dist/cli/handlers/release.js

@@ -0,0 +1,203 @@
+/**
+ * `chant release` (#4026, ws-104): the release is what graduates.
+ *
+ *   release cut [<label>] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
+ *       cut a release of this member from the checkout's HEAD, which must be green;
+ *       --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
+ *       `--lexicon` shape the build of a project with no components (#4046)
+ *   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
+ *   release export <label|digest> --env <env> [-o <dir>] [--json]
+ *       write the files the release recorded for <env>, checked against their digests (#4046)
+ *   release compile --env <env> [--build <command>] [--artifacts --component <a,b>] --json
+ *       internal: what the cut runs in a child process per environment
+ *
+ * The workstation UX for `cut` grows in #4027. A declaration whose
+ * `identity.gates` names a `release` gate requires a signed cut by an actor
+ * in its class (#4031).
+ */
+import { resolve } from "node:path";
+import { formatBold, formatError, formatSuccess, formatWarning } from "../format.js";
+import { parseParamFlags } from "../build-params-cli.js";
+const USAGE = "chant release cut [<label>] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--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, params) {
+    const { args } = ctx;
+    return {
+        projectDir: resolve("."),
+        ...(args.buildCommand ? { buildCommand: args.buildCommand } : {}),
+        ...(params ? { params } : {}),
+        ...(args.paramsFile ? { paramsFile: args.paramsFile } : {}),
+        ...(args.src ? { src: args.src } : {}),
+        ...(args.output ? { output: args.output } : {}),
+        ...(args.lexicon ? { lexicon: args.lexicon } : {}),
+    };
+}
+function resolveActor(ctx) {
+    return ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+}
+export async function runReleaseCut(ctx) {
+    const { args } = ctx;
+    const positional = args.extraPositional;
+    if (positional && args.label && positional !== args.label) {
+        console.error(formatError({ message: `the label is given twice, as "${positional}" and --label "${args.label}"`, hint: USAGE }));
+        return 1;
+    }
+    const label = positional ?? args.label ?? null;
+    const actor = resolveActor(ctx);
+    if (!actor) {
+        console.error(formatError({ message: "Could not resolve --actor from the environment", hint: "Pass --actor explicitly, or set GITHUB_ACTOR / GITLAB_USER_LOGIN / USER." }));
+        return 1;
+    }
+    const cwd = resolve(".");
+    const { spawnTargetCompiler, ReleaseCompileError } = await import("../../components/release-compile.js");
+    const { cutRelease, ReleaseCutError } = await import("../../lifecycle/release-cut.js");
+    const { ReleaseLabelError } = await import("../../lifecycle/release-store.js");
+    const { pushLifecycleReport } = await import("../../lifecycle/git.js");
+    const params = parseParamFlags(args.param);
+    const compiler = spawnTargetCompiler(compileInputs(ctx, params));
+    try {
+        const result = await cutRelease({ cwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) });
+        const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
+        if (args.json) {
+            console.log(JSON.stringify({ release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused }, null, 2));
+        }
+        else {
+            const name = result.label ? formatBold(result.label) : "unlabelled release";
+            if (result.cut)
+                console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
+            else
+                console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
+            console.error(`  commit ${result.release.commit}`);
+            if (result.cut)
+                console.error(result.cut.signature ? `  signed by ${result.cut.actor}` : "  not signed");
+            console.error(`  artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
+            for (const r of result.reused)
+                console.error(`  ${r.component}: artifacts unchanged, carried from ${r.from}`);
+            console.log(result.release.releaseDigest);
+        }
+        if (push.pushWarning)
+            console.error(formatWarning({ message: push.pushWarning }));
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof ReleaseCutError) {
+            console.error(formatError({ message: `${err.message} [${err.code}]`, ...(err.fix ? { hint: err.fix } : {}) }));
+            return 1;
+        }
+        if (err instanceof ReleaseLabelError) {
+            console.error(formatError({ message: `${err.message} [${err.code}]` }));
+            return 1;
+        }
+        if (err instanceof ReleaseCompileError) {
+            console.error(formatError({ message: `no release was cut: ${err.message}` }));
+            return 1;
+        }
+        throw err;
+    }
+}
+export async function runReleaseList(ctx) {
+    const { releasesDocument } = await import("../../workspace/releases.js");
+    const doc = await releasesDocument({ cwd: resolve(".") });
+    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, hint: USAGE }));
+        return 1;
+    }
+    if (doc.reason)
+        console.error(formatWarning({ message: doc.reason.message }));
+    if (doc.releases.length === 0) {
+        console.error("No releases. Cut one from a green commit: chant release cut <label>");
+        return 0;
+    }
+    for (const r of doc.releases) {
+        const where = r.environments.map((e) => e.env).join(", ") || "not deployed from the release";
+        // #4031: the newest cut's signature, as the policy at base judges it.
+        const newest = r.cuts.at(-1);
+        const signature = newest ? (newest.signatureCheck.status === "verified" ? `signed by ${newest.actor}` : newest.signatureCheck.status) : "-";
+        console.log(`${(r.label ?? "-").padEnd(16)}  ${r.releaseDigest}  ${r.commit.slice(0, 12)}  ${signature}  ${where}`);
+        if (newest?.signatureCheck.status === "unverified")
+            console.error(`  ${r.label ?? r.releaseDigest}: ${newest.signatureCheck.reason}`);
+    }
+    return 0;
+}
+/**
+ * `release export <label|digest> --env <env> [-o <dir>]` (#4046): write each
+ * file the release's target for <env> records, at the path it was compiled to,
+ * under <dir> (the member's directory by default), after checking each one's
+ * bytes against its digest. This is how a project with no components deploys
+ * a release: its own deploy reads these files instead of building again.
+ */
+export async function runReleaseExport(ctx) {
+    const { args } = ctx;
+    const ref = args.extraPositional;
+    if (!ref || !args.env) {
+        console.error(formatError({ message: "release export needs a release and an environment", hint: USAGE }));
+        return 1;
+    }
+    const { fetchLifecycle } = await import("../../lifecycle/git.js");
+    const { resolveRelease, readReleaseTemplate } = await import("../../lifecycle/release-store.js");
+    const { targetFor, targetFiles, writePinnedTemplates } = await import("../../components/release-promote.js");
+    await fetchLifecycle().catch(() => false);
+    const found = await resolveRelease(ref);
+    if (!found) {
+        console.error(formatError({ message: `no release is labelled or digested "${ref}" in this member`, hint: "List them with: chant release list" }));
+        return 1;
+    }
+    const target = targetFor(found.release, args.env);
+    if ("error" in target) {
+        console.error(formatError({ message: target.error }));
+        return 1;
+    }
+    const read = await targetFiles(found.release, target.target, (digest) => readReleaseTemplate(digest));
+    if ("errors" in read) {
+        for (const e of read.errors)
+            console.error(formatError({ message: e }));
+        return 1;
+    }
+    const dir = resolve(args.output ?? ".");
+    writePinnedTemplates(dir, read.files);
+    if (args.json) {
+        console.log(JSON.stringify({ releaseDigest: found.release.releaseDigest, label: found.label, env: args.env, dir, templates: target.target.templates, params: target.target.params }, null, 2));
+    }
+    else {
+        console.error(formatSuccess(`Wrote ${read.files.length} file(s) of ${found.label ? formatBold(found.label) : found.release.releaseDigest} for "${args.env}"`));
+        for (const f of read.files)
+            console.log(f.path);
+    }
+    return 0;
+}
+/** Internal: compile one environment, or build artifacts, in this process, and print the JSON the cut reads. */
+export async function runReleaseCompile(ctx) {
+    const { args } = ctx;
+    const env = args.env;
+    if (!env) {
+        console.error(formatError({ message: "release compile needs --env <env>" }));
+        return 1;
+    }
+    const { compileEnvironment, buildReleaseArtifacts } = await import("../../components/release-compile.js");
+    const params = parseParamFlags(args.param);
+    const inputs = compileInputs(ctx, params);
+    try {
+        if (args.artifacts) {
+            const names = (args.component ?? "").split(",").map((n) => n.trim()).filter(Boolean);
+            console.log(JSON.stringify({ artifacts: await buildReleaseArtifacts(inputs, env, names) }));
+        }
+        else {
+            console.log(JSON.stringify(await compileEnvironment(inputs, env)));
+        }
+        return 0;
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+}
+export async function runReleaseUnknown(ctx) {
+    console.error(formatError({ message: `Unknown release subcommand: ${ctx.args.path}`, hint: USAGE }));
+    return 1;
+}