mandrel 1.57.0

package/.agents/scripts/lib/orchestration/story-close/merge-runner.js

@@ -0,0 +1,636 @@
+/**
+ * merge-runner.js — collapse the duplicated epic-merge-lock try/finally and
+ * the duplicated `pushEpicWithRetry` + `PushRetryConflictError` envelope
+ * into two reusable helpers used by both finalizeMerge and
+ * completeInProgressMerge.
+ *
+ * Extracted from story-close.js (Story #955, Theme A part 1) so the close
+ * orchestrator becomes a thin CLI shell.
+ *
+ * `withEpicMergeLock` wraps acquire → user fn → release in a single
+ * try/finally with consistent `🔒 Acquired` / `🔓 Released` log lines.
+ * Acquisition failure throws a single, operator-actionable Error mentioning
+ * the lock-file path so a stale lock can be cleared by hand.
+ *
+ * `pushEpicAndHandleConflicts` wraps `pushEpicWithRetry` + the
+ * `PushRetryConflictError` → throw envelope, plus the retry-exhausted / * generic-failure → throw envelope used by `runFinalizeMerge`. The resume
+ * path (`runResumeMerge`) shares the same envelope but routes generic
+ * failures through the `describeResumePushFailure` helper for consistent
+ * operator-facing copy (see `comment-bodies.js`). Errors thrown from these
+ * helpers reach the `runAsCli` boundary in `story-close.js` and are mapped
+ * to `process.exit(1)` (Story #959 — close-tail scripts must throw rather
+ * than route through the logger's fatal sink, see
+ * `.agents/instructions.md`).
+ *
+ * Both helpers are dependency-injected: the lock acquire/release pair and
+ * the push retry runner are parameters so unit tests can pin behaviour
+ * without spawning the close script. Default arguments point at the
+ * production wiring from `lib/epic-merge-lock.js` + `lib/push-epic-retry.js`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunners as defaultGetRunners } from '../../config/runners.js';
+import { resolveWorkingPath } from '../../config-resolver.js';
+import {
+  acquireEpicMergeLock as defaultAcquire,
+  releaseEpicMergeLock as defaultRelease,
+  resolveGitCommonDir,
+} from '../../epic-merge-lock.js';
+import { mergeFeatureBranch } from '../../git-merge-orchestrator.js';
+import {
+  gitSpawn as defaultGitSpawn,
+  gitSync as defaultGitSync,
+} from '../../git-utils.js';
+import { Logger as DefaultLogger } from '../../Logger.js';
+import {
+  pushEpicWithRetry as defaultPushEpicWithRetry,
+  PushRetryConflictError,
+} from '../../push-epic-retry.js';
+import {
+  buildResumeMergeCommitMsg,
+  describeResumePushFailure,
+} from './comment-bodies.js';
+import {
+  buildMergeMessageWithCap,
+  loadHeaderMaxLength,
+} from './merge-subject.js';
+
+/**
+ * Render the lock-file path for a given main-repo `cwd` + `epicId`. Pure;
+ * exported so the operator-facing error message stays a single source of
+ * truth.
+ */
+export function lockPathDisplay(cwd, epicId) {
+  return path.join(resolveGitCommonDir(cwd), `epic-${epicId}.merge.lock`);
+}
+
+/**
+ * Best-effort `story.blocked` lifecycle emit (Story #2241 / Task #2247).
+ * Used by the merge runner's failure paths to surface a typed `reason`
+ * on the bus before re-throwing. The bus is optional — every legacy
+ * caller and the existing unit fixtures pass `null` — and emit failures
+ * are swallowed so the original throw (which the operator must see)
+ * always reaches `runAsCli`.
+ *
+ * Exported so the wider story-close path (and the spawn-timeout helper
+ * in `story-close.js`) can use the same low-friction wrapper.
+ *
+ * @param {{
+ *   bus?: object|null,
+ *   storyId: number|string,
+ *   reason: string,
+ *   logger?: { warn?: Function },
+ * }} args
+ * @returns {Promise<void>}
+ */
+export async function emitStoryBlockedSafe({ bus, storyId, reason, logger }) {
+  if (!bus) return;
+  try {
+    await bus.emit('story.blocked', {
+      storyId: Number(storyId),
+      reason: String(reason),
+    });
+  } catch (err) {
+    logger?.warn?.(
+      `[story-close] ⚠️ story.blocked emit failed for #${storyId} (swallowed): ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Canonical "blocked close-result" envelope builder used by all four
+ * pre-merge and merge-phase blocked exits (Story #3638 — duplication
+ * noted by audit fe90dd9c36fc).
+ *
+ * The four previously-parallel patterns each:
+ *   1. Build a `{ success: false, status: 'blocked', phase, reason, …extra }` result.
+ *   2. Call `emitStoryBlockedSafe` (best-effort bus emit, optional).
+ *   3. Print the `--- STORY CLOSE RESULT ---` banner via `Logger.info`.
+ *   4. Call `progress('BLOCKED', blockedMessage)` for the operator-facing line.
+ *
+ * This helper centralises all four steps so callers supply only their
+ * domain-specific fields via `extra` and the human-facing `blockedMessage`.
+ * Bus emission is skipped when `bus` is `null`/`undefined` (the same
+ * semantics as `emitStoryBlockedSafe`).
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   phase: string,
+ *   reason: string,
+ *   extra?: object,
+ *   bus?: object|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   blockedMessage: string,
+ *   logger?: { info?: Function, warn?: Function },
+ * }} args
+ * @returns {Promise<{ success: false, status: 'blocked', phase: string, reason: string, [key: string]: unknown }>}
+ */
+export async function emitBlockedCloseResult({
+  storyId,
+  phase,
+  reason,
+  extra = {},
+  bus = null,
+  progress,
+  blockedMessage,
+  logger = DefaultLogger,
+}) {
+  const result = { success: false, status: 'blocked', phase, reason, ...extra };
+  await emitStoryBlockedSafe({ bus, storyId, reason, logger });
+  logger.info?.(
+    `\n--- STORY CLOSE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  );
+  progress('BLOCKED', blockedMessage);
+  return result;
+}
+
+/**
+ * Acquire the per-Epic filesystem merge lock, run `fn(handle)` inside a
+ * try/finally, and always release. Logs `🔒 Acquired ...` at acquire and
+ * `🔓 Released epic-merge lock` on release via the supplied `log` sink.
+ *
+ * @template T
+ * @param {number|string} epicId
+ * @param {{
+ *   repoRoot: string,
+ *   timeoutMs?: number,
+ *   log?: (tag: string, msg: string) => void,
+ *   acquire?: typeof defaultAcquire,
+ *   release?: typeof defaultRelease,
+ * }} opts
+ * @param {(handle: object) => Promise<T> | T} fn
+ * @returns {Promise<T>}
+ */
+export async function withEpicMergeLock(
+  epicId,
+  {
+    repoRoot,
+    timeoutMs = 60_000,
+    log = () => {},
+    acquire = defaultAcquire,
+    release = defaultRelease,
+  },
+  fn,
+) {
+  log('LOCK', `Acquiring epic-merge lock for epic #${epicId}...`);
+  let lockHandle;
+  try {
+    lockHandle = await acquire(epicId, { repoRoot, timeoutMs });
+  } catch (err) {
+    throw new Error(
+      `Could not acquire epic-merge lock for epic #${epicId}: ${err.message}. ` +
+        `Another story closure may be in progress, or a stale lock is present at ` +
+        `${lockPathDisplay(repoRoot, epicId)} — inspect and remove it manually if no ` +
+        `other process is running.`,
+    );
+  }
+  log('LOCK', `🔒 Acquired ${path.basename(lockHandle.filePath)}`);
+  try {
+    return await fn(lockHandle);
+  } finally {
+    release(lockHandle);
+    log('LOCK', '🔓 Released epic-merge lock');
+  }
+}
+
+/**
+ * Push the Epic branch with retry, surfacing `PushRetryConflictError` and
+ * generic failure modes by throwing an `Error` (Story #959 — see file
+ * header). Used by both `runFinalizeMerge` (post-merge push) and
+ * `runResumeMerge` (resume-after-conflict push).
+ *
+ * The two callers diverge only on how they format generic-failure copy:
+ *   - finalize path inlines the `retries-exhausted vs other-reason` switch
+ *     directly,
+ *   - resume path routes through `describeResumePushFailure`.
+ *
+ * Pass `mode: 'resume'` to use the resume-style copy.
+ *
+ * @param {{
+ *   cwd: string,
+ *   epicBranch: string,
+ *   storyBranch: string,
+ *   config: object,
+ *   log?: (msg: string) => void,
+ *   mode?: 'finalize' | 'resume',
+ *   pushEpicWithRetry?: typeof defaultPushEpicWithRetry,
+ *   git?: { gitSpawn: typeof defaultGitSpawn },
+ *   getRunners?: (config: object) => any,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, attempts: number, reason?: string, result?: object }>}
+ */
+export async function pushEpicAndHandleConflicts({
+  cwd,
+  epicBranch,
+  storyBranch,
+  config,
+  log = () => {},
+  mode = 'finalize',
+  mergeMessage = null,
+  pushEpicWithRetry = defaultPushEpicWithRetry,
+  git = { gitSpawn: defaultGitSpawn },
+  getRunners = defaultGetRunners,
+}) {
+  let pushOutcome;
+  try {
+    pushOutcome = await pushEpicWithRetry({
+      cwd,
+      epicBranch,
+      storyBranch,
+      storyMergeRetry: getRunners(config).storyMergeRetry,
+      git,
+      log,
+      mergeMessage,
+    });
+  } catch (err) {
+    if (err instanceof PushRetryConflictError) {
+      throw new Error(err.message);
+    }
+    throw err;
+  }
+
+  if (!pushOutcome.ok) {
+    if (mode === 'resume') {
+      const fatal = describeResumePushFailure(pushOutcome);
+      if (fatal) throw new Error(fatal);
+    } else {
+      const reasonLabel =
+        pushOutcome.reason === 'retry-exhausted'
+          ? `retries exhausted after ${pushOutcome.attempts} attempt(s)`
+          : pushOutcome.reason;
+      throw new Error(
+        `Push failed (${reasonLabel}): ${pushOutcome.result?.stderr || pushOutcome.result?.stdout || 'unknown'}`,
+      );
+    }
+  }
+  return pushOutcome;
+}
+
+// ---------------------------------------------------------------------------
+// Story-close merge sequencing
+// ---------------------------------------------------------------------------
+//
+// `runFinalizeMerge` and `runResumeMerge` previously lived inline in
+// `story-close.js`. They both take the per-Epic merge lock, then either
+// rebase + merge + push (finalize path) or commit-the-pending-merge + push
+// (resume path). Extracted from story-close.js (Story #956, Theme A finishing
+// touch) so the close orchestrator becomes a thin CLI shell. Both helpers
+// take the same dependency-injection seams as withEpicMergeLock /
+// pushEpicAndHandleConflicts so tests can pin behaviour without spawning
+// the script.
+
+/**
+ * Pre-merge rebase of the Story branch onto `origin/<epicBranch>`.
+ *
+ * Parallel wave execution lets two Stories land on the Epic between the time
+ * a later Story branched off and the time it closes. Rebasing the Story on
+ * the latest Epic before the close-merge shrinks the conflict surface to the
+ * Story's real delta and lets `mergeFeatureBranch`'s minor-conflict auto-
+ * resolve apply surgically instead of against stale base content.
+ *
+ * Runs inside the per-story worktree so it does not disturb the main
+ * checkout. On any failure (fetch error, rebase conflict) the rebase is
+ * aborted and the caller falls through to the plain merge path, which will
+ * surface the same conflict via triage.
+ *
+ * @returns {{ rebased: boolean, reason?: string }}
+ */
+function resolveStoryWorktreePath({ config, storyId, repoRoot }) {
+  const wtConfig = config?.delivery?.worktreeIsolation;
+  if (!wtConfig?.enabled) return { reason: 'isolation-disabled' };
+  const wtPath = resolveWorkingPath({
+    worktreeEnabled: true,
+    repoRoot,
+    storyId,
+    worktreeRoot: wtConfig.root,
+  });
+  if (!fs.existsSync(wtPath)) return { reason: 'worktree-missing' };
+  return { wtPath };
+}
+
+function runFetchOrigin({ wtPath, epicBranch, log, gitSpawn }) {
+  const fetch = gitSpawn(wtPath, 'fetch', 'origin', epicBranch);
+  if (fetch.status === 0) return true;
+  log('GIT', `⚠️ fetch origin ${epicBranch} failed; skipping pre-merge rebase`);
+  return false;
+}
+
+function runRebaseAndAbortOnConflict({ wtPath, epicBranch, log, gitSpawn }) {
+  const rebase = gitSpawn(wtPath, 'rebase', `origin/${epicBranch}`);
+  if (rebase.status === 0) return true;
+  gitSpawn(wtPath, 'rebase', '--abort');
+  log('GIT', '⚠️ rebase conflicted; aborted — merge triage will handle overlap');
+  return false;
+}
+
+export function rebaseStoryOnEpic({
+  config,
+  storyId,
+  epicBranch,
+  storyBranch,
+  repoRoot,
+  log = () => {},
+  gitSpawn = defaultGitSpawn,
+}) {
+  const wt = resolveStoryWorktreePath({ config, storyId, repoRoot });
+  if (!wt.wtPath) return { rebased: false, reason: wt.reason };
+  const { wtPath } = wt;
+
+  log('GIT', `Rebasing ${storyBranch} onto origin/${epicBranch}...`);
+  if (!runFetchOrigin({ wtPath, epicBranch, log, gitSpawn })) {
+    return { rebased: false, reason: 'fetch-failed' };
+  }
+  if (!runRebaseAndAbortOnConflict({ wtPath, epicBranch, log, gitSpawn })) {
+    return { rebased: false, reason: 'rebase-conflict' };
+  }
+  log('GIT', `✅ Rebased ${storyBranch} onto origin/${epicBranch}`);
+  return { rebased: true };
+}
+
+/**
+ * Run the finalize-path merge: optional rebase, checkout + pull --rebase,
+ * merge --no-ff, push (with retry/conflict handling). Branch cleanup is
+ * deferred to after worktree reap (git refuses to delete a branch still
+ * checked out by a worktree).
+ *
+ * The caller (story-close.js) holds the per-Epic merge lock across the
+ * entire close flow, so this helper no longer acquires it itself.
+ *
+ * @param {{
+ *   epicBranch: string,
+ *   storyBranch: string,
+ *   storyTitle: string,
+ *   storyId: number|string,
+ *   epicId: number|string,
+ *   cwd: string,
+ *   config: object,
+ *   log?: (tag: string, msg: string) => void,
+ *   logger?: { error: (msg: string) => void },
+ *   gitSync?: typeof defaultGitSync,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ * }} opts
+ */
+async function buildMergeMessage(storyTitle, storyId, { cwd, logger }) {
+  const headerMaxLength = await loadHeaderMaxLength(cwd, { logger });
+  const { message } = buildMergeMessageWithCap({
+    type: 'feat',
+    title: storyTitle,
+    storyId,
+    headerMaxLength,
+    logger,
+  });
+  return message;
+}
+
+function buildVerboseMergeLogger(logger) {
+  return (_level, _ctx, msg, meta) => {
+    const tail = meta ? ` ${JSON.stringify(meta)}` : '';
+    logger.error(`[merge] ${msg}${tail}`);
+  };
+}
+
+function throwOnMajorConflict({ result, epicBranch }) {
+  if (result.merged || !result.major) return;
+  throw new Error(
+    `Major merge conflict on story close: ` +
+      `${result.conflicts.files} file(s), ${result.conflicts.lines} marker(s). ` +
+      `Conflicting files: ${result.conflicts.fileList.join(', ')}. ` +
+      `Merge has been aborted. Resolve manually on ${epicBranch}, then ` +
+      `re-run this script.`,
+  );
+}
+
+function logMergeOutcome({ result, log }) {
+  if (!result.autoResolved) {
+    log('GIT', '✅ Merge successful');
+    return;
+  }
+  log(
+    'GIT',
+    `✅ Merge completed with auto-resolved minor conflicts ` +
+      `(${result.conflicts.files} file(s) resolved to theirs)`,
+  );
+  for (const f of result.autoResolvedFiles ?? []) {
+    log(
+      'GIT',
+      `  ↳ auto-resolved ${f.file} (${f.discardedLines} base line(s) discarded; trailer in merge commit)`,
+    );
+  }
+}
+
+export async function runFinalizeMerge({
+  epicBranch,
+  storyBranch,
+  storyTitle,
+  storyId,
+  epicId: _epicId,
+  cwd,
+  config,
+  bus = null,
+  log = () => {},
+  logger = DefaultLogger,
+  gitSync = defaultGitSync,
+  gitSpawn = defaultGitSpawn,
+}) {
+  rebaseStoryOnEpic({
+    config,
+    storyId,
+    epicBranch,
+    storyBranch,
+    repoRoot: cwd,
+    log,
+    gitSpawn,
+  });
+
+  log('GIT', `Checking out ${epicBranch}...`);
+  gitSync(cwd, 'checkout', epicBranch);
+  gitSpawn(cwd, 'pull', '--rebase', 'origin', epicBranch);
+
+  log('GIT', `Merging ${storyBranch} into ${epicBranch} (--no-ff)...`);
+  const mergeMessage = await buildMergeMessage(storyTitle, storyId, {
+    cwd,
+    logger,
+  });
+  const result = mergeFeatureBranch(
+    cwd,
+    storyBranch,
+    buildVerboseMergeLogger(logger),
+    { message: mergeMessage },
+  );
+
+  // Story #2241 / Task #2247 — surface a `story.blocked` lifecycle emit
+  // on the typed merge-failure paths before re-throwing so the bus
+  // ledger (and any subscribed BlockerHandler listener) sees the
+  // typed reason. The emit is best-effort; the throw is the canonical
+  // signal that the close was halted.
+  try {
+    throwOnMajorConflict({ result, epicBranch });
+  } catch (err) {
+    await emitStoryBlockedSafe({
+      bus,
+      storyId,
+      reason: 'merge-conflict:major',
+      logger,
+    });
+    throw err;
+  }
+  logMergeOutcome({ result, log });
+
+  log('GIT', `Pushing ${epicBranch}...`);
+  let pushOutcome;
+  try {
+    pushOutcome = await pushEpicAndHandleConflicts({
+      cwd,
+      epicBranch,
+      storyBranch,
+      config,
+      log: (msg) => log('GIT', msg),
+      mode: 'finalize',
+      mergeMessage,
+    });
+  } catch (err) {
+    await emitStoryBlockedSafe({
+      bus,
+      storyId,
+      reason: 'push-failed:finalize',
+      logger,
+    });
+    throw err;
+  }
+  if (pushOutcome.attempts > 1) {
+    log(
+      'GIT',
+      `✅ Push succeeded on attempt ${pushOutcome.attempts} after sibling session landed on ${epicBranch}`,
+    );
+  }
+}
+
+/**
+ * Commit a pending in-progress merge (resume path) using the
+ * conventional-commit subject from `buildResumeMergeCommitMsg`. No-op when
+ * `.git/MERGE_HEAD` is absent (merge already committed by the operator).
+ */
+function isMergePending(cwd) {
+  return fs.existsSync(path.join(cwd, '.git', 'MERGE_HEAD'));
+}
+
+function commitPendingMerge({
+  cwd,
+  storyTitle,
+  storyId,
+  gitSpawn,
+  headerMaxLength,
+  logger,
+}) {
+  return gitSpawn(
+    cwd,
+    'commit',
+    '--no-verify',
+    '-m',
+    buildResumeMergeCommitMsg(storyTitle, storyId, {
+      headerMaxLength,
+      logger,
+    }),
+  );
+}
+
+export async function finalizeMergeIfPending({
+  cwd,
+  epicBranch,
+  storyBranch,
+  storyTitle,
+  storyId,
+  log = () => {},
+  gitSpawn = defaultGitSpawn,
+  logger = DefaultLogger,
+}) {
+  if (!isMergePending(cwd)) {
+    log(
+      'GIT',
+      '⚠️ No MERGE_HEAD found — merge already committed; proceeding to push',
+    );
+    return;
+  }
+  log('GIT', 'Finalizing in-progress merge (git commit --no-verify)');
+  const headerMaxLength = await loadHeaderMaxLength(cwd, { logger });
+  const commit = commitPendingMerge({
+    cwd,
+    storyTitle,
+    storyId,
+    gitSpawn,
+    headerMaxLength,
+    logger,
+  });
+  if (commit.status !== 0) {
+    throw new Error(
+      `Failed to finalize merge commit: ${commit.stderr || commit.stdout || 'unknown'}. ` +
+        `Check that all conflicts are resolved and staged on ${epicBranch}.`,
+    );
+  }
+  log('GIT', `✅ Merge of ${storyBranch} finalized on ${epicBranch}`);
+}
+
+/**
+ * Run the resume-path merge: finalize the in-progress merge (if any), then
+ * push. Used by `runStoryClose` when prior state is `partial-merge`. The
+ * caller holds the per-Epic merge lock across the entire close flow.
+ */
+export async function runResumeMerge({
+  cwd,
+  epicBranch,
+  storyBranch,
+  storyTitle,
+  storyId,
+  epicId: _epicId,
+  config,
+  bus = null,
+  logger = DefaultLogger,
+  log = () => {},
+  gitSpawn = defaultGitSpawn,
+}) {
+  const resumeMergeMessage = await buildMergeMessage(storyTitle, storyId, {
+    cwd,
+    logger,
+  });
+  try {
+    await finalizeMergeIfPending({
+      cwd,
+      epicBranch,
+      storyBranch,
+      storyTitle,
+      storyId,
+      log,
+      gitSpawn,
+      logger,
+    });
+  } catch (err) {
+    await emitStoryBlockedSafe({
+      bus,
+      storyId,
+      reason: 'merge-finalize-failed:resume',
+      logger,
+    });
+    throw err;
+  }
+  log('GIT', `Pushing ${epicBranch}...`);
+  try {
+    await pushEpicAndHandleConflicts({
+      cwd,
+      epicBranch,
+      storyBranch,
+      config,
+      log: (msg) => log('GIT', msg),
+      mode: 'resume',
+      mergeMessage: resumeMergeMessage,
+    });
+  } catch (err) {
+    await emitStoryBlockedSafe({
+      bus,
+      storyId,
+      reason: 'push-failed:resume',
+      logger,
+    });
+    throw err;
+  }
+}