@intentius/chant 0.124.28 → 0.124.29

package/src/lifecycle/release-revocation.ts

@@ -0,0 +1,147 @@
+/**
+ * Which releases are revoked (#4033, ws-105 question 2).
+ *
+ * A release traces to one commit (ws-104), and a commit is revoked when it
+ * carries a `ci/revoked/<sha>` tag that counts (ws-103). So a release is
+ * revoked exactly when its commit is, and this module derives that at read
+ * time from the tags. Nothing is written when a commit is revoked: the tag is
+ * the record, `chant ci tick` makes it once, and every reader below judges it
+ * the same way.
+ *
+ * The tags are judged as `release cut` judges them (#4031): with
+ * `ci.green.signedSince` declared, a revoked tag without a valid runner
+ * statement is ignored and revokes nothing. The declaration and the runner
+ * keys are read at base, the green branch's tip on `origin` (or the local
+ * branch, or `HEAD`). Only local tags are read; nothing is fetched.
+ *
+ * The readers:
+ *
+ * - `chant approve` refuses a release gate whose release is revoked
+ *   (`release-revoked`), and `chant components promote --release` refuses to
+ *   deploy one, so a pending gate for it can never pass.
+ * - `chant workspace status --json` reads such a gate as `superseded` and
+ *   flags a component whose environment runs a revoked release, with the
+ *   rollback line.
+ * - `chant release list` marks a revoked release.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { CiGreen } from "../workspace/declaration";
+import type { CiTags, RevokedTagView } from "../workspace/ci-green";
+
+/** A revoked release: the commit it was cut from and the revoked tag on it, as `ci list` shows the tag. */
+export interface ReleaseRevocation extends RevokedTagView {
+  /** The release's commit, which the tag names. */
+  commit: string;
+}
+
+/** The stable code `approve` and `promote --release` refuse a revoked release with. */
+export const RELEASE_REVOKED_CODE = "release-revoked";
+
+function tryGit(top: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The ci tags at `top`, judged against `green` at base: the green branch's
+ * tip on `origin`, else the local branch, else `HEAD`. With no `ci.green`
+ * every tag counts. Throws `WorkspaceReadError` (`declaration-invalid`) when
+ * `ci.green.signedSince` names no commit here.
+ */
+export async function judgedCiTags(top: string, green: CiGreen | null): Promise<CiTags> {
+  const { readCiTags } = await import("../workspace/ci-green");
+  const base = green
+    ? (tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${green.branch}^{commit}`]) ??
+      tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]) ??
+      tryGit(top, ["rev-parse", "HEAD"]))
+    : null;
+  return readCiTags(top, green, base);
+}
+
+/**
+ * Every revoked commit in the repository holding `cwd`, keyed by its full
+ * sha, with the declaration's `ci.green` read at base as `release cut` reads
+ * it. Empty outside a git repository. Throws `WorkspaceReadError`
+ * (`declaration-invalid`) when the tags can't be judged.
+ */
+export async function readRevokedCommits(cwd: string): Promise<Map<string, ReleaseRevocation>> {
+  const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) return new Map();
+  const { scopeSource } = await import("../workspace/write-scope");
+  return revokedCommitsAt(top, scopeSource(cwd).declaration?.ci?.green ?? null);
+}
+
+/** {@link readRevokedCommits} for a caller that has the git top and the declaration's `ci.green` at base already. */
+export async function revokedCommitsAt(top: string, green: CiGreen | null): Promise<Map<string, ReleaseRevocation>> {
+  const { revokedTagView } = await import("../workspace/ci-green");
+  const out = new Map<string, ReleaseRevocation>();
+  for (const [sha, counted] of (await judgedCiTags(top, green)).revoked) out.set(sha, { commit: sha, ...revokedTagView(sha, counted) });
+  return out;
+}
+
+/** What a reader prints for a release it found revoked: the revocation, the release and its label. */
+export interface RevokedRelease extends ReleaseRevocation {
+  releaseDigest: string;
+  /** The release's label, or null when its cuts gave it none. */
+  label: string | null;
+}
+
+/**
+ * A memoised lookup from a release digest to its revocation, for the member
+ * whose ledger is read from `memberDir`: null when the release is not
+ * revoked, or its file can't be read. `revoked` is called on the first
+ * lookup only, so a reader that meets no release reads no tags, and no
+ * release file is read while no commit is revoked.
+ */
+export function revokedReleaseLookup(
+  memberDir: string,
+  revoked: () => Promise<ReadonlyMap<string, ReleaseRevocation>>,
+): (releaseDigest: string) => Promise<RevokedRelease | null> {
+  const seen = new Map<string, Promise<RevokedRelease | null>>();
+  let labels: Promise<Map<string, string>> | undefined;
+  return (releaseDigest) => {
+    let found = seen.get(releaseDigest);
+    if (!found) {
+      found = (async () => {
+        const commits = await revoked();
+        if (commits.size === 0) return null;
+        const { readRelease, readCuts, labelsByDigest } = await import("./release-store");
+        const loc = { cwd: memberDir };
+        const release = await readRelease(releaseDigest, loc).catch(() => null);
+        const r = release ? revocationOf(release, commits) : null;
+        if (!r) return null;
+        labels ??= readCuts(loc).then((c) => labelsByDigest(c.cuts), () => new Map<string, string>());
+        return { ...r, releaseDigest, label: (await labels).get(releaseDigest) ?? null };
+      })();
+      seen.set(releaseDigest, found);
+    }
+    return found;
+  };
+}
+
+/** Whether `release` is revoked: its commit's revoked tag, or null. */
+export function revocationOf(release: { commit: string }, revoked: ReadonlyMap<string, ReleaseRevocation>): ReleaseRevocation | null {
+  return revoked.get(release.commit) ?? null;
+}
+
+/** What failed, in words: `phase e2e failed in deploy-smoke (Op run r-12 in staging)`. */
+export function describeRevocation(r: ReleaseRevocation): string {
+  const run = r.run
+    ? ` in ${r.run.name}${r.run.opRun ? ` (Op run ${r.run.opRun.id} in ${r.run.opRun.env})` : r.run.id !== null ? ` (run ${r.run.id})` : ""}`
+    : "";
+  return r.phase !== null ? `phase ${r.phase} failed${run}` : `a required phase failed${run}`;
+}
+
+/** The refusal `approve` and `promote --release` print for a revoked release, and the line that fixes it. */
+export function revokedRefusal(release: { releaseDigest: string; label: string | null }, r: ReleaseRevocation, fix: string): { message: string; hint: string } {
+  return {
+    message:
+      `release ${release.label ?? release.releaseDigest} was cut from commit ${r.commit.slice(0, 12)}, which ${r.tag} revokes ` +
+      `(${describeRevocation(r)}), so it is not deployed and no approval of it counts [${RELEASE_REVOKED_CODE}]`,
+    hint: fix,
+  };
+}

package/src/lifecycle/release-store.ts

@@ -111,7 +111,16 @@ export interface ReleaseCut {
   label: string | null;
   actor: string;
   timestamp: string;
-  /** The CI run the cut ran in, or null outside CI. */
+  /**
+   * The run the cut ran in (#4027): the CI run's id in CI, or an id minted on
+   * the machine that cut (`local-<epoch ms>`). Null on every cut written
+   * before 0.124.29.
+   */
+  runId: string | null;
+  /**
+   * Where that run ran: the CI run's origin, or `{ forge: "local" }` for a
+   * minted id (#4027). A cut written before 0.124.29 holds null outside CI.
+   */
   runOrigin: RunOrigin | null;
   /**
    * The cut's signature (#4031): an armored ssh signature by the actor's key
@@ -310,12 +319,13 @@ export function parseCuts(text: string | null): { cuts: ReleaseCut[]; malformed:
         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.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 as ReleaseCut), signature: c.signature ?? null });
+      cuts.push({ ...(c as ReleaseCut), runId: c.runId ?? null, signature: c.signature ?? null });
     } catch {
       malformed++;
     }
@@ -351,7 +361,7 @@ const CUT_RETRY_ATTEMPTS = 5;
  * label another digest has, throws {@link ReleaseLabelError}. Does not push.
  */
 export async function appendCut(
-  input: Omit<ReleaseCut, "version" | "signature"> & { signature?: string | null },
+  input: Omit<ReleaseCut, "version" | "signature" | "runId"> & { signature?: string | null; runId?: string | null },
   opts?: { cwd?: string },
 ): Promise<CutOutcome> {
   if (input.label !== null) {
@@ -387,6 +397,7 @@ export async function appendCut(
       label: input.label,
       actor: input.actor,
       timestamp: input.timestamp,
+      runId: input.runId ?? null,
       runOrigin: input.runOrigin,
       signature: input.signature ?? null,
     };

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`);
+  });
+});