@intentius/chant 0.124.27 → 0.124.29

package/src/lifecycle/release-verify.test.ts

@@ -0,0 +1,110 @@
+/**
+ * #4049: `chant release verify` checks a release's signature offline against
+ * `.chant/allowed_signers` at the release's commit. A release signed by a
+ * listed key verifies; an unsigned one and one signed by a key the file does
+ * not list do not; and a key listed only after the release's commit does not
+ * make it verify. Throwaway keys in temp repos only.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { rmSync } from "node:fs";
+import { dirname } from "node:path";
+import { cutRelease } from "./release-cut";
+import { verificationCode, verifyRelease, type ReleaseVerification } from "./release-verify";
+import type { ReleaseArtifact } from "./release-store";
+import type { CompiledTarget, TargetCompiler } from "../components/release-compile";
+import { hasSshKeygen, TestRepo, type Key } from "../workspace/trust/test-repo";
+
+const repos: TestRepo[] = [];
+afterAll(() => {
+  for (const r of repos) rmSync(dirname(r.dir), { recursive: true, force: true });
+});
+
+const compiler: TargetCompiler = {
+  async compile(env): Promise<CompiledTarget> {
+    return { env, params: [], components: ["api"], buildSteps: {}, buildInputs: {}, componentFiles: { api: "api.component.ts" }, templates: [{ component: "api", path: "dist/api.json", content: `{"env":"${env}"}\n` }] };
+  },
+  async buildArtifacts(): Promise<ReleaseArtifact[]> {
+    return [];
+  },
+};
+
+/** A plain project whose signers file lists alice, with one green commit. */
+function setup(): { r: TestRepo; alice: Key; bob: Key } {
+  const r = new TestRepo("release-verify");
+  repos.push(r);
+  const alice = r.key("alice");
+  const bob = r.key("bob");
+  r.write(".chant/allowed_signers", `alice ${alice.pub}\n`);
+  r.write("chant.config.ts", `export default { environments: ["dev"] };\n`);
+  r.write("api.component.ts", "export const api = {};\n");
+  green(r, "init");
+  return { r, alice, bob };
+}
+
+function green(r: TestRepo, message: string): string {
+  const head = r.commit(message);
+  r.git(["tag", `ci/green/${head}`]);
+  return head;
+}
+
+const cut = (r: TestRepo, label: string, actor: string, sign?: Key) =>
+  cutRelease({ cwd: r.dir, compiler, label, actor, env: {}, now: () => new Date("2026-10-17T10:00:00.000Z"), ...(sign ? { sign: sign.file } : {}) });
+const checked = async (r: TestRepo, ref: string): Promise<ReleaseVerification> => {
+  const v = await verifyRelease({ cwd: r.dir, ref });
+  if ("error" in v) throw new Error(v.error.message);
+  return v;
+};
+
+describe("chant release verify", () => {
+  test.skipIf(!hasSshKeygen)("passes for a release signed by a key the signers file lists at its commit", async () => {
+    const { r, alice } = setup();
+    const { release } = await cut(r, "v1", "alice", alice);
+    const v = await checked(r, "v1");
+    expect(v).toMatchObject({ releaseDigest: release.releaseDigest, label: "v1", commit: release.commit, digestMatches: true, status: "verified", verifiedBy: { actor: "alice", key: expect.stringMatching(/^SHA256:/) } });
+    expect(v.signers).toEqual({ path: ".chant/allowed_signers", at: release.commit, active: true });
+    expect(v.reason).toBe(`signed by alice, checked against .chant/allowed_signers at ${release.commit.slice(0, 12)}`);
+    expect(verificationCode(v)).toBeNull();
+    // By digest too.
+    expect((await checked(r, release.releaseDigest)).status).toBe("verified");
+  });
+
+  test("fails for an unsigned release", async () => {
+    const { r } = setup();
+    await cut(r, "v1", "alice");
+    const v = await checked(r, "v1");
+    expect(v.status).toBe("unsigned");
+    expect(v.verifiedBy).toBeNull();
+    expect(v.cuts).toEqual([expect.objectContaining({ actor: "alice", signatureCheck: { status: "unsigned", key: null, reason: "the cut carries no signature" } })]);
+    expect(verificationCode(v)).toBe("release-unsigned");
+  });
+
+  test.skipIf(!hasSshKeygen)("fails for a release signed by a key the signers file does not list, also once a later commit lists it", async () => {
+    const { r, bob } = setup();
+    await cut(r, "v1", "bob", bob);
+    const v = await checked(r, "v1");
+    expect(v.status).toBe("unverified");
+    expect(v.reason).toBe(`bob has no key in .chant/allowed_signers at ${v.commit.slice(0, 12)}, so the cut's signature can't count`);
+    expect(verificationCode(v)).toBe("release-signature-unverified");
+
+    // bob's key is listed after the release's commit: the release still reads the file at its own commit.
+    r.write(".chant/allowed_signers", `alice ${r.key("alice2").pub}\nbob ${bob.pub}\n`);
+    green(r, "list bob");
+    expect((await checked(r, "v1")).status).toBe("unverified");
+  });
+
+  test.skipIf(!hasSshKeygen)("fails for a cut signed with one key in another signer's name", async () => {
+    const { r, bob } = setup();
+    // bob's key, in alice's name.
+    await cut(r, "v1", "alice", bob);
+    const v = await checked(r, "v1");
+    expect(v.status).toBe("unverified");
+    expect(v.reason).toMatch(/the cut's signature does not verify for alice/);
+  });
+
+  test("names a release it can't find", async () => {
+    const { r } = setup();
+    const v = await verifyRelease({ cwd: r.dir, ref: "v9" });
+    expect("error" in v && v.error.code).toBe("release-not-found");
+  });
+});

package/src/lifecycle/release-verify.ts

@@ -0,0 +1,120 @@
+/**
+ * `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";
+import type { Release, ReleaseCut } from "./release-store";
+
+/** 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 function verificationCode(v: ReleaseVerification): "release-digest-mismatch" | "release-unsigned" | "release-signature-unverified" | null {
+  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: { cwd: string; ref: string }): Promise<ReleaseVerification | { error: ReleaseVerifyError }> {
+  const { resolveRelease, readCuts, verifyReleaseDigest } = await import("./release-store");
+  const { gitRoot } = await import("../workspace/record-source");
+  const { resolveBase } = await import("../workspace/trust/provenance");
+  const { scopeSource } = await import("../workspace/write-scope");
+  const { releaseRuleFrom } = await import("../workspace/identity");
+  const { checkReleaseSignature } = await import("../workspace/identity-gate-rule");
+  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: 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: ReleaseSignatureCheck): ReleaseSignatureCheck => ({ ...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: ReleaseVerification["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/src/lifecycle/release-workstation.test.ts

@@ -0,0 +1,204 @@
+/**
+ * #4027: what a cut reads from the checkout and the environment before it
+ * compiles, against temp repos with temp bare remotes. Nothing is pushed
+ * anywhere but those remotes, and no tag is pushed at all.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  checkCleanTree,
+  checkOnTrunk,
+  checkReleaseTag,
+  createReleaseTag,
+  publicKeyOf,
+  releaseTagName,
+  resolveCutActor,
+  resolveTrunk,
+  WorkstationCheckError,
+} from "./release-workstation";
+import { nextCommands, sameWithYes } from "../cli/handlers/release";
+import { hasSshKeygen } from "../workspace/trust/test-repo";
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/** A repo at `<root>/work` with one commit on main, pushed to the bare `<root>/origin.git`. */
+function pushedRepo(root: string): { dir: string; sha: string } {
+  const dir = join(root, "work");
+  mkdirSync(dir);
+  git(root, "init", "-q", "--bare", "-b", "main", "origin.git");
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "dev@chant.dev");
+  git(dir, "config", "user.name", "Dev");
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  writeFileSync(join(dir, ".gitignore"), "dist/\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  git(dir, "remote", "add", "origin", join(root, "origin.git"));
+  git(dir, "push", "-q", "origin", "main");
+  git(dir, "fetch", "-q", "origin");
+  return { dir, sha: git(dir, "rev-parse", "HEAD") };
+}
+
+const codeOf = (fn: () => unknown): string | undefined => {
+  try {
+    fn();
+    return undefined;
+  } catch (err) {
+    if (err instanceof WorkstationCheckError) return err.code;
+    throw err;
+  }
+};
+
+describe("trunk and pushed", () => {
+  test("trunk is ci.green.branch when declared, else what origin/HEAD names, else main", () =>
+    withTestDir(async (root) => {
+      const { dir } = pushedRepo(root);
+      expect(resolveTrunk(dir, "release")).toEqual({ remote: "origin", branch: "release", from: "ci.green.branch" });
+      // A fetch may set origin/HEAD, depending on the git version.
+      git(dir, "remote", "set-head", "origin", "-d");
+      expect(resolveTrunk(dir, null)).toEqual({ remote: "origin", branch: "main", from: "default" });
+      git(dir, "symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/trunk");
+      expect(resolveTrunk(dir, null)).toEqual({ remote: "origin", branch: "trunk", from: "origin/HEAD" });
+    }));
+
+  test("a commit reachable from origin/<trunk> passes; one only on the local branch is not pushed; one off trunk is refused", () =>
+    withTestDir(async (root) => {
+      const { dir, sha } = pushedRepo(root);
+      const trunk = resolveTrunk(dir, null);
+      expect(codeOf(() => checkOnTrunk(dir, sha, trunk))).toBeUndefined();
+
+      writeFileSync(join(dir, "a.txt"), "a\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "local only");
+      const local = git(dir, "rev-parse", "HEAD");
+      expect(codeOf(() => checkOnTrunk(dir, local, trunk))).toBe("release-commit-not-pushed");
+      // An older commit stays pushed whatever the local branch holds.
+      expect(codeOf(() => checkOnTrunk(dir, sha, trunk))).toBeUndefined();
+
+      git(dir, "checkout", "-q", "-b", "feature", sha);
+      writeFileSync(join(dir, "b.txt"), "b\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "feature");
+      const feature = git(dir, "rev-parse", "HEAD");
+      expect(codeOf(() => checkOnTrunk(dir, feature, trunk))).toBe("release-commit-not-on-trunk");
+      // The branch ci.green names is trunk even when the commit is pushed elsewhere.
+      git(dir, "push", "-q", "origin", "feature");
+      git(dir, "fetch", "-q", "origin");
+      expect(codeOf(() => checkOnTrunk(dir, feature, trunk))).toBe("release-commit-not-on-trunk");
+      expect(codeOf(() => checkOnTrunk(dir, feature, resolveTrunk(dir, "feature")))).toBeUndefined();
+    }));
+
+  test("a clone with no origin/<trunk> can't show the commit pushed", () =>
+    withTestDir(async (root) => {
+      git(root, "init", "-q", "-b", "main", "solo");
+      const dir = join(root, "solo");
+      git(dir, "-c", "user.email=a@b", "-c", "user.name=a", "commit", "-q", "--allow-empty", "-m", "init");
+      const err = (() => {
+        try {
+          checkOnTrunk(dir, git(dir, "rev-parse", "HEAD"), resolveTrunk(dir, null));
+        } catch (e) {
+          return e as WorkstationCheckError;
+        }
+      })();
+      expect(err?.code).toBe("release-commit-not-pushed");
+      expect(err?.message).toMatch(/this clone knows no origin\/main/);
+    }));
+});
+
+describe("a clean tree", () => {
+  test("refuses a tracked change and an untracked file, and ignores what .gitignore covers", () =>
+    withTestDir(async (root) => {
+      const { dir, sha } = pushedRepo(root);
+      expect(codeOf(() => checkCleanTree(dir, sha))).toBeUndefined();
+      mkdirSync(join(dir, "dist"));
+      writeFileSync(join(dir, "dist", "out.json"), "{}\n");
+      expect(codeOf(() => checkCleanTree(dir, sha))).toBeUndefined();
+      writeFileSync(join(dir, "extra.component.ts"), "export const x = {};\n");
+      expect(() => checkCleanTree(dir, sha)).toThrow(/1 untracked file\(s\) such as extra\.component\.ts/);
+      git(dir, "add", "extra.component.ts");
+      writeFileSync(join(dir, "README.md"), "changed\n");
+      expect(() => checkCleanTree(dir, sha)).toThrow(/2 tracked file\(s\) with uncommitted changes/);
+    }));
+});
+
+describe("the actor", () => {
+  test("is --actor, else the CI's actor, else git's user.email", () =>
+    withTestDir(async (root) => {
+      const { dir } = pushedRepo(root);
+      expect(resolveCutActor({ cwd: dir, explicit: "carol", env: { GITHUB_ACTOR: "ci" } })).toEqual({ actor: "carol", source: "flag" });
+      expect(resolveCutActor({ cwd: dir, env: { GITHUB_ACTOR: "octo", USER: "u" } })).toEqual({ actor: "octo", source: "ci" });
+      expect(resolveCutActor({ cwd: dir, env: { GITLAB_USER_LOGIN: "gl", USER: "u" } })).toEqual({ actor: "gl", source: "ci" });
+      expect(resolveCutActor({ cwd: dir, env: { USER: "u" } })).toEqual({ actor: "dev@chant.dev", source: "git" });
+    }));
+
+  test.skipIf(!hasSshKeygen)("is the principal the signers file lists for the signing key, ahead of the CI and git", () =>
+    withTestDir(async (root) => {
+      const { dir } = pushedRepo(root);
+      const key = join(root, "key-alice");
+      execFileSync("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "alice", "-f", key]);
+      const pub = publicKeyOf(key);
+      expect(pub).toMatch(/^ssh-ed25519 [A-Za-z0-9+/=]+$/);
+      expect(publicKeyOf(`${key}.pub`)).toBe(pub);
+      const signers = [
+        { principal: "github:alice", key: pub!, line: 1 },
+        { principal: "bob", key: "ssh-ed25519 AAAAother", line: 2 },
+      ];
+      expect(resolveCutActor({ cwd: dir, publicKey: pub, signers, env: { GITHUB_ACTOR: "octo" } })).toEqual({ actor: "github:alice", source: "signer" });
+      // A key listed for two principals names no one, so the next source answers.
+      const twice = [...signers, { principal: "alice2", key: pub!, line: 3 }];
+      expect(resolveCutActor({ cwd: dir, publicKey: pub, signers: twice, env: { GITHUB_ACTOR: "octo" } })).toEqual({ actor: "octo", source: "ci" });
+      expect(resolveCutActor({ cwd: dir, explicit: "carol", publicKey: pub, signers })).toEqual({ actor: "carol", source: "flag" });
+    }));
+});
+
+describe("the release tag", () => {
+  test("is release/<label>, or release/<member>/<label> in a member, made locally as an annotated tag naming the digest", () =>
+    withTestDir(async (root) => {
+      const { dir, sha } = pushedRepo(root);
+      expect(releaseTagName(null, "v1.2.0")).toBe("release/v1.2.0");
+      expect(releaseTagName("services/api", "v1.2.0")).toBe("release/services/api/v1.2.0");
+      expect(checkReleaseTag(dir, "release/v1", sha)).toBe("absent");
+      createReleaseTag(dir, "release/v1", sha, { releaseDigest: "jcs1-sha256:abc", label: "v1", member: null });
+      expect(git(dir, "cat-file", "-t", "release/v1")).toBe("tag");
+      expect(git(dir, "tag", "-l", "--format=%(contents)", "release/v1")).toBe("release v1\n\nRelease-Digest: jcs1-sha256:abc");
+      expect(checkReleaseTag(dir, "release/v1", sha)).toBe("present");
+      expect(git(root, "ls-remote", "--tags", join(root, "origin.git"))).toBe("");
+
+      writeFileSync(join(dir, "c.txt"), "c\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "next");
+      expect(codeOf(() => checkReleaseTag(dir, "release/v1", git(dir, "rev-parse", "HEAD")))).toBe("release-tag-taken");
+      expect(codeOf(() => checkReleaseTag(dir, "release/v1..2", sha))).toBe("release-tag-invalid");
+    }));
+});
+
+describe("the next command", () => {
+  test("in CI is the publish; on a workstation it pushes the tag first, then publish or deploy", () => {
+    expect(nextCommands({ ref: "v1", tag: "release/v1", inCi: true, firstEnv: "dev", noComponents: false })).toEqual([
+      "chant release publish v1",
+      "chant components promote --release v1 --to dev",
+    ]);
+    expect(nextCommands({ ref: "v1", tag: "release/v1", inCi: false, firstEnv: "dev", noComponents: false })).toEqual([
+      "git push origin release/v1",
+      "chant release publish v1",
+      "chant components promote --release v1 --to dev",
+    ]);
+    expect(nextCommands({ ref: "jcs1-sha256:ab", tag: null, inCi: false, firstEnv: "dev", noComponents: true })).toEqual([
+      "chant release publish jcs1-sha256:ab",
+      "chant release export jcs1-sha256:ab --env dev",
+    ]);
+  });
+
+  test("after a dry run is the same command line with --yes, without --json", () => {
+    expect(sameWithYes(["release", "cut", "v1", "--build", "npm run build", "--json"])).toBe("chant release cut v1 --build 'npm run build' --yes");
+    expect(sameWithYes(["release", "cut", "v1", "--build", "echo 'x'"])).toBe(`chant release cut v1 --build 'echo '\\''x'\\''' --yes`);
+  });
+});

package/src/lifecycle/release-workstation.ts

@@ -0,0 +1,216 @@
+/**
+ * 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 { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import type { Signer } from "../workspace/trust/trust-files";
+
+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 class WorkstationCheckError extends Error {
+  constructor(
+    readonly code: WorkstationCheckCode,
+    message: string,
+    readonly fix?: string,
+  ) {
+    super(message);
+    this.name = "WorkstationCheckError";
+  }
+}
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+const isAncestor = (cwd: string, a: string, b: string): boolean =>
+  spawnSync("git", ["merge-base", "--is-ancestor", a, b], { cwd, stdio: "ignore" }).status === 0;
+
+/** The remote a release's commit must be pushed to. */
+export 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 function resolveTrunk(cwd: string, greenBranch: string | null): Trunk {
+  if (greenBranch) return { remote: RELEASE_REMOTE, branch: greenBranch, from: "ci.green.branch" };
+  const head = tryGit(cwd, ["symbolic-ref", "--quiet", `refs/remotes/${RELEASE_REMOTE}/HEAD`]);
+  const prefix = `refs/remotes/${RELEASE_REMOTE}/`;
+  if (head?.startsWith(prefix)) return { remote: RELEASE_REMOTE, branch: head.slice(prefix.length), from: "origin/HEAD" };
+  return { remote: RELEASE_REMOTE, branch: "main", from: "default" };
+}
+
+/**
+ * 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 function checkOnTrunk(cwd: string, commit: string, trunk: Trunk): void {
+  const remoteRef = `refs/remotes/${trunk.remote}/${trunk.branch}`;
+  const short = commit.slice(0, 12);
+  const named = `${trunk.remote}/${trunk.branch}`;
+  const why = trunk.from === "ci.green.branch" ? " (the branch ci.green names)" : trunk.from === "origin/HEAD" ? ` (the branch ${trunk.remote}/HEAD names)` : "";
+  const remoteTip = tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${remoteRef}^{commit}`]);
+  if (remoteTip && isAncestor(cwd, commit, remoteTip)) return;
+  const localTip = tryGit(cwd, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk.branch}^{commit}`]);
+  if (localTip && isAncestor(cwd, commit, localTip)) {
+    throw new WorkstationCheckError(
+      "release-commit-not-pushed",
+      remoteTip
+        ? `commit ${short} is on ${trunk.branch}${why} but not on ${named}, so it has not been pushed`
+        : `commit ${short} is on ${trunk.branch}${why}, and this clone knows no ${named}, so it can't be shown pushed`,
+      `Push it, or fetch if it was pushed elsewhere: git push ${trunk.remote} ${trunk.branch}, or git fetch ${trunk.remote} ${trunk.branch}`,
+    );
+  }
+  throw new WorkstationCheckError(
+    "release-commit-not-on-trunk",
+    remoteTip
+      ? `commit ${short} is not on ${named}${why}, so a release cut from it would ship what trunk never had`
+      : `commit ${short} is not on ${trunk.branch}${why}, and this clone knows no ${named}`,
+    `Check out a commit of ${named} after fetching it: git fetch ${trunk.remote} ${trunk.branch}`,
+  );
+}
+
+/** Refuse a tree with a tracked change or an untracked file git does not ignore. */
+export function checkCleanTree(cwd: string, commit: string): void {
+  const status = tryGit(cwd, ["status", "--porcelain", "--untracked-files=normal"]);
+  if (status === null || status === "") return;
+  const lines = status.split("\n");
+  const untracked = lines.filter((l) => l.startsWith("??")).map((l) => l.slice(3));
+  const tracked = lines.length - untracked.length;
+  const parts = [
+    ...(tracked > 0 ? [`${tracked} tracked file(s) with uncommitted changes`] : []),
+    ...(untracked.length > 0 ? [`${untracked.length} untracked file(s) such as ${untracked[0]}`] : []),
+  ];
+  throw new WorkstationCheckError(
+    "release-worktree-dirty",
+    `the working tree has ${parts.join(" and ")}, so a compile here would not be commit ${commit.slice(0, 12)}'s`,
+    "Commit, stash or remove them (or add them to .gitignore), or cut from a clean checkout of the commit.",
+  );
+}
+
+/** 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 function publicKeyOf(keyFile: string): string | null {
+  const parse = (text: string): string | null => {
+    const [type, blob] = text.trim().split(/\s+/);
+    return type && blob && /^(ssh-|ecdsa-|sk-)/.test(type) ? `${type} ${blob}` : null;
+  };
+  try {
+    if (existsSync(keyFile)) {
+      const own = parse(readFileSync(keyFile, "utf-8"));
+      if (own) return own;
+    }
+    if (existsSync(`${keyFile}.pub`)) {
+      const pub = parse(readFileSync(`${keyFile}.pub`, "utf-8"));
+      if (pub) return pub;
+    }
+  } catch {
+    return null;
+  }
+  const derived = spawnSync("ssh-keygen", ["-y", "-P", "", "-f", keyFile], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+  return derived.status === 0 ? parse(derived.stdout) : null;
+}
+
+/** The one principal `signers` lists for `publicKey`, or null for none or several. */
+export function signerPrincipal(publicKey: string, signers: readonly Signer[]): string | null {
+  const principals = [...new Set(signers.filter((s) => s.key === publicKey).map((s) => s.principal))];
+  return principals.length === 1 ? principals[0] : 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 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 {
+  const env = req.env ?? process.env;
+  if (req.explicit) return { actor: req.explicit, source: "flag" };
+  if (req.publicKey && req.signers) {
+    const principal = signerPrincipal(req.publicKey, req.signers);
+    if (principal) return { actor: principal, source: "signer" };
+  }
+  const ci = env.GITHUB_ACTOR || env.GITLAB_USER_LOGIN;
+  if (ci) return { actor: ci, source: "ci" };
+  const email = tryGit(req.cwd, ["config", "--get", "user.email"]);
+  if (email) return { actor: email, source: "git" };
+  if (env.USER) return { actor: env.USER, source: "user" };
+  return undefined;
+}
+
+/** The tag a labelled release gets: `release/<label>`, or `release/<member>/<label>` for a workspace member. */
+export function releaseTagName(member: string | null, label: string): string {
+  return member ? `release/${member}/${label}` : `release/${label}`;
+}
+
+/**
+ * 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 function checkReleaseTag(cwd: string, tag: string, commit: string): "absent" | "present" {
+  if (spawnSync("git", ["check-ref-format", `refs/tags/${tag}`], { cwd, stdio: "ignore" }).status !== 0) {
+    throw new WorkstationCheckError("release-tag-invalid", `"${tag}" is not a valid git tag name, so the release can't be tagged`, "Pick a label git accepts in a ref name.");
+  }
+  const at = tryGit(cwd, ["rev-parse", "--verify", "--quiet", `refs/tags/${tag}^{commit}`]);
+  if (at === null) return "absent";
+  if (at === commit) return "present";
+  throw new WorkstationCheckError(
+    "release-tag-taken",
+    `the tag ${tag} already names commit ${at.slice(0, 12)}, not ${commit.slice(0, 12)}`,
+    "Pick another label, or delete the tag if it was made by mistake: git tag -d " + tag,
+  );
+}
+
+/**
+ * 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 function createReleaseTag(cwd: string, tag: string, commit: string, release: { releaseDigest: string; label: string; member: string | null }): void {
+  const ident: string[] = [];
+  if (tryGit(cwd, ["config", "user.name"]) === null) ident.push("-c", "user.name=chant");
+  if (tryGit(cwd, ["config", "user.email"]) === null) ident.push("-c", "user.email=chant@localhost");
+  const message = [`release ${release.label}`, "", `Release-Digest: ${release.releaseDigest}`, ...(release.member ? [`Member: ${release.member}`] : [])].join("\n");
+  execFileSync("git", [...ident, "tag", "-a", "-m", message, tag, commit], { cwd, stdio: ["ignore", "ignore", "pipe"] });
+}