@intentius/chant 0.124.27 → 0.124.29

package/dist/lifecycle/publish-targets.js

@@ -0,0 +1,85 @@
+/**
+ * The publish targets (#4047): a member's `release.publish` declarations
+ * (./publish-declaration.ts) made into {@link PublishTarget}s, and what the
+ * targets share.
+ *
+ * - `npm` (./publish-npm.ts): `npm publish` per package, in order, with
+ *   `--provenance` when the run has an OIDC token.
+ * - `oci` (./publish-oci.ts): an OCI image layout pushed to a registry such
+ *   as GHCR or Docker Hub over the registry HTTP API, by digest, then tagged.
+ * - `forge` (./publish-forge.ts): files attached to the GitHub, GitLab or
+ *   Forgejo release named by the release's tag.
+ *
+ * A file a target reads that the release records as an artifact at the same
+ * path is checked against the release's digest, and a file that differs is
+ * refused (`publish-artifact-digest-mismatch`). Other files are the commit's
+ * by the checkout check (`checkCheckoutIsRelease` in ./release-publish.ts).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, normalize, relative, resolve } from "node:path";
+import { PublishTargetError } from "./release-publish.js";
+import { sortedJsonReplacer } from "../utils.js";
+/** Make each declaration a target, in the order declared. */
+export async function createPublishTargets(decls, deps = {}) {
+    const out = [];
+    for (const d of decls) {
+        switch (d.type) {
+            case "npm":
+                out.push((await import("./publish-npm.js")).npmTarget(d, deps));
+                break;
+            case "oci":
+                out.push((await import("./publish-oci.js")).ociTarget(d, deps));
+                break;
+            case "forge":
+                out.push((await import("./publish-forge.js")).forgeTarget(d, deps));
+                break;
+        }
+    }
+    return out;
+}
+/**
+ * The key of a target made from `decl` (#4048): its kind and the first 16 hex
+ * digits of the SHA-256 of its sorted JSON. A declaration holds variable
+ * names, never a credential, so the key holds none either.
+ */
+export function publishTargetKey(decl) {
+    return `${decl.type}:${createHash("sha256").update(JSON.stringify(decl, sortedJsonReplacer)).digest("hex").slice(0, 16)}`;
+}
+/** `path` resolved in the member at `cwd`, refused when it is not there. */
+export function memberFile(cwd, path) {
+    const abs = isAbsolute(path) ? path : resolve(cwd, path);
+    if (!existsSync(abs)) {
+        throw new PublishTargetError("publish-file-missing", `${path} does not exist in ${cwd}`, "Build it before publishing: a publish uploads what is there and never builds.");
+    }
+    return abs;
+}
+/** `sha256:<hex>` of a file's bytes. */
+export function fileDigest(abs) {
+    return `sha256:${createHash("sha256").update(readFileSync(abs)).digest("hex")}`;
+}
+/** `sha256:<hex>` of bytes. */
+export function bytesDigest(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/** True when `abs` is a directory. */
+export function isDir(abs) {
+    return statSync(abs).isDirectory();
+}
+const normal = (p) => normalize(p).replace(/\\/g, "/").replace(/^\.\//, "");
+/** The release's artifact of `kind` at `path` (relative to the member at `cwd`), if it records one. */
+export function releaseArtifactAt(release, kind, cwd, path) {
+    const rel = normal(isAbsolute(path) ? relative(cwd, path) : path);
+    return release.artifactDigests.find((a) => a.kind === kind && normal(a.path) === rel);
+}
+/**
+ * Refuse a file the release records at `path` whose digest is none of
+ * `digests`, the identities the target can compute for it (the file's bytes,
+ * and for an image its manifest and config digests).
+ */
+export function checkReleaseDigest(release, kind, cwd, path, digests) {
+    const recorded = releaseArtifactAt(release, kind, cwd, path);
+    if (!recorded || digests.includes(recorded.digest))
+        return;
+    throw new PublishTargetError("publish-artifact-digest-mismatch", `${path} is not the ${kind} release ${release.releaseDigest} built: the release records ${recorded.digest}, and the file here is ${digests[0]}`, "Publish the files the cut built. A publish never builds, so restore them from the cut's build, or cut a new release.");
+}

package/dist/lifecycle/release-cut.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Cutting a release from a green commit (#4026, ws-104).
+ *
+ * The cut takes the checkout's `HEAD`, refuses it unless it carries a
+ * `ci/green/<sha>` tag and no `ci/revoked/<sha>` tag (ws-103, read from local
+ * tags), and refuses a working tree with uncommitted changes to tracked
+ * files, since the compile would then not be the commit's. It compiles every
+ * environment the member declares, in its promotion order (#4030), and
+ * refuses a component whose build steps differ between environments, since
+ * "built once" can't hold for it. It then builds each component's artifacts
+ * once, stores the release and appends the cut.
+ *
+ * An artifact whose source did not change since the earlier release cut
+ * from the nearest ancestor commit is not built again: the release carries that
+ * release's entry, so a config-only release keeps the same artifact digests.
+ * "Did not change" means git sees no change between the two commits in the
+ * component's own file, the member's `chant.config.ts` and the paths its
+ * build steps read.
+ *
+ * A project with no components (#4046) needs no special case here: its
+ * targets hold the files `chant build --env <env>` writes, each with
+ * `component: null`, and `artifactDigests` is empty.
+ *
+ * Compiling goes through a {@link TargetCompiler}, so a test hands the cut
+ * fixtures and the CLI hands it child processes.
+ *
+ * Who may cut (#4031): when the declaration at base names a `release` gate
+ * in `identity.gates`, a cut must be signed (`--sign`), its signature must
+ * verify for the actor against the signers at base, and when the gate names
+ * a class the actor must be in it. A cut signed without that gate is signed
+ * all the same, and readers report whether the signature verifies. With
+ * `ci.green.signedSince` declared, a green tag counts only with a valid
+ * statement (`../workspace/ci-green.ts`), so a hand-pushed tag cuts nothing.
+ */
+import { type Release, type ReleaseCut, type ReleaseTarget } from "./release-store.js";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile.js";
+/** The stable codes a cut refuses with. */
+export type ReleaseCutCode = "not-a-git-repository" | "release-commit-not-green" | "release-commit-revoked" | "release-worktree-dirty" | "release-no-environments" | "release-no-components" | "release-build-inputs-differ" | "release-unsigned" | "release-signer-refused" | "declaration-invalid";
+export declare class ReleaseCutError extends Error {
+    readonly code: ReleaseCutCode;
+    readonly fix?: string | undefined;
+    constructor(code: ReleaseCutCode, message: string, fix?: string | undefined);
+}
+export interface CutRequest {
+    /** The member's directory. */
+    cwd: string;
+    compiler: TargetCompiler;
+    /** The label, or null to cut without one. */
+    label: string | null;
+    actor: string;
+    /** The environments in promotion order. Read from the member's `chant.config.ts` when absent. */
+    environments?: readonly string[];
+    now?: () => Date;
+    /** The process environment the CI run is read from. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Sign the cut (#4031): an ssh key file, or true for git's
+     * `user.signingkey`, as `chant approve --sign` takes it. The signature is
+     * over the release digest, the label, the actor and the time, and `actor`
+     * must be the principal the signers file lists the key for.
+     */
+    sign?: string | true;
+}
+export interface CutResult {
+    release: Release;
+    /** The cut line written, or null when this digest was already cut. */
+    cut: ReleaseCut | null;
+    /** The release's label after the cut. */
+    label: string | null;
+    /** Whether the release file was written now, rather than already stored. */
+    stored: boolean;
+    /** The components whose artifacts were taken from an earlier release, and that release's digest. */
+    reused: Array<{
+        component: string;
+        from: string;
+    }>;
+}
+/**
+ * Whether `sha` has a green tag and no revoked tag, read from local tags,
+ * and the tags on it that were ignored for want of a valid statement
+ * (#4031). The tags are judged by `green`, the declaration's `ci.green` at
+ * base, with the runner keys read at its branch's tip; with no `ci.green`,
+ * every tag counts.
+ */
+export declare function greenState(top: string, sha: string, green?: import("../workspace/declaration.js").CiGreen | null): Promise<{
+    state: "green" | "revoked" | "none";
+    ignored: Array<{
+        tag: string;
+        status: string;
+        reason: string;
+    }>;
+}>;
+/** Which components' build steps differ between environments, with the environments they appear in. */
+export declare function differingBuildSteps(targets: readonly CompiledTarget[]): Array<{
+    component: string;
+    envs: string[];
+}>;
+/** What a dry run of the cut found (#4027): what the cut would do, with nothing built, signed or written. */
+export interface CutPlan {
+    commit: string;
+    member: string | null;
+    label: string | null;
+    /** The release's digest when no artifact needs building, so it is known now; null when a build decides it. */
+    releaseDigest: string | null;
+    /** The digest already cut under `label`, or this digest when it is already cut: the cut would then write no new release. */
+    alreadyCut: string | null;
+    /** Each environment's target: its params, and its templates by component and path. */
+    targets: Array<{
+        env: string;
+        params: ReleaseTarget["params"];
+        templates: Array<{
+            component: string | null;
+            path: string;
+        }>;
+    }>;
+    /** The components whose artifacts would be built, and the environment each is built in. */
+    build: Array<{
+        component: string;
+        env: string;
+    }>;
+    /** The components whose artifacts would be carried from an earlier release. */
+    reused: CutResult["reused"];
+    /** Each component's publish steps, with the environments whose deploy runs them. */
+    publishSteps: Array<{
+        component: string;
+        kind: string;
+        to: string | null;
+        envs: string[];
+    }>;
+    /** Whether the release gate in identity.gates requires a signed cut. */
+    signatureRequired: boolean;
+}
+/**
+ * The dry run of {@link cutRelease} (#4027): the same checks and compile,
+ * then what the cut would build, carry and record, without building an
+ * artifact, signing, or writing anything. Throws what the cut throws before
+ * it builds, and `ReleaseLabelError` when the label is invalid or names a
+ * release of another commit.
+ */
+export declare function planRelease(req: CutRequest): Promise<CutPlan>;
+/**
+ * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
+ * the release and the cut to the local `chant/lifecycle` branch and does not
+ * push. Throws {@link ReleaseCutError} before anything is written when the
+ * commit isn't green, the tree is dirty, or an environment can't be compiled
+ * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
+ * label is taken or the release already carries another one.
+ *
+ * The cut line names its run (#4027): the CI run's id and origin in CI, and
+ * outside CI an id minted from the cut's time, `local-<epoch ms>`, with the
+ * origin `{ forge: "local" }`.
+ */
+export declare function cutRelease(req: CutRequest): Promise<CutResult>;
+//# sourceMappingURL=release-cut.d.ts.map

package/dist/lifecycle/release-cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-cut.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-cut.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,EAUL,KAAK,OAAO,EAEZ,KAAK,UAAU,EACf,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpF,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,0BAA0B,GAC1B,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,uBAAuB,GACvB,6BAA6B,GAC7B,kBAAkB,GAClB,wBAAwB,GACxB,qBAAqB,CAAC;AAE1B,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAE7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM;IAHvB,YACW,IAAI,EAAE,cAAc,EAC7B,OAAO,EAAE,MAAM,EACN,GAAG,CAAC,EAAE,MAAM,YAAA,EAItB;CACF;AAED,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,cAAc,CAAC;IACzB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,oGAAoG;IACpG,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAcD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,OAAO,0BAA0B,EAAE,OAAO,GAAG,IAAW,GAC9D,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAanH;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAapH;AAyKD,6GAA6G;AAC7G,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8GAA8G;IAC9G,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4HAA4H;IAC5H,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sFAAsF;IACtF,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;QAAC,SAAS,EAAE,KAAK,CAAC;YAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/H,2FAA2F;IAC3F,KAAK,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,+EAA+E;IAC/E,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,oFAAoF;IACpF,YAAY,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC5F,wEAAwE;IACxE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA4DnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA6DpE"}

package/dist/lifecycle/release-cut.js

@@ -0,0 +1,366 @@
+/**
+ * Cutting a release from a green commit (#4026, ws-104).
+ *
+ * The cut takes the checkout's `HEAD`, refuses it unless it carries a
+ * `ci/green/<sha>` tag and no `ci/revoked/<sha>` tag (ws-103, read from local
+ * tags), and refuses a working tree with uncommitted changes to tracked
+ * files, since the compile would then not be the commit's. It compiles every
+ * environment the member declares, in its promotion order (#4030), and
+ * refuses a component whose build steps differ between environments, since
+ * "built once" can't hold for it. It then builds each component's artifacts
+ * once, stores the release and appends the cut.
+ *
+ * An artifact whose source did not change since the earlier release cut
+ * from the nearest ancestor commit is not built again: the release carries that
+ * release's entry, so a config-only release keeps the same artifact digests.
+ * "Did not change" means git sees no change between the two commits in the
+ * component's own file, the member's `chant.config.ts` and the paths its
+ * build steps read.
+ *
+ * A project with no components (#4046) needs no special case here: its
+ * targets hold the files `chant build --env <env>` writes, each with
+ * `component: null`, and `artifactDigests` is empty.
+ *
+ * Compiling goes through a {@link TargetCompiler}, so a test hands the cut
+ * fixtures and the CLI hands it child processes.
+ *
+ * Who may cut (#4031): when the declaration at base names a `release` gate
+ * in `identity.gates`, a cut must be signed (`--sign`), its signature must
+ * verify for the actor against the signers at base, and when the gate names
+ * a class the actor must be in it. A cut signed without that gate is signed
+ * all the same, and readers report whether the signature verifies. With
+ * `ci.green.signedSince` declared, a green tag counts only with a valid
+ * statement (`../workspace/ci-green.ts`), so a hand-pushed tag cuts nothing.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { canonicalJson } from "../effect-receipt.js";
+import { contentDigest } from "../content-digest.js";
+import { getHeadCommit } from "./git.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+import { resolveCiRun } from "./release-ledger.js";
+import { appendCut, invalidLabel, labelsByDigest, makeRelease, persistRelease, readAllReleases, readCuts, readRelease, ReleaseLabelError, } from "./release-store.js";
+export class ReleaseCutError extends Error {
+    constructor(code, message, fix) {
+        super(message);
+        this.code = code;
+        this.fix = fix;
+        this.name = "ReleaseCutError";
+    }
+}
+function git(top, args) {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function tryGit(top, args) {
+    try {
+        return git(top, args);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether `sha` has a green tag and no revoked tag, read from local tags,
+ * and the tags on it that were ignored for want of a valid statement
+ * (#4031). The tags are judged by `green`, the declaration's `ci.green` at
+ * base, with the runner keys read at its branch's tip; with no `ci.green`,
+ * every tag counts.
+ */
+export async function greenState(top, sha, green = null) {
+    const { judgedCiTags } = await import("./release-revocation.js");
+    let tags;
+    try {
+        tags = await judgedCiTags(top, green);
+    }
+    catch (err) {
+        const { WorkspaceReadError } = await import("../workspace/declaration.js");
+        if (err instanceof WorkspaceReadError)
+            throw new ReleaseCutError("declaration-invalid", err.message);
+        throw err;
+    }
+    const ignored = tags.ignored.get(sha) ?? [];
+    if (tags.revoked.has(sha))
+        return { state: "revoked", ignored };
+    return { state: tags.green.has(sha) ? "green" : "none", ignored };
+}
+/** Which components' build steps differ between environments, with the environments they appear in. */
+export function differingBuildSteps(targets) {
+    const byComponent = new Map();
+    for (const t of targets) {
+        for (const [component, steps] of Object.entries(t.buildSteps)) {
+            if (!byComponent.has(component))
+                byComponent.set(component, new Map());
+            byComponent.get(component).set(t.env, canonicalJson(steps));
+        }
+    }
+    const out = [];
+    for (const [component, perEnv] of byComponent) {
+        if (new Set(perEnv.values()).size > 1)
+            out.push({ component, envs: [...perEnv.keys()] });
+    }
+    return out.sort((a, b) => (a.component < b.component ? -1 : 1));
+}
+/** The earlier release of this member cut from the nearest ancestor of `commit`. */
+async function previousRelease(top, commit, cwd) {
+    const { releases } = await readAllReleases({ cwd });
+    const { cuts } = await readCuts({ cwd });
+    const cutAt = new Map();
+    for (const c of cuts)
+        if (!cutAt.has(c.releaseDigest) || c.timestamp > cutAt.get(c.releaseDigest))
+            cutAt.set(c.releaseDigest, c.timestamp);
+    const candidates = releases
+        .filter((r) => cutAt.has(r.releaseDigest) && r.commit !== commit)
+        .filter((r) => tryGit(top, ["merge-base", "--is-ancestor", r.commit, commit]) !== null)
+        .map((r) => ({ r, depth: Number(tryGit(top, ["rev-list", "--count", r.commit]) ?? 0), at: cutAt.get(r.releaseDigest) }))
+        // The nearest ancestor first, then the newest cut of it.
+        .sort((a, b) => b.depth - a.depth || (b.at < a.at ? -1 : b.at > a.at ? 1 : 0));
+    return candidates[0]?.r;
+}
+/**
+ * The checks and the compile a cut makes before it builds or writes: the
+ * commit is green and not revoked, the cut is signed when the release gate
+ * asks, the tree is clean, every environment compiles with the same build
+ * steps, and which artifacts are carried from an earlier release.
+ */
+async function prepare(req) {
+    const cwd = resolve(req.cwd);
+    const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+    if (!top)
+        throw new ReleaseCutError("not-a-git-repository", "a release is cut from a commit, and this directory is not in a git repository");
+    const commit = await getHeadCommit({ cwd });
+    // #4031: the declaration at base says whether tags need a statement and who may cut.
+    const { scopeSource } = await import("../workspace/write-scope.js");
+    const { releaseRuleFrom } = await import("../workspace/identity.js");
+    const source = scopeSource(cwd);
+    const { state, ignored } = await greenState(top, commit, source.declaration?.ci?.green ?? null);
+    if (state !== "green") {
+        const why = ignored.length > 0 ? `; ignored: ${ignored.map((t) => `${t.tag} (${t.status}): ${t.reason}`).join("; ")}` : "";
+        throw new ReleaseCutError(state === "revoked" ? "release-commit-revoked" : "release-commit-not-green", state === "revoked"
+            ? `commit ${commit.slice(0, 12)} has a ci/revoked tag: it went red after it was green, so no release is cut from it`
+            : ignored.some((t) => t.tag.startsWith("ci/green/"))
+                ? `commit ${commit.slice(0, 12)} has no ci/green tag that counts, so no release is cut from it${why}`
+                : `commit ${commit.slice(0, 12)} has no ci/green tag, so no release is cut from it`, "Check out a green commit (`chant ci last-green` names the newest) after fetching the tags: git fetch origin --tags");
+    }
+    // Who may cut is the declaration's identity.gates.release, read at base.
+    const releaseRule = releaseRuleFrom(source);
+    if (releaseRule.requirement && req.sign === undefined) {
+        throw new ReleaseCutError("release-unsigned", `chant.workspace.json at base names a release gate in identity.gates${releaseRule.requirement.class !== null ? `, from the class ${releaseRule.requirement.class}` : ""}, and this cut is not signed`, `chant release cut <label> --actor <principal> --sign [<key file>], with a key ${releaseRule.rule.signers.signersPath} at base lists for that principal.`);
+    }
+    const dirty = tryGit(top, ["status", "--porcelain", "--untracked-files=no"]);
+    if (dirty) {
+        throw new ReleaseCutError("release-worktree-dirty", `the working tree has uncommitted changes to tracked files, so a compile here would not be commit ${commit.slice(0, 12)}'s`, "Commit or stash them, or cut from a clean checkout of the commit.");
+    }
+    let envs = req.environments;
+    if (!envs) {
+        const { readMemberPromotionOrder } = await import("../workspace/promotion-order.js");
+        envs = ((await readMemberPromotionOrder(cwd)) ?? []).map((s) => s.name);
+    }
+    if (envs.length === 0) {
+        throw new ReleaseCutError("release-no-environments", "this member's chant.config.ts declares no environments, so there is nothing to compile a release for", "Declare them in promotion order: environments: [\"dev\", \"staging\", \"prod\"]");
+    }
+    const compiled = [];
+    for (const env of envs)
+        compiled.push(await req.compiler.compile(env));
+    // A project with no components compiles to its build output (#4046), so only a target with neither is empty.
+    if (compiled.every((t) => t.components.length === 0 && t.templates.length === 0)) {
+        throw new ReleaseCutError("release-no-components", "no component is enabled in any environment and nothing was compiled, so there is nothing to release", "Enable a component under one environment's parameters, or remove the component files so the project's build output is released.");
+    }
+    const differing = differingBuildSteps(compiled);
+    if (differing.length > 0) {
+        throw new ReleaseCutError("release-build-inputs-differ", `the build steps of ${differing.map((d) => `"${d.component}"`).join(", ")} differ between environments (${[...new Set(differing.flatMap((d) => d.envs))].join(", ")}), ` +
+            "so their artifacts can't be built once for every environment", "Make the build steps read no environment-specific value; pass the value to a deploy step instead.");
+    }
+    // Which environment each component's artifacts are built in: the first one it is enabled in.
+    const firstEnv = new Map();
+    for (const t of compiled)
+        for (const c of t.components)
+            if (!firstEnv.has(c) && (t.buildSteps[c]?.length ?? 0) > 0)
+                firstEnv.set(c, t);
+    // git names paths from its top with symlinks resolved (/private/var on macOS).
+    const realCwd = realpathSync(cwd);
+    const previous = firstEnv.size > 0 ? await previousRelease(top, commit, cwd) : undefined;
+    const reused = [];
+    const artifacts = [];
+    const toBuild = new Map();
+    for (const [component, target] of firstEnv) {
+        const prior = previous?.artifactDigests.filter((a) => a.component === component) ?? [];
+        if (previous && prior.length > 0) {
+            const paths = [target.componentFiles[component], "chant.config.ts", ...(target.buildInputs[component] ?? [])]
+                .filter((p) => typeof p === "string")
+                .map((p) => relative(top, resolve(realCwd, p)))
+                .filter((p) => p !== "" && !p.startsWith(".."));
+            // With no path to compare, the source can't be shown unchanged, so it is built.
+            const changed = paths.length === 0 ? null : tryGit(top, ["diff", "--name-only", previous.commit, commit, "--", ...paths]);
+            if (changed === "") {
+                artifacts.push(...prior);
+                reused.push({ component, from: previous.releaseDigest });
+                continue;
+            }
+        }
+        toBuild.set(target.env, [...(toBuild.get(target.env) ?? []), component]);
+    }
+    const ledger = await resolveMemberLedger(cwd);
+    return {
+        cwd,
+        commit,
+        envs,
+        compiled,
+        releaseRule,
+        toBuild,
+        carried: artifacts,
+        reused,
+        member: ledger.members.length > 0 ? ledger.members.join("/") : null,
+    };
+}
+/** The targets and template bytes of a compile, each template by its content digest. */
+function targetsOf(compiled) {
+    const templates = [];
+    const targets = compiled.map((t) => ({
+        env: t.env,
+        params: t.params,
+        templates: t.templates.map((tpl) => {
+            const digest = contentDigest(tpl.content);
+            templates.push({ digest, content: tpl.content });
+            return { component: tpl.component, path: tpl.path, digest };
+        }),
+    }));
+    return { targets, templates };
+}
+/**
+ * The dry run of {@link cutRelease} (#4027): the same checks and compile,
+ * then what the cut would build, carry and record, without building an
+ * artifact, signing, or writing anything. Throws what the cut throws before
+ * it builds, and `ReleaseLabelError` when the label is invalid or names a
+ * release of another commit.
+ */
+export async function planRelease(req) {
+    const p = await prepare(req);
+    const { targets } = targetsOf(p.compiled);
+    const build = [];
+    for (const env of p.envs)
+        for (const component of p.toBuild.get(env) ?? [])
+            build.push({ component, env });
+    const releaseDigest = build.length === 0 ? makeRelease({ member: p.member, commit: p.commit, artifactDigests: p.carried, targets }).releaseDigest : null;
+    const { cuts } = await readCuts({ cwd: p.cwd });
+    const labels = labelsByDigest(cuts);
+    let alreadyCut = null;
+    if (req.label !== null) {
+        const why = invalidLabel(req.label);
+        if (why)
+            throw new ReleaseLabelError("release-label-invalid", why);
+        const named = [...labels].find(([, l]) => l === req.label)?.[0];
+        if (named !== undefined) {
+            const other = await readRelease(named, { cwd: p.cwd });
+            const sameCommit = other?.commit === p.commit;
+            if (!sameCommit || (releaseDigest !== null && named !== releaseDigest)) {
+                throw new ReleaseLabelError("release-label-taken", `the label "${req.label}" already names release ${named}${other && !sameCommit ? `, cut from commit ${other.commit.slice(0, 12)}` : ""}`);
+            }
+            alreadyCut = named;
+        }
+    }
+    if (releaseDigest !== null && alreadyCut === null && cuts.some((c) => c.releaseDigest === releaseDigest)) {
+        const own = labels.get(releaseDigest);
+        if (own !== undefined && req.label !== null && own !== req.label) {
+            throw new ReleaseLabelError("release-already-labelled", `release ${releaseDigest} is already labelled "${own}", and a release takes one label`);
+        }
+        alreadyCut = releaseDigest;
+    }
+    const steps = new Map();
+    for (const t of p.compiled) {
+        for (const [component, list] of Object.entries(t.publishSteps ?? {})) {
+            for (const step of list) {
+                const kind = typeof step.kind === "string" ? step.kind : "publish";
+                const to = typeof step.to === "string" ? step.to : null;
+                const key = JSON.stringify([component, kind, to]);
+                const entry = steps.get(key) ?? { component, kind, to, envs: [] };
+                if (!entry.envs.includes(t.env))
+                    entry.envs.push(t.env);
+                steps.set(key, entry);
+            }
+        }
+    }
+    return {
+        commit: p.commit,
+        member: p.member,
+        label: req.label,
+        releaseDigest,
+        alreadyCut,
+        targets: targets.map((t) => ({ env: t.env, params: t.params, templates: t.templates.map(({ component, path }) => ({ component, path })) })),
+        build,
+        reused: p.reused,
+        publishSteps: [...steps.values()],
+        signatureRequired: p.releaseRule.requirement !== null,
+    };
+}
+/**
+ * Cut a release of the member at `req.cwd` from its checkout's `HEAD`. Writes
+ * the release and the cut to the local `chant/lifecycle` branch and does not
+ * push. Throws {@link ReleaseCutError} before anything is written when the
+ * commit isn't green, the tree is dirty, or an environment can't be compiled
+ * to the same artifacts, and `ReleaseLabelError` (./release-store.ts) when the
+ * label is taken or the release already carries another one.
+ *
+ * The cut line names its run (#4027): the CI run's id and origin in CI, and
+ * outside CI an id minted from the cut's time, `local-<epoch ms>`, with the
+ * origin `{ forge: "local" }`.
+ */
+export async function cutRelease(req) {
+    const p = await prepare(req);
+    const { cwd, commit, compiled, releaseRule, reused } = p;
+    const artifacts = [...p.carried];
+    for (const env of p.envs) {
+        const names = p.toBuild.get(env);
+        if (names)
+            artifacts.push(...(await req.compiler.buildArtifacts(env, names)));
+    }
+    const { targets, templates } = targetsOf(compiled);
+    const release = makeRelease({ member: p.member, commit, artifactDigests: artifacts, targets });
+    const timestamp = (req.now ?? (() => new Date()))().toISOString();
+    const signed = { releaseDigest: release.releaseDigest, label: req.label, actor: req.actor, timestamp };
+    let signature = null;
+    if (req.sign !== undefined) {
+        const { resolveSigningKey, sealReleaseCut, SealError } = await import("../workspace/trust/seal.js");
+        try {
+            const key = resolveSigningKey(req.sign, cwd);
+            try {
+                signature = sealReleaseCut(key.file, signed).signature;
+            }
+            finally {
+                key.cleanup();
+            }
+        }
+        catch (err) {
+            if (!(err instanceof SealError))
+                throw err;
+            throw new ReleaseCutError("release-signer-refused", `no release was cut: ${err.message}`);
+        }
+    }
+    if (releaseRule.requirement) {
+        const { admitReleaseCut } = await import("../workspace/identity-gate-rule.js");
+        const why = admitReleaseCut(releaseRule.rule, { ...signed, signature });
+        if (why !== null) {
+            throw new ReleaseCutError("release-signer-refused", `no release was cut: ${why}`, `identity.gates.release in chant.workspace.json at base counts only a cut signed by a key ${releaseRule.rule.signers.signersPath} lists for the actor` +
+                (releaseRule.requirement.class !== null ? `, who holds the role of the class ${releaseRule.requirement.class}` : "") +
+                ". Pass --actor <principal> naming that signer.");
+        }
+    }
+    const stored = await persistRelease(release, templates, { cwd });
+    const ci = resolveCiRun(req.env ?? process.env);
+    const outcome = await appendCut({
+        releaseDigest: release.releaseDigest,
+        label: req.label,
+        actor: req.actor,
+        timestamp,
+        runId: ci?.runId ?? `local-${Date.parse(timestamp)}`,
+        runOrigin: ci?.runOrigin ?? { forge: "local" },
+        signature,
+    }, { cwd });
+    return {
+        release,
+        cut: outcome.appended ? outcome.cut : null,
+        label: outcome.appended ? outcome.cut.label : outcome.label,
+        stored: stored.written,
+        reused,
+    };
+}