@i-santos/create-package-starter 1.5.0-beta.8 → 1.5.0-beta.9

package/README.md

@@ -95,15 +95,20 @@ Orchestrate release cycle:
 - `--title <text>`
 - `--body-file <path>`
 - `--draft`
+- `--phase <code|full>` (default: `full`)
 - `--auto-merge` (default behavior: enabled)
 - `--watch-checks` (default behavior: enabled)
 - `--check-timeout <minutes>` (default: `30`)
+- `--confirm-merges` (require confirmation before each merge step)
 - `--merge-when-green` (default behavior: enabled)
 - `--merge-method <squash|merge|rebase>` (default: `squash`)
 - `--wait-release-pr` (default behavior: enabled)
 - `--release-pr-timeout <minutes>` (default: `30`)
 - `--merge-release-pr` (default behavior: enabled)
 - `--verify-npm` (default behavior: enabled)
+- `--confirm-cleanup` (require confirmation before cleanup; only after npm validation pass)
+- `--sync-base <auto|rebase|merge|off>` (default: `auto`; keeps code branch updated with `release/beta`)
+- `--no-resume` (disable automatic resume/reconciliation behavior)
 - `--no-cleanup` (disable default local cleanup after successful cycle)
 - `--yes`
 - `--dry-run`
@@ -221,25 +226,30 @@ Body source priority:
 
 Default mode is `auto`:
 - if current branch starts with `changeset-release/` => `publish`
-- else if exactly one open `changeset-release/*` PR exists => `publish`
+- else if current branch is `release/beta` and exactly one open `changeset-release/*` PR exists => `publish`
 - else => `open-pr`
 
 For `open-pr` mode:
 - runs open-pr flow
-- can merge code PR when green
+- auto-syncs feature/fix branch with `origin/release/beta` before PR (default `--sync-base auto`)
+- enables auto-merge for code PR by default
+- auto-resumes release phase if current code branch is already integrated into `release/beta`
+- supports `--phase code` to stop after code PR merge
 - can wait for release PR creation (`changeset-release/*`)
-- can watch checks and merge release PR when green
+- enables auto-merge for release PR by default
 - validates npm publish (package + version + expected dist-tag)
 - cleans local branch by default when safety gates are satisfied (`--no-cleanup` to disable)
 
 For `publish` mode:
 - resolves release PR directly
 - watches checks
-- merges when green (policy permitting)
+- enables auto-merge and waits for merge completion (policy permitting)
 
 The command is policy-aware:
 - never bypasses required checks/reviews/rulesets
 - fails fast with actionable diagnostics when blocked
+- stops with actionable guidance when approval is still required before merge
+- cleanup runs only when npm validation passes
 
 ### Protected `release/beta` stable promotion
 

package/lib/run.js

@@ -45,7 +45,7 @@ function usage() {
     '  create-package-starter setup-github [--repo <owner/repo>] [--default-branch <branch>] [--ruleset <path>] [--dry-run]',
     '  create-package-starter setup-beta [--dir <directory>] [--repo <owner/repo>] [--beta-branch <branch>] [--default-branch <branch>] [--release-auth github-token|pat|app|manual-trigger] [--force] [--dry-run] [--yes]',
     '  create-package-starter open-pr [--repo <owner/repo>] [--base <branch>] [--head <branch>] [--title <text>] [--body <text>] [--body-file <path>] [--template <path>] [--draft] [--auto-merge] [--watch-checks] [--check-timeout <minutes>] [--yes] [--dry-run]',
-    '  create-package-starter release-cycle [--repo <owner/repo>] [--mode auto|open-pr|publish] [--track auto|beta|stable] [--promote-stable] [--promote-type patch|minor|major] [--promote-summary <text>] [--head <branch>] [--base <branch>] [--title <text>] [--body-file <path>] [--draft] [--auto-merge] [--watch-checks] [--check-timeout <minutes>] [--merge-when-green] [--merge-method squash|merge|rebase] [--wait-release-pr] [--release-pr-timeout <minutes>] [--merge-release-pr] [--verify-npm] [--no-cleanup] [--yes] [--dry-run]',
+    '  create-package-starter release-cycle [--repo <owner/repo>] [--mode auto|open-pr|publish] [--phase code|full] [--track auto|beta|stable] [--promote-stable] [--promote-type patch|minor|major] [--promote-summary <text>] [--head <branch>] [--base <branch>] [--title <text>] [--body-file <path>] [--update-pr-description] [--draft] [--auto-merge] [--watch-checks] [--check-timeout <minutes>] [--confirm-merges] [--merge-when-green] [--merge-method squash|merge|rebase] [--wait-release-pr] [--release-pr-timeout <minutes>] [--merge-release-pr] [--verify-npm] [--confirm-cleanup] [--sync-base auto|rebase|merge|off] [--no-resume] [--no-cleanup] [--yes] [--dry-run]',
     '  create-package-starter promote-stable [--dir <directory>] [--type patch|minor|major] [--summary <text>] [--dry-run]',
     '  create-package-starter setup-npm [--dir <directory>] [--publish-first] [--dry-run]',
     '',
@@ -446,6 +446,7 @@ function parseOpenPrArgs(argv) {
     autoMerge: false,
     watchChecks: false,
     checkTimeout: 30,
+    updateExistingPr: true,
     yes: false,
     dryRun: false
   };
@@ -496,11 +497,16 @@ function parseOpenPrArgs(argv) {
     }
 
     if (token === '--check-timeout') {
-      args.checkTimeout = Number.parseInt(parseValueFlag(argv, i, '--check-timeout'), 10);
+      args.checkTimeout = Number.parseFloat(parseValueFlag(argv, i, '--check-timeout'));
       i += 1;
       continue;
     }
 
+    if (token === '--update-pr-description') {
+      args.updateExistingPr = true;
+      continue;
+    }
+
     if (token === '--draft') {
       args.draft = true;
       continue;
@@ -534,8 +540,8 @@ function parseOpenPrArgs(argv) {
     throw new Error(`Invalid argument: ${token}\n\n${usage()}`);
   }
 
-  if (!Number.isInteger(args.checkTimeout) || args.checkTimeout <= 0) {
-    throw new Error('Invalid --check-timeout value. Expected a positive integer (minutes).');
+  if (!Number.isFinite(args.checkTimeout) || args.checkTimeout <= 0) {
+    throw new Error('Invalid --check-timeout value. Expected a positive number (minutes).');
   }
 
   return args;
@@ -545,6 +551,8 @@ function parseReleaseCycleArgs(argv) {
   const args = {
     repo: '',
     mode: 'auto',
+    phase: 'full',
+    phaseProvided: false,
     track: 'auto',
     promoteStable: false,
     promoteType: 'patch',
@@ -553,16 +561,21 @@ function parseReleaseCycleArgs(argv) {
     base: '',
     title: '',
     bodyFile: '',
+    updatePrDescription: false,
     draft: false,
     autoMerge: true,
     watchChecks: true,
     checkTimeout: 30,
+    confirmMerges: false,
+    syncBase: 'auto',
+    resume: true,
     mergeWhenGreen: true,
     mergeMethod: 'squash',
     waitReleasePr: true,
     releasePrTimeout: 30,
     mergeReleasePr: true,
     verifyNpm: true,
+    confirmCleanup: false,
     noCleanup: false,
     yes: false,
     dryRun: false
@@ -583,6 +596,13 @@ function parseReleaseCycleArgs(argv) {
       continue;
     }
 
+    if (token === '--phase') {
+      args.phase = parseValueFlag(argv, i, '--phase');
+      args.phaseProvided = true;
+      i += 1;
+      continue;
+    }
+
     if (token === '--track') {
       args.track = parseValueFlag(argv, i, '--track');
       i += 1;
@@ -625,14 +645,19 @@ function parseReleaseCycleArgs(argv) {
       continue;
     }
 
+    if (token === '--update-pr-description') {
+      args.updatePrDescription = true;
+      continue;
+    }
+
     if (token === '--check-timeout') {
-      args.checkTimeout = Number.parseInt(parseValueFlag(argv, i, '--check-timeout'), 10);
+      args.checkTimeout = Number.parseFloat(parseValueFlag(argv, i, '--check-timeout'));
       i += 1;
       continue;
     }
 
     if (token === '--release-pr-timeout') {
-      args.releasePrTimeout = Number.parseInt(parseValueFlag(argv, i, '--release-pr-timeout'), 10);
+      args.releasePrTimeout = Number.parseFloat(parseValueFlag(argv, i, '--release-pr-timeout'));
       i += 1;
       continue;
     }
@@ -658,6 +683,22 @@ function parseReleaseCycleArgs(argv) {
       continue;
     }
 
+    if (token === '--confirm-merges') {
+      args.confirmMerges = true;
+      continue;
+    }
+
+    if (token === '--sync-base') {
+      args.syncBase = parseValueFlag(argv, i, '--sync-base');
+      i += 1;
+      continue;
+    }
+
+    if (token === '--no-resume') {
+      args.resume = false;
+      continue;
+    }
+
     if (token === '--merge-when-green') {
       args.mergeWhenGreen = true;
       continue;
@@ -683,6 +724,11 @@ function parseReleaseCycleArgs(argv) {
       continue;
     }
 
+    if (token === '--confirm-cleanup') {
+      args.confirmCleanup = true;
+      continue;
+    }
+
     if (token === '--no-cleanup') {
       args.noCleanup = true;
       continue;
@@ -710,6 +756,10 @@ function parseReleaseCycleArgs(argv) {
     throw new Error('Invalid --mode value. Expected auto, open-pr, or publish.');
   }
 
+  if (!['code', 'full'].includes(args.phase)) {
+    throw new Error('Invalid --phase value. Expected code or full.');
+  }
+
   if (!['auto', 'beta', 'stable'].includes(args.track)) {
     throw new Error('Invalid --track value. Expected auto, beta, or stable.');
   }
@@ -718,16 +768,20 @@ function parseReleaseCycleArgs(argv) {
     throw new Error('Invalid --promote-type value. Expected patch, minor, or major.');
   }
 
+  if (!['auto', 'rebase', 'merge', 'off'].includes(args.syncBase)) {
+    throw new Error('Invalid --sync-base value. Expected auto, rebase, merge, or off.');
+  }
+
   if (!['squash', 'merge', 'rebase'].includes(args.mergeMethod)) {
     throw new Error('Invalid --merge-method value. Expected squash, merge, or rebase.');
   }
 
-  if (!Number.isInteger(args.checkTimeout) || args.checkTimeout <= 0) {
-    throw new Error('Invalid --check-timeout value. Expected a positive integer (minutes).');
+  if (!Number.isFinite(args.checkTimeout) || args.checkTimeout <= 0) {
+    throw new Error('Invalid --check-timeout value. Expected a positive number (minutes).');
   }
 
-  if (!Number.isInteger(args.releasePrTimeout) || args.releasePrTimeout <= 0) {
-    throw new Error('Invalid --release-pr-timeout value. Expected a positive integer (minutes).');
+  if (!Number.isFinite(args.releasePrTimeout) || args.releasePrTimeout <= 0) {
+    throw new Error('Invalid --release-pr-timeout value. Expected a positive number (minutes).');
   }
 
   return args;
@@ -1281,6 +1335,29 @@ function sleepMs(milliseconds) {
   Atomics.wait(view, 0, 0, milliseconds);
 }
 
+function nowMs(deps) {
+  if (deps && typeof deps.now === 'function') {
+    return Number(deps.now());
+  }
+
+  return Date.now();
+}
+
+function waitForNextPoll(timeoutAt, defaultIntervalMs, deps) {
+  const remainingMs = Math.max(0, timeoutAt - nowMs(deps));
+  if (remainingMs <= 0) {
+    return;
+  }
+
+  const pollMs = Math.max(100, Math.min(defaultIntervalMs, remainingMs));
+  if (deps && typeof deps.sleep === 'function') {
+    deps.sleep(pollMs);
+    return;
+  }
+
+  sleepMs(pollMs);
+}
+
 function resolveGitContext(args, deps) {
   const insideWorkTree = deps.exec('git', ['rev-parse', '--is-inside-work-tree']);
   if (insideWorkTree.status !== 0 || insideWorkTree.stdout.trim() !== 'true') {
@@ -1454,6 +1531,14 @@ function ensureBranchPushed(repo, head, deps) {
 
 function createOrUpdatePr(context, body, args, deps) {
   const existing = findOpenPrByHeadBase(context.repo, context.head, context.base, deps);
+  if (existing && !args.updateExistingPr) {
+    return {
+      action: 'reused',
+      number: existing.number,
+      url: existing.url
+    };
+  }
+
   const bodyFilePath = path.join(process.cwd(), `.tmp-pr-body-${Date.now()}.md`);
   fs.writeFileSync(bodyFilePath, body);
 
@@ -1540,8 +1625,8 @@ function getPrCheckState(repo, prNumber, deps) {
 }
 
 function watchPrChecks(repo, prNumber, timeoutMinutes, deps) {
-  const timeoutAt = Date.now() + timeoutMinutes * 60 * 1000;
-  while (Date.now() <= timeoutAt) {
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
+  while (nowMs(deps) <= timeoutAt) {
     const state = getPrCheckState(repo, prNumber, deps);
     if (state.failed > 0) {
       throw new Error(`PR #${prNumber} has failing required checks.`);
@@ -1551,7 +1636,7 @@ function watchPrChecks(repo, prNumber, timeoutMinutes, deps) {
       return 'green';
     }
 
-    sleepMs(5000);
+    waitForNextPoll(timeoutAt, 5000, deps);
   }
 
   throw new Error(`Timed out waiting for checks on PR #${prNumber} after ${timeoutMinutes} minutes.`);
@@ -1569,6 +1654,237 @@ function mergePrWhenGreen(repo, prNumber, mergeMethod, deps) {
   }
 }
 
+function getPrMergeReadiness(repo, prNumber, deps) {
+  const view = deps.exec('gh', [
+    'pr',
+    'view',
+    String(prNumber),
+    '--repo',
+    repo,
+    '--json',
+    'number,url,reviewDecision,mergeStateStatus,isDraft,headRefName'
+  ]);
+  if (view.status !== 0) {
+    throw new Error(`Failed to inspect merge readiness for PR #${prNumber}: ${view.stderr || view.stdout}`.trim());
+  }
+
+  const parsed = parseJsonSafely(view.stdout || '{}', {});
+  return {
+    number: parsed.number || prNumber,
+    url: parsed.url || '',
+    reviewDecision: String(parsed.reviewDecision || '').toUpperCase(),
+    mergeStateStatus: String(parsed.mergeStateStatus || '').toUpperCase(),
+    isDraft: Boolean(parsed.isDraft),
+    headRefName: String(parsed.headRefName || '')
+  };
+}
+
+function getLatestWorkflowRunForBranch(repo, branch, deps) {
+  if (!branch) {
+    return null;
+  }
+
+  const runs = deps.exec('gh', [
+    'run',
+    'list',
+    '--repo',
+    repo,
+    '--branch',
+    branch,
+    '--json',
+    'databaseId,workflowName,status,conclusion,url',
+    '--limit',
+    '10'
+  ]);
+  if (runs.status !== 0) {
+    return null;
+  }
+
+  const parsed = parseJsonSafely(runs.stdout || '[]', []);
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    return null;
+  }
+
+  return parsed[0];
+}
+
+function waitForPrMergeReadinessOrThrow(repo, prNumber, label, timeoutMinutes, deps, options = {}) {
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
+  let lastReadiness = null;
+  let lastChecks = null;
+  const allowBehindTransient = Boolean(options.allowBehindTransient);
+  let behindObservedAt = 0;
+  while (nowMs(deps) <= timeoutAt) {
+    const mergeState = getPrMergeState(repo, prNumber, deps);
+    if (mergeState.state === 'MERGED' || mergeState.mergedAt) {
+      return {
+        number: prNumber,
+        url: '',
+        reviewDecision: 'APPROVED',
+        mergeStateStatus: 'MERGED',
+        isDraft: false
+      };
+    }
+
+    const readiness = getPrMergeReadiness(repo, prNumber, deps);
+    const checks = getPrCheckState(repo, prNumber, deps);
+    lastReadiness = readiness;
+    lastChecks = checks;
+
+    if (readiness.isDraft) {
+      throw new Error(`${label} is still a draft PR. Mark it ready for review before merge.`);
+    }
+
+    if (readiness.reviewDecision === 'REVIEW_REQUIRED' || readiness.reviewDecision === 'CHANGES_REQUESTED') {
+      throw new Error(
+        [
+          `${label} still requires review approval before merge.`,
+          `reviewDecision: ${readiness.reviewDecision}`,
+          readiness.url ? `PR: ${readiness.url}` : ''
+        ].filter(Boolean).join('\n')
+      );
+    }
+
+    if (checks.failed > 0) {
+      throw new Error(`${label} has failing required checks.`);
+    }
+
+    if (readiness.mergeStateStatus === 'DIRTY') {
+      throw new Error(
+        [
+          `${label} is not mergeable yet due to branch policy/state.`,
+          `mergeStateStatus: ${readiness.mergeStateStatus}`,
+          readiness.url ? `PR: ${readiness.url}` : ''
+        ].filter(Boolean).join('\n')
+      );
+    }
+
+    if (readiness.mergeStateStatus === 'BEHIND') {
+      if (allowBehindTransient) {
+        const workflowRun = getLatestWorkflowRunForBranch(repo, readiness.headRefName, deps);
+        const runStatus = String((workflowRun && workflowRun.status) || '').toLowerCase();
+        const runConclusion = String((workflowRun && workflowRun.conclusion) || '').toLowerCase();
+        const runCompleted = runStatus === 'completed';
+        const runFailed = runCompleted && !['success', 'neutral', 'skipped'].includes(runConclusion);
+        const runInProgress = ['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(runStatus);
+
+        if (runFailed) {
+          throw new Error(
+            [
+              `${label} stayed BEHIND because latest workflow run failed.`,
+              `workflow: ${workflowRun.workflowName || 'unknown'}`,
+              `status/conclusion: ${workflowRun.status || 'n/a'}/${workflowRun.conclusion || 'n/a'}`,
+              workflowRun.url ? `run: ${workflowRun.url}` : '',
+              readiness.url ? `PR: ${readiness.url}` : ''
+            ].filter(Boolean).join('\n')
+          );
+        }
+
+        if (!behindObservedAt) {
+          behindObservedAt = nowMs(deps);
+        }
+
+        // Avoid waiting the full global timeout when there is no active workflow progress.
+        const behindElapsedMs = nowMs(deps) - behindObservedAt;
+        const stagnationWindowMs = 10 * 1000;
+        if (!runInProgress && behindElapsedMs >= stagnationWindowMs) {
+          throw new Error(
+            [
+              `${label} remained BEHIND for more than 10s with no active workflow progress.`,
+              runCompleted ? `latest workflow conclusion: ${runConclusion || 'n/a'}` : 'latest workflow status: unavailable',
+              workflowRun && workflowRun.url ? `run: ${workflowRun.url}` : '',
+              readiness.url ? `PR: ${readiness.url}` : '',
+              'If changeset workflow is still updating, rerun release-cycle in a moment.'
+            ].filter(Boolean).join('\n')
+          );
+        }
+
+        waitForNextPoll(timeoutAt, 5000, deps);
+        continue;
+      }
+      throw new Error(
+        [
+          `${label} is not mergeable yet due to branch policy/state.`,
+          `mergeStateStatus: ${readiness.mergeStateStatus}`,
+          readiness.url ? `PR: ${readiness.url}` : ''
+        ].filter(Boolean).join('\n')
+      );
+    }
+
+    const mergeStateReady = readiness.mergeStateStatus === 'CLEAN'
+      || readiness.mergeStateStatus === 'HAS_HOOKS'
+      || readiness.mergeStateStatus === 'UNSTABLE';
+    const mergeStateUnknown = !readiness.mergeStateStatus || readiness.mergeStateStatus === 'UNKNOWN' || readiness.mergeStateStatus === 'BLOCKED';
+    if ((mergeStateReady && checks.pending === 0) || (mergeStateUnknown && checks.pending === 0 && !readiness.mergeStateStatus)) {
+      return readiness;
+    }
+
+    waitForNextPoll(timeoutAt, 5000, deps);
+  }
+
+  throw new Error(
+    [
+      `${label} did not become merge-ready after ${timeoutMinutes} minutes.`,
+      `mergeStateStatus: ${lastReadiness ? (lastReadiness.mergeStateStatus || 'n/a') : 'n/a'}`,
+      `reviewDecision: ${lastReadiness ? (lastReadiness.reviewDecision || 'n/a') : 'n/a'}`,
+      `pending checks: ${lastChecks ? lastChecks.pending : 'n/a'}`,
+      allowBehindTransient ? 'Hint: release PR can stay BEHIND while changeset workflow updates its branch. Wait for workflow completion and rerun if needed.' : '',
+      lastReadiness && lastReadiness.url ? `PR: ${lastReadiness.url}` : ''
+    ].filter(Boolean).join('\n')
+  );
+}
+
+async function confirmMergeIfNeeded(args, readiness, label) {
+  if (args.confirmMerges && !args.yes) {
+    await confirmOrThrow(
+      [
+        `${label} is ready for merge.`,
+        `reviewDecision: ${readiness.reviewDecision || 'n/a'}`,
+        `mergeStateStatus: ${readiness.mergeStateStatus || 'n/a'}`,
+        'Proceed with merge now?'
+      ].join('\n')
+    );
+  }
+}
+
+function getPrMergeState(repo, prNumber, deps) {
+  const view = deps.exec('gh', [
+    'pr',
+    'view',
+    String(prNumber),
+    '--repo',
+    repo,
+    '--json',
+    'state,mergedAt'
+  ]);
+  if (view.status !== 0) {
+    throw new Error(`Failed to read PR #${prNumber} merge state: ${view.stderr || view.stdout}`.trim());
+  }
+
+  const parsed = parseJsonSafely(view.stdout || '{}', {});
+  return {
+    state: String(parsed.state || '').toUpperCase(),
+    mergedAt: parsed.mergedAt || ''
+  };
+}
+
+function waitForPrMerged(repo, prNumber, timeoutMinutes, deps) {
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
+  while (nowMs(deps) <= timeoutAt) {
+    const state = getPrMergeState(repo, prNumber, deps);
+    if (state.state === 'MERGED' || state.mergedAt) {
+      return true;
+    }
+    if (state.state === 'CLOSED') {
+      throw new Error(`PR #${prNumber} was closed without merge.`);
+    }
+
+    waitForNextPoll(timeoutAt, 5000, deps);
+  }
+
+  throw new Error(`Timed out waiting for PR #${prNumber} merge after ${timeoutMinutes} minutes.`);
+}
+
 function findReleasePrs(repo, deps) {
   const prs = listOpenPullRequests(repo, deps);
   return prs.filter(
@@ -1579,8 +1895,8 @@ function findReleasePrs(repo, deps) {
 }
 
 function waitForReleasePr(repo, timeoutMinutes, deps) {
-  const timeoutAt = Date.now() + timeoutMinutes * 60 * 1000;
-  while (Date.now() <= timeoutAt) {
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
+  while (nowMs(deps) <= timeoutAt) {
     const releasePrs = findReleasePrs(repo, deps);
     if (releasePrs.length === 1) {
       return releasePrs[0];
@@ -1589,7 +1905,7 @@ function waitForReleasePr(repo, timeoutMinutes, deps) {
       throw new Error(`Multiple release PRs detected: ${releasePrs.map((item) => item.url).join(', ')}`);
     }
 
-    sleepMs(5000);
+    waitForNextPoll(timeoutAt, 5000, deps);
   }
 
   throw new Error(`Timed out waiting for release PR after ${timeoutMinutes} minutes.`);
@@ -1640,8 +1956,8 @@ function findPromotionPrs(repo, deps) {
 }
 
 function waitForPromotionPr(repo, timeoutMinutes, deps) {
-  const timeoutAt = Date.now() + timeoutMinutes * 60 * 1000;
-  while (Date.now() <= timeoutAt) {
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
+  while (nowMs(deps) <= timeoutAt) {
     const promotionPrs = findPromotionPrs(repo, deps);
     if (promotionPrs.length === 1) {
       return promotionPrs[0];
@@ -1652,7 +1968,7 @@ function waitForPromotionPr(repo, timeoutMinutes, deps) {
       return promotionPrs[0];
     }
 
-    sleepMs(5000);
+    waitForNextPoll(timeoutAt, 5000, deps);
   }
 
   throw new Error(`Timed out waiting for promotion PR after ${timeoutMinutes} minutes.`);
@@ -1678,11 +1994,11 @@ function getRemotePackageVersion(repo, ref, deps) {
 }
 
 function validateNpmPublishedVersionAndTag(packageName, expectedVersion, expectedTag, timeoutMinutes, deps) {
-  const timeoutAt = Date.now() + timeoutMinutes * 60 * 1000;
+  const timeoutAt = nowMs(deps) + timeoutMinutes * 60 * 1000;
   let lastObservedVersion = '';
   let lastObservedTagVersion = '';
 
-  while (Date.now() <= timeoutAt) {
+  while (nowMs(deps) <= timeoutAt) {
     const versionResult = deps.exec('npm', ['view', packageName, 'version', '--json']);
     const tagsResult = deps.exec('npm', ['view', packageName, 'dist-tags', '--json']);
     if (versionResult.status === 0 && tagsResult.status === 0) {
@@ -1701,7 +2017,7 @@ function validateNpmPublishedVersionAndTag(packageName, expectedVersion, expecte
       }
     }
 
-    sleepMs(10000);
+    waitForNextPoll(timeoutAt, 10000, deps);
   }
 
   return {
@@ -1739,6 +2055,103 @@ function isCleanupCandidateBranch(branchName) {
   return /^(feat|fix|chore|refactor|test)\//.test(branchName);
 }
 
+function syncBranchWithBase({
+  deps,
+  headBranch,
+  baseBranch,
+  strategy,
+  reporter,
+  summary,
+  dryRun
+}) {
+  if (strategy === 'off') {
+    summary.actionsSkipped.push('sync base branch');
+    return {
+      synchronized: false,
+      wasBehind: false
+    };
+  }
+
+  reporter.start('release-cycle-sync-fetch', `Fetching origin/${baseBranch}...`);
+  const fetch = deps.exec('git', ['fetch', 'origin', baseBranch]);
+  if (fetch.status !== 0) {
+    throw new Error(`Failed to fetch origin/${baseBranch}: ${(fetch.stderr || fetch.stdout || '').trim()}`);
+  }
+  reporter.ok('release-cycle-sync-fetch', `Fetched origin/${baseBranch}.`);
+
+  const behindCheck = deps.exec('git', ['rev-list', '--left-right', '--count', `${headBranch}...origin/${baseBranch}`]);
+  if (behindCheck.status !== 0) {
+    throw new Error(`Failed to compare ${headBranch} against origin/${baseBranch}.`);
+  }
+
+  const parts = (behindCheck.stdout || '').trim().split(/\s+/);
+  const behindCount = Number.parseInt(parts[1] || '0', 10);
+  const isBehind = Number.isInteger(behindCount) && behindCount > 0;
+  if (!isBehind) {
+    summary.actionsPerformed.push(`sync base: ${headBranch} already up to date with origin/${baseBranch}`);
+    return {
+      synchronized: true,
+      wasBehind: false
+    };
+  }
+
+  const effectiveStrategy = strategy === 'auto' ? 'rebase' : strategy;
+  if (dryRun) {
+    summary.actionsPerformed.push(`dry-run: would ${effectiveStrategy} ${headBranch} onto origin/${baseBranch}`);
+    return {
+      synchronized: false,
+      wasBehind: true
+    };
+  }
+
+  if (effectiveStrategy === 'rebase') {
+    reporter.start('release-cycle-sync-rebase', `Rebasing ${headBranch} onto origin/${baseBranch}...`);
+    const rebase = deps.exec('git', ['rebase', `origin/${baseBranch}`]);
+    if (rebase.status !== 0) {
+      throw new Error(
+        [
+          `Rebase failed while syncing ${headBranch} with origin/${baseBranch}.`,
+          'Resolve conflicts, then run `git rebase --continue` or `git rebase --abort`.',
+          (rebase.stderr || rebase.stdout || '').trim()
+        ].filter(Boolean).join('\n')
+      );
+    }
+    reporter.ok('release-cycle-sync-rebase', `${headBranch} rebased onto origin/${baseBranch}.`);
+    summary.actionsPerformed.push(`sync base: rebased ${headBranch} onto origin/${baseBranch}`);
+    return {
+      synchronized: true,
+      wasBehind: true
+    };
+  }
+
+  reporter.start('release-cycle-sync-merge', `Merging origin/${baseBranch} into ${headBranch}...`);
+  const merge = deps.exec('git', ['merge', '--no-edit', `origin/${baseBranch}`]);
+  if (merge.status !== 0) {
+    throw new Error(
+      [
+        `Merge failed while syncing ${headBranch} with origin/${baseBranch}.`,
+        'Resolve conflicts and commit merge before rerunning.',
+        (merge.stderr || merge.stdout || '').trim()
+      ].filter(Boolean).join('\n')
+    );
+  }
+  reporter.ok('release-cycle-sync-merge', `Merged origin/${baseBranch} into ${headBranch}.`);
+  summary.actionsPerformed.push(`sync base: merged origin/${baseBranch} into ${headBranch}`);
+  return {
+    synchronized: true,
+    wasBehind: true
+  };
+}
+
+function isHeadIntegratedIntoBase(headRef, baseBranch, deps) {
+  const fetch = deps.exec('git', ['fetch', 'origin', baseBranch]);
+  if (fetch.status !== 0) {
+    return false;
+  }
+  const ancestor = deps.exec('git', ['merge-base', '--is-ancestor', headRef, `origin/${baseBranch}`]);
+  return ancestor.status === 0;
+}
+
 function runLocalCleanup({
   deps,
   originalBranch,
@@ -2406,6 +2819,9 @@ async function runOpenPrFlow(args, dependencies = {}) {
   summary.prAction = `${prResult.action} (#${prResult.number})`;
   summary.prUrl = prResult.url || 'n/a';
   summary.actionsPerformed.push(`pr ${prResult.action}: #${prResult.number}`);
+  if (prResult.action === 'reused') {
+    summary.warnings.push('Existing PR reused without body/title changes. Use --update-pr-description to refresh PR content.');
+  }
 
   if (args.autoMerge) {
     reporter.start('open-pr-auto-merge', `Enabling auto-merge for PR #${prResult.number}...`);
@@ -2452,6 +2868,7 @@ async function runReleaseCycle(args, dependencies = {}) {
   const summary = createOrchestrationSummary();
   const reporter = new StepReporter();
   const originalBranch = deps.exec('git', ['rev-parse', '--abbrev-ref', 'HEAD']).stdout.trim();
+  const useAutoMerge = args.autoMerge;
 
   reporter.start('release-cycle-preflight-gh', 'Validating GitHub CLI and authentication...');
   ensureGhAvailable(deps);
@@ -2459,6 +2876,7 @@ async function runReleaseCycle(args, dependencies = {}) {
 
   const gitContext = resolveGitContext(args, deps);
   summary.repoResolved = gitContext.repo;
+  const effectivePhase = args.phase;
   const requestedTrack = args.track === 'auto' ? (args.promoteStable ? 'stable' : 'beta') : args.track;
   if (args.promoteStable && gitContext.head !== DEFAULT_BETA_BRANCH) {
     throw new Error(`--promote-stable is only allowed when running from "${DEFAULT_BETA_BRANCH}".`);
@@ -2471,7 +2889,6 @@ async function runReleaseCycle(args, dependencies = {}) {
   }
   summary.actionsPerformed.push(`release track: ${requestedTrack}`);
   summary.releaseTrack = requestedTrack;
-
   let detectedMode = args.mode;
   if (args.promoteStable) {
     detectedMode = 'open-pr';
@@ -2479,6 +2896,8 @@ async function runReleaseCycle(args, dependencies = {}) {
     const releasePrs = findReleasePrs(gitContext.repo, deps);
     if (gitContext.head.startsWith('changeset-release/')) {
       detectedMode = 'publish';
+    } else if (gitContext.head !== DEFAULT_BETA_BRANCH) {
+      detectedMode = 'open-pr';
     } else if (releasePrs.length === 1) {
       detectedMode = 'publish';
     } else if (releasePrs.length > 1) {
@@ -2551,40 +2970,95 @@ async function runReleaseCycle(args, dependencies = {}) {
       summary.promotionPr = 'skipped';
     }
 
-    const openPrResult = await runOpenPrFlow(
-      {
-        ...args,
-        head: args.promoteStable ? DEFAULT_BETA_BRANCH : args.head,
-        base: args.promoteStable ? DEFAULT_BASE_BRANCH : args.base,
-        autoMerge: args.autoMerge,
-        watchChecks: args.watchChecks,
-        checkTimeout: args.checkTimeout,
-        mergeMethod: args.mergeMethod,
-        skipPush: args.promoteStable,
-        printSummary: false
-      },
-      dependencies
-    );
-
-    const codePr = openPrResult.pr;
-    summary.prAction = openPrResult.summary.prAction;
-    summary.prUrl = openPrResult.summary.prUrl;
-    summary.branchPushed = openPrResult.summary.branchPushed;
-    summary.autoMerge = openPrResult.summary.autoMerge;
-    summary.checks = openPrResult.summary.checks;
-    summary.actionsPerformed.push(...openPrResult.summary.actionsPerformed);
-    summary.actionsSkipped.push(...openPrResult.summary.actionsSkipped);
-    summary.warnings.push(...openPrResult.summary.warnings);
-
-    if (args.mergeWhenGreen && codePr && !args.dryRun) {
-      reporter.start('release-cycle-merge-code-pr', `Merging code PR #${codePr.number}...`);
-      mergePrWhenGreen(gitContext.repo, codePr.number, args.mergeMethod, deps);
-      reporter.ok('release-cycle-merge-code-pr', `Code PR #${codePr.number} merged.`);
-      summary.merge = `code pr merged (#${codePr.number})`;
-      summary.actionsPerformed.push(`code pr merged: #${codePr.number}`);
+    const canResumeFromMergedCode = args.resume
+      && !args.promoteStable
+      && gitContext.head !== DEFAULT_BETA_BRANCH
+      && !gitContext.head.startsWith('changeset-release/')
+      && isHeadIntegratedIntoBase('HEAD', DEFAULT_BETA_BRANCH, deps);
+
+    let codePr = null;
+    if (canResumeFromMergedCode) {
+      summary.prAction = 'skipped (resume: code already merged)';
+      summary.prUrl = 'n/a';
+      summary.branchPushed = 'skipped (resume)';
+      summary.autoMerge = 'skipped (resume)';
+      summary.checks = 'skipped (resume)';
+      summary.merge = 'skipped (resume: already merged)';
+      summary.actionsPerformed.push(`resume detected: ${gitContext.head} already integrated into ${DEFAULT_BETA_BRANCH}`);
+      summary.actionsSkipped.push('open/update code pr (resume)');
     } else {
-      summary.merge = args.dryRun ? 'dry-run: would merge code PR' : 'skipped';
-      summary.actionsSkipped.push('merge code pr');
+      if (!args.promoteStable && gitContext.head !== DEFAULT_BETA_BRANCH && !gitContext.head.startsWith('changeset-release/')) {
+        syncBranchWithBase({
+          deps,
+          headBranch: gitContext.head,
+          baseBranch: DEFAULT_BETA_BRANCH,
+          strategy: args.syncBase,
+          reporter,
+          summary,
+          dryRun: args.dryRun
+        });
+      }
+
+      const openPrResult = await runOpenPrFlow(
+        {
+          ...args,
+          head: args.promoteStable ? DEFAULT_BETA_BRANCH : args.head,
+          base: args.promoteStable ? DEFAULT_BASE_BRANCH : args.base,
+          autoMerge: useAutoMerge,
+          watchChecks: args.watchChecks,
+          checkTimeout: args.checkTimeout,
+          mergeMethod: args.mergeMethod,
+          updateExistingPr: args.updatePrDescription,
+          skipPush: args.promoteStable,
+          printSummary: false
+        },
+        dependencies
+      );
+
+      codePr = openPrResult.pr;
+      summary.prAction = openPrResult.summary.prAction;
+      summary.prUrl = openPrResult.summary.prUrl;
+      summary.branchPushed = openPrResult.summary.branchPushed;
+      summary.autoMerge = openPrResult.summary.autoMerge;
+      summary.checks = openPrResult.summary.checks;
+      summary.actionsPerformed.push(...openPrResult.summary.actionsPerformed);
+      summary.actionsSkipped.push(...openPrResult.summary.actionsSkipped);
+      summary.warnings.push(...openPrResult.summary.warnings);
+
+      if (args.mergeWhenGreen && codePr && !args.dryRun) {
+        reporter.start('release-cycle-merge-code-ready', `Checking merge readiness for code PR #${codePr.number}...`);
+        const codeReadiness = waitForPrMergeReadinessOrThrow(
+          gitContext.repo,
+          codePr.number,
+          `Code PR #${codePr.number}`,
+          args.checkTimeout,
+          deps
+        );
+        await confirmMergeIfNeeded(args, codeReadiness, `Code PR #${codePr.number}`);
+        reporter.ok('release-cycle-merge-code-ready', `Code PR #${codePr.number} is ready for merge.`);
+        reporter.start('release-cycle-code-auto-merge', `Enabling auto-merge for code PR #${codePr.number}...`);
+        enablePrAutoMerge(gitContext.repo, codePr.number, args.mergeMethod, deps);
+        reporter.ok('release-cycle-code-auto-merge', `Auto-merge enabled for code PR #${codePr.number}.`);
+        reporter.start('release-cycle-wait-code-merge', `Waiting for code PR #${codePr.number} merge...`);
+        waitForPrMerged(gitContext.repo, codePr.number, args.releasePrTimeout, deps);
+        reporter.ok('release-cycle-wait-code-merge', `Code PR #${codePr.number} merged.`);
+        summary.actionsPerformed.push(`code pr merged: #${codePr.number}`);
+        summary.merge = `code pr merged (#${codePr.number})`;
+      } else {
+        summary.merge = args.dryRun ? 'dry-run: would merge code PR' : 'skipped';
+        summary.actionsSkipped.push('merge code pr');
+      }
+    }
+
+    if (effectivePhase === 'code') {
+      summary.releasePr = 'skipped (phase=code)';
+      summary.npmValidation = 'skipped (phase=code)';
+      summary.cleanup = 'skipped (phase=code; requires npm validation)';
+      summary.actionsSkipped.push('wait release pr (phase=code)');
+      summary.actionsSkipped.push('verify npm (phase=code)');
+      summary.actionsSkipped.push('cleanup (phase=code)');
+      printOrchestrationSummary(`release-cycle completed in ${detectedMode} mode`, summary);
+      return;
     }
 
     let mergedReleasePr = null;
@@ -2605,11 +3079,26 @@ async function runReleaseCycle(args, dependencies = {}) {
         }
 
         if (args.mergeReleasePr) {
-          reporter.start('release-cycle-merge-release-pr', `Merging release PR #${releasePr.number}...`);
-          mergePrWhenGreen(gitContext.repo, releasePr.number, args.mergeMethod, deps);
-          reporter.ok('release-cycle-merge-release-pr', `Release PR #${releasePr.number} merged.`);
+          reporter.start('release-cycle-merge-release-ready', `Checking merge readiness for release PR #${releasePr.number}...`);
+          const releaseReadiness = waitForPrMergeReadinessOrThrow(
+            gitContext.repo,
+            releasePr.number,
+            `Release PR #${releasePr.number}`,
+            args.checkTimeout,
+            deps,
+            { allowBehindTransient: true }
+          );
+          await confirmMergeIfNeeded(args, releaseReadiness, `Release PR #${releasePr.number}`);
+          reporter.ok('release-cycle-merge-release-ready', `Release PR #${releasePr.number} is ready for merge.`);
+          reporter.start('release-cycle-release-auto-merge', `Enabling auto-merge for release PR #${releasePr.number}...`);
+          enablePrAutoMerge(gitContext.repo, releasePr.number, args.mergeMethod, deps);
+          reporter.ok('release-cycle-release-auto-merge', `Auto-merge enabled for release PR #${releasePr.number}.`);
+          reporter.start('release-cycle-release-wait-merge', `Waiting for release PR #${releasePr.number} merge...`);
+          waitForPrMerged(gitContext.repo, releasePr.number, args.releasePrTimeout, deps);
+          reporter.ok('release-cycle-release-wait-merge', `Release PR #${releasePr.number} merged.`);
           summary.releasePr = `merged (#${releasePr.number})`;
           summary.actionsPerformed.push(`release pr merged: #${releasePr.number}`);
+          summary.autoMerge = 'enabled (code + release)';
           mergedReleasePr = releasePr;
         } else {
           summary.actionsSkipped.push('merge release pr');
@@ -2620,6 +3109,7 @@ async function runReleaseCycle(args, dependencies = {}) {
       summary.actionsSkipped.push('wait release pr');
     }
 
+    let npmValidationPassed = false;
     if (args.verifyNpm && !args.dryRun && mergedReleasePr) {
       reporter.start('release-cycle-verify-npm', 'Validating npm publish and dist-tag...');
       const targetRef = args.promoteStable ? DEFAULT_BASE_BRANCH : DEFAULT_BETA_BRANCH;
@@ -2646,6 +3136,7 @@ async function runReleaseCycle(args, dependencies = {}) {
       reporter.ok('release-cycle-verify-npm', `${remotePackage.name}@${remotePackage.version} validated on tag ${expectedTag}.`);
       summary.actionsPerformed.push(`npm validation: ${remotePackage.name}@${remotePackage.version} (${expectedTag})`);
       summary.npmValidation = `pass (${expectedTag} -> ${remotePackage.version})`;
+      npmValidationPassed = true;
     } else if (!args.verifyNpm) {
       summary.actionsSkipped.push('verify npm');
       summary.npmValidation = 'skipped';
@@ -2655,7 +3146,10 @@ async function runReleaseCycle(args, dependencies = {}) {
       summary.npmValidation = 'skipped (release pr not merged)';
     }
 
-    if (!args.dryRun) {
+    if (!args.dryRun && npmValidationPassed) {
+      if (args.confirmCleanup && !args.yes) {
+        await confirmOrThrow('Release completed and npm validation passed.\nProceed with local cleanup now?');
+      }
       runLocalCleanup({
         deps,
         originalBranch,
@@ -2664,6 +3158,9 @@ async function runReleaseCycle(args, dependencies = {}) {
         summary,
         reporter
       });
+    } else if (!args.dryRun && !npmValidationPassed) {
+      summary.actionsSkipped.push('cleanup (npm validation did not pass)');
+      summary.cleanup = 'skipped (requires npm validation pass)';
     } else {
       summary.actionsSkipped.push('cleanup (dry-run)');
       summary.cleanup = 'skipped (dry-run)';
@@ -2711,11 +3208,26 @@ async function runReleaseCycle(args, dependencies = {}) {
       summary.merge = `dry-run: would merge release PR #${releasePr.number}`;
       summary.releasePr = `dry-run: would merge (#${releasePr.number})`;
     } else {
-      reporter.start('release-cycle-publish-merge', `Merging release PR #${releasePr.number}...`);
-      mergePrWhenGreen(gitContext.repo, releasePr.number, args.mergeMethod, deps);
-      reporter.ok('release-cycle-publish-merge', `Release PR #${releasePr.number} merged.`);
+      reporter.start('release-cycle-publish-merge-ready', `Checking merge readiness for release PR #${releasePr.number}...`);
+      const publishReadiness = waitForPrMergeReadinessOrThrow(
+        gitContext.repo,
+        releasePr.number,
+        `Release PR #${releasePr.number}`,
+        args.checkTimeout,
+        deps,
+        { allowBehindTransient: true }
+      );
+      await confirmMergeIfNeeded(args, publishReadiness, `Release PR #${releasePr.number}`);
+      reporter.ok('release-cycle-publish-merge-ready', `Release PR #${releasePr.number} is ready for merge.`);
+      reporter.start('release-cycle-publish-auto-merge', `Enabling auto-merge for release PR #${releasePr.number}...`);
+      enablePrAutoMerge(gitContext.repo, releasePr.number, args.mergeMethod, deps);
+      reporter.ok('release-cycle-publish-auto-merge', `Auto-merge enabled for release PR #${releasePr.number}.`);
+      reporter.start('release-cycle-publish-wait-merge', `Waiting for release PR #${releasePr.number} merge...`);
+      waitForPrMerged(gitContext.repo, releasePr.number, args.releasePrTimeout, deps);
+      reporter.ok('release-cycle-publish-wait-merge', `Release PR #${releasePr.number} merged.`);
       summary.merge = `merged release pr (#${releasePr.number})`;
       summary.releasePr = `merged (#${releasePr.number})`;
+      summary.autoMerge = 'enabled (release)';
       summary.actionsPerformed.push(`release pr merged: #${releasePr.number}`);
     }
   } else {
@@ -2724,6 +3236,7 @@ async function runReleaseCycle(args, dependencies = {}) {
     summary.actionsSkipped.push('merge release pr');
   }
 
+  let npmValidationPassed = false;
   if (args.verifyNpm && !args.dryRun && (args.mergeReleasePr || args.mergeWhenGreen)) {
     reporter.start('release-cycle-verify-npm', 'Validating npm publish and dist-tag...');
     const targetRef = requestedTrack === 'stable' ? DEFAULT_BASE_BRANCH : DEFAULT_BETA_BRANCH;
@@ -2750,6 +3263,7 @@ async function runReleaseCycle(args, dependencies = {}) {
     reporter.ok('release-cycle-verify-npm', `${remotePackage.name}@${remotePackage.version} validated on tag ${expectedTag}.`);
     summary.actionsPerformed.push(`npm validation: ${remotePackage.name}@${remotePackage.version} (${expectedTag})`);
     summary.npmValidation = `pass (${expectedTag} -> ${remotePackage.version})`;
+    npmValidationPassed = true;
   } else if (!args.verifyNpm) {
     summary.npmValidation = 'skipped';
   } else if (args.dryRun) {
@@ -2758,7 +3272,10 @@ async function runReleaseCycle(args, dependencies = {}) {
     summary.npmValidation = 'skipped (release pr not merged)';
   }
 
-  if (!args.dryRun) {
+  if (!args.dryRun && npmValidationPassed) {
+    if (args.confirmCleanup && !args.yes) {
+      await confirmOrThrow('Release completed and npm validation passed.\nProceed with local cleanup now?');
+    }
     runLocalCleanup({
       deps,
       originalBranch,
@@ -2767,6 +3284,9 @@ async function runReleaseCycle(args, dependencies = {}) {
       summary,
       reporter
     });
+  } else if (!args.dryRun && !npmValidationPassed) {
+    summary.actionsSkipped.push('cleanup (npm validation did not pass)');
+    summary.cleanup = 'skipped (requires npm validation pass)';
   } else {
     summary.cleanup = 'skipped (dry-run)';
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i-santos/create-package-starter",
-  "version": "1.5.0-beta.8",
+  "version": "1.5.0-beta.9",
   "description": "Scaffold new npm packages with a standardized Changesets release workflow",
   "license": "MIT",
   "author": "Igor Santos",