update_cmd_check.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327
  1. """Steps of ``hermes update --check``: debris cleanup, channel target, scoped fetch, verdict.
  2. ``update_cmd._cmd_update_check`` (a frozen updater surface, see ``tests/compat``) orchestrates
  3. these. Facade helpers are read through ``_uc()`` at call time and origin helpers are imported
  4. per function, so test patches on ``hermes_cli.update_cmd`` and the origin modules stay effective.
  5. """
  6. from __future__ import annotations
  7. import logging
  8. import subprocess
  9. import sys
  10. from pathlib import Path
  11. from typing import Any
  12. logger = logging.getLogger(__name__)
  13. def _git(git_cmd: list[str], root: Path, args: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]:
  14. from hermes_cli._subprocess_compat import windows_hide_flags
  15. # Callers pass **_no_prompt_git_kwargs() which already carries creationflags;
  16. # OR the hide flag into the shared kwargs instead of passing the keyword twice.
  17. kwargs["creationflags"] = kwargs.get("creationflags", 0) | windows_hide_flags()
  18. from hermes_cli.update_custody import run_git
  19. return run_git(
  20. git_cmd, args, cwd=root, capture_output=True, text=True, encoding="utf-8", errors="replace",
  21. **kwargs,
  22. )
  23. def _uc():
  24. from hermes_cli import update_cmd
  25. return update_cmd
  26. def clear_git_debris(root: Path) -> None:
  27. """Remove abandoned git locks and aborted-fetch pack temps before fetching.
  28. A crashed fetch can leave ``.git/shallow.lock`` (or another lock) behind, and every later
  29. fetch then fails with "File exists". Aborted fetches on flaky lines also strand
  30. ``tmp_pack_*`` debris: unchecked it reached 6 GB and corrupted the pack dir (#93732).
  31. A partial clone also gets its commit-graph-off keys re-applied (#127711).
  32. """
  33. from hermes_cli.gitlock import clear_stale_git_locks, clear_stale_tmp_packs, settle_partial_clone_maintenance
  34. for lock_path in clear_stale_git_locks(root):
  35. print(f" (removed stale git lock: {lock_path})")
  36. swept = clear_stale_tmp_packs(root)
  37. if swept:
  38. print(f" (removed {len(swept)} aborted-fetch pack temp file(s))")
  39. settle_partial_clone_maintenance(root)
  40. def report_pack_tidy(root: Path) -> None:
  41. """Spend the update's bounded slice on a partial clone's on-demand packs, and say what it did."""
  42. from hermes_cli.git_pack_tidy import TIDY_BUDGET_SECONDS, tidy_partial_clone_packs
  43. tidy = tidy_partial_clone_packs(root)
  44. if tidy.erased or tidy.merged:
  45. print(f" (git cleanup: erased {tidy.erased} duplicate pack(s), {tidy.freed_bytes / 1e6:.0f} MB freed;"
  46. f" merged {tidy.merged}; {tidy.packs_left} left)")
  47. if tidy.out_of_time:
  48. print(f" (git cleanup stopped at its {TIDY_BUDGET_SECONDS}s limit; the next update continues it)")
  49. def _refuses(git_cmd: list[str], root: Path, target: str, repository: str) -> bool:
  50. """`hermes update` would refuse ``target`` (see update_downgrade_guard), so --check must not offer it."""
  51. from hermes_cli.update_downgrade_guard import would_refuse
  52. from hermes_cli._subprocess_compat import NO_LAZY_FETCH_ENV, noninteractive_git_env
  53. from hermes_cli.source_check import _github_predates_runtime
  54. from hermes_constants import get_hermes_home
  55. def git(*args: str) -> int:
  56. try:
  57. return _git(git_cmd, root, list(args), env={**noninteractive_git_env(), **NO_LAZY_FETCH_ENV},
  58. timeout=20).returncode
  59. except (OSError, subprocess.SubprocessError):
  60. return -1
  61. def remote(sha: str):
  62. return _github_predates_runtime(repository, sha, get_hermes_home() / "source-checks" / "release-runtime.json")
  63. return would_refuse(root, target, git=git, remote=remote)
  64. def channel_compare_branch(selected_channel: str, git_cmd: list[str], root: Path) -> str | None:
  65. """Report a release-pinned channel's verdict, or return the branch to compare against.
  66. ``None`` means the verdict is printed (the channel pins a commit); exits 1 when the channel
  67. cannot be resolved. An install riding its default channel only ever moves forward.
  68. """
  69. from hermes_cli.config import get_config_path, require_readable_config_before_write
  70. from hermes_cli.source_releases import resolve_source_target
  71. from hermes_cli.update_channel import channel_record, rides_default_channel
  72. print(f"→ Update channel: {selected_channel}")
  73. record = channel_record(require_readable_config_before_write(get_config_path()), root)
  74. forward_only = rides_default_channel(record, selected_channel, root)
  75. try:
  76. target = resolve_source_target(selected_channel, git_cmd, root, forward_only=forward_only)
  77. except (OSError, ValueError, subprocess.SubprocessError) as exc:
  78. print(f"✗ Could not resolve the {selected_channel} source channel: {exc}")
  79. sys.exit(1)
  80. if not target.commit:
  81. return target.branch
  82. if target.retired:
  83. print(f"→ {selected_channel} retired; source destination: {target.channel}")
  84. if target.ahead:
  85. print(f"✓ No newer release: {target.label}.")
  86. elif _uc()._capture_head_sha(git_cmd, root) == target.commit:
  87. print(f"✓ Up to date with the latest release ({target.label}).")
  88. elif _refuses(git_cmd, root, target.commit, target.repository):
  89. # Before the rollback branch: a release this checkout contains is held too, not moved back to.
  90. print(f"→ Holding at this build: {target.label} predates the gateway runtime your sessions use.")
  91. print(" `hermes update` stays on this build; the next release that includes the runtime"
  92. " installs normally (`hermes update --set-channel main` follows every commit).")
  93. elif _git(git_cmd, root, ["merge-base", "--is-ancestor", target.commit, "HEAD"]).returncode == 0:
  94. print(f"→ This checkout is newer than the selected release: {target.label}.")
  95. print(" `hermes update` moves it back to that release"
  96. " (`hermes update --set-channel main` follows every commit).")
  97. else:
  98. print(f"→ Selected release available: {target.label}")
  99. print(" Run `hermes update` to install it.")
  100. return None
  101. def is_shallow_repository(git_cmd: list[str], root: Path) -> bool:
  102. return _git(git_cmd, root, ["rev-parse", "--is-shallow-repository"]).stdout.strip() == "true"
  103. def tracking_refspec(remote: str, branch: str) -> str:
  104. """Refspec that always writes ``<remote>/<branch>``, whatever ``remote.<remote>.fetch`` says.
  105. Narrow clones (tag-pinned ``--single-branch``, #125112) map only the tag, so a by-name fetch
  106. writes FETCH_HEAD and never the tracking ref the updater resolves. The ``+`` is load-bearing:
  107. on a depth-1 clone the new tip is not a descendant of the old one.
  108. """
  109. return f"+refs/heads/{branch}:refs/remotes/{remote}/{branch}"
  110. def _fetch(git_cmd: list[str], root: Path, depth_args: list[str], remote: str, branch: str):
  111. print(f"→ Fetching from {remote}...")
  112. return _git(
  113. git_cmd, root, ["fetch", *depth_args, remote, tracking_refspec(remote, branch)],
  114. **_uc()._no_prompt_git_kwargs())
  115. def fetch_compare_branch(git_cmd: list[str], root: Path, branch: str, depth_args: list[str]):
  116. """Fetch only ``branch`` and return ``(fetch_result, compare_ref)``.
  117. A bare ``git fetch <remote>`` pulls every ref, and this repo has thousands of auto-generated
  118. branches. ``main`` prefers upstream as the canonical reference; other branches go straight
  119. to origin, because a fork's branch usually has no upstream counterpart.
  120. """
  121. if branch == "main":
  122. # A local probe (~6 ms) spares non-fork installs a failed network fetch (~0.3-1 s).
  123. if _git(git_cmd, root, ["remote", "get-url", "upstream"]).returncode == 0:
  124. fetch_result = _fetch(git_cmd, root, depth_args, "upstream", branch)
  125. if fetch_result.returncode == 0:
  126. return fetch_result, f"upstream/{branch}"
  127. from hermes_cli.gitlock import fetch_with_partial_clone_recovery
  128. # Marking the unmarked packs clears the git 2.53+ partial-clone pack-objects crash (#124272).
  129. print("→ Fetching from origin...")
  130. return fetch_with_partial_clone_recovery(
  131. lambda gc, a: _git(gc, root, a, **_uc()._no_prompt_git_kwargs()),
  132. git_cmd, ["fetch", *depth_args, "origin", tracking_refspec("origin", branch)], root), f"origin/{branch}"
  133. def repair_shallow_grafts(root: Path) -> None:
  134. """Drop the stale ``.git/shallow`` grafts a depth-1 fetch leaves behind.
  135. Git never removes old grafts; unpruned, the file keeps growing and merge-base / the
  136. orphan-divergence heuristic stop working (#105951).
  137. """
  138. from hermes_cli.gitlock import prune_stale_shallow_grafts, repair_broken_shallow_boundaries
  139. repaired = repair_broken_shallow_boundaries(root)
  140. if repaired:
  141. print(f" (restored {repaired} broken shallow boundary(ies))")
  142. pruned = prune_stale_shallow_grafts(root)
  143. if pruned:
  144. print(f" (pruned {pruned} stale shallow graft(s) left by past depth-1 checks)")
  145. def compare_ref_exists(git_cmd: list[str], root: Path, compare_branch: str) -> bool:
  146. # rev-list on a missing ref exits 128 and would surface a traceback; report it instead.
  147. return _git(git_cmd, root, ["rev-parse", "--verify", "--quiet", compare_branch]).returncode == 0
  148. def report_shallow_verdict(git_cmd: list[str], root: Path, compare_branch: str) -> None:
  149. """Report behind-ness without local history across the shallow boundary.
  150. Compares tip SHAs (mirrors the banner's ``_check_via_local_git``), then asks the GitHub
  151. compare API for the exact count: the remote graph is complete even when the local one is not.
  152. """
  153. head_sha = _git(git_cmd, root, ["rev-parse", "HEAD"]).stdout.strip()
  154. target_sha = _git(git_cmd, root, ["rev-parse", compare_branch]).stdout.strip()
  155. if head_sha and target_sha and head_sha == target_sha:
  156. print("✓ Already up to date.")
  157. return
  158. from hermes_cli.config import recommended_update_command
  159. from hermes_cli.source_check import _github_compare_behind
  160. counted = _github_compare_behind(head_sha, target_sha)
  161. if counted == 0:
  162. # Local commits on top of the remote tip — not behind.
  163. print("✓ Already up to date.")
  164. return
  165. if counted is not None:
  166. commits_word = "commit" if counted == 1 else "commits"
  167. print(f"⚕ Update available: {counted} {commits_word} behind {compare_branch}.")
  168. else:
  169. print(f"⚕ Update available (behind {compare_branch}).")
  170. print(f" Run '{recommended_update_command()}' to install.")
  171. def report_rev_list_verdict(git_cmd: list[str], root: Path, compare_branch: str) -> None:
  172. rev_result = _git(git_cmd, root, ["rev-list", f"HEAD..{compare_branch}", "--count"], check=True)
  173. behind = int(rev_result.stdout.strip())
  174. if behind == 0:
  175. print("✓ Already up to date.")
  176. return
  177. commits_word = "commit" if behind == 1 else "commits"
  178. print(f"⚕ Update available: {behind} {commits_word} behind {compare_branch}.")
  179. from hermes_cli.config import recommended_update_command
  180. print(f" Run '{recommended_update_command()}' to install.")
  181. def select_apply_target(args, branch: str, request: dict, *, git_cmd, stop) -> tuple:
  182. """Resolve the update's target before any tree write: ``(target_ref, release_sha,
  183. target_is_head, repository)``; records branch/expected_sha/retirement on ``request``.
  184. ``target_is_head`` means an unchosen default subscription is already past the release,
  185. so HEAD itself is the target. Exits 1 (after ``stop()``) when the channel is unresolvable.
  186. """
  187. from copy import deepcopy
  188. from hermes_cli.config import require_readable_config_before_write
  189. from hermes_cli.release_channels import retrying_reads
  190. from hermes_cli.source_releases import resolve_source_target
  191. from hermes_cli.update_channel import channel_record, rides_default_channel
  192. from hermes_cli.update_cmd_common import _record_stop
  193. if getattr(args, "branch", None):
  194. return f"origin/{branch}", None, False, None
  195. root = _uc()._m().PROJECT_ROOT
  196. selected = _uc()._update_run_channel(args)
  197. original = deepcopy(channel_record(require_readable_config_before_write(
  198. Path(request["home"]) / "config.yaml"), root))
  199. print(f"→ Update channel: {selected}")
  200. try:
  201. with retrying_reads():
  202. target = resolve_source_target(selected, git_cmd, root,
  203. forward_only=rides_default_channel(original, selected, root))
  204. except (OSError, ValueError, subprocess.SubprocessError) as exc:
  205. print(f"✗ Could not resolve the {selected} source channel: {exc}. No update was applied.")
  206. stop()
  207. _record_stop("channel_unresolved")
  208. sys.exit(1)
  209. if target.retired:
  210. print(f"→ {selected} retired; source destination: {target.channel}")
  211. if not getattr(args, "channel", None) and original.get("channel", "main") == selected:
  212. request["channel_retirement"] = {"original": original, "destination": target.channel}
  213. if target.commit:
  214. print(f"→ {'Release' if target.ahead else 'Latest release'}: {target.label}")
  215. request["expected_sha"] = target.commit
  216. if target.channel == "stable" and target.version and not target.ahead:
  217. request["release_tag"] = f"v{target.version}" # verified on origin by the resolver
  218. return target.commit, target.commit, target.ahead, target.repository
  219. assert target.branch is not None # a SourceTarget without a commit names its branch
  220. request["branch"] = target.branch
  221. return f"origin/{target.branch}", None, False, target.repository
  222. def fetch_release_tag(git_cmd: list[str], root: Path, request: dict) -> None:
  223. """Fetch a pinned release's own tag when this checkout lacks it.
  224. The checkout's version is the newest release tag merged into HEAD (version_info), so a
  225. tagless release fetch moved HEAD to vX.Y.Z while every reader -- /health, the install
  226. stamp, the receipt, About -- still named the previous release (#143656). Best effort and
  227. create-only: a fork or mirror without the tag still updates, and an existing local tag
  228. never moves (the stable pin contract). Only that one tag: others drag in their histories.
  229. """
  230. from hermes_cli._subprocess_compat import no_prompt_git_kwargs
  231. from hermes_cli.update_cmd import NETWORK_GIT_TIMEOUT_SECONDS
  232. tag = request.get("release_tag")
  233. if not tag:
  234. return
  235. try:
  236. if _git(git_cmd, root, ["rev-parse", "--verify", "--quiet", f"refs/tags/{tag}"]).returncode == 0:
  237. return
  238. fetched = _git(git_cmd, root, ["fetch", "--no-tags", "origin", f"refs/tags/{tag}:refs/tags/{tag}"],
  239. timeout=NETWORK_GIT_TIMEOUT_SECONDS, **no_prompt_git_kwargs())
  240. detail = (fetched.stderr or "").strip().splitlines()[-1:] if fetched.returncode else None
  241. except (OSError, subprocess.SubprocessError) as exc: # custody refusals are OSErrors too
  242. detail = [str(exc)]
  243. if detail is not None:
  244. # Not fatal (a mirror may lack the tag), but say so: without it every version reader keeps
  245. # naming the previous release, the symptom this fetch exists to prevent.
  246. reason = detail[0] if detail else "git fetch failed"
  247. logger.warning("Could not fetch release tag %s: %s", tag, reason)
  248. print(f"⚠ Could not fetch the {tag} tag ({reason}); the version shown may name the previous "
  249. "release until the next update fetches it.")
  250. def hold_channel_release_behind_runtime(git_cmd, target_ref: str, channel: str) -> str | None:
  251. """HEAD's sha when the channel's release predates the gateway runtime these stores use, else None.
  252. The channel picked the release, the user did not ask for that commit: moving there is the
  253. refused downgrade, so the update stays where it is and says why (#140729). An explicit
  254. ``--branch`` never reaches here and keeps the refusal in ``update_cmd._refuse_before_commit_point``.
  255. """
  256. from hermes_cli.update_downgrade_guard import downgrade_refusal
  257. if downgrade_refusal(git_cmd, _uc()._m().PROJECT_ROOT, target_ref) is None:
  258. return None
  259. head = _uc()._capture_head_sha(git_cmd, _uc()._m().PROJECT_ROOT)
  260. if not head:
  261. return None # HEAD unreadable: the caller's refusal still stops the move
  262. # "newer", not "ahead": the release may sit beside HEAD's line rather than behind it (#140729).
  263. print(f"→ This build is newer than the {channel} release {target_ref[:12]}: that release predates the "
  264. "gateway runtime your sessions use, so there is nothing to update to yet.")
  265. print(f" Hermes stays on {head[:12]} until a newer {channel} release ships. "
  266. "To follow every commit instead: `hermes update --set-channel main`.")
  267. return head