gh-stack 0.7.1 → 0.10.0

package/src/commands/merge.ts

@@ -3,15 +3,148 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  stackBase,
+  writeMetadata,
+} from "../lib/metadata.ts";
 import { ensureMetadata, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
-import { getPrMergeState } from "../lib/github.ts";
+import { getBranchRefSha, getPrMergeState, resyncPrHead } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
 
 const MAX_RETRIES = 12;
 const RETRY_DELAY_MS = 5000;
 
+// After GitHub rejects a merge with the "still recomputing" signature, back off
+// (capped) and re-poll before retrying. One entry per retry; length+1 = max
+// attempts. Bounds total transient wait per PR to ~30s.
+const MERGE_RETRY_BACKOFF_MS = [2000, 4000, 8000, 8000, 8000];
+
+/**
+ * GitHub returns these when `mergePullRequest` rejects a merge it considers
+ * out of date. In a top-down cascade this is almost always one of two timing
+ * artifacts (NOT a genuine conflict): a stale PR head pointer (most common —
+ * the child squash moved this branch but GitHub didn't advance the PR's
+ * `headRefOid`), or the brief async mergeability-recompute window.
+ */
+export function isTransientMergeError(stderr: string): boolean {
+  const s = stderr.toLowerCase();
+  return (
+    s.includes("head branch is out of date") ||
+    s.includes("base branch was modified") ||
+    s.includes("review and try the merge again")
+  );
+}
+
+/**
+ * Squash-merge a PR, healing the two timing artifacts a top-down cascade
+ * provokes — neither of which is a real conflict:
+ *
+ *  1. **Stale PR head (the dominant case).** Squash-merging the child moves
+ *     this PR's branch server-side, but GitHub sometimes fails to advance the
+ *     PR's recorded `headRefOid`. Every status read (`mergeable`,
+ *     `mergeStateStatus`, base…head compare) is computed against that stale
+ *     head and reports CLEAN, yet `mergePullRequest` checks the live ref and
+ *     rejects "Head branch is out of date" — indefinitely. We detect it by
+ *     comparing the PR's head to the live branch ref, and fix it by
+ *     close→reopen (`resyncPrHead`), which forces GitHub to re-read the branch.
+ *  2. **Mergeability recompute window.** Heads already match but GitHub is
+ *     still recomputing (`mergeStateStatus: UNKNOWN`); back off and re-poll.
+ *
+ * Only a state that settles genuinely non-mergeable (real conflict / failing
+ * required check) — or exhausted retries — is a hard failure.
+ */
+async function squashMergeWithRetry(
+  prNumber: number,
+  branch: string,
+  deleteFlag: boolean,
+  s: ReturnType<typeof p.spinner>,
+): Promise<{ ok: true } | { ok: false; stderr: string; genuine: boolean }> {
+  const maxAttempts = MERGE_RETRY_BACKOFF_MS.length + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const ghArgs = ["pr", "merge", String(prNumber), "--squash"];
+    if (deleteFlag) ghArgs.push("--delete-branch");
+
+    const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    if (exitCode === 0) return { ok: true };
+
+    // Raced with another merge / a prior re-run? If it's already merged, done.
+    const state = await getPrMergeState(prNumber);
+    if (state?.state === "MERGED") return { ok: true };
+
+    const transient = isTransientMergeError(stderr);
+    if (!transient || attempt === maxAttempts) {
+      return { ok: false, stderr: stderr.trim(), genuine: !transient };
+    }
+
+    // Is the PR's head stuck behind the live branch tip? If so, the merge will
+    // fail forever until GitHub re-reads the branch — nudge it via close/reopen
+    // rather than burning the backoff budget polling a status that never moves.
+    if (await ensureFreshHead(prNumber, branch, s)) {
+      await waitForMergeable(prNumber, s);
+      continue; // retry the merge with a freshly-synced head
+    }
+
+    // Heads match — genuine recompute window. Back off and re-poll; if it
+    // settles non-mergeable instead, it was a real conflict after all.
+    const delay = MERGE_RETRY_BACKOFF_MS[attempt - 1]!;
+    s.message(
+      `PR #${prNumber}: GitHub still recomputing mergeability — retrying in ${delay / 1000}s (${attempt}/${maxAttempts - 1})...`,
+    );
+    await Bun.sleep(delay);
+    const ready = await waitForMergeable(prNumber, s);
+    if (!ready) return { ok: false, stderr: stderr.trim(), genuine: true };
+  }
+  // Unreachable — the loop returns on the final attempt.
+  return { ok: false, stderr: "merge retries exhausted", genuine: false };
+}
+
+/**
+ * After a `resyncPrHead` nudge, poll until GitHub advances the PR's recorded
+ * head to the live branch SHA (or we give up). Bounded by MAX_RETRIES.
+ */
+async function waitForHeadSync(
+  prNumber: number,
+  liveSha: string,
+  spinner: ReturnType<typeof p.spinner>,
+): Promise<boolean> {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const state = await getPrMergeState(prNumber);
+    if (state?.headRefOid === liveSha) return true;
+    if (state?.state === "MERGED") return true;
+    spinner.message(`Waiting for PR #${prNumber} head to sync... (${attempt}/${MAX_RETRIES})`);
+    await Bun.sleep(RETRY_DELAY_MS);
+  }
+  return false;
+}
+
+/**
+ * Heal a stuck PR head pointer. If the PR's recorded head has fallen behind the
+ * live branch ref (GitHub missed the head-sync after a child squash landed on
+ * this branch), force a re-read via close/reopen and wait for the head to catch
+ * up. Returns true if a nudge was performed; false (a no-op) when the heads
+ * already match, the PR is already merged, or the live ref can't be resolved.
+ */
+async function ensureFreshHead(
+  prNumber: number,
+  branch: string,
+  s: ReturnType<typeof p.spinner>,
+): Promise<boolean> {
+  const liveSha = await getBranchRefSha(branch);
+  const state = await getPrMergeState(prNumber);
+  if (!liveSha || !state?.headRefOid || state.state === "MERGED") return false;
+  if (state.headRefOid === liveSha) return false;
+
+  s.message(`PR #${prNumber}: head out of sync with ${pc.yellow(branch)} — nudging GitHub...`);
+  await resyncPrHead(prNumber);
+  await waitForHeadSync(prNumber, liveSha, s);
+  return true;
+}
+
 /**
  * Wait for a PR to become mergeable after a previous merge lands.
  * GitHub needs time to process the new commit on the target branch.
@@ -57,7 +190,10 @@ All merges happen on GitHub, so PRs show as "Merged", Linear tickets
 close automatically, and all GitHub Actions/webhooks fire normally.
 
 Skips PRs that are already merged (safe to re-run after partial failure).
-Waits for GitHub to process between merges if needed.
+Waits for GitHub to process between merges, and self-heals GitHub's
+spurious "Head branch is out of date" (a stale PR head pointer after a
+child squash) by re-syncing the branch and retrying — only a genuine
+conflict or failing required check is reported as a hard failure.
 
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
@@ -84,6 +220,19 @@ OPTIONS
   await ensureValidStack(meta, stackName);
   const ordered = getOrderedBranches(stack);
 
+  // A split stack is rooted on a branch in another stack, so its base PR
+  // doesn't target main — merging it now would land it against the wrong base.
+  // Re-root onto main first (after the parent stack merges).
+  const base = stackBase(stack);
+  if (base !== "main" && base !== "master") {
+    p.cancel(
+      `${pc.yellow(stackName)} is based on ${pc.yellow(base)}, not main — can't merge yet.\n\n` +
+        `  Merge (or finish) the parent stack first, then re-root onto main:\n` +
+        `    ${pc.green("gh-stack restack --onto main")}`,
+    );
+    process.exit(1);
+  }
+
   if (ordered.length <= 1) {
     // Single branch — just enable auto-merge
     const basePr = stack.branches[ordered[0]!]?.pr;
@@ -212,21 +361,22 @@ OPTIONS
 
     s.message(`Squash-merging PR #${childPrNum} via GitHub...`);
 
-    const ghArgs = ["pr", "merge", String(childPrNum), "--squash"];
-    if (deleteFlag) ghArgs.push("--delete-branch");
+    const result = await squashMergeWithRetry(childPrNum, childBranch, deleteFlag, s);
 
-    const proc = Bun.spawn(["gh", ...ghArgs], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    if (exitCode === 0) {
+    if (result.ok) {
       s.stop(`Merged PR #${childPrNum} into ${pc.blue(parentBranch)}`);
     } else {
       s.stop(pc.red(`Failed to merge PR #${childPrNum}`));
-      p.log.error(stderr.trim());
+      p.log.error(result.stderr);
+      if (result.genuine) {
+        p.log.info(
+          "This looks like a real conflict or a failing required check — resolve it on GitHub.",
+        );
+      } else {
+        p.log.info(
+          "GitHub's mergeability recompute didn't settle in time (transient lag, not a conflict).",
+        );
+      }
       p.log.info("Re-run merge to continue from where you left off.");
       process.exit(2);
     }
@@ -310,25 +460,38 @@ OPTIONS
 
   const autoSpinner = p.spinner();
 
-  // Wait for base PR to be ready (may need time after last intermediate merge)
+  // Wait for base PR to be ready (may need time after last intermediate merge).
+  // The last intermediate merge moved this branch, so — like the cascade — the
+  // base PR's head can be stuck behind the live ref; heal it before enabling
+  // auto-merge, then once more if GitHub still rejects the first attempt.
   autoSpinner.start(`Waiting for PR #${basePr} to be ready...`);
+  await ensureFreshHead(basePr!, baseBranch, autoSpinner);
   await waitForMergeable(basePr!, autoSpinner);
 
   autoSpinner.message(`Enabling auto-merge for PR #${basePr}...`);
 
-  try {
+  const enableAutoMerge = async (): Promise<{ ok: boolean; stderr: string }> => {
     const ghArgs = ["pr", "merge", String(basePr), "--squash", "--auto"];
     if (deleteFlag) ghArgs.push("--delete-branch");
+    const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    return { ok: exitCode === 0, stderr: stderr.trim() };
+  };
+
+  let auto = await enableAutoMerge();
+  if (!auto.ok && isTransientMergeError(auto.stderr)) {
+    // Same stale-head artifact as the cascade — re-sync and try once more.
+    await ensureFreshHead(basePr!, baseBranch, autoSpinner);
+    await waitForMergeable(basePr!, autoSpinner);
+    auto = await enableAutoMerge();
+  }
 
-    const proc = Bun.spawn(["gh", ...ghArgs], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await proc.exited;
-
+  if (auto.ok) {
     autoSpinner.stop(`Auto-merge enabled for PR #${basePr} — will merge into main when CI passes`);
-  } catch {
+  } else {
     autoSpinner.stop(pc.yellow(`Could not enable auto-merge for PR #${basePr}`));
+    if (auto.stderr) p.log.error(auto.stderr);
     p.log.info(`Enable manually: ${pc.dim(`gh pr merge ${basePr} --squash --auto`)}`);
   }
 

package/src/commands/rename.ts

@@ -0,0 +1,111 @@
+// gh-stack rename — Rename a tracked branch and keep metadata in sync.
+//
+// The common flow: build on a throwaway branch (`kiliman/feature-wip`), then
+// rename it to a ticketed convention (`kiliman/feature-BEE-1234`) before
+// submitting. `git branch -m` moves the branch's rename-proof config section,
+// and gh-stack reconciles the name-keyed topology files on the next read — this
+// command is just the discoverable front door that does both and persists
+// immediately. (Renaming with raw `git branch -m` still self-heals; see
+// `reconcileRenames` in lib/metadata.ts.)
+import pc from "picocolors";
+import * as p from "../lib/output.ts";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, readMetadata, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+import { confirmAction } from "../lib/ui.ts";
+
+const HELP = `
+gh-stack rename — Rename a tracked branch and update metadata
+
+USAGE
+  gh-stack rename <new-name>           Rename the current branch
+  gh-stack rename <old-name> <new-name>
+
+Renames the local git branch (\`git branch -m\`) and re-keys the stack
+topology so the branch stays tracked — re-parenting any children that
+pointed at the old name. Use this for the throwaway-branch → ticketed-PR
+flow without hand-editing metadata.
+
+Renaming a branch that already has a PR only renames it locally; the
+GitHub PR still tracks the old remote branch.
+`;
+
+export default async function rename(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  if (positionals.length === 0 || positionals.length > 2) {
+    p.cancel("Usage: gh-stack rename [<old-name>] <new-name>");
+    process.exit(1);
+  }
+
+  const meta = await ensureMetadata();
+  const current = await git.currentBranch();
+
+  const oldName = positionals.length === 2 ? positionals[0]! : current;
+  const newName = positionals.length === 2 ? positionals[1]! : positionals[0]!;
+
+  // ── Validate ──
+  if (oldName === newName) {
+    p.cancel("Old and new names are identical — nothing to do.");
+    process.exit(1);
+  }
+  if (newName === "main" || newName === "master") {
+    p.cancel(`Refusing to rename a branch to ${pc.red(newName)}.`);
+    process.exit(1);
+  }
+  if (!(await git.localBranchExists(oldName))) {
+    p.cancel(`Branch ${pc.yellow(oldName)} does not exist locally.`);
+    process.exit(1);
+  }
+  if (await git.localBranchExists(newName)) {
+    p.cancel(`A branch named ${pc.yellow(newName)} already exists.`);
+    process.exit(1);
+  }
+
+  const stackName = findStackForBranch(meta, oldName);
+  if (!stackName) {
+    p.cancel(
+      `Branch ${pc.yellow(oldName)} isn't tracked in a stack.\n\n  Rename it with plain git instead:\n    ${pc.green(`git branch -m ${oldName} ${newName}`)}`,
+    );
+    process.exit(1);
+  }
+
+  const hadPr = meta.stacks[stackName]?.branches[oldName]?.pr;
+
+  // ── Confirm ──
+  const ok = await confirmAction(
+    `Rename ${pc.yellow(oldName)} → ${pc.green(newName)} (stack: ${stackName})?`,
+  );
+  if (!ok) {
+    p.cancel("Rename cancelled.");
+    return;
+  }
+
+  // ── Rename + persist ──
+  if (!(await git.renameBranch(oldName, newName))) {
+    p.cancel(`git failed to rename ${pc.yellow(oldName)} → ${pc.yellow(newName)}.`);
+    process.exit(1);
+  }
+
+  // Re-read so reconcileRenames re-keys the topology from the (moved) config,
+  // then write it back to persist the new name + repoint child config.
+  const updated = await readMetadata();
+  if (!updated) {
+    p.cancel("Renamed the branch, but failed to re-read metadata.");
+    process.exit(1);
+  }
+  await writeMetadata(updated);
+
+  p.log.success(`Renamed ${pc.yellow(oldName)} → ${pc.green(newName)}`);
+
+  if (hadPr) {
+    p.log.warn(
+      `PR ${pc.cyan(`#${hadPr}`)} still tracks the old remote branch ${pc.dim(oldName)}.\n` +
+        `  This rename was local only — update the PR's branch on GitHub if needed.`,
+    );
+  }
+}