feat(updater): add cooldown option to delay applying updates (#13814)

* feat(updater): add cooldown option to delay applying updates (#13813)

Introduces a new `zstyle ':omz:update' cooldown <days>` setting that limits
the updater to only apply commits that are at least N days old. Defaults to 0
(current behavior — always pull latest).

When cooldown is set, the updater fetches the remote branch and finds the most
recent commit whose committer timestamp is at least N days old, then applies it
via `git merge --ff-only`. If the local copy is already at or past the cooldown
ref, nothing changes.

- tools/upgrade.sh: reads cooldown zstyle, replaces git pull with fetch +
  merge --ff-only when cooldown > 0
- README.md: documents the new setting under "Getting Updates"
- templates/zshrc.zsh-template: adds commented-out cooldown example alongside
  frequency, with rephrased comments to clarify how the two work together

* fix(updater): address cooldown review feedback

Pass cooldown into upgrade.sh as -c, extract the update helpers, and only
prompt when a cooldown-eligible commit would actually move HEAD.

* fix(updater): follow first-parent history for cooldown

tools/check_for_upgrade.sh

@@ -67,6 +67,26 @@ function is_update_available() {
   remote=${"$(builtin cd -q "$ZSH"; git config --local oh-my-zsh.remote)":-origin}
   remote_url=$(builtin cd -q "$ZSH"; git config remote.$remote.url)
 
+  local cooldown_days
+  zstyle -s ':omz:update' cooldown cooldown_days || cooldown_days=0
+  [[ $cooldown_days == <-> ]] || cooldown_days=0
+
+  if (( cooldown_days > 0 )); then
+    local local_head cutoff_epoch cooldown_ref
+    local_head=$(builtin cd -q "$ZSH"; git rev-parse $branch 2>/dev/null) || return 0
+    (builtin cd -q "$ZSH"; LANG= git fetch --quiet $remote $branch) || return 1
+    zmodload zsh/datetime
+    cutoff_epoch=$(( EPOCHSECONDS - cooldown_days * 86400 ))
+    cooldown_ref=$(builtin cd -q "$ZSH"; git log --first-parent --format="%H %ct" FETCH_HEAD \
+      | awk -v c="$cutoff_epoch" '$2 <= c { print $1; exit }')
+    [[ -n "$cooldown_ref" ]] || return 1
+    [[ "$cooldown_ref" != "$local_head" ]] || return 1
+    if (builtin cd -q "$ZSH"; git merge-base --is-ancestor "$cooldown_ref" "$local_head" 2>/dev/null); then
+      return 1
+    fi
+    return 0
+  fi
+
   local repo
   case "$remote_url" in
   https://github.com/*) repo=${${remote_url#https://github.com/}%.git} ;;
@@ -129,8 +149,10 @@ EOD
 }
 
 function update_ohmyzsh() {
-  local verbose_mode
+  local verbose_mode cooldown_days
   zstyle -s ':omz:update' verbose verbose_mode || verbose_mode=default
+  zstyle -s ':omz:update' cooldown cooldown_days || cooldown_days=0
+  [[ $cooldown_days == <-> ]] || cooldown_days=0
 
   # Force verbose mode to silent if p10k instant prompt is enabled
   if [[ ${POWERLEVEL9K_INSTANT_PROMPT:-off} != "off" ]]; then
@@ -138,13 +160,13 @@ function update_ohmyzsh() {
   fi
 
   if [[ "$update_mode" != background-alpha ]] \
-    && LANG= ZSH="$ZSH" zsh -f "$ZSH/tools/upgrade.sh" -i -v $verbose_mode; then
+    && LANG= ZSH="$ZSH" zsh -f "$ZSH/tools/upgrade.sh" -i -v $verbose_mode -c $cooldown_days; then
     update_last_updated_file
     return $?
   fi
 
   local exit_status error
-  if error=$(LANG= ZSH="$ZSH" zsh -f "$ZSH/tools/upgrade.sh" -i -v silent 2>&1); then
+  if error=$(LANG= ZSH="$ZSH" zsh -f "$ZSH/tools/upgrade.sh" -i -v silent -c $cooldown_days 2>&1); then
     update_last_updated_file 0 "Update successful"
   else
     exit_status=$?