@git.zone/cli 3.2.1 → 5.0.0

package/ts/mod_release/index.ts

@@ -18,6 +18,16 @@ import {
 } from "../helpers.workflow.js";
 import * as commitHelpers from "../mod_commit/mod.helpers.js";
 import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
+import {
+  inspectReleaseBranch,
+  integrateReleaseBranch,
+  prepareReleaseIntegration,
+  revalidatePreparedReleaseBranch,
+  revalidateReleasePublicationState,
+  releaseGitEnv,
+  resolveReleaseMergeFlag,
+  type IReleaseBranchContext,
+} from "./helpers.releasebranch.js";
 
 type TTargetStatus = "success" | "already-published" | "skipped" | "failed";
 
@@ -39,24 +49,49 @@ export const run = async (argvArg: any) => {
   if (mode.json) {
     printJson({
       ok: false,
-      error: "JSON output is not supported for mutating release workflows yet. Use `gitzone release --plan` for a human-readable plan.",
+      error:
+        "JSON output is not supported for mutating release workflows yet. Use `gitzone release --plan` for a human-readable plan.",
     });
     return;
   }
 
-  const workflow = await resolveReleaseWorkflow(argvArg);
-  printReleasePlan(workflow);
-  if (workflow.confirmation === "plan") {
-    return;
-  }
-
   const smartshellInstance = new plugins.smartshell.Smartshell({
     executor: "bash",
     sourceFilePaths: [],
   });
+  let mergeRequested: boolean;
+  try {
+    mergeRequested = resolveReleaseMergeFlag(argvArg);
+  } catch (error) {
+    logger.log("error", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+    return;
+  }
+  const workflow = await resolveReleaseWorkflow(argvArg);
+  let branchContext: IReleaseBranchContext;
+  try {
+    branchContext = await inspectReleaseBranch({
+      smartshell: smartshellInstance,
+      cwd: paths.cwd,
+      gitRemote: workflow.gitRemote,
+      gitTargetActive: workflow.targets.includes("git"),
+      pushBranch: workflow.pushBranch,
+      pushTags: workflow.pushTags,
+      mergeRequested,
+      planMode: workflow.confirmation === "plan",
+    });
+  } catch (error) {
+    logger.log("error", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+    return;
+  }
+  printReleasePlan(workflow, branchContext);
+  if (workflow.confirmation === "plan") {
+    return;
+  }
 
   const pending = await readPendingChangelog(
-    plugins.path.join(paths.cwd, workflow.changelogFile),
+    plugins.path.join(branchContext.sourceCwd, workflow.changelogFile),
     workflow.changelogPendingSection,
   );
   if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
@@ -65,18 +100,29 @@ export const run = async (argvArg: any) => {
   }
 
   const versionType = resolveVersionType(argvArg, pending.block);
-  const projectType = await commitHelpers.detectProjectType();
-  const currentVersion = await commitHelpers.readCurrentVersion(projectType);
-  const plannedVersion = commitHelpers.calculateNewVersion(currentVersion, versionType);
+  const projectType = await commitHelpers.detectProjectType(
+    branchContext.sourceCwd,
+  );
+  const currentVersion = await commitHelpers.readCurrentVersion(
+    projectType,
+    branchContext.sourceCwd,
+  );
+  const plannedVersion = commitHelpers.calculateNewVersion(
+    currentVersion,
+    versionType,
+  );
 
   if (workflow.confirmation === "prompt") {
     if (!mode.interactive) {
-      throw new Error("Release confirmation requires an interactive terminal. Use `-y` or set release.confirmation to `auto`.");
+      throw new Error(
+        "Release confirmation requires an interactive terminal. Use `-y` or set release.confirmation to `auto`.",
+      );
     }
-    const confirmed = await plugins.smartinteract.SmartInteract.getCliConfirmation(
-      `Release v${plannedVersion} (${versionType}) now?`,
-      true,
-    );
+    const confirmed =
+      await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        `Release v${plannedVersion} (${versionType}) now?`,
+        true,
+      );
     if (!confirmed) {
       logger.log("info", "Release cancelled.");
       return;
@@ -88,40 +134,171 @@ export const run = async (argvArg: any) => {
   const npmResults: ITargetResult[] = [];
   const dockerResults: ITargetResult[] = [];
 
-  if (workflow.requireCleanTree) {
-    await verifyCleanTree(smartshellInstance, "Working tree is not clean. Commit or stash changes before releasing.");
+  try {
+    branchContext = await prepareReleaseIntegration(
+      smartshellInstance,
+      branchContext,
+    );
+  } catch (error) {
+    logger.log("error", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+    return;
   }
   if (workflow.runTests) {
-    await runCommandStep(smartshellInstance, "Running tests", workflow.testCommand);
+    await runCommandStep(
+      smartshellInstance,
+      branchContext.sourceCwd,
+      "Running tests",
+      workflow.testCommand,
+    );
   }
 
-  newVersion = await runVersionStep(projectType, versionType);
-  await runChangelogStep(workflow, newVersion);
-  await runReleaseCommitStep(smartshellInstance, newVersion);
-  await runTagStep(smartshellInstance, newVersion);
+  let releaseCwd = branchContext.sourceCwd;
+  let releasePushUrl = branchContext.pushUrl;
+  let expectedRemoteMainOid = branchContext.remoteMainOid;
+  if (branchContext.sourceBranch === "main") {
+    try {
+      await revalidatePreparedReleaseBranch(smartshellInstance, branchContext);
+    } catch (error) {
+      logger.log(
+        "error",
+        error instanceof Error ? error.message : String(error),
+      );
+      process.exit(1);
+      return;
+    }
+  } else {
+    try {
+      const integration = await integrateReleaseBranch(
+        smartshellInstance,
+        branchContext,
+      );
+      releaseCwd = integration.releaseCwd;
+      releasePushUrl = integration.pushUrl;
+      expectedRemoteMainOid = integration.expectedRemoteMainOid;
+    } catch (error) {
+      logger.log(
+        "error",
+        error instanceof Error ? error.message : String(error),
+      );
+      process.exit(1);
+      return;
+    }
+  }
+
+  newVersion = await runVersionStep(projectType, versionType, releaseCwd);
+  await runChangelogStep(workflow, newVersion, releaseCwd);
+  const releaseCommitOid = await runReleaseCommitStep(
+    smartshellInstance,
+    newVersion,
+    releaseCwd,
+  );
+  await runTagStep(
+    smartshellInstance,
+    newVersion,
+    releaseCommitOid,
+    releaseCwd,
+  );
+  const releaseRefs = await captureReleaseRefs(
+    smartshellInstance,
+    releaseCwd,
+    newVersion,
+    releaseCommitOid,
+  );
 
   if (workflow.runBuild) {
-    await runCommandStep(smartshellInstance, "Running release build", workflow.buildCommand);
-    await verifyCleanTree(smartshellInstance, "Build produced uncommitted changes. Aborting release.");
+    await runCommandStep(
+      smartshellInstance,
+      releaseCwd,
+      "Running release build",
+      workflow.buildCommand,
+    );
+    await verifyCleanTree(
+      smartshellInstance,
+      releaseCwd,
+      "Build produced uncommitted changes. Aborting release.",
+    );
+  }
+
+  const ensurePublicationState = async (): Promise<boolean> => {
+    try {
+      await verifyReleaseRefs(
+        smartshellInstance,
+        releaseCwd,
+        newVersion,
+        releaseRefs,
+      );
+      await revalidateReleasePublicationState(
+        smartshellInstance,
+        branchContext,
+        releaseRefs.mainOid,
+        expectedRemoteMainOid,
+      );
+      return true;
+    } catch (error) {
+      logger.log(
+        "error",
+        error instanceof Error ? error.message : String(error),
+      );
+      process.exit(1);
+      return false;
+    }
+  };
+
+  if (!(await ensurePublicationState())) {
+    return;
   }
 
   if (workflow.targets.includes("git")) {
-    gitResults.push(...(await runGitTarget(smartshellInstance, workflow)));
+    gitResults.push(
+      ...(await runGitTarget(
+        smartshellInstance,
+        workflow,
+        releaseCwd,
+        newVersion,
+        releaseRefs,
+        releasePushUrl,
+        expectedRemoteMainOid,
+      )),
+    );
+    if (gitResults.some((result) => result.status === "failed")) {
+      printReleaseSummary(newVersion, gitResults, npmResults, dockerResults);
+      process.exit(1);
+      return;
+    }
+    expectedRemoteMainOid = releaseRefs.mainOid;
   }
   if (workflow.targets.includes("npm")) {
-    npmResults.push(...(await runNpmTarget(smartshellInstance, workflow)));
+    if (!(await ensurePublicationState())) {
+      return;
+    }
+    npmResults.push(
+      ...(await runNpmTarget(smartshellInstance, workflow, releaseCwd)),
+    );
   }
   if (workflow.targets.includes("docker")) {
-    dockerResults.push(...(await runDockerTarget(smartshellInstance, workflow)));
+    if (!(await ensurePublicationState())) {
+      return;
+    }
+    dockerResults.push(
+      ...(await runDockerTarget(smartshellInstance, workflow, releaseCwd)),
+    );
   }
 
   printReleaseSummary(newVersion, gitResults, npmResults, dockerResults);
-  if ([...gitResults, ...npmResults, ...dockerResults].some((result) => result.status === "failed")) {
+  if (
+    [...gitResults, ...npmResults, ...dockerResults].some(
+      (result) => result.status === "failed",
+    )
+  ) {
     process.exit(1);
   }
 };
 
-function resolveVersionType(argvArg: any, pendingBlock: string): commitHelpers.VersionType {
+function resolveVersionType(
+  argvArg: any,
+  pendingBlock: string,
+): commitHelpers.VersionType {
   if (argvArg.major) return "major";
   if (argvArg.minor) return "minor";
   if (argvArg.patch) return "patch";
@@ -130,11 +307,12 @@ function resolveVersionType(argvArg: any, pendingBlock: string): commitHelpers.V
 
 async function runCommandStep(
   smartshellInstance: plugins.smartshell.Smartshell,
+  cwdArg: string,
   label: string,
   command: string,
 ): Promise<void> {
   console.log(`\n${label}`);
-  const result = await smartshellInstance.exec(command);
+  const result = await smartshellInstance.exec(command, { cwd: cwdArg });
   if (result.exitCode !== 0) {
     logger.log("error", `${label} failed. Aborting release.`);
     process.exit(1);
@@ -144,9 +322,14 @@ async function runCommandStep(
 
 async function verifyCleanTree(
   smartshellInstance: plugins.smartshell.Smartshell,
+  cwdArg: string,
   errorMessage: string,
 ): Promise<void> {
-  const statusResult = await smartshellInstance.exec("git status --porcelain");
+  const statusResult = await smartshellInstance.execSpawn(
+    "git",
+    ["status", "--porcelain"],
+    { cwd: cwdArg, env: releaseGitEnv },
+  );
   if (statusResult.stdout.trim() !== "") {
     logger.log("error", errorMessage);
     console.log(statusResult.stdout);
@@ -157,24 +340,36 @@ async function verifyCleanTree(
 async function runVersionStep(
   projectType: commitHelpers.ProjectType,
   versionType: commitHelpers.VersionType,
+  cwdArg: string,
 ): Promise<string> {
-  const currentVersion = await commitHelpers.readCurrentVersion(projectType);
-  const newVersion = commitHelpers.calculateNewVersion(currentVersion, versionType);
+  const currentVersion = await commitHelpers.readCurrentVersion(
+    projectType,
+    cwdArg,
+  );
+  const newVersion = commitHelpers.calculateNewVersion(
+    currentVersion,
+    versionType,
+  );
   logger.log("info", `Bumping version: ${currentVersion} -> ${newVersion}`);
 
-  const commitInfo = new plugins.commitinfo.CommitInfo(paths.cwd, versionType);
+  const commitInfo = new plugins.commitinfo.CommitInfo(cwdArg, versionType);
   await commitInfo.writeIntoPotentialDirs();
-  await commitHelpers.updateProjectVersionFiles(projectType, newVersion);
+  await commitHelpers.updateProjectVersionFiles(
+    projectType,
+    newVersion,
+    cwdArg,
+  );
   return newVersion;
 }
 
 async function runChangelogStep(
   workflow: IResolvedReleaseWorkflow,
   newVersion: string,
+  cwdArg: string,
 ): Promise<void> {
   const dateString = new Date().toISOString().slice(0, 10);
   await movePendingToVersion(
-    plugins.path.join(paths.cwd, workflow.changelogFile),
+    plugins.path.join(cwdArg, workflow.changelogFile),
     workflow.changelogPendingSection,
     workflow.changelogVersionHeading,
     newVersion,
@@ -185,80 +380,261 @@ async function runChangelogStep(
 async function runReleaseCommitStep(
   smartshellInstance: plugins.smartshell.Smartshell,
   newVersion: string,
-): Promise<void> {
-  await smartshellInstance.exec("git add -A");
-  const result = await smartshellInstance.exec(`git commit -m ${shellQuote(`v${newVersion}`)}`);
+  cwdArg: string,
+): Promise<string> {
+  const addResult = await smartshellInstance.execSpawn("git", ["add", "-A"], {
+    cwd: cwdArg,
+    env: releaseGitEnv,
+  });
+  if (addResult.exitCode !== 0) {
+    throw new Error("Staging release metadata failed.");
+  }
+  const result = await smartshellInstance.execSpawn(
+    "git",
+    ["commit", "-m", `v${newVersion}`],
+    { cwd: cwdArg, env: releaseGitEnv },
+  );
   if (result.exitCode !== 0) {
-    logger.log("error", "Release commit failed.");
-    process.exit(1);
+    throw new Error("Release commit failed.");
+  }
+  const branchResult = await smartshellInstance.execSpawn(
+    "git",
+    ["symbolic-ref", "--quiet", "HEAD"],
+    { cwd: cwdArg, env: releaseGitEnv, silent: true },
+  );
+  if (
+    branchResult.exitCode !== 0 ||
+    branchResult.stdout.trim() !== "refs/heads/main"
+  ) {
+    throw new Error("The release commit was not created on main.");
+  }
+  const headOid = await resolveGitObjectOid(
+    smartshellInstance,
+    cwdArg,
+    "HEAD^{commit}",
+  );
+  const mainOid = await resolveGitObjectOid(
+    smartshellInstance,
+    cwdArg,
+    "refs/heads/main^{commit}",
+  );
+  if (headOid !== mainOid) {
+    throw new Error("HEAD and main diverged after creating the release commit.");
   }
+  return mainOid;
 }
 
 async function runTagStep(
   smartshellInstance: plugins.smartshell.Smartshell,
   newVersion: string,
+  releaseCommitOidArg: string,
+  cwdArg: string,
 ): Promise<void> {
-  const result = await smartshellInstance.exec(`git tag v${newVersion} -m ${shellQuote(`v${newVersion}`)}`);
+  const result = await smartshellInstance.execSpawn(
+    "git",
+    [
+      "tag",
+      "-a",
+      `v${newVersion}`,
+      "-m",
+      `v${newVersion}`,
+      releaseCommitOidArg,
+    ],
+    { cwd: cwdArg, env: releaseGitEnv },
+  );
   if (result.exitCode !== 0) {
-    logger.log("error", "Release tag failed.");
-    process.exit(1);
+    throw new Error("Release tag failed.");
   }
 }
 
+interface IReleaseRefs {
+  mainOid: string;
+  tagOid: string;
+}
+
+const resolveGitObjectOid = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  revisionArg: string,
+): Promise<string> => {
+  const result = await smartshellInstanceArg.execSpawn(
+    "git",
+    ["rev-parse", "--verify", revisionArg],
+    { cwd: cwdArg, env: releaseGitEnv, silent: true },
+  );
+  const oid = result.stdout.trim();
+  if (result.exitCode !== 0 || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(oid)) {
+    throw new Error(`Unable to resolve release Git object ${revisionArg}.`);
+  }
+  return oid;
+};
+
+const captureReleaseRefs = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  newVersionArg: string,
+  expectedMainOidArg?: string,
+): Promise<IReleaseRefs> => {
+  const mainOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    "refs/heads/main^{commit}",
+  );
+  const tagOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    `refs/tags/v${newVersionArg}^{tag}`,
+  );
+  const tagCommitOid = await resolveGitObjectOid(
+    smartshellInstanceArg,
+    cwdArg,
+    `refs/tags/v${newVersionArg}^{commit}`,
+  );
+  if (
+    (expectedMainOidArg && mainOid !== expectedMainOidArg) ||
+    tagCommitOid !== mainOid
+  ) {
+    throw new Error(
+      "The release tag is not bound to the captured main release commit.",
+    );
+  }
+  return { mainOid, tagOid };
+};
+
+const verifyReleaseRefs = async (
+  smartshellInstanceArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  newVersionArg: string,
+  expectedRefsArg: IReleaseRefs,
+): Promise<void> => {
+  const currentRefs = await captureReleaseRefs(
+    smartshellInstanceArg,
+    cwdArg,
+    newVersionArg,
+    expectedRefsArg.mainOid,
+  );
+  if (
+    currentRefs.mainOid !== expectedRefsArg.mainOid ||
+    currentRefs.tagOid !== expectedRefsArg.tagOid
+  ) {
+    throw new Error(
+      "Local release refs changed before publication. Inspect main and the release tag before retrying.",
+    );
+  }
+};
+
 async function runGitTarget(
   smartshellInstance: plugins.smartshell.Smartshell,
   workflow: IResolvedReleaseWorkflow,
+  cwdArg: string,
+  newVersionArg: string,
+  releaseRefsArg: IReleaseRefs,
+  pushUrlArg?: string,
+  expectedRemoteMainOidArg?: string,
 ): Promise<ITargetResult[]> {
-  const currentBranchResult = await smartshellInstance.exec("git branch --show-current");
-  const currentBranch = currentBranchResult.stdout.trim() || "master";
-  const commands: Array<{ target: string; command: string }> = [];
+  const destination = pushUrlArg || workflow.gitRemote;
+  const targets: string[] = [];
+  const refspecs: string[] = [];
   if (workflow.pushBranch) {
-    commands.push({
-      target: `${workflow.gitRemote}/${currentBranch}`,
-      command: `git push ${workflow.gitRemote} ${currentBranch}`,
-    });
+    targets.push(`${workflow.gitRemote}/main`);
+    refspecs.push("refs/heads/main:refs/heads/main");
   }
   if (workflow.pushTags) {
-    commands.push({
-      target: `${workflow.gitRemote}/tags`,
-      command: `git push ${workflow.gitRemote} --tags`,
-    });
+    targets.push(`${workflow.gitRemote}/v${newVersionArg}`);
+    refspecs.push(`refs/tags/v${newVersionArg}:refs/tags/v${newVersionArg}`);
+  }
+  if (refspecs.length === 0) {
+    return [];
   }
 
-  const results: ITargetResult[] = [];
-  for (const { target, command } of commands) {
-    const result = await smartshellInstance.exec(command);
-    results.push({
-      target,
-      status: result.exitCode === 0 ? "success" : "failed",
-      message: result.exitCode === 0 ? undefined : "push failed",
-    });
+  const args = buildReleaseGitPushArgs({
+    destination,
+    newVersion: newVersionArg,
+    pushBranch: workflow.pushBranch,
+    pushTags: workflow.pushTags,
+    mainOid: releaseRefsArg.mainOid,
+    tagOid: releaseRefsArg.tagOid,
+    expectedRemoteMainOid: expectedRemoteMainOidArg,
+  });
+  const result = await smartshellInstance.execSpawn("git", args, {
+    cwd: cwdArg,
+    env: releaseGitEnv,
+  });
+  return targets.map((target) => ({
+    target,
+    status: result.exitCode === 0 ? "success" : "failed",
+    message:
+      result.exitCode === 0
+        ? undefined
+        : firstMeaningfulLine(result.combinedOutput),
+  }));
+}
+
+export interface IBuildReleaseGitPushArgsOptions {
+  destination: string;
+  newVersion: string;
+  pushBranch: boolean;
+  pushTags: boolean;
+  mainOid: string;
+  tagOid: string;
+  expectedRemoteMainOid?: string;
+}
+
+export function buildReleaseGitPushArgs(
+  optionsArg: IBuildReleaseGitPushArgsOptions,
+): string[] {
+  const refspecs: string[] = [];
+  if (optionsArg.pushBranch) {
+    refspecs.push(`${optionsArg.mainOid}:refs/heads/main`);
   }
-  return results;
+  if (optionsArg.pushTags) {
+    refspecs.push(`${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`);
+  }
+  const args = ["push", "--no-follow-tags"];
+  if (refspecs.length > 1) {
+    args.push("--atomic");
+  }
+  if (optionsArg.pushBranch && optionsArg.expectedRemoteMainOid) {
+    args.push(
+      `--force-with-lease=refs/heads/main:${optionsArg.expectedRemoteMainOid}`,
+    );
+  }
+  args.push(optionsArg.destination, ...refspecs);
+  return args;
 }
 
 async function runNpmTarget(
   smartshellInstance: plugins.smartshell.Smartshell,
   workflow: IResolvedReleaseWorkflow,
+  cwdArg: string,
 ): Promise<ITargetResult[]> {
   if (!workflow.npmEnabled) {
     return [{ target: "npm", status: "skipped", message: "disabled" }];
   }
   if (workflow.npmRegistries.length === 0) {
-    return [{ target: "npm", status: "failed", message: "no registries configured" }];
+    return [
+      { target: "npm", status: "failed", message: "no registries configured" },
+    ];
   }
 
   const results: ITargetResult[] = [];
   for (const registry of workflow.npmRegistries) {
     const command = `pnpm publish --registry=${registry} --access=${workflow.npmAccessLevel}`;
-    const result = await smartshellInstance.exec(command);
+    const result = await smartshellInstance.exec(command, { cwd: cwdArg });
     const output = result.combinedOutput;
     if (result.exitCode === 0) {
       results.push({ target: registry, status: "success" });
-    } else if (isAlreadyPublishedOutput(output) && workflow.npmAlreadyPublished === "success") {
+    } else if (
+      isAlreadyPublishedOutput(output) &&
+      workflow.npmAlreadyPublished === "success"
+    ) {
       results.push({ target: registry, status: "already-published" });
     } else {
-      results.push({ target: registry, status: "failed", message: firstMeaningfulLine(output) });
+      results.push({
+        target: registry,
+        status: "failed",
+        message: firstMeaningfulLine(output),
+      });
     }
   }
   return results;
@@ -267,6 +643,7 @@ async function runNpmTarget(
 async function runDockerTarget(
   smartshellInstance: plugins.smartshell.Smartshell,
   workflow: IResolvedReleaseWorkflow,
+  cwdArg: string,
 ): Promise<ITargetResult[]> {
   if (!workflow.dockerEnabled) {
     return [{ target: "docker", status: "skipped", message: "disabled" }];
@@ -275,24 +652,33 @@ async function runDockerTarget(
   let packageJson: unknown;
   try {
     packageJson = JSON.parse(
-      await plugins.fs.readFile(plugins.path.join(paths.cwd, "package.json"), "utf8"),
+      await plugins.fs.readFile(
+        plugins.path.join(cwdArg, "package.json"),
+        "utf8",
+      ),
     );
   } catch {
     packageJson = undefined;
   }
   if (!getDeclaredTsdockerRange(packageJson)) {
-    return [{
-      target: "tsdocker",
-      status: "failed",
-      message: "Docker releases require @git.zone/tsdocker as a project dependency",
-    }];
-  }
-  if (!(await hasInstalledProjectTsdockerBinary(paths.cwd))) {
-    return [{
-      target: "tsdocker",
-      status: "failed",
-      message: "Docker releases require the installed project-local tSDocker binary",
-    }];
+    return [
+      {
+        target: "tsdocker",
+        status: "failed",
+        message:
+          "Docker releases require @git.zone/tsdocker as a project dependency",
+      },
+    ];
+  }
+  if (!(await hasInstalledProjectTsdockerBinary(cwdArg))) {
+    return [
+      {
+        target: "tsdocker",
+        status: "failed",
+        message:
+          "Docker releases require the installed project-local tSDocker binary",
+      },
+    ];
   }
 
   const minimumTsdockerVersion = getTsdockerMinimumVersion(
@@ -300,33 +686,43 @@ async function runDockerTarget(
     workflow.dockerTest,
   );
   if (minimumTsdockerVersion) {
-    const versionResult = await smartshellInstance.exec("pnpm exec tsdocker --version");
+    const versionResult = await smartshellInstance.exec(
+      "pnpm exec tsdocker --version",
+      { cwd: cwdArg },
+    );
     if (
-      versionResult.exitCode !== 0
-      || !supportsTsdockerMinimumVersion(
+      versionResult.exitCode !== 0 ||
+      !supportsTsdockerMinimumVersion(
         versionResult.combinedOutput,
         minimumTsdockerVersion,
       )
     ) {
-      const minimumVersion = formatTsdockerMinimumVersion(minimumTsdockerVersion);
-      return [{
-        target: "tsdocker",
-        status: "failed",
-        message: `Docker release options require project-local @git.zone/tsdocker >= ${minimumVersion}`,
-      }];
+      const minimumVersion = formatTsdockerMinimumVersion(
+        minimumTsdockerVersion,
+      );
+      return [
+        {
+          target: "tsdocker",
+          status: "failed",
+          message: `Docker release options require project-local @git.zone/tsdocker >= ${minimumVersion}`,
+        },
+      ];
     }
   }
 
   const command = buildTsdockerPushCommand(workflow);
-  const result = await smartshellInstance.exec(command);
+  const result = await smartshellInstance.exec(command, { cwd: cwdArg });
   const output = result.combinedOutput;
-  return [{
-    target: workflow.dockerPatterns.length > 0
-      ? `tsdocker:${workflow.dockerPatterns.join(",")}`
-      : "tsdocker",
-    status: result.exitCode === 0 ? "success" : "failed",
-    message: result.exitCode === 0 ? undefined : firstMeaningfulLine(output),
-  }];
+  return [
+    {
+      target:
+        workflow.dockerPatterns.length > 0
+          ? `tsdocker:${workflow.dockerPatterns.join(",")}`
+          : "tsdocker",
+      status: result.exitCode === 0 ? "success" : "failed",
+      message: result.exitCode === 0 ? undefined : firstMeaningfulLine(output),
+    },
+  ];
 }
 
 type TDockerCommandWorkflow = Pick<
@@ -341,7 +737,9 @@ type TDockerCommandWorkflow = Pick<
   | "dockerPatterns"
 >;
 
-export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): string {
+export function buildTsdockerPushCommand(
+  workflow: TDockerCommandWorkflow,
+): string {
   const commandParts = ["pnpm", "exec", "tsdocker", "push"];
   for (const pattern of workflow.dockerPatterns) {
     commandParts.push(shellQuote(pattern));
@@ -350,7 +748,9 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
     commandParts.push(`--registry=${shellQuote(workflow.dockerRegistry)}`);
   }
   if (workflow.dockerBuildRegistries.length > 0) {
-    commandParts.push(`--build-registries=${shellQuote(workflow.dockerBuildRegistries.join(","))}`);
+    commandParts.push(
+      `--build-registries=${shellQuote(workflow.dockerBuildRegistries.join(","))}`,
+    );
   }
   if (workflow.dockerTest) {
     commandParts.push("--test");
@@ -363,7 +763,11 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
   }
   if (workflow.dockerParallel === true) {
     commandParts.push("--parallel");
-  } else if (typeof workflow.dockerParallel === "number" && Number.isFinite(workflow.dockerParallel) && workflow.dockerParallel > 0) {
+  } else if (
+    typeof workflow.dockerParallel === "number" &&
+    Number.isFinite(workflow.dockerParallel) &&
+    workflow.dockerParallel > 0
+  ) {
     commandParts.push(`--parallel=${Math.floor(workflow.dockerParallel)}`);
   }
   if (workflow.dockerContext) {
@@ -373,36 +777,64 @@ export function buildTsdockerPushCommand(workflow: TDockerCommandWorkflow): stri
 }
 
 function isAlreadyPublishedOutput(output: string): boolean {
-  return /previously published versions|cannot publish over|already exists/i.test(output);
+  return /previously published versions|cannot publish over|already exists/i.test(
+    output,
+  );
 }
 
 function firstMeaningfulLine(output: string): string {
-  return output
-    .split("\n")
-    .map((line) => line.trim())
-    .find((line) => line.length > 0) || "command failed";
+  return (
+    output
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line.length > 0) || "command failed"
+  );
 }
 
 function shellQuote(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-function printReleasePlan(workflow: IResolvedReleaseWorkflow): void {
+function printReleasePlan(
+  workflow: IResolvedReleaseWorkflow,
+  branchContextArg: IReleaseBranchContext,
+): void {
   console.log("");
   console.log("gitzone release - resolved workflow");
   console.log(`confirmation: ${workflow.confirmation}`);
   console.log(`plan: ${workflow.plan.join(" -> ")}`);
-  console.log(`targets: ${workflow.targets.length > 0 ? workflow.targets.join(", ") : "none"}`);
-  console.log(`changelog: ${workflow.changelogFile}#${workflow.changelogPendingSection}`);
+  console.log(`source branch: ${branchContextArg.sourceBranch}`);
+  if (branchContextArg.sourceBranch !== "main") {
+    console.log("release branch: main (fast-forward integration requested)");
+    console.log(
+      `remote main ancestry: ${branchContextArg.planAncestryVerified ? "verified" : "deferred until execution"}`,
+    );
+  }
+  console.log(
+    `targets: ${workflow.targets.length > 0 ? workflow.targets.join(", ") : "none"}`,
+  );
+  console.log(
+    `changelog: ${workflow.changelogFile}#${workflow.changelogPendingSection}`,
+  );
   if (workflow.targets.includes("npm")) {
-    console.log(`npm registries: ${workflow.npmRegistries.length > 0 ? workflow.npmRegistries.join(", ") : "none"}`);
+    console.log(
+      `npm registries: ${workflow.npmRegistries.length > 0 ? workflow.npmRegistries.join(", ") : "none"}`,
+    );
   }
   if (workflow.targets.includes("docker")) {
     console.log(`docker engine: ${workflow.dockerEngine}`);
-    console.log(`docker registry: ${workflow.dockerRegistry || "all configured registries"}`);
-    console.log(`docker build authentication: ${workflow.dockerBuildRegistries.length > 0 ? workflow.dockerBuildRegistries.join(", ") : "all configured registries"}`);
-    console.log(`docker image tests: ${workflow.dockerTest ? "required before destination publication" : "not requested"}`);
-    console.log(`docker patterns: ${workflow.dockerPatterns.length > 0 ? workflow.dockerPatterns.join(", ") : "all Dockerfiles"}`);
+    console.log(
+      `docker registry: ${workflow.dockerRegistry || "all configured registries"}`,
+    );
+    console.log(
+      `docker build authentication: ${workflow.dockerBuildRegistries.length > 0 ? workflow.dockerBuildRegistries.join(", ") : "all configured registries"}`,
+    );
+    console.log(
+      `docker image tests: ${workflow.dockerTest ? "required before destination publication" : "not requested"}`,
+    );
+    console.log(
+      `docker patterns: ${workflow.dockerPatterns.length > 0 ? workflow.dockerPatterns.join(", ") : "all Dockerfiles"}`,
+    );
     console.log(`docker options: ${formatDockerOptions(workflow)}`);
   }
   console.log("");
@@ -410,13 +842,17 @@ function printReleasePlan(workflow: IResolvedReleaseWorkflow): void {
 
 function formatDockerOptions(workflow: IResolvedReleaseWorkflow): string {
   const options: string[] = [];
-  if (workflow.dockerRegistry) options.push(`registry=${workflow.dockerRegistry}`);
+  if (workflow.dockerRegistry)
+    options.push(`registry=${workflow.dockerRegistry}`);
   if (workflow.dockerBuildRegistries.length > 0) {
     options.push(`buildRegistries=${workflow.dockerBuildRegistries.join(",")}`);
   }
   if (workflow.dockerTest) options.push("test");
   if (workflow.dockerCached) options.push("cached");
-  if (workflow.dockerParallel) options.push(`parallel=${workflow.dockerParallel === true ? "true" : workflow.dockerParallel}`);
+  if (workflow.dockerParallel)
+    options.push(
+      `parallel=${workflow.dockerParallel === true ? "true" : workflow.dockerParallel}`,
+    );
   if (workflow.dockerNoBuild) options.push("no-build");
   if (workflow.dockerContext) options.push(`context=${workflow.dockerContext}`);
   return options.length > 0 ? options.join(", ") : "default";
@@ -435,21 +871,27 @@ function printReleaseSummary(
   if (gitResults.length > 0) {
     console.log("git:");
     for (const result of gitResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
+      console.log(
+        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
+      );
     }
   }
 
   if (npmResults.length > 0) {
     console.log("npm:");
     for (const result of npmResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
+      console.log(
+        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
+      );
     }
   }
 
   if (dockerResults.length > 0) {
     console.log("docker:");
     for (const result of dockerResults) {
-      console.log(`  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`);
+      console.log(
+        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
+      );
     }
   }
 }
@@ -459,17 +901,44 @@ export function showHelp(mode?: ICliMode): void {
     printJson({
       command: "release",
       usage: "gitzone release [options]",
-      description: "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
+      description:
+        "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
       flags: [
-        { flag: "-y, --yes", description: "Run without interactive confirmation" },
+        {
+          flag: "-y, --yes",
+          description: "Run without interactive confirmation",
+        },
         { flag: "-t, --test", description: "Enable release preflight tests" },
-        { flag: "-b, --build", description: "Enable release preflight build" },
+        {
+          flag: "-b, --build",
+          description:
+            "Enable the build after local release metadata is created",
+        },
+        {
+          flag: "--no-build",
+          description: "Disable the post-metadata release build",
+        },
         { flag: "-p, --push", description: "Enable the git release target" },
-        { flag: "--target <names>", description: "Release only selected targets: git,npm,docker" },
+        {
+          flag: "--target <names>",
+          description: "Release only selected targets: git,npm,docker",
+        },
         { flag: "--npm", description: "Enable the npm release target" },
         { flag: "--docker", description: "Enable the tsdocker release target" },
-        { flag: "--no-publish", description: "Run release core and git target only" },
-        { flag: "--plan", description: "Show resolved workflow without mutating files" },
+        {
+          flag: "--no-publish",
+          description: "Run release core and git target only",
+        },
+        {
+          flag: "--merge",
+          description:
+            "Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
+        },
+        {
+          flag: "--plan",
+          description:
+            "Show the workflow without fetching or mutating refs, files, the index, or worktrees",
+        },
       ],
     });
     return;
@@ -483,13 +952,23 @@ export function showHelp(mode?: ICliMode): void {
   console.log("Flags:");
   console.log("  -y, --yes           Run without interactive confirmation");
   console.log("  -t, --test          Enable release preflight tests");
-  console.log("  -b, --build         Enable release preflight build");
+  console.log(
+    "  -b, --build         Build after creating local release metadata",
+  );
+  console.log("  --no-build          Disable the post-metadata release build");
   console.log("  -p, --push          Enable the git release target");
-  console.log("  --target <names>    Release only selected targets: git,npm,docker");
+  console.log(
+    "  --target <names>    Release only selected targets: git,npm,docker",
+  );
   console.log("  --npm               Enable the npm release target");
   console.log("  --docker            Enable the tsdocker release target");
   console.log("  --no-publish        Run release core and git target only");
+  console.log(
+    "  --merge             Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
+  );
   console.log("  --major|--minor|--patch  Override inferred semver level");
-  console.log("  --plan              Show resolved workflow without mutating files");
+  console.log(
+    "  --plan              Show workflow without fetching or mutating refs, files, index, or worktrees",
+  );
   console.log("");
 }