@git.zone/cli 4.0.0 → 5.0.0

package/ts/mod_release/helpers.releasebranch.ts

@@ -0,0 +1,1282 @@
+import * as plugins from "./mod.plugins.js";
+
+const mainBranch = "main";
+const mainBranchRef = `refs/heads/${mainBranch}`;
+
+interface IGitWorktree {
+  path: string;
+  head?: string;
+  branch?: string;
+  prunable: boolean;
+}
+
+export interface IReleaseBranchContext {
+  sourceCwd: string;
+  sourceBranch: string;
+  sourceRef: string;
+  sourceOid: string;
+  gitRemote: string;
+  localMainOid?: string;
+  remoteMainOid?: string;
+  mainWorktreePath?: string;
+  mainWorktreeGitDir?: string;
+  pushUrl?: string;
+  mergeRequested: boolean;
+  planAncestryVerified: boolean;
+}
+
+export interface IIntegratedReleaseBranch {
+  releaseCwd: string;
+  pushUrl: string;
+  expectedRemoteMainOid: string;
+}
+
+export interface IInspectReleaseBranchOptions {
+  smartshell: TSmartshell;
+  cwd: string;
+  gitRemote: string;
+  gitTargetActive: boolean;
+  pushBranch: boolean;
+  pushTags?: boolean;
+  mergeRequested: boolean;
+  planMode: boolean;
+}
+
+type TSmartshell = plugins.smartshell.Smartshell;
+
+export const releaseGitEnv: NodeJS.ProcessEnv = {
+  ...process.env,
+  GIT_NO_REPLACE_OBJECTS: "1",
+};
+
+const readOnlyGitEnv: NodeJS.ProcessEnv = {
+  ...releaseGitEnv,
+  GIT_NO_LAZY_FETCH: "1",
+  GIT_OPTIONAL_LOCKS: "0",
+};
+
+export function resolveReleaseMergeFlag(
+  argvArg: Record<string, unknown>,
+): boolean {
+  if (argvArg.merge === undefined || argvArg.merge === false) {
+    return false;
+  }
+  if (argvArg.merge !== true) {
+    throw new Error("`--merge` is a boolean flag and does not accept a value.");
+  }
+  return true;
+}
+
+export function parseGitWorktreePorcelain(outputArg: string): IGitWorktree[] {
+  const worktrees: IGitWorktree[] = [];
+  let current: Partial<IGitWorktree> = {};
+
+  const flush = () => {
+    if (current.path) {
+      worktrees.push({
+        path: current.path,
+        head: current.head,
+        branch: current.branch,
+        prunable: current.prunable ?? false,
+      });
+    }
+    current = {};
+  };
+
+  for (const field of outputArg.split("\0")) {
+    if (!field) {
+      flush();
+      continue;
+    }
+    const separatorIndex = field.indexOf(" ");
+    const key = separatorIndex === -1 ? field : field.slice(0, separatorIndex);
+    const value = separatorIndex === -1 ? "" : field.slice(separatorIndex + 1);
+    if (key === "worktree") {
+      flush();
+      current.path = value;
+    } else if (key === "HEAD") {
+      current.head = value;
+    } else if (key === "branch") {
+      current.branch = value;
+    } else if (key === "prunable") {
+      current.prunable = true;
+    }
+  }
+  flush();
+  return worktrees;
+}
+
+const runGit = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  argsArg: string[],
+  readOnlyArg = false,
+) =>
+  smartshellArg.execSpawn("git", argsArg, {
+    cwd: cwdArg,
+    env: readOnlyArg ? readOnlyGitEnv : releaseGitEnv,
+    silent: true,
+  });
+
+const requireGitSuccess = (
+  resultArg: plugins.smartshell.IExecResult,
+  messageArg: string,
+): plugins.smartshell.IExecResult => {
+  if (resultArg.exitCode !== 0) {
+    throw new Error(messageArg);
+  }
+  return resultArg;
+};
+
+const resolveSymbolicBranch = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  readOnlyArg = false,
+): Promise<{ branch: string; ref: string }> => {
+  const result = await runGit(
+    smartshellArg,
+    cwdArg,
+    ["symbolic-ref", "--quiet", "HEAD"],
+    readOnlyArg,
+  );
+  const ref = result.stdout.trim();
+  if (result.exitCode !== 0 || !ref.startsWith("refs/heads/")) {
+    throw new Error(
+      "A release requires a checked-out local branch; detached HEAD is not supported.",
+    );
+  }
+  return {
+    branch: ref.slice("refs/heads/".length),
+    ref,
+  };
+};
+
+const resolveCommit = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  revisionArg: string,
+  messageArg: string,
+  readOnlyArg = false,
+): Promise<string> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["rev-parse", "--verify", `${revisionArg}^{commit}`],
+      readOnlyArg,
+    ),
+    messageArg,
+  );
+  return result.stdout.trim();
+};
+
+const verifyCleanTree = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  labelArg: string,
+  readOnlyArg = false,
+): Promise<void> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+        "--ignore-submodules=none",
+      ],
+      readOnlyArg,
+    ),
+    `Unable to inspect the ${labelArg} worktree.`,
+  );
+  if (result.stdout.trim()) {
+    throw new Error(
+      `The ${labelArg} worktree is not clean. Commit or stash changes before releasing.`,
+    );
+  }
+};
+
+const pathExists = async (pathArg: string): Promise<boolean> => {
+  try {
+    await plugins.fs.stat(pathArg);
+    return true;
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      error.code === "ENOENT"
+    ) {
+      return false;
+    }
+    throw new Error(`Unable to inspect Git operation marker ${pathArg}.`, {
+      cause: error,
+    });
+  }
+};
+
+const verifyNoGitOperation = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  labelArg: string,
+  readOnlyArg = false,
+): Promise<void> => {
+  const markers = [
+    "MERGE_HEAD",
+    "CHERRY_PICK_HEAD",
+    "REVERT_HEAD",
+    "rebase-apply",
+    "rebase-merge",
+    "sequencer",
+    "BISECT_START",
+    "BISECT_LOG",
+  ];
+  for (const marker of markers) {
+    const pathResult = requireGitSuccess(
+      await runGit(
+        smartshellArg,
+        cwdArg,
+        ["rev-parse", "--git-path", marker],
+        readOnlyArg,
+      ),
+      `Unable to inspect Git operation state in the ${labelArg} worktree.`,
+    );
+    const markerPath = plugins.path.resolve(cwdArg, pathResult.stdout.trim());
+    if (await pathExists(markerPath)) {
+      throw new Error(
+        `The ${labelArg} worktree has an in-progress Git operation. Complete or abort it before releasing.`,
+      );
+    }
+  }
+};
+
+const verifyNoHistoryOverrides = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  readOnlyArg = false,
+): Promise<void> => {
+  const replaceRefs = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["for-each-ref", "--format=%(refname)", "refs/replace/"],
+      readOnlyArg,
+    ),
+    "Unable to inspect local Git replacement refs.",
+  );
+  if (replaceRefs.stdout.trim()) {
+    throw new Error(
+      "Release ancestry cannot be verified while local Git replacement refs exist. Remove them explicitly and retry.",
+    );
+  }
+
+  const graftsPathResult = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["rev-parse", "--git-path", "info/grafts"],
+      readOnlyArg,
+    ),
+    "Unable to locate the local Git grafts file.",
+  );
+  const graftsPath = plugins.path.resolve(
+    cwdArg,
+    graftsPathResult.stdout.trim(),
+  );
+  try {
+    const grafts = await plugins.fs.readFile(graftsPath, "utf8");
+    if (grafts.trim()) {
+      throw new Error(
+        "Release ancestry cannot be verified while a local Git grafts file is active. Remove it explicitly and retry.",
+      );
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return;
+    }
+    throw error;
+  }
+};
+
+const listWorktrees = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  readOnlyArg = false,
+): Promise<IGitWorktree[]> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["worktree", "list", "--porcelain", "-z"],
+      readOnlyArg,
+    ),
+    "Unable to inspect Git worktrees.",
+  );
+  return parseGitWorktreePorcelain(result.stdout);
+};
+
+const resolveAbsoluteGitDir = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  readOnlyArg = false,
+): Promise<string> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["rev-parse", "--absolute-git-dir"],
+      readOnlyArg,
+    ),
+    "Unable to identify the destination Git worktree.",
+  );
+  return result.stdout.trim();
+};
+
+const resolvePushUrl = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  remoteArg: string,
+  readOnlyArg = false,
+): Promise<string> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["remote", "get-url", "--push", "--all", remoteArg],
+      readOnlyArg,
+    ),
+    `Unable to resolve the push URL for Git remote ${remoteArg}.`,
+  );
+  const urls = result.stdout
+    .split("\n")
+    .map((url) => url.trim())
+    .filter(Boolean);
+  if (urls.length !== 1) {
+    throw new Error(
+      `Release merge mode requires exactly one push URL for Git remote ${remoteArg}.`,
+    );
+  }
+  const pushUrl = urls[0];
+  const hasUrlScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(pushUrl);
+  const isScpStyle = /^(?:[^@/\\:]+@)?[^/\\:]+:.+/.test(pushUrl);
+  const isWindowsAbsolutePath = /^[a-z]:[\\/]/i.test(pushUrl);
+  if (
+    !hasUrlScheme &&
+    !isScpStyle &&
+    !plugins.path.isAbsolute(pushUrl) &&
+    !isWindowsAbsolutePath
+  ) {
+    return plugins.path.resolve(cwdArg, pushUrl);
+  }
+  return pushUrl;
+};
+
+const resolveRemoteMainOid = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  pushUrlArg: string,
+  readOnlyArg = false,
+): Promise<string> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["ls-remote", "--exit-code", pushUrlArg, mainBranchRef],
+      readOnlyArg,
+    ),
+    "The configured Git push destination does not expose refs/heads/main.",
+  );
+  const oid = result.stdout.trim().split(/\s+/)[0];
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(oid)) {
+    throw new Error(
+      "The configured Git push destination returned an invalid main commit ID.",
+    );
+  }
+  return oid;
+};
+
+const hasCommitObject = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  oidArg: string,
+  readOnlyArg = false,
+): Promise<boolean> => {
+  const result = await runGit(
+    smartshellArg,
+    cwdArg,
+    ["cat-file", "-e", `${oidArg}^{commit}`],
+    readOnlyArg,
+  );
+  return result.exitCode === 0;
+};
+
+const isShallowRepository = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  readOnlyArg = false,
+): Promise<boolean> => {
+  const result = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["rev-parse", "--is-shallow-repository"],
+      readOnlyArg,
+    ),
+    "Unable to determine whether the repository is shallow.",
+  );
+  return result.stdout.trim() === "true";
+};
+
+const verifyLinearAncestry = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  baseOidArg: string,
+  sourceOidArg: string,
+  readOnlyArg = false,
+): Promise<void> => {
+  const ancestryResult = await runGit(
+    smartshellArg,
+    cwdArg,
+    ["merge-base", "--is-ancestor", baseOidArg, sourceOidArg],
+    readOnlyArg,
+  );
+  if (ancestryResult.exitCode !== 0) {
+    if (await isShallowRepository(smartshellArg, cwdArg, readOnlyArg)) {
+      throw new Error(
+        "Release merge ancestry cannot be verified in this shallow clone. Fetch complete main and feature history, then retry.",
+      );
+    }
+    throw new Error(
+      "The release branch is not cleanly rebased onto current main. Rebase it onto main, resolve conflicts, and retry.",
+    );
+  }
+
+  const mergeResult = requireGitSuccess(
+    await runGit(
+      smartshellArg,
+      cwdArg,
+      ["rev-list", "--merges", `${baseOidArg}..${sourceOidArg}`],
+      readOnlyArg,
+    ),
+    "Unable to verify linear release-branch history.",
+  );
+  if (mergeResult.stdout.trim()) {
+    throw new Error(
+      "The release branch contains merge commits after main. Rebase it cleanly onto main, then retry.",
+    );
+  }
+};
+
+const verifyMainWorktree = async (
+  smartshellArg: TSmartshell,
+  pathArg: string,
+  expectedOidArg: string,
+  expectedGitDirArg?: string,
+  readOnlyArg = false,
+): Promise<string> => {
+  const symbolic = await resolveSymbolicBranch(
+    smartshellArg,
+    pathArg,
+    readOnlyArg,
+  );
+  if (symbolic.ref !== mainBranchRef) {
+    throw new Error(
+      "The destination worktree is no longer checked out on main. Retry after restoring a clean main worktree.",
+    );
+  }
+  const head = await resolveCommit(
+    smartshellArg,
+    pathArg,
+    "HEAD",
+    "Unable to resolve the destination main commit.",
+    readOnlyArg,
+  );
+  if (head !== expectedOidArg) {
+    throw new Error(
+      "Local main changed during release preparation. Rebase the feature branch onto current main and retry.",
+    );
+  }
+  const gitDir = await resolveAbsoluteGitDir(
+    smartshellArg,
+    pathArg,
+    readOnlyArg,
+  );
+  if (expectedGitDirArg && gitDir !== expectedGitDirArg) {
+    throw new Error(
+      "The destination main worktree identity changed during release preparation. Retry from a stable worktree.",
+    );
+  }
+  await verifyCleanTree(smartshellArg, pathArg, "main", readOnlyArg);
+  await verifyNoGitOperation(smartshellArg, pathArg, "main", readOnlyArg);
+  return gitDir;
+};
+
+const resolveMainWorktree = async (
+  smartshellArg: TSmartshell,
+  cwdArg: string,
+  localMainOidArg: string,
+  readOnlyArg = false,
+): Promise<{ path: string; gitDir: string }> => {
+  const records = await listWorktrees(smartshellArg, cwdArg, readOnlyArg);
+  const mainRecords = records.filter(
+    (record) => record.branch === mainBranchRef,
+  );
+  if (mainRecords.length > 1) {
+    throw new Error(
+      "Multiple worktrees claim main. Repair the Git worktree registry before releasing.",
+    );
+  }
+  const mainRecord = mainRecords[0];
+  if (!mainRecord) {
+    throw new Error(
+      "Release merge mode requires exactly one existing worktree checked out on main.",
+    );
+  }
+  if (mainRecord.prunable) {
+    throw new Error(
+      "The registered main worktree is stale. Repair it explicitly before releasing.",
+    );
+  }
+  const gitDir = await verifyMainWorktree(
+    smartshellArg,
+    mainRecord.path,
+    localMainOidArg,
+    undefined,
+    readOnlyArg,
+  );
+  return {
+    path: mainRecord.path,
+    gitDir,
+  };
+};
+
+const verifySourceState = async (
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+  readOnlyArg = false,
+): Promise<void> => {
+  await verifyNoHistoryOverrides(
+    smartshellArg,
+    contextArg.sourceCwd,
+    readOnlyArg,
+  );
+  const symbolic = await resolveSymbolicBranch(
+    smartshellArg,
+    contextArg.sourceCwd,
+    readOnlyArg,
+  );
+  if (symbolic.ref !== contextArg.sourceRef) {
+    throw new Error(
+      "The release source worktree changed branches during preparation. Retry from the intended feature branch.",
+    );
+  }
+  const sourceHead = await resolveCommit(
+    smartshellArg,
+    contextArg.sourceCwd,
+    "HEAD",
+    "Unable to resolve the release source commit.",
+    readOnlyArg,
+  );
+  const sourceRefOid = await resolveCommit(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.sourceRef,
+    "Unable to resolve the release source branch.",
+    readOnlyArg,
+  );
+  if (
+    sourceHead !== contextArg.sourceOid ||
+    sourceRefOid !== contextArg.sourceOid
+  ) {
+    throw new Error(
+      "The release source branch changed during preparation. Restart the release from its new tip.",
+    );
+  }
+  await verifyCleanTree(
+    smartshellArg,
+    contextArg.sourceCwd,
+    "release source",
+    readOnlyArg,
+  );
+  await verifyNoGitOperation(
+    smartshellArg,
+    contextArg.sourceCwd,
+    "release source",
+    readOnlyArg,
+  );
+};
+
+export async function inspectReleaseBranch(
+  optionsArg: IInspectReleaseBranchOptions,
+): Promise<IReleaseBranchContext> {
+  const symbolic = await resolveSymbolicBranch(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    optionsArg.planMode,
+  );
+  await verifyNoHistoryOverrides(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    optionsArg.planMode,
+  );
+  const sourceOid = await resolveCommit(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    "HEAD",
+    "Unable to resolve the release source commit.",
+    optionsArg.planMode,
+  );
+  const context: IReleaseBranchContext = {
+    sourceCwd: optionsArg.cwd,
+    sourceBranch: symbolic.branch,
+    sourceRef: symbolic.ref,
+    sourceOid,
+    gitRemote: optionsArg.gitRemote,
+    mergeRequested: optionsArg.mergeRequested,
+    planAncestryVerified: false,
+  };
+
+  await verifyNoGitOperation(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    "release source",
+    optionsArg.planMode,
+  );
+
+  if (symbolic.branch === mainBranch && optionsArg.mergeRequested) {
+    throw new Error(
+      "`gitzone release --merge` is only valid when releasing from a non-main branch.",
+    );
+  }
+  if (symbolic.branch !== mainBranch && !optionsArg.mergeRequested) {
+    throw new Error(
+      `Releases must run from main. Current branch: ${symbolic.branch}. Re-run with \`gitzone release --merge\` after rebasing cleanly onto main.`,
+    );
+  }
+  if (symbolic.branch !== mainBranch && !optionsArg.gitTargetActive) {
+    throw new Error(
+      "`gitzone release --merge` requires the active Git target.",
+    );
+  }
+  if (
+    optionsArg.gitTargetActive &&
+    (!optionsArg.pushBranch || optionsArg.pushTags === false)
+  ) {
+    throw new Error(
+      "The Git release target requires both branch and tag pushing so release history can publish atomically.",
+    );
+  }
+
+  await verifyCleanTree(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    "release source",
+    optionsArg.planMode,
+  );
+  context.localMainOid = await resolveCommit(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    mainBranchRef,
+    "A local main branch is required for release merge mode.",
+    optionsArg.planMode,
+  );
+  if (symbolic.branch !== mainBranch) {
+    await verifyLinearAncestry(
+      optionsArg.smartshell,
+      optionsArg.cwd,
+      context.localMainOid,
+      context.sourceOid,
+      optionsArg.planMode,
+    );
+  }
+
+  const mainWorktree = await resolveMainWorktree(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    context.localMainOid,
+    optionsArg.planMode,
+  );
+  context.mainWorktreePath = mainWorktree.path;
+  context.mainWorktreeGitDir = mainWorktree.gitDir;
+  if (
+    symbolic.branch === mainBranch &&
+    plugins.path.resolve(mainWorktree.path) !==
+      plugins.path.resolve(optionsArg.cwd)
+  ) {
+    throw new Error(
+      "The current main worktree does not match Git worktree ownership.",
+    );
+  }
+
+  if (optionsArg.gitTargetActive) {
+    context.pushUrl = await resolvePushUrl(
+      optionsArg.smartshell,
+      optionsArg.cwd,
+      optionsArg.gitRemote,
+      optionsArg.planMode,
+    );
+    context.remoteMainOid = await resolveRemoteMainOid(
+      optionsArg.smartshell,
+      optionsArg.cwd,
+      context.pushUrl,
+      true,
+    );
+    if (
+      await hasCommitObject(
+        optionsArg.smartshell,
+        optionsArg.cwd,
+        context.remoteMainOid,
+        optionsArg.planMode,
+      )
+    ) {
+      await verifyLinearAncestry(
+        optionsArg.smartshell,
+        optionsArg.cwd,
+        context.remoteMainOid,
+        context.sourceOid,
+        optionsArg.planMode,
+      );
+      context.planAncestryVerified = true;
+    }
+  }
+
+  return context;
+}
+
+export async function prepareReleaseIntegration(
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+): Promise<IReleaseBranchContext> {
+  if (!contextArg.localMainOid || !contextArg.mainWorktreePath) {
+    throw new Error(
+      "Release branch context is incomplete. Restart the release.",
+    );
+  }
+
+  await verifySourceState(smartshellArg, contextArg);
+  await verifyMainWorktree(
+    smartshellArg,
+    contextArg.mainWorktreePath,
+    contextArg.localMainOid,
+    contextArg.mainWorktreeGitDir,
+  );
+  if (!contextArg.pushUrl) {
+    return contextArg;
+  }
+  const currentPushUrl = await resolvePushUrl(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.gitRemote,
+  );
+  if (currentPushUrl !== contextArg.pushUrl) {
+    throw new Error(
+      "The Git push destination changed during release preparation. Restart the release after reviewing the remote configuration.",
+    );
+  }
+  const remoteMainOid = await resolveRemoteMainOid(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.pushUrl,
+  );
+  if (contextArg.remoteMainOid && remoteMainOid !== contextArg.remoteMainOid) {
+    throw new Error(
+      "Remote main changed during release preparation. Fetch, rebase cleanly, and retry.",
+    );
+  }
+  requireGitSuccess(
+    await runGit(smartshellArg, contextArg.sourceCwd, [
+      "fetch",
+      "--no-tags",
+      "--no-recurse-submodules",
+      "--no-write-fetch-head",
+      contextArg.pushUrl,
+      mainBranchRef,
+    ]),
+    "Unable to fetch current main from the configured Git push destination.",
+  );
+  const verifiedRemoteMainOid = await resolveRemoteMainOid(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.pushUrl,
+  );
+  if (verifiedRemoteMainOid !== remoteMainOid) {
+    throw new Error(
+      "Remote main changed during release preparation. Fetch, rebase the feature branch cleanly, and retry.",
+    );
+  }
+  if (
+    !(await hasCommitObject(smartshellArg, contextArg.sourceCwd, remoteMainOid))
+  ) {
+    throw new Error(
+      "Current remote main could not be loaded locally. Fetch complete history and retry.",
+    );
+  }
+  await verifyLinearAncestry(
+    smartshellArg,
+    contextArg.sourceCwd,
+    remoteMainOid,
+    contextArg.sourceOid,
+  );
+  await verifySourceState(smartshellArg, contextArg);
+  await verifyMainWorktree(
+    smartshellArg,
+    contextArg.mainWorktreePath,
+    contextArg.localMainOid,
+    contextArg.mainWorktreeGitDir,
+  );
+  return {
+    ...contextArg,
+    remoteMainOid,
+    planAncestryVerified: true,
+  };
+}
+
+export async function revalidatePreparedReleaseBranch(
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+): Promise<void> {
+  if (
+    !contextArg.localMainOid ||
+    !contextArg.mainWorktreePath ||
+    !contextArg.mainWorktreeGitDir
+  ) {
+    throw new Error(
+      "Release branch context is incomplete. Restart the release.",
+    );
+  }
+  await verifySourceState(smartshellArg, contextArg);
+  await verifyMainWorktree(
+    smartshellArg,
+    contextArg.mainWorktreePath,
+    contextArg.localMainOid,
+    contextArg.mainWorktreeGitDir,
+  );
+  if (contextArg.pushUrl) {
+    const currentPushUrl = await resolvePushUrl(
+      smartshellArg,
+      contextArg.sourceCwd,
+      contextArg.gitRemote,
+    );
+    if (currentPushUrl !== contextArg.pushUrl) {
+      throw new Error(
+        "The Git push destination changed after release preflight. Restart after reviewing the remote configuration.",
+      );
+    }
+    const currentRemoteMainOid = await resolveRemoteMainOid(
+      smartshellArg,
+      contextArg.sourceCwd,
+      contextArg.pushUrl,
+    );
+    if (currentRemoteMainOid !== contextArg.remoteMainOid) {
+      throw new Error(
+        "Remote main changed after release preflight. Fetch, rebase cleanly, and retry.",
+      );
+    }
+  }
+}
+
+export async function revalidateReleasePublicationState(
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+  expectedMainOidArg: string,
+  expectedRemoteMainOidArg?: string,
+): Promise<void> {
+  if (!contextArg.mainWorktreePath || !contextArg.mainWorktreeGitDir) {
+    throw new Error(
+      "Release branch context is incomplete. Restart the release.",
+    );
+  }
+  await verifyNoHistoryOverrides(smartshellArg, contextArg.sourceCwd);
+  const currentMainWorktree = await resolveMainWorktree(
+    smartshellArg,
+    contextArg.sourceCwd,
+    expectedMainOidArg,
+  );
+  if (
+    currentMainWorktree.path !== contextArg.mainWorktreePath ||
+    currentMainWorktree.gitDir !== contextArg.mainWorktreeGitDir
+  ) {
+    throw new Error(
+      "Main worktree ownership changed before release publication. Inspect the worktree layout before retrying.",
+    );
+  }
+  if (contextArg.sourceBranch !== mainBranch) {
+    await verifySourceState(smartshellArg, contextArg);
+  }
+  if (contextArg.pushUrl) {
+    if (!expectedRemoteMainOidArg) {
+      throw new Error(
+        "Expected remote main state is unavailable. Restart the release.",
+      );
+    }
+    const currentPushUrl = await resolvePushUrl(
+      smartshellArg,
+      contextArg.sourceCwd,
+      contextArg.gitRemote,
+    );
+    if (currentPushUrl !== contextArg.pushUrl) {
+      throw new Error(
+        "The Git push destination changed before release publication. Restart after reviewing the remote configuration.",
+      );
+    }
+    const currentRemoteMainOid = await resolveRemoteMainOid(
+      smartshellArg,
+      contextArg.sourceCwd,
+      contextArg.pushUrl,
+    );
+    if (currentRemoteMainOid !== expectedRemoteMainOidArg) {
+      throw new Error(
+        "Remote main changed before release publication. Inspect the remote state before retrying.",
+      );
+    }
+  }
+}
+
+const describeLocalMainState = async (
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+  releaseCwdArg: string,
+  destinationGitDirArg: string,
+): Promise<string> => {
+  let mainOid: string;
+  try {
+    mainOid = await resolveCommit(
+      smartshellArg,
+      releaseCwdArg,
+      mainBranchRef,
+      "Local main no longer resolves after rollback failure.",
+    );
+  } catch {
+    return " Local main no longer resolves; inspect its ref and worktree before retrying.";
+  }
+  try {
+    await verifyMainWorktree(
+      smartshellArg,
+      releaseCwdArg,
+      mainOid,
+      destinationGitDirArg,
+    );
+    return ` Local main remains at ${mainOid} with a verified clean worktree.`;
+  } catch {
+    return ` Local main points to ${mainOid}, but its index or worktree could not be verified; inspect it before retrying.`;
+  }
+};
+
+const compensateFailedLocalMainTransition = async (
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+  releaseCwdArg: string,
+  destinationGitDirArg: string,
+): Promise<string> => {
+  if (!contextArg.localMainOid) {
+    return " Local main state is unknown; inspect it before retrying.";
+  }
+  const restoreResult = await runGit(smartshellArg, releaseCwdArg, [
+    "update-ref",
+    "-m",
+    "gitzone release integration rollback",
+    mainBranchRef,
+    contextArg.localMainOid,
+    contextArg.sourceOid,
+  ]);
+  const localState = await describeLocalMainState(
+    smartshellArg,
+    contextArg,
+    releaseCwdArg,
+    destinationGitDirArg,
+  );
+  if (restoreResult.exitCode === 0) {
+    return ` Local main ref was restored after the worktree update failed.${localState}`;
+  }
+  return ` Local main changed before its ref could be restored.${localState}`;
+};
+
+const rollbackLocalMain = async (
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+  releaseCwdArg: string,
+  destinationGitDirArg: string,
+): Promise<string> => {
+  if (!contextArg.localMainOid) {
+    return " Local main state is unknown; inspect it before retrying.";
+  }
+  let refRestored = false;
+  try {
+    await verifyMainWorktree(
+      smartshellArg,
+      releaseCwdArg,
+      contextArg.sourceOid,
+      destinationGitDirArg,
+    );
+    requireGitSuccess(
+      await runGit(smartshellArg, releaseCwdArg, [
+        "update-ref",
+        mainBranchRef,
+        contextArg.localMainOid,
+        contextArg.sourceOid,
+      ]),
+      "Unable to restore local main after failed release integration.",
+    );
+    refRestored = true;
+    requireGitSuccess(
+      await runGit(smartshellArg, releaseCwdArg, [
+        "read-tree",
+        "-m",
+        "-u",
+        contextArg.sourceOid,
+        contextArg.localMainOid,
+      ]),
+      "Unable to restore the local main worktree after failed release integration.",
+    );
+    await verifyMainWorktree(
+      smartshellArg,
+      releaseCwdArg,
+      contextArg.localMainOid,
+      destinationGitDirArg,
+    );
+    return " Local main was restored.";
+  } catch {
+    if (refRestored) {
+      await runGit(smartshellArg, releaseCwdArg, [
+        "update-ref",
+        mainBranchRef,
+        contextArg.sourceOid,
+        contextArg.localMainOid,
+      ]);
+    }
+    return describeLocalMainState(
+      smartshellArg,
+      contextArg,
+      releaseCwdArg,
+      destinationGitDirArg,
+    );
+  }
+};
+
+export async function integrateReleaseBranch(
+  smartshellArg: TSmartshell,
+  contextArg: IReleaseBranchContext,
+): Promise<IIntegratedReleaseBranch> {
+  if (contextArg.sourceBranch === mainBranch) {
+    throw new Error(
+      "The release branch is already main and does not require integration.",
+    );
+  }
+  if (
+    !contextArg.pushUrl ||
+    !contextArg.localMainOid ||
+    !contextArg.remoteMainOid
+  ) {
+    throw new Error(
+      "Release merge preparation is incomplete. Restart the release.",
+    );
+  }
+
+  await verifySourceState(smartshellArg, contextArg);
+  const currentPushUrl = await resolvePushUrl(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.gitRemote,
+  );
+  if (currentPushUrl !== contextArg.pushUrl) {
+    throw new Error(
+      "The Git push destination changed before integration. No local branch was changed.",
+    );
+  }
+  const currentRemoteMainOid = await resolveRemoteMainOid(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.pushUrl,
+  );
+  if (currentRemoteMainOid !== contextArg.remoteMainOid) {
+    throw new Error(
+      "Remote main changed before integration. Fetch, rebase the feature branch cleanly, and retry.",
+    );
+  }
+  const currentLocalMainOid = await resolveCommit(
+    smartshellArg,
+    contextArg.sourceCwd,
+    mainBranchRef,
+    "Local main disappeared during release preparation.",
+  );
+  if (currentLocalMainOid !== contextArg.localMainOid) {
+    throw new Error(
+      "Local main changed before integration. Rebase the feature branch cleanly and retry.",
+    );
+  }
+
+  const currentMainWorktree = await resolveMainWorktree(
+    smartshellArg,
+    contextArg.sourceCwd,
+    contextArg.localMainOid,
+  );
+  if (
+    currentMainWorktree.path !== contextArg.mainWorktreePath ||
+    currentMainWorktree.gitDir !== contextArg.mainWorktreeGitDir
+  ) {
+    throw new Error(
+      "Main worktree ownership changed during release preparation. Retry from a stable worktree layout.",
+    );
+  }
+
+  const releaseCwd = contextArg.mainWorktreePath;
+  if (!releaseCwd) {
+    throw new Error(
+      "The required main worktree disappeared before integration. No local branch was changed.",
+    );
+  }
+  const destinationGitDir = await verifyMainWorktree(
+    smartshellArg,
+    releaseCwd,
+    contextArg.localMainOid,
+    contextArg.mainWorktreeGitDir,
+  );
+
+  const refAdvanceResult = await runGit(smartshellArg, releaseCwd, [
+    "update-ref",
+    "-m",
+    "gitzone release integration",
+    mainBranchRef,
+    contextArg.sourceOid,
+    contextArg.localMainOid,
+  ]);
+  if (refAdvanceResult.exitCode !== 0) {
+    throw new Error(
+      "Local main changed before integration. No local ref or worktree rollback was attempted.",
+    );
+  }
+  const worktreeAdvanceResult = await runGit(smartshellArg, releaseCwd, [
+    "read-tree",
+    "-m",
+    "-u",
+    contextArg.localMainOid,
+    contextArg.sourceOid,
+  ]);
+  if (worktreeAdvanceResult.exitCode !== 0) {
+    const rollbackState = await compensateFailedLocalMainTransition(
+      smartshellArg,
+      contextArg,
+      releaseCwd,
+      destinationGitDir,
+    );
+    throw new Error(
+      `Local main advanced, but its index and worktree could not be updated. No remote ref or release metadata was changed.${rollbackState}`,
+    );
+  }
+  try {
+    await verifyMainWorktree(
+      smartshellArg,
+      releaseCwd,
+      contextArg.sourceOid,
+      destinationGitDir,
+    );
+  } catch {
+    const rollbackState = await rollbackLocalMain(
+      smartshellArg,
+      contextArg,
+      releaseCwd,
+      destinationGitDir,
+    );
+    throw new Error(
+      `Local main could not be verified after integration. No remote ref or release metadata was changed.${rollbackState}`,
+    );
+  }
+  const sourceRefOid = await resolveCommit(
+    smartshellArg,
+    releaseCwd,
+    contextArg.sourceRef,
+    "The release source branch disappeared during integration.",
+  );
+  if (sourceRefOid !== contextArg.sourceOid) {
+    const rollbackState = await rollbackLocalMain(
+      smartshellArg,
+      contextArg,
+      releaseCwd,
+      destinationGitDir,
+    );
+    throw new Error(
+      `The release source branch changed during integration. Release metadata was not created.${rollbackState}`,
+    );
+  }
+
+  const pushResult = await runGit(smartshellArg, releaseCwd, [
+    "push",
+    "--no-follow-tags",
+    `--force-with-lease=${mainBranchRef}:${contextArg.remoteMainOid}`,
+    contextArg.pushUrl,
+    `${contextArg.sourceOid}:${mainBranchRef}`,
+  ]);
+  if (pushResult.exitCode !== 0) {
+    let remoteAfterPush: string | undefined;
+    try {
+      remoteAfterPush = await resolveRemoteMainOid(
+        smartshellArg,
+        contextArg.sourceCwd,
+        contextArg.pushUrl,
+      );
+    } catch {
+      remoteAfterPush = undefined;
+    }
+    if (remoteAfterPush !== contextArg.sourceOid) {
+      const rollbackState = await rollbackLocalMain(
+        smartshellArg,
+        contextArg,
+        releaseCwd,
+        destinationGitDir,
+      );
+      throw new Error(
+        `Integrated main could not be confirmed at the remote. No release metadata was created.${rollbackState}${
+          remoteAfterPush
+            ? ""
+            : " The remote outcome is unknown; inspect refs/heads/main before retrying."
+        }`,
+      );
+    }
+  }
+  await verifyMainWorktree(
+    smartshellArg,
+    releaseCwd,
+    contextArg.sourceOid,
+    destinationGitDir,
+  );
+  let pushedRemoteMainOid: string;
+  try {
+    pushedRemoteMainOid = await resolveRemoteMainOid(
+      smartshellArg,
+      contextArg.sourceCwd,
+      contextArg.pushUrl,
+    );
+  } catch {
+    const rollbackState = await rollbackLocalMain(
+      smartshellArg,
+      contextArg,
+      releaseCwd,
+      destinationGitDir,
+    );
+    throw new Error(
+      `The pre-release push outcome could not be verified. No release metadata was created.${rollbackState} Inspect remote refs/heads/main before retrying.`,
+    );
+  }
+  if (pushedRemoteMainOid !== contextArg.sourceOid) {
+    const rollbackState = await rollbackLocalMain(
+      smartshellArg,
+      contextArg,
+      releaseCwd,
+      destinationGitDir,
+    );
+    throw new Error(
+      `Remote main did not retain the integrated release commit. No release metadata was created.${rollbackState}`,
+    );
+  }
+
+  return {
+    releaseCwd,
+    pushUrl: contextArg.pushUrl,
+    expectedRemoteMainOid: contextArg.sourceOid,
+  };
+}