@intentius/chant 0.124.27 → 0.124.29

package/dist/lifecycle/release-store.js

@@ -0,0 +1,320 @@
+/**
+ * The release (#4026, ws-104): one green commit of one member, compiled for
+ * every environment the member declares, stored on `chant/lifecycle`.
+ *
+ * A release is a different object from a deploy record. A deploy record is
+ * one line of `<env>/releases.jsonl` (./release-ledger.ts) saying a component
+ * was deployed. A release is what is cut once from a green commit and then
+ * moves through the environments: the commit, the artifacts built once from
+ * it, and one compile target per environment, each with the template digests
+ * and the build parameters that environment was compiled with.
+ *
+ * Storage, per ws-104 question 3:
+ *
+ *   _releases/<releaseDigest>.json      the release, written once and never rewritten
+ *   _releases/cuts.jsonl                one line per cut, with the release's label
+ *   _releases/templates/<digest>.txt    each template's bytes, by content digest
+ *
+ * `:` is written as `_` in file names, as `_plans/` and `_builds/` do. A
+ * workspace member's copy sits under `_members/<member>/` through the same
+ * `ledgerDir` prefix every other store uses.
+ *
+ * The template bytes are kept so that a promote under a release deploys the
+ * templates the cut recorded, not whatever the promoting checkout holds
+ * (ws-104 question 5). They are named by content digest, so a template that
+ * two environments or two releases share is stored once.
+ *
+ * `releaseDigest` is `computePlanDigest("release", subject)` over the member,
+ * the commit, the artifact digests and each target's env, templates and the
+ * name and value of each param. A param's `source`, the label, the actor, the
+ * time and any signature stay outside it, so two cuts of one commit give the
+ * same digest.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { contentDigest } from "../content-digest.js";
+import { computePlanDigest } from "./plan-digest.js";
+import { ledgerDir, listFilesInDir, readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles, } from "./git.js";
+/** The directory on `chant/lifecycle` that holds releases, cuts and template bytes. */
+export const RELEASES_DIR = "_releases";
+/** The cut log inside {@link RELEASES_DIR}. */
+export const CUTS_FILE = "cuts.jsonl";
+/** The directory inside {@link RELEASES_DIR} that holds template bytes by content digest. */
+export const TEMPLATES_SUBDIR = "templates";
+/** The `kind` a release digest is computed under, so it can never equal a plan digest of another kind. */
+export const RELEASE_DIGEST_KIND = "release";
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** The same release with every list in the order ws-104 sets: artifacts by component then path, targets by env, templates by component then path, params by name. */
+export function normalizeRelease(release) {
+    return {
+        ...release,
+        artifactDigests: [...release.artifactDigests]
+            .map(({ component, kind, path, digest }) => ({ component, kind, path, digest }))
+            .sort((a, b) => byString(a.component, b.component) || byString(a.path, b.path)),
+        targets: [...release.targets]
+            .map((t) => ({
+            env: t.env,
+            templates: [...t.templates]
+                .map(({ component, path, digest }) => ({ component, path, digest }))
+                .sort((a, b) => byString(a.component ?? "", b.component ?? "") || byString(a.path, b.path)),
+            params: [...t.params].map(({ name, value, source }) => ({ name, value, source })).sort((a, b) => byString(a.name, b.name)),
+        }))
+            .sort((a, b) => byString(a.env, b.env)),
+    };
+}
+/** The hash input of ws-104 question 3: a param's `source` is left out. */
+export function releaseHashInput(release) {
+    const n = normalizeRelease(release);
+    return {
+        member: n.member,
+        commit: n.commit,
+        artifactDigests: n.artifactDigests,
+        targets: n.targets.map((t) => ({ env: t.env, templates: t.templates, params: t.params.map(({ name, value }) => ({ name, value })) })),
+    };
+}
+/** `computePlanDigest("release", input)` over {@link releaseHashInput}. */
+export function computeReleaseDigest(release) {
+    return computePlanDigest(RELEASE_DIGEST_KIND, releaseHashInput(release));
+}
+/** A release with its digest computed and its lists in order. */
+export function makeRelease(subject) {
+    const normalized = normalizeRelease(subject);
+    return { version: 1, releaseDigest: computeReleaseDigest(normalized), ...normalized };
+}
+/** Whether a release's own `releaseDigest` is the digest of what it holds. */
+export function verifyReleaseDigest(release) {
+    return release.releaseDigest === computeReleaseDigest(release);
+}
+const stem = (digest) => digest.replace(/:/g, "_");
+const releaseFile = (digest) => `${stem(digest)}.json`;
+const templateFile = (digest) => `${stem(digest)}.txt`;
+/** A label names a release in commands such as `chant release cut <label>`, so it is one plain word. */
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/;
+/** Why a label can't be used, or undefined when it can. */
+export function invalidLabel(label) {
+    if (LABEL_PATTERN.test(label))
+        return undefined;
+    return `"${label}" is not a release label: use letters, digits and . _ + -, starting with a letter or digit, at most 128 characters`;
+}
+/** Thrown when a cut would give a label two digests, or a digest two labels. */
+export class ReleaseLabelError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ReleaseLabelError";
+    }
+}
+/**
+ * Store a release and its template bytes in one commit. A release already
+ * stored under its digest is never rewritten, and a template already stored
+ * is not written again. Does not push.
+ */
+export async function persistRelease(release, templates, opts) {
+    if (!verifyReleaseDigest(release)) {
+        throw new Error(`release ${release.releaseDigest} does not hash to its own digest; refusing to store it`);
+    }
+    for (const t of templates) {
+        if (contentDigest(t.content) !== t.digest)
+            throw new Error(`template bytes do not hash to ${t.digest}; refusing to store them`);
+    }
+    const dir = await ledgerDir(RELEASES_DIR, opts);
+    const files = [];
+    const releasePath = `${dir}/${releaseFile(release.releaseDigest)}`;
+    const exists = (await readPathSha(RELEASES_DIR, releaseFile(release.releaseDigest), opts)) !== null;
+    if (!exists)
+        files.push({ path: releasePath, content: `${JSON.stringify(release, sortedJsonReplacer)}\n`, expectPriorSha: null });
+    const seen = new Set();
+    for (const t of templates) {
+        if (seen.has(t.digest))
+            continue;
+        seen.add(t.digest);
+        if ((await readPathSha(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(t.digest), opts)) !== null)
+            continue;
+        files.push({ path: `${dir}/${TEMPLATES_SUBDIR}/${templateFile(t.digest)}`, content: t.content, expectPriorSha: null });
+    }
+    if (files.length === 0)
+        return { commit: null, written: false };
+    try {
+        const commit = await writeLedgerFiles(files, `Release ${release.releaseDigest}`, opts);
+        return { commit, written: !exists };
+    }
+    catch (err) {
+        // Another writer stored the same content-addressed files first.
+        if (err instanceof RefCASConflictError)
+            return { commit: null, written: false };
+        throw err;
+    }
+}
+/** Parse a stored release file, or null when it is not a release. */
+export function parseRelease(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const r = parsed;
+    const ok = r.version === 1 &&
+        typeof r.releaseDigest === "string" &&
+        (r.member === null || typeof r.member === "string") &&
+        typeof r.commit === "string" &&
+        Array.isArray(r.artifactDigests) &&
+        r.artifactDigests.every((a) => a && typeof a.component === "string" && (a.kind === "image" || a.kind === "asset") && typeof a.path === "string" && typeof a.digest === "string") &&
+        Array.isArray(r.targets) &&
+        r.targets.every((t) => t &&
+            typeof t.env === "string" &&
+            Array.isArray(t.templates) &&
+            t.templates.every((x) => x && (x.component === null || typeof x.component === "string") && typeof x.path === "string" && typeof x.digest === "string") &&
+            Array.isArray(t.params) &&
+            t.params.every((p) => p && typeof p.name === "string" && ["string", "number", "boolean"].includes(typeof p.value) && typeof p.source === "string"));
+    return ok ? r : null;
+}
+/** Read one release by digest. Null when none is stored, or when the file is not a release whose content hashes to its digest. */
+export async function readRelease(digest, opts) {
+    const text = await readBlobFromPath(RELEASES_DIR, releaseFile(digest), opts);
+    if (text === null)
+        return null;
+    const release = parseRelease(text);
+    if (!release || release.releaseDigest !== digest || !verifyReleaseDigest(release))
+        return null;
+    return release;
+}
+/** Every stored release, and how many release files could not be read as one. */
+export async function readAllReleases(opts) {
+    const releases = [];
+    let malformed = 0;
+    for (const name of await listFilesInDir(RELEASES_DIR, opts)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const digest = name.slice(0, -".json".length).replace(/_/g, ":");
+        const release = await readRelease(digest, opts);
+        if (release)
+            releases.push(release);
+        else
+            malformed++;
+    }
+    return { releases, malformed };
+}
+/** Parse the lines of `cuts.jsonl`. A line that is not a cut is counted and skipped. */
+export function parseCuts(text) {
+    const cuts = [];
+    let malformed = 0;
+    for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const c = JSON.parse(line);
+            const ok = c &&
+                c.version === 1 &&
+                typeof c.releaseDigest === "string" &&
+                (c.label === null || typeof c.label === "string") &&
+                typeof c.actor === "string" &&
+                typeof c.timestamp === "string" &&
+                (c.runOrigin === null || (typeof c.runOrigin === "object" && typeof c.runOrigin?.forge === "string")) &&
+                (c.signature === null || c.signature === undefined || typeof c.signature === "string") &&
+                (c.runId === null || c.runId === undefined || typeof c.runId === "string");
+            if (!ok) {
+                malformed++;
+                continue;
+            }
+            cuts.push({ ...c, runId: c.runId ?? null, signature: c.signature ?? null });
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { cuts, malformed };
+}
+/** Every cut, oldest first. */
+export async function readCuts(opts) {
+    return parseCuts(await readBlobFromPath(RELEASES_DIR, CUTS_FILE, opts));
+}
+/** The label each digest carries, from its labelled cuts. */
+export function labelsByDigest(cuts) {
+    const out = new Map();
+    for (const c of cuts)
+        if (c.label !== null && !out.has(c.releaseDigest))
+            out.set(c.releaseDigest, c.label);
+    return out;
+}
+const CUT_RETRY_ATTEMPTS = 5;
+/**
+ * Append a cut for `releaseDigest`. A label names one digest and a digest
+ * takes at most one label (ws-104 question 3): cutting a digest again is a
+ * no-op that returns its label, giving an unlabelled digest a label appends a
+ * cut, and cutting a digest under a label other than its own, or under a
+ * label another digest has, throws {@link ReleaseLabelError}. Does not push.
+ */
+export async function appendCut(input, opts) {
+    if (input.label !== null) {
+        const why = invalidLabel(input.label);
+        if (why)
+            throw new ReleaseLabelError("release-label-invalid", why);
+    }
+    let lastErr;
+    for (let attempt = 1; attempt <= CUT_RETRY_ATTEMPTS; attempt++) {
+        const priorSha = await readPathSha(RELEASES_DIR, CUTS_FILE, opts);
+        const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+        const { cuts } = parseCuts(existing);
+        const labels = labelsByDigest(cuts);
+        const own = labels.get(input.releaseDigest);
+        const alreadyCut = cuts.some((c) => c.releaseDigest === input.releaseDigest);
+        if (own !== undefined) {
+            if (input.label === null || input.label === own)
+                return { appended: false, label: own };
+            throw new ReleaseLabelError("release-already-labelled", `release ${input.releaseDigest} is already labelled "${own}", and a release takes one label`);
+        }
+        if (input.label === null && alreadyCut)
+            return { appended: false, label: null };
+        if (input.label !== null) {
+            for (const [digest, label] of labels) {
+                if (label === input.label) {
+                    throw new ReleaseLabelError("release-label-taken", `the label "${input.label}" already names release ${digest}`);
+                }
+            }
+        }
+        const cut = {
+            version: 1,
+            releaseDigest: input.releaseDigest,
+            label: input.label,
+            actor: input.actor,
+            timestamp: input.timestamp,
+            runId: input.runId ?? null,
+            runOrigin: input.runOrigin,
+            signature: input.signature ?? null,
+        };
+        const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${JSON.stringify(cut, sortedJsonReplacer)}\n`;
+        try {
+            const dir = await ledgerDir(RELEASES_DIR, opts);
+            await writeLedgerFiles([{ path: `${dir}/${CUTS_FILE}`, content, expectPriorSha: priorSha }], "Release cut", opts);
+            return { appended: true, cut };
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/** A template's bytes by digest, or null when none is stored. */
+export async function readReleaseTemplate(digest, opts) {
+    return readBlobFromPath(`${RELEASES_DIR}/${TEMPLATES_SUBDIR}`, templateFile(digest), opts);
+}
+/**
+ * Find a release by its digest or its label. Null when neither names one.
+ * A string that names a digest is read as a digest first.
+ */
+export async function resolveRelease(ref, opts) {
+    const { cuts } = await readCuts(opts);
+    const labels = labelsByDigest(cuts);
+    let digest = ref.includes(":") ? ref : undefined;
+    if (!digest)
+        for (const [d, label] of labels)
+            if (label === ref)
+                digest = d;
+    if (!digest)
+        return null;
+    const release = await readRelease(digest, opts);
+    return release ? { release, label: labels.get(digest) ?? null } : null;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `chant release verify <label|digest>` (#4049): whether a release was
+ * signed by a key `.chant/allowed_signers` lists, checked offline.
+ *
+ * It reads the release and its cuts from the local `chant/lifecycle` branch,
+ * and the signers file, its signed history (#2553) and the declaration at the
+ * release's own commit, as `chant workspace evidence verify` reads the policy
+ * at the revision it is given. It fetches nothing and needs no key. A release
+ * verifies when its file's digest is the digest of what it holds and one of
+ * its cuts carries a signature in the `chant-release` namespace that verifies
+ * for the cut's actor, over the release digest, the label, the actor and the
+ * time (`releaseSealPayload`), and, when the declaration at that commit has an
+ * `identity.gates.release` entry naming a class, the actor is in it.
+ *
+ * Reading the signers at the release's commit means a key added later does
+ * not make an old release verify, and one removed later does not unmake it.
+ */
+import type { ReleaseSignatureCheck } from "../workspace/identity-gate-rule.js";
+import type { ReleaseCut } from "./release-store.js";
+/** What `release verify --json` prints. */
+export interface ReleaseVerification {
+    releaseDigest: string;
+    label: string | null;
+    member: string | null;
+    commit: string;
+    /** Where the signers were read: the signers file's path and the commit. */
+    signers: {
+        path: string;
+        at: string;
+        active: boolean;
+    };
+    /** True when the release file's digest is the digest of what it holds. */
+    digestMatches: boolean;
+    /** `verified` when a cut's signature verifies; `unsigned` when no cut carries one; `unverified` otherwise. */
+    status: "verified" | "unsigned" | "unverified";
+    /** The cut whose signature verified, or null. */
+    verifiedBy: {
+        actor: string;
+        key: string | null;
+    } | null;
+    reason: string;
+    cuts: Array<Pick<ReleaseCut, "label" | "actor" | "timestamp" | "runId"> & {
+        signatureCheck: ReleaseSignatureCheck;
+    }>;
+}
+/** Why a release could not be checked at all. */
+export interface ReleaseVerifyError {
+    code: "release-not-found" | "release-commit-missing" | "trust-policy-unreadable" | "not-a-git-repository";
+    message: string;
+    fix?: string;
+}
+/** The exit-1 codes of a release that was checked and did not verify. */
+export declare function verificationCode(v: ReleaseVerification): "release-digest-mismatch" | "release-unsigned" | "release-signature-unverified" | null;
+/** Check the release `ref` names in the member at `cwd`. Reads only the local repository. */
+export declare function verifyRelease(req: {
+    cwd: string;
+    ref: string;
+}): Promise<ReleaseVerification | {
+    error: ReleaseVerifyError;
+}>;
+//# sourceMappingURL=release-verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"release-verify.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,KAAK,EAAW,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE3D,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACvD,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;IACvB,8GAA8G;IAC9G,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;IAC/C,iDAAiD;IACjD,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC,GAAG;QAAE,cAAc,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;CACtH;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,mBAAmB,GAAG,wBAAwB,GAAG,yBAAyB,GAAG,sBAAsB,CAAC;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,mBAAmB,GAAG,yBAAyB,GAAG,kBAAkB,GAAG,8BAA8B,GAAG,IAAI,CAI/I;AAED,6FAA6F;AAC7F,wBAAsB,aAAa,CAAC,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,GAAG;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAiEnI"}

package/dist/lifecycle/release-verify.js

@@ -0,0 +1,92 @@
+/**
+ * `chant release verify <label|digest>` (#4049): whether a release was
+ * signed by a key `.chant/allowed_signers` lists, checked offline.
+ *
+ * It reads the release and its cuts from the local `chant/lifecycle` branch,
+ * and the signers file, its signed history (#2553) and the declaration at the
+ * release's own commit, as `chant workspace evidence verify` reads the policy
+ * at the revision it is given. It fetches nothing and needs no key. A release
+ * verifies when its file's digest is the digest of what it holds and one of
+ * its cuts carries a signature in the `chant-release` namespace that verifies
+ * for the cut's actor, over the release digest, the label, the actor and the
+ * time (`releaseSealPayload`), and, when the declaration at that commit has an
+ * `identity.gates.release` entry naming a class, the actor is in it.
+ *
+ * Reading the signers at the release's commit means a key added later does
+ * not make an old release verify, and one removed later does not unmake it.
+ */
+/** The exit-1 codes of a release that was checked and did not verify. */
+export function verificationCode(v) {
+    if (!v.digestMatches)
+        return "release-digest-mismatch";
+    if (v.status === "verified")
+        return null;
+    return v.status === "unsigned" ? "release-unsigned" : "release-signature-unverified";
+}
+/** Check the release `ref` names in the member at `cwd`. Reads only the local repository. */
+export async function verifyRelease(req) {
+    const { resolveRelease, readCuts, verifyReleaseDigest } = await import("./release-store.js");
+    const { gitRoot } = await import("../workspace/record-source.js");
+    const { resolveBase } = await import("../workspace/trust/provenance.js");
+    const { scopeSource } = await import("../workspace/write-scope.js");
+    const { releaseRuleFrom } = await import("../workspace/identity.js");
+    const { checkReleaseSignature } = await import("../workspace/identity-gate-rule.js");
+    const { cwd, ref } = req;
+    const top = gitRoot(cwd);
+    if (!top)
+        return { error: { code: "not-a-git-repository", message: "a release is checked against the signers file at its commit, and this directory is not in a git repository" } };
+    const found = await resolveRelease(ref, { cwd });
+    if (!found)
+        return { error: { code: "release-not-found", message: `no release is labelled or digested "${ref}" in this member`, fix: "Fetch chant/lifecycle (git fetch origin chant/lifecycle:chant/lifecycle), then list them with: chant release list" } };
+    const release = found.release;
+    const at = resolveBase(top, release.commit).commit;
+    if (!at) {
+        return {
+            error: {
+                code: "release-commit-missing",
+                message: `the release's commit ${release.commit} is not in this clone, so the signers file at it can't be read`,
+                fix: `Fetch it: git fetch origin ${release.commit}`,
+            },
+        };
+    }
+    const source = scopeSource(cwd, at);
+    if (source.policy.problems.length > 0) {
+        return { error: { code: "trust-policy-unreadable", message: `the signers at ${at.slice(0, 12)} can't be read: ${source.policy.problems.join("; ")}` } };
+    }
+    const read = releaseRuleFrom(source);
+    // A declaration read from the working tree is not the commit's, so its class does not apply.
+    const rule = source.from === "base" ? read.rule : { ...read.rule, class: null };
+    const own = (await readCuts({ cwd })).cuts.filter((c) => c.releaseDigest === release.releaseDigest);
+    // The check words where it read the signers as "at base"; here that is the release's commit.
+    const atCommit = (check) => ({ ...check, reason: check.reason.split(`${rule.signers.signersPath} at base`).join(`${rule.signers.signersPath} at ${at.slice(0, 12)}`) });
+    const cuts = own.map((c) => ({
+        label: c.label,
+        actor: c.actor,
+        timestamp: c.timestamp,
+        runId: c.runId ?? null,
+        signatureCheck: atCommit(checkReleaseSignature(rule, { releaseDigest: c.releaseDigest, label: c.label, actor: c.actor, timestamp: c.timestamp, signature: c.signature })),
+    }));
+    const verified = cuts.find((c) => c.signatureCheck.status === "verified");
+    const digestMatches = verifyReleaseDigest(release);
+    const status = verified ? "verified" : cuts.every((c) => c.signatureCheck.status === "unsigned") ? "unsigned" : "unverified";
+    const where = `${rule.signers.signersPath} at ${at.slice(0, 12)}`;
+    const reason = !digestMatches
+        ? `the release file's digest ${release.releaseDigest} is not the digest of what it holds, so it was changed after the cut`
+        : verified
+            ? `${verified.signatureCheck.reason}, checked against ${where}`
+            : status === "unsigned"
+                ? `no cut of the release carries a signature`
+                : cuts.map((c) => c.signatureCheck.reason).join("; ");
+    return {
+        releaseDigest: release.releaseDigest,
+        label: found.label,
+        member: release.member,
+        commit: release.commit,
+        signers: { path: rule.signers.signersPath, at, active: rule.signers.active },
+        digestMatches,
+        status: digestMatches ? status : "unverified",
+        verifiedBy: digestMatches && verified ? { actor: verified.actor, key: verified.signatureCheck.key } : null,
+        reason,
+        cuts,
+    };
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Cutting a release from a workstation as from CI (#4027).
+ *
+ * `chant release cut` runs the same steps wherever it runs. What differs
+ * between a laptop and a CI job is read here, from git and the process
+ * environment, so the CLI and its tests resolve it the same way:
+ *
+ * - trunk: the branch `ci.green.branch` names in the declaration at base,
+ *   else the branch `origin/HEAD` points at, else `main`. The commit must be
+ *   reachable from `origin/<branch>` as this clone last fetched it, so a
+ *   commit that is on the local branch only is refused as not pushed. Nothing
+ *   is fetched: a stale `origin/<branch>` can only refuse a commit that was
+ *   pushed since, never admit one that wasn't.
+ * - a clean tree: no tracked change and no untracked file that git does not
+ *   ignore, since the compile reads the directory and a new
+ *   `*.component.ts` would be compiled into the release.
+ * - the actor: `--actor`, else the principal the signers file at base lists
+ *   for the signing key, else the CI's actor, else git's `user.email`, else
+ *   `$USER`.
+ * - the tag: `release/<label>`, or `release/<member>/<label>` in a workspace
+ *   member, an annotated tag on the commit that is created locally and never
+ *   pushed by chant.
+ */
+import type { Signer } from "../workspace/trust/trust-files.js";
+export type WorkstationCheckCode = "release-commit-not-on-trunk" | "release-commit-not-pushed" | "release-worktree-dirty" | "release-tag-taken" | "release-tag-invalid";
+/** A refusal before anything is compiled or written. */
+export declare class WorkstationCheckError extends Error {
+    readonly code: WorkstationCheckCode;
+    readonly fix?: string | undefined;
+    constructor(code: WorkstationCheckCode, message: string, fix?: string | undefined);
+}
+/** The remote a release's commit must be pushed to. */
+export declare const RELEASE_REMOTE = "origin";
+/** The trunk branch, and where its name came from. */
+export interface Trunk {
+    remote: string;
+    branch: string;
+    from: "ci.green.branch" | "origin/HEAD" | "default";
+}
+/** The trunk of the repository at `cwd`: `ci.green.branch` when declared, else what `origin/HEAD` names, else `main`. */
+export declare function resolveTrunk(cwd: string, greenBranch: string | null): Trunk;
+/**
+ * Refuse `commit` unless it is reachable from `<remote>/<branch>` as this
+ * clone knows it. A commit on the local branch only is `release-commit-not-pushed`;
+ * any other is `release-commit-not-on-trunk`.
+ */
+export declare function checkOnTrunk(cwd: string, commit: string, trunk: Trunk): void;
+/** Refuse a tree with a tracked change or an untracked file git does not ignore. */
+export declare function checkCleanTree(cwd: string, commit: string): void;
+/** Where the actor came from. */
+export type ActorSource = "flag" | "signer" | "ci" | "git" | "user";
+/** The public key `keyFile` holds or names, as `<type> <base64>`, or null when it can't be read without a passphrase. */
+export declare function publicKeyOf(keyFile: string): string | null;
+/** The one principal `signers` lists for `publicKey`, or null for none or several. */
+export declare function signerPrincipal(publicKey: string, signers: readonly Signer[]): string | null;
+/**
+ * Who cut the release, and where the name came from: `--actor`, else the
+ * signer the signers file at base lists for the signing key, else the CI's
+ * actor (`GITHUB_ACTOR`, `GITLAB_USER_LOGIN`), else git's `user.email`, else
+ * `$USER`. Undefined when none is set.
+ */
+export declare function resolveCutActor(req: {
+    cwd: string;
+    explicit?: string;
+    /** The signing key's public half, when the cut is signed and it could be read. */
+    publicKey?: string | null;
+    signers?: readonly Signer[];
+    env?: NodeJS.ProcessEnv;
+}): {
+    actor: string;
+    source: ActorSource;
+} | undefined;
+/** The tag a labelled release gets: `release/<label>`, or `release/<member>/<label>` for a workspace member. */
+export declare function releaseTagName(member: string | null, label: string): string;
+/**
+ * Whether `tag` can name `commit`: `absent` (the cut creates it), `present`
+ * (it already names the commit), or a {@link WorkstationCheckError} for a
+ * tag that names another commit or is not a valid tag name.
+ */
+export declare function checkReleaseTag(cwd: string, tag: string, commit: string): "absent" | "present";
+/**
+ * Create `tag` on `commit` as an annotated tag whose message names the
+ * release. Local only. A clone with no git identity tags as chant, as the ci
+ * tags are made.
+ */
+export declare function createReleaseTag(cwd: string, tag: string, commit: string, release: {
+    releaseDigest: string;
+    label: string;
+    member: string | null;
+}): void;
+//# sourceMappingURL=release-workstation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"release-workstation.d.ts","sourceRoot":"","sources":["../../src/lifecycle/release-workstation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAE7D,MAAM,MAAM,oBAAoB,GAAG,6BAA6B,GAAG,2BAA2B,GAAG,wBAAwB,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAExK,wDAAwD;AACxD,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,QAAQ,CAAC,IAAI,EAAE,oBAAoB;IAEnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM;IAHvB,YACW,IAAI,EAAE,oBAAoB,EACnC,OAAO,EAAE,MAAM,EACN,GAAG,CAAC,EAAE,MAAM,YAAA,EAItB;CACF;AAaD,uDAAuD;AACvD,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,sDAAsD;AACtD,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAAC;CACrD;AAED,yHAAyH;AACzH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAM3E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAwB5E;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAehE;AAED,iCAAiC;AACjC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpE,yHAAyH;AACzH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmB1D;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAG5F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,SAAS,CAarD;AAED,gHAAgH;AAChH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAY9F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAMzJ"}