@intentius/chant 0.124.34 → 0.124.35

package/src/cli/handlers/promote.ts

@@ -21,6 +21,7 @@
  * ran from it, through the release gate `promote --release` binds (#4045).
  */
 
+import { ENV_VAR } from "../../env";
 import { dirname, join, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { loadChantConfig, type ChantConfig } from "../../config";
@@ -116,9 +117,16 @@ function resolveActor(ctx: CommandContext): string | undefined {
   return ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
 }
 
-/** Config, params and the declared components, or the exit code of a refusal already printed. */
-async function loadProject(ctx: CommandContext, selector: string) {
+/**
+ * Config, params and the declared components, or the exit code of a refusal
+ * already printed. `env` is the environment being deployed: it is set as
+ * `CHANT_ENV` before the components load, as `--env` sets it for `chant run`
+ * (../main.ts), so a component that reads it (a stack name per environment)
+ * deploys to that environment and not to the one it was promoted from (#4222).
+ */
+async function loadProject(ctx: CommandContext, selector: string, env: string) {
   const { args } = ctx;
+  process.env[ENV_VAR] = env;
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
@@ -397,17 +405,22 @@ async function deployPlan(
   const prepared: DriverComponent[] = [];
   const removed = new Map<string, string[]>();
   const refusals: string[] = [];
+  // #4222: a component with no artifact, deployed from the templates the release records, and its record's digest.
+  const templateDigests = new Map<string, string>();
+  const { releaseTemplatesDigest } = await import("../../components/release-promote");
   for (const item of plan.items) {
+    const templates = under ? releaseTemplatesDigest(under.target, item.component) : null;
     // A rollback and a redeploy deploy a release this environment already
     // received, so neither runs the publish step.
     const result = withoutBuildSteps(
       byName.get(item.component)!,
-      verb === "promote" ? {} : { pinDigest: item.digest, verb: `a ${verb}` },
+      { ...(verb === "promote" ? {} : { pinDigest: item.digest, verb: `a ${verb}` }), templatesPinned: templates !== null },
     );
     if ("error" in result) refusals.push(result.error);
     else {
       prepared.push(result.component);
       removed.set(item.component, result.removed);
+      if (result.templateOnly && templates !== null) templateDigests.set(item.component, templates);
     }
   }
   if (refusals.length > 0) {
@@ -647,7 +660,8 @@ async function deployPlan(
         const approver = gateApprover(result);
         const admission = gateAdmission(result);
         const input = record(item, plan.to, { runId, ...(runOrigin ? { runOrigin } : {}), actor: actor!, timestamp, ...(approver ? { approver } : {}), ...(admission ? { admission } : {}) });
-        const { record: written } = await appendReleaseRecord(under ? { ...input, releaseDigest: under.release.releaseDigest } : input);
+        const templates = templateDigests.get(item.component);
+        const { record: written } = await appendReleaseRecord(under ? { ...input, ...(templates ? { digest: templates } : {}), releaseDigest: under.release.releaseDigest } : input);
         recorded.push(written);
       }
       if (outcome) await appendDeployOutcome(outcome);
@@ -872,7 +886,7 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
   const who = actorOrRefuse(ctx);
   if (typeof who === "number") return who;
 
-  const project = await loadProject(ctx, args.component ?? "all");
+  const project = await loadProject(ctx, args.component ?? "all", to);
   if (typeof project === "number") return project;
 
   // The member's `environments` array is its promotion order (#4030). It
@@ -958,7 +972,7 @@ export async function runComponentsRollback(ctx: CommandContext): Promise<number
   if (typeof who === "number") return who;
   if (args.release) return runReleaseRollback(ctx, env, args.release, who.actor);
 
-  const project = await loadProject(ctx, args.component!);
+  const project = await loadProject(ctx, args.component!, env);
   if (typeof project === "number") return project;
 
   await fetchLifecycle().catch(() => false);
@@ -988,7 +1002,7 @@ export async function runComponentsRollback(ctx: CommandContext): Promise<number
  * runs now, as `promote --release` binds them (#4045).
  */
 async function runReleaseRollback(ctx: CommandContext, env: string, ref: string, actor: string | undefined): Promise<number> {
-  const project = await loadProject(ctx, "all");
+  const project = await loadProject(ctx, "all", env);
   if (typeof project === "number") return project;
   await fetchLifecycle().catch(() => false);
   const records = await readLedger(env);
@@ -1025,7 +1039,7 @@ export async function runComponentsRedeploy(ctx: CommandContext): Promise<number
   const who = actorOrRefuse(ctx);
   if (typeof who === "number") return who;
 
-  const project = await loadProject(ctx, args.component);
+  const project = await loadProject(ctx, args.component, env);
   if (typeof project === "number") return project;
 
   await fetchLifecycle().catch(() => false);

package/src/cli/handlers/release-compose.e2e.test.ts

@@ -0,0 +1,133 @@
+/**
+ * `chant release compose` end to end (#4168 4.3, mode b): a chosen trunk
+ * change composed onto a released commit while trunk carries unready work,
+ * a conflict that stops with nothing written, the tick judging the pushed
+ * compose branch, and a cut of the composed commit that records its base,
+ * its sources and a publish channel. A temp repo with a temp bare remote;
+ * the tick's forge is a fake that answers check runs. No key or signer.
+ */
+
+import { describe, test, expect } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { REPO } from "../../workspace/__fixtures__/contract-repo";
+import { ciTick } from "../../workspace/ci-green";
+import type { CheckRun, CiForge } from "../../workspace/ci-green-forge";
+
+const CHANT = [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")];
+const CI_VARS = ["CI", "GITHUB_ACTIONS", "GITHUB_RUN_ID", "GITHUB_SHA", "GITHUB_ACTOR", "GITLAB_CI", "CI_PIPELINE_ID", "CHANT_ENV", "CHANT_RELEASE_LABEL"];
+
+function chant(cwd: string, args: string[]): { code: number; stdout: string; stderr: string } {
+  const env: NodeJS.ProcessEnv = { ...process.env, USER: "tester" };
+  for (const k of CI_VARS) delete env[k];
+  const r = spawnSync(CHANT[0], [...CHANT.slice(1), ...args], { cwd, encoding: "utf-8", env, timeout: 120_000 });
+  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function git(cwd: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(r.stderr);
+  return r.stdout.trim();
+}
+
+const BUILD = `mkdir -p dist && printf '{"env":"%s","marker":"%s","fix":"%s"}' "$CHANT_ENV" "$(cat marker.txt)" "$(cat fix.txt 2>/dev/null)" > dist/api.template.json`;
+const PASSING: CheckRun[] = [{ id: 1, name: "test", status: "completed", conclusion: "success", url: null } as unknown as CheckRun];
+
+describe("chant release compose", () => {
+  test(
+    "composes a fix onto a released commit, stops on a conflict, and cuts the composed commit once the tick has judged it green",
+    async () => {
+      const root = mkdtempSync(join(tmpdir(), "chant-release-compose-"));
+      try {
+        const dir = join(root, "work");
+        const remote = join(root, "origin.git");
+        git(root, "init", "-q", "--bare", "-b", "main", remote);
+        git(root, "init", "-q", "-b", "main", dir);
+        git(dir, "config", "user.email", "t@chant.dev");
+        git(dir, "config", "user.name", "T");
+        writeFileSync(
+          join(dir, "chant.workspace.json"),
+          JSON.stringify({ name: "w", schema: 1, members: [{ name: "api", dir: ".", kind: "chant" }], ci: { green: { branch: "main", phases: { test: ["test"] }, require: ["test"] } } }, null, 2),
+        );
+        writeFileSync(join(dir, "chant.config.ts"), `export default { environments: ["dev", "prod"] };\n`);
+        writeFileSync(
+          join(dir, "api.component.ts"),
+          `export const api = { name: "api", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "dist/api.template.json" }] }] };\n`,
+        );
+        writeFileSync(join(dir, ".gitignore"), "dist/\n");
+        writeFileSync(join(dir, "marker.txt"), "one");
+        git(dir, "add", ".");
+        git(dir, "commit", "-q", "-m", "one (#11)");
+        const one = git(dir, "rev-parse", "HEAD");
+        // Trunk moves on: unready work, a fix, and work on top of the unready work.
+        writeFileSync(join(dir, "marker.txt"), "two");
+        git(dir, "commit", "-q", "-am", "unready (#12)");
+        writeFileSync(join(dir, "fix.txt"), "fixed");
+        git(dir, "add", "fix.txt");
+        git(dir, "commit", "-q", "-m", "the fix (#13)\n\nChant-Record: work:fix-1");
+        const fix = git(dir, "rev-parse", "HEAD");
+        writeFileSync(join(dir, "marker.txt"), "four");
+        git(dir, "commit", "-q", "-am", "more on unready (#14)");
+        git(dir, "remote", "add", "origin", remote);
+        git(dir, "push", "-q", "origin", "main");
+        git(dir, "fetch", "-q", "origin");
+
+        // A change that needs the unready one stops, naming it and the file, and writes nothing.
+        const conflict = chant(dir, ["release", "compose", "bad", "--base", one, "--pr", "14", "--yes"]);
+        expect(conflict.code).toBe(1);
+        expect(conflict.stderr).toContain("[compose-conflict]");
+        expect(conflict.stderr).toContain("marker.txt");
+        expect(spawnSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/compose/bad"], { cwd: remote }).status).not.toBe(0);
+
+        const dry = chant(dir, ["release", "compose", "hotfix", "--base", one, "--work", "fix-1", "--json"]);
+        expect(dry.code, dry.stderr).toBe(0);
+        expect(JSON.parse(dry.stdout)).toMatchObject({ dryRun: true, written: false, pushed: false, picked: [{ commit: fix, pr: 13, work: ["fix-1"] }] });
+
+        const composed = chant(dir, ["release", "compose", "hotfix", "--base", one, "--pr", "13", "--yes", "--json"]);
+        expect(composed.code, composed.stderr).toBe(0);
+        const tip = JSON.parse(composed.stdout).tip as string;
+        expect(git(remote, "rev-parse", "refs/heads/chant/compose/hotfix")).toBe(tip);
+        expect(git(dir, "show", "-s", "--format=%(trailers:key=Chant-Composed-From,valueonly)", tip)).toBe(fix);
+
+        // Not green yet, so no cut.
+        const early = chant(dir, ["release", "cut", "v1.0.1", "--at", tip, "--build", BUILD]);
+        expect(early.code).toBe(1);
+        expect(early.stderr).toContain("[release-commit-not-green]");
+
+        // The tick walks the compose branch and tags the composed commit green.
+        const forge: CiForge = { kind: "github", checkRuns: async () => PASSING };
+        const tick = await ciTick({ cwd: dir, forge, now: new Date() });
+        expect(tick.composed.map((b) => b.branch)).toEqual(["chant/compose/hotfix"]);
+        expect(tick.made).toContain(`ci/green/${tip}`);
+
+        const cut = chant(dir, ["release", "cut", "v1.0.1", "--at", tip, "--build", BUILD, "--channel", "hotfix", "--yes", "--json"]);
+        expect(cut.code, cut.stderr).toBe(0);
+        const result = JSON.parse(cut.stdout);
+        expect(result.release.commit).toBe(tip);
+        expect(result.composed).toEqual({ branch: "chant/compose/hotfix", base: one, sources: [fix] });
+        expect(result.cut).toMatchObject({ label: "v1.0.1", channel: "hotfix", composed: { base: one, sources: [fix] }, signature: null });
+
+        // The release carries the fix on the released marker, not trunk's unready one.
+        const out = join(root, "export");
+        expect(chant(dir, ["release", "export", "v1.0.1", "--env", "prod", "-o", out]).code).toBe(0);
+        expect(JSON.parse(spawnSync("cat", [join(out, "dist", "api.template.json")], { encoding: "utf-8" }).stdout)).toEqual({ env: "prod", marker: "one", fix: "fixed" });
+
+        // A commit that is on neither trunk nor a compose branch is still refused.
+        git(dir, "checkout", "-q", "-b", "side", one);
+        writeFileSync(join(dir, "marker.txt"), "side");
+        git(dir, "commit", "-q", "-am", "side");
+        const side = git(dir, "rev-parse", "HEAD");
+        git(dir, "checkout", "-q", "main");
+        const refused = chant(dir, ["release", "cut", "v9", "--at", side, "--build", BUILD]);
+        expect(refused.code).toBe(1);
+        expect(refused.stderr).toContain("[release-commit-not-on-trunk]");
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+    300_000,
+  );
+});

package/src/cli/handlers/release.ts

@@ -20,6 +20,11 @@
  *   release candidates [--env <env>] [--json]
  *       the green commits of trunk a release can be cut from, each with what it
  *       would ship, and what each environment runs (#4168 4.2)
+ *   release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json]
+ *       pick chosen trunk changes onto a base, each with a Chant-Composed-From
+ *       trailer, on the pushed branch chant/compose/<name> (#4168 4.3); a dry
+ *       run unless --yes. `release cut` takes a green commit of that branch,
+ *       and `--channel <tag>` makes its publish move that tag, not latest
  *   release list [--json]
  *       every release of this member with its targets, its cuts and where it runs;
  *       `--json` prints the read contract's `releases` document
@@ -42,7 +47,7 @@ import { parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 
 const USAGE =
-  "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
+  "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
 
 /** The build inputs `release cut` and `release compile` share. */
 function compileInputs(
@@ -155,6 +160,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     let trunk: import("../../lifecycle/release-workstation").Trunk | null = null;
     let signers: readonly import("../../workspace/trust/trust-files").Signer[] = [];
     let member: string | null = null;
+    let composed: { branch: string; base: string; sources: string[] } | undefined;
     if (args.at !== undefined && !top) {
       return fail("not-a-git-repository", "--at names a commit, and this directory is not in a git repository");
     }
@@ -169,7 +175,18 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const { releaseRuleFrom } = await import("../../workspace/identity");
       const source = scopeSource(cwd);
       trunk = ws.resolveTrunk(top, source.declaration?.ci?.green?.branch ?? null);
-      ws.checkOnTrunk(top, commit, trunk);
+      try {
+        ws.checkOnTrunk(top, commit, trunk);
+      } catch (err) {
+        // #4168 4.3: a commit of a pushed compose branch is cut too, and the cut records what it carries.
+        if (!(err instanceof ws.WorkstationCheckError) || err.code !== "release-commit-not-on-trunk") throw err;
+        const refs = await import("../../lifecycle/compose-refs");
+        const on = refs.composeBranchContaining(top, commit, trunk.remote);
+        const trunkRef = `refs/remotes/${trunk.remote}/${trunk.branch}`;
+        const composition = on ? refs.compositionOnTrunk(top, commit, trunkRef, on.branch) : null;
+        if (!on || !composition) throw err;
+        composed = { branch: on.branch, base: composition.base, sources: composition.sources };
+      }
       signers = releaseRuleFrom(source).rule.signers.signers;
       const { resolveMemberLedger } = await import("../../lifecycle/member-ledger");
       const ledger = await resolveMemberLedger(cwd);
@@ -206,7 +223,15 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
     const cutCwd = checkout?.memberDir ?? cwd;
     const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
-    const request = { cwd: cutCwd, compiler, label, actor, ...(args.sign !== undefined ? { sign: args.sign } : {}) };
+    const request = {
+      cwd: cutCwd,
+      compiler,
+      label,
+      actor,
+      ...(args.sign !== undefined ? { sign: args.sign } : {}),
+      ...(composed ? { composed } : {}),
+      ...(args.channel ? { channel: args.channel } : {}),
+    };
 
     if (dryRun) {
       const plan = await planRelease(request);
@@ -233,6 +258,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
         actorSource: who.source,
         run: ci ? { runId: ci.runId, runOrigin: ci.runOrigin } : { runId: null, runOrigin: { forge: "local" as const } },
         trunk,
+        composed: composed ?? null,
+        channel: args.channel ?? null,
         at: args.at !== undefined ? { ref: args.at, commit } : null,
         sign: args.sign !== undefined ? { key: publicKey !== null ? publicKey.split(" ")[0] : null, readable: publicKey !== null } : null,
         tag: tag ? { name: tag.name, exists: tag.state === "present" } : null,
@@ -244,7 +271,13 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
         return 0;
       }
       const name = plan.label ? formatBold(plan.label) : "an unlabelled release";
-      console.log(`Dry run: cut ${name} from commit ${plan.commit.slice(0, 12)}${trunk ? ` (on ${trunk.remote}/${trunk.branch}, green)` : ""}`);
+      const where = composed
+        ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), green)`
+        : trunk
+          ? ` (on ${trunk.remote}/${trunk.branch}, green)`
+          : "";
+      console.log(`Dry run: cut ${name} from commit ${plan.commit.slice(0, 12)}${where}`);
+      if (args.channel) console.log(`  channel ${args.channel}: a publish moves ${args.channel}, not latest`);
       if (plan.alreadyCut) console.log(`  already cut as ${plan.alreadyCut}: the cut would record nothing new`);
       console.log(`  actor ${actor} (from ${describeActorSource(who.source)})`);
       console.log(`  run ${ci ? `${ci.runId} (${ci.runOrigin.forge})` : "minted on this machine at the cut (local)"}`);
@@ -299,7 +332,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
     if (args.json) {
       console.log(
         JSON.stringify(
-          { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, next },
+          { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, next },
           null,
           2,
         ),
@@ -308,7 +341,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const name = result.label ? formatBold(result.label) : "unlabelled release";
       if (result.cut) console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
       else console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
-      console.error(`  commit ${result.release.commit}`);
+      console.error(`  commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}`);
+      if (args.channel) console.error(`  channel ${args.channel}`);
       if (result.cut) console.error(`  ${result.cut.signature ? `signed by ${result.cut.actor}` : `not signed; actor ${result.cut.actor}`}, run ${result.cut.runId}`);
       console.error(`  artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
       for (const r of result.reused) console.error(`  ${r.component}: artifacts unchanged, carried from ${r.from}`);
@@ -386,7 +420,8 @@ export async function runReleasePublish(ctx: CommandContext): Promise<number> {
   // The warnings go to stderr with --json too, before any target runs.
   if (signatureWarning) console.error(formatWarning({ message: signatureWarning }));
   if (warning) console.error(formatWarning({ message: warning }));
-  const pctx = publishContext(prepared, { cwd, log: (line) => (args.json ? undefined : console.error(`    ${line}`)) });
+  // #4168 4.3: a release cut with --channel moves that tag, not latest.
+  const pctx = publishContext(prepared, { cwd, tag: prepared.channel, log: (line) => (args.json ? undefined : console.error(`    ${line}`)) });
 
   // Every target is planned before any publishes, so a missing file or credential stops the publish with nothing sent.
   const progress = publishProgress(await readPublishRecords(release.releaseDigest, { cwd }).catch(() => []));
@@ -539,9 +574,14 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
   for (const c of doc.candidates) {
     const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
     console.log(`${c.commit.slice(0, 12)}  ${c.subject}${tags.length > 0 ? `  (${tags.join("; ")})` : ""}`);
-    for (const ch of c.changes) {
-      const links = [...(ch.pr !== null ? [`#${ch.pr}`] : []), ...ch.work.map((w) => `work:${w}`)];
-      console.log(`    ${ch.commit.slice(0, 12)}  ${ch.subject}${links.length > 0 ? `  [${links.join(", ")}]` : ""}`);
+    // #4168 4.4: by work item, then pull request, then commit.
+    const subjectOf = new Map(c.changes.map((ch) => [ch.commit, ch.subject]));
+    for (const g of c.groups) {
+      console.log(`    ${g.work !== null ? `work:${g.work}` : "no work item"}`);
+      for (const p of g.pullRequests) {
+        console.log(`      ${p.pr !== null ? `#${p.pr}` : "no pull request"}`);
+        for (const sha of p.commits) console.log(`        ${sha.slice(0, 12)}  ${subjectOf.get(sha) ?? ""}`);
+      }
     }
     for (const f of c.flags) console.log(`    flag ${f.id} (${f.member} ${f.param}) changed`);
   }
@@ -661,3 +701,65 @@ export async function runReleaseUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({ message: `Unknown release subcommand: ${ctx.args.path}`, hint: USAGE }));
   return 1;
 }
+
+/**
+ * `release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json]`
+ * (#4168 4.3): pick the chosen trunk changes onto a base, on
+ * `chant/compose/<name>` (../../lifecycle/release-compose.ts). A dry run
+ * unless `--yes`, which moves the branch and pushes it so CI builds it.
+ */
+export async function runReleaseCompose(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const name = args.extraPositional;
+  if (!name) {
+    console.error(formatError({ message: "release compose needs a name for the compose branch", hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  const { composeRelease, ComposeError } = await import("../../lifecycle/release-compose");
+  const ws = await import("../../lifecycle/release-workstation");
+  const { scopeSource } = await import("../../workspace/write-scope");
+  const top = (() => {
+    try {
+      return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      return null;
+    }
+  })();
+  if (!top) {
+    console.error(formatError({ message: "a compose picks commits, and this directory is not in a git repository [not-a-git-repository]" }));
+    return 1;
+  }
+  const trunk = ws.resolveTrunk(top, scopeSource(cwd).declaration?.ci?.green?.branch ?? null);
+  try {
+    const r = await composeRelease({
+      cwd,
+      name,
+      ...(args.base !== undefined ? { base: args.base } : {}),
+      prs: args.prs ?? [],
+      works: args.works ?? [],
+      yes: args.yes === true,
+      trunk,
+    });
+    if (args.json) {
+      console.log(JSON.stringify({ dryRun: args.yes !== true, ...r, next: r.written || r.pushed ? [`chant release cut <label> --at ${r.tip}`] : [sameWithYes(process.argv.slice(2))] }, null, 2));
+      return 0;
+    }
+    const verb = args.yes === true ? "Composed" : "Dry run: would compose";
+    console.log(`${verb} ${formatBold(r.branch)} on ${r.base.slice(0, 12)}${r.from ? `, after ${r.from.slice(0, 12)}` : ""}`);
+    for (const s of r.picked) console.log(`  pick ${s.commit.slice(0, 12)}  ${s.subject}  [${s.chosenBy.join(", ")}]`);
+    for (const s of r.already) console.log(`  carried already ${s.commit.slice(0, 12)}  ${s.subject}`);
+    if (r.picked.length === 0) console.log("  nothing new to pick");
+    console.log(`  tip ${r.tip.slice(0, 12)}${r.pushed ? `, pushed to ${trunk.remote}` : ""}`);
+    if (args.yes !== true) console.error(`Dry run: no branch was moved or pushed. Run again with --yes: ${sameWithYes(process.argv.slice(2))}`);
+    else console.error(`Next: once CI tags ${r.tip.slice(0, 12)} green, cut it: chant release cut <label> --at ${r.tip} --channel <channel>`);
+    return 0;
+  } catch (err) {
+    if (err instanceof ComposeError) {
+      if (args.json) console.log(JSON.stringify({ error: { code: err.code, message: err.message, ...(err.conflict ? { conflict: err.conflict } : {}) } }, null, 2));
+      console.error(formatError({ message: `${err.message} [${err.code}]`, ...(err.fix ? { hint: err.fix } : {}) }));
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/cli/handlers/run.ts

@@ -933,6 +933,8 @@ export async function recordAutoReleasesForRun(
   disabled: boolean,
   runOrigin: RunOrigin = { forge: "local" },
   releaseDigest?: string,
+  /** #4222: the digest of the templates the release records for a component in `env`, for one that publishes no artifact. */
+  templatesDigestOf?: (component: string) => string | null,
 ): Promise<ReleaseRecord[]> {
   const recorded: ReleaseRecord[] = [];
   for (const componentResult of results) {
@@ -951,6 +953,7 @@ export async function recordAutoReleasesForRun(
         ...(gateAdmission(componentResult) ? { admission: gateAdmission(componentResult) } : {}),
         // #4043: the release the deploy was made under, when `--release` named one.
         ...(releaseDigest !== undefined ? { releaseDigest } : {}),
+        ...(releaseDigest !== undefined && templatesDigestOf?.(componentResult.component) ? { templatesDigest: templatesDigestOf(componentResult.component)! } : {}),
       },
       { disabled },
     );
@@ -1083,6 +1086,13 @@ export async function resolveRunRelease(ref: string, env: string, cwd: string) {
 }
 
 /** A rebuilt image need not digest as the release's own did; say so, as promote does. Never fails the run. */
+/** #4222: a component's templates digest in the release's target for `env`, or null when the release has no such target. */
+async function releaseTemplatesDigestOf(release: import("../../lifecycle/release-store").Release, env: string): Promise<(component: string) => string | null> {
+  const { targetFor, releaseTemplatesDigest } = await import("../../components/release-promote");
+  const found = targetFor(release, env);
+  return (component) => ("target" in found ? releaseTemplatesDigest(found.target, component) : null);
+}
+
 async function warnOnArtifactMismatch(release: import("../../lifecycle/release-store").Release, recorded: readonly ReleaseRecord[]): Promise<void> {
   try {
     const { releaseArtifactMismatches } = await import("../../components/release-promote");
@@ -1270,7 +1280,8 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
   if (result.success && result.run) {
     // #3955: a run that records nothing has no release to report either.
     const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord) || ledgerRecordingOff();
-    const recorded = await recordAutoReleasesForRun(result.run.results, env, release.runId, disabled, release.runOrigin, underRelease?.releaseDigest);
+    const templatesDigestOf = underRelease ? await releaseTemplatesDigestOf(underRelease.release, env) : undefined;
+    const recorded = await recordAutoReleasesForRun(result.run.results, env, release.runId, disabled, release.runOrigin, underRelease?.releaseDigest, templatesDigestOf);
     if (underRelease) await warnOnArtifactMismatch(underRelease.release, recorded);
     // `--digest-file` (#2602): the releases this run recorded, one
     // `<component>=<digest>` line each, the form `chant components promote

package/src/cli/main.ts

@@ -368,7 +368,7 @@ CI:
 Releases:
   release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>]
               [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>]
-              [--actor <name>] [--sign [<key file>]] [--json]
+              [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json]
                         A dry run of a cut of this member from HEAD, which
                         must be clean, on trunk and pushed, and carry a
                         ci/green tag: compile every environment in the
@@ -389,6 +389,18 @@ Releases:
                         trunk from a temporary worktree instead of HEAD, so
                         the checkout need not be clean. The label reaches
                         every compile and build as CHANT_RELEASE_LABEL.
+                        A green commit of a pushed chant/compose/<name>
+                        branch is cut too, recording its base and sources.
+                        --channel <tag> records the tag a publish moves in
+                        place of latest.
+  release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)...
+                  [--yes] [--json]
+                        Cherry-pick the chosen trunk changes, in trunk order,
+                        onto the base, each with a Chant-Composed-From
+                        trailer, on chant/compose/<name>. Appends to a branch
+                        that exists; stops on a conflict, naming the change
+                        and files, and writes nothing. A dry run unless --yes,
+                        which moves the branch and pushes it.
   release candidates [--env <env>] [--json]
                         The green commits of trunk a release can be cut from,
                         newest first, each with the commits, work items, pull
@@ -1010,6 +1022,10 @@ Component release ledger + status:
                             planned after the one before applied, a moved
                             wave waiting at <name>-wave-<k>, with --wave <k>
                             for one wave per CI job;
+                            --green: apply the green commit at HEAD, measured
+                            from the one last applied to --env, under the
+                            approved plans of the merges since, else at gate
+                            op green-<sha>;
                             --events-json, both commands: the run-event
                             stream on stdout; --report-url <s3 or file URL>,
                             both commands: copy the report, the change set
@@ -1467,6 +1483,8 @@ export const commandRegistry: CommandDef[] = [
   // #4049: check a release's signature offline.
   { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseVerify(ctx) },
   { name: "release workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-workflow")).runReleaseWorkflow(ctx) },
+  // #4168 4.3: mode (b), chosen changes composed onto a base on chant/compose/<name>.
+  { name: "release compose", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompose(ctx) },
   { name: "release candidates", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCandidates(ctx) },
   { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseList(ctx) },
   { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseExport(ctx) },

package/src/cli/parse-args.ts

@@ -385,6 +385,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       const pr = Number(raw);
       if (!Number.isInteger(pr) || pr < 1) throw new Error(`--pr needs a pull or merge request number: got "${raw ?? ""}"`);
       result.pr = pr;
+      // `chant release compose --pr <n>...` (#4168 4.3) reads every one.
+      (result.prs ??= []).push(pr);
+    } else if (arg === "--channel") {
+      // `chant release cut --channel <tag>` (#4168 4.3): the tag a publish moves in place of latest.
+      result.channel = args[++i];
+      if (!result.channel || !/^[A-Za-z][A-Za-z0-9._-]*$/.test(result.channel)) throw new Error(`--channel needs a channel name, such as next or hotfix: got "${result.channel ?? ""}"`);
     } else if (arg === "--forge") {
       result.forge = args[++i];
       if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
@@ -410,6 +416,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.requireProvenance = true;
     } else if (arg === "--pr-loop") {
       result.prLoop = true;
+    } else if (arg === "--green") {
+      // `chant components pr-apply --green` (#4168 step 9): apply the green commit at HEAD.
+      result.green = true;
     } else if (arg === "--apply-on-merge") {
       // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
       result.applyOnMerge = true;
@@ -421,6 +430,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       const line = args[++i];
       if (line === undefined || line === "") throw new Error("--build-command needs a shell line: --build-command '<line>'");
       result.ciBuildCommand = line;
+    } else if (arg === "--land") {
+      // `chant ci serve --land` (#4168 4.4): fast-forward the target to a chant/land/<name> branch once its pre-merge phases pass.
+      result.ciLand = true;
     } else if (arg === "--pr-build-command") {
       const line = args[++i];
       if (line === undefined || line === "") throw new Error("--pr-build-command needs a shell line: --pr-build-command '<line>'");
@@ -822,6 +834,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (!value || value.startsWith("-")) throw new Error("--work needs a work item id: --work <id>");
       result.work = value;
+      (result.works ??= []).push(value);
     } else if (arg === "--holder" || arg === "--ttl" || arg === "--token" || arg === "--outcome") {
       // `chant workspace work claim|renew|release <id>` (#2732)
       const value = args[++i];

package/src/cli/registry.ts

@@ -302,6 +302,10 @@ export interface ParsedArgs {
    * pr-apply finds it from the commit through `--forge` when omitted.
    */
   pr?: number;
+  /** Every `--pr <n>`, in order: `chant release compose` (#4168 4.3) takes several. */
+  prs?: number[];
+  /** `chant release cut --channel <tag>` (#4168 4.3): the tag a publish of the release moves in place of `latest`. */
+  channel?: string;
   /**
    * `chant components pr-plan|pr-apply --forge github|gitlab|forgejo` (#3183)
    * — post the note and the commit status on this forge, with the client
@@ -335,10 +339,18 @@ export interface ParsedArgs {
    * #4168, in place of recording it. Opt-in: a merge deploys nothing without it.
    */
   applyOnMerge?: boolean;
+  /**
+   * `chant components pr-apply --green` (#4168 step 9): apply the green commit
+   * at HEAD, measured from the one last applied to the environment, under the
+   * approved plans of the merges between or a gate of its own.
+   */
+  green?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
   /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */
   ciBuildCommand?: string;
+  /** `chant ci serve --land` (#4168 4.4) — fast-forward the target branch to each pushed `chant/land/<name>` branch whose `ci.green.preMerge` phases pass on it. */
+  ciLand?: boolean;
   /** `chant build --pr-loop --pr-build-command <line>` (#4088) — the build line to run in place of `chant build --env <env>`. */
   prBuildCommand?: string;
   /**
@@ -701,6 +713,8 @@ export interface ParsedArgs {
   holder?: string;
   /** `chant run <op> --work <id>` (#2748): the work item an Op with a work lease runs under. `chant workspace check --changes --work <id>` (#2773): the work item in hand. */
   work?: string;
+  /** Every `--work <id>`, in order: `chant release compose` (#4168 4.3) takes several. */
+  works?: string[];
   /** `chant workspace work claim|renew <id> --ttl <seconds|duration>` (#2732): how long the lease lasts unless renewed. */
   ttl?: string;
   /** `chant workspace work renew|release <id> --token <token>` (#2732): the fencing token the caller holds. */