main_install_repair.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354
  1. """Update dependency diagnostics, historical markers and Windows launcher recovery."""
  2. import logging
  3. import os
  4. import shutil
  5. import sys
  6. import time as _time
  7. from pathlib import Path
  8. from typing import NoReturn
  9. from hermes_cli import _early_recovery as _early_recovery_mod
  10. # Log-record parity with the origin module.
  11. logger = logging.getLogger("hermes_cli.main")
  12. def _pyproject_project(debug_fmt: str | None = None) -> dict | None:
  13. """``[project]`` table of pyproject.toml, or ``None`` when absent/unreadable."""
  14. from hermes_cli.main import PROJECT_ROOT
  15. pyproject = PROJECT_ROOT / "pyproject.toml"
  16. if not pyproject.is_file():
  17. return None
  18. try:
  19. import tomllib
  20. with pyproject.open("rb") as handle:
  21. project = tomllib.load(handle).get("project", {})
  22. except Exception as exc:
  23. if debug_fmt:
  24. logger.debug(debug_fmt, exc)
  25. return None
  26. return project if isinstance(project, dict) else None
  27. # Install-scoped breadcrumbs live next to the venv (not under $HERMES_HOME)
  28. # because the venv is shared across profiles.
  29. # ``.update-incomplete`` — generic core ``.[all]`` install was interrupted;
  30. # cleared only after a confirmed full dependency reinstall/recovery.
  31. # ``.lazy-refresh-incomplete`` — lazy-backend refresh may have corrupted packages;
  32. # cleared only after import-probe repair confirms healthy (never on indeterminate).
  33. # Narrow lazy probes must NEVER clear the generic core marker.
  34. # See #58004.
  35. def _update_marker_path() -> Path:
  36. from hermes_cli.main import PROJECT_ROOT
  37. return PROJECT_ROOT / ".update-incomplete"
  38. def _lazy_refresh_marker_path() -> Path:
  39. from hermes_cli.main import PROJECT_ROOT
  40. return PROJECT_ROOT / ".lazy-refresh-incomplete"
  41. def _pytest_owns_live_checkout(root: Path) -> bool:
  42. """True under pytest when ``root`` is this checkout: unsandboxed update/recovery tests must
  43. neither litter the live repo root with breadcrumbs (false-arming the developer's next launch)
  44. nor run a real reinstall against the executing venv (cf. ``managed_scope._under_pytest``)."""
  45. return "PYTEST_CURRENT_TEST" in os.environ and root == Path(__file__).resolve().parent.parent
  46. def _clear_marker_file(path: Path, *, label: str) -> None:
  47. """Remove an update-recovery breadcrumb. Never raises."""
  48. try:
  49. path.unlink()
  50. except FileNotFoundError:
  51. pass
  52. except OSError as exc:
  53. logger.debug("Could not clear %s marker: %s", label, exc)
  54. def _clear_update_incomplete_marker() -> None:
  55. """Remove the interrupted core-install breadcrumb. Never raises."""
  56. _clear_marker_file(_update_marker_path(), label="update-incomplete")
  57. def _clear_lazy_refresh_incomplete_marker() -> None:
  58. """Remove the interrupted lazy-refresh breadcrumb. Never raises."""
  59. _clear_marker_file(_lazy_refresh_marker_path(), label="lazy-refresh-incomplete")
  60. # Frozen old-updater import; current updates never detach dependency work.
  61. _UPDATE_REEXEC_ENV = "HERMES_UPDATE_REEXEC"
  62. def _reexec_dependency_sync_off_windows_shim() -> NoReturn:
  63. """Stop a mixed old-code/new-files updater at the retired sync boundary."""
  64. from hermes_cli._old_updater import stop_for_relaunch
  65. stop_for_relaunch()
  66. def _is_windows() -> bool:
  67. return sys.platform == "win32"
  68. def _venv_scripts_dir() -> Path | None:
  69. """Return the venv Scripts directory if we're running inside the project venv."""
  70. from hermes_cli.main import PROJECT_ROOT
  71. from hermes_constants import project_venv_dir
  72. from pm.environments import venv_bin_dir
  73. venv_dir = project_venv_dir(PROJECT_ROOT)
  74. if venv_dir is None:
  75. return None
  76. scripts = venv_bin_dir(venv_dir, windows=_is_windows())
  77. return scripts if scripts.is_dir() else None
  78. def _hermes_exe_shims(scripts_dir: Path) -> list[Path]:
  79. """Entry-point shims uv may rewrite during ``pip install -e .`` — Windows .exe launchers
  80. only; POSIX shims are plain scripts replaced atomically."""
  81. if not _is_windows():
  82. return []
  83. names = set(_load_console_script_names()) or {"hermes", "hermes-agent", "hermes-acp"}
  84. # Not a [project.scripts] entry point, but older update/install paths still
  85. # rewrite and quarantine it.
  86. names.add("hermes-gateway")
  87. return [scripts_dir / f"{name}.exe" for name in sorted(names)]
  88. _PENDING_RENAME_KEY = r"SYSTEM\CurrentControlSet\Control\Session Manager"
  89. _PENDING_RENAME_VALUE = "PendingFileRenameOperations"
  90. def _filter_pending_shim_renames(entries: list[str], shims: list[Path]) -> tuple[list[str], int]:
  91. """Drop our ``<shim>`` -> ``<shim>.old.<stamp>`` pairs from a PendingFileRenameOperations
  92. value (a flat REG_MULTI_SZ of (source, target) pairs shared with other installers).
  93. Returns the entries to keep and how many pairs were dropped."""
  94. import ntpath
  95. def _norm(value: str) -> str:
  96. path = str(value).lstrip("!")
  97. path = path.removeprefix("\\??\\")
  98. return ntpath.normcase(ntpath.normpath(path))
  99. shim_paths = {_norm(str(shim)) for shim in shims}
  100. kept: list[str] = []
  101. removed = 0
  102. for index in range(0, len(entries) - 1, 2):
  103. source, target = entries[index], entries[index + 1]
  104. source_norm = _norm(source)
  105. if source_norm in shim_paths and _norm(target).startswith(f"{source_norm}.old."):
  106. removed += 1
  107. else:
  108. kept.extend((source, target))
  109. if len(entries) % 2:
  110. kept.append(entries[-1])
  111. return kept, removed
  112. def _cleanup_pending_shim_renames(scripts_dir: Path) -> int:
  113. """Drop reboot renames older Hermes versions queued for our shims: ``MOVEFILE_DELAY_UNTIL_REBOOT``
  114. fallbacks outlive the update that queued them and move away whatever sits at the shim path
  115. at next boot — even a shim a later repair just wrote. Needs elevation; a no-op otherwise."""
  116. if not _is_windows():
  117. return 0
  118. try:
  119. import winreg
  120. with winreg.OpenKey(
  121. winreg.HKEY_LOCAL_MACHINE, _PENDING_RENAME_KEY, 0,
  122. winreg.KEY_QUERY_VALUE | winreg.KEY_SET_VALUE,
  123. ) as key:
  124. entries, value_type = winreg.QueryValueEx(key, _PENDING_RENAME_VALUE)
  125. if value_type != winreg.REG_MULTI_SZ or not isinstance(entries, list):
  126. return 0
  127. kept, removed = _filter_pending_shim_renames(entries, _hermes_exe_shims(scripts_dir))
  128. if not removed:
  129. return 0
  130. if kept:
  131. winreg.SetValueEx(key, _PENDING_RENAME_VALUE, 0, winreg.REG_MULTI_SZ, kept)
  132. else:
  133. winreg.DeleteValue(key, _PENDING_RENAME_VALUE)
  134. return removed
  135. except (OSError, ValueError):
  136. return 0
  137. # Fresh orphan files can belong to an updater still running.
  138. _QUARANTINE_GRACE_SECONDS = 15 * 60
  139. def _quarantine_stamp_ms(stale: Path) -> int | None:
  140. """The ``.old.<unix-ms>`` stamp in a quarantine filename; ``None`` (not ours — neither rescued
  141. nor deleted) otherwise. Parsed from the NAME, not ``st_mtime``: ``rename`` preserves the
  142. shim's mtime (when uv wrote it), not when it was quarantined."""
  143. try:
  144. return int(stale.name.rsplit(".old.", 1)[1])
  145. except (IndexError, ValueError):
  146. return None
  147. def _recover_update_debts_on_startup() -> None:
  148. """The startup half of a previous update, run on every launch before dispatch."""
  149. # Dependency recovery already ran before imports. Report any fleet restart
  150. # still owed by a previous update without restarting services here.
  151. if "update" not in sys.argv[1:]:
  152. try:
  153. from hermes_cli.update_cmd_fleet import _warn_pending_fleet_restart_on_startup
  154. _warn_pending_fleet_restart_on_startup()
  155. except Exception: # a startup warning never blocks the launch it warns about
  156. logger.debug("pending fleet restart check failed", exc_info=True)
  157. from hermes_cli.update_pause_record import recover as _recover_paused_gateways
  158. # Unconditional: recover() itself skips the PARSED `update`/`gateway run` commands; a raw argv
  159. # value equal to "update" (`--resume update`) is no reason to strand paused gateways.
  160. _recover_paused_gateways() # a killed `hermes update` left gateways paused (Windows)
  161. def _cleanup_quarantined_exes(scripts_dir: Path | None = None) -> None:
  162. """Sweep — and where necessary RESCUE — ``hermes.exe.old.*`` from updates.
  163. Called early on every invocation. Two cases an unconditional ``unlink()`` gets wrong:
  164. (1) orphan rescue — ``hermes.exe`` missing while ``hermes.exe.old.*`` exists means the .old
  165. file is the ONLY surviving copy (update died between rename and uv's write); put it back via
  166. the same retry-and-report helper the update-time restore uses. (2) concurrency — a fresh
  167. quarantine file may belong to an update in flight in another process; leave anything inside
  168. the grace window alone. Silent no-op on non-Windows, nothing to do, or locked/permission errors.
  169. Deleting it converts a one-rename recovery into a full reinstall. See #75584.
  170. """
  171. if not _is_windows():
  172. return
  173. scripts_dir = scripts_dir if scripts_dir is not None else _venv_scripts_dir()
  174. if scripts_dir is None:
  175. return
  176. from hermes_cli.main import PROJECT_ROOT
  177. from hermes_cli.update_lock import update_in_progress
  178. if update_in_progress(PROJECT_ROOT):
  179. return # every quarantine may be that update's own, mid rename-back
  180. _cleanup_pending_shim_renames(scripts_dir)
  181. now = _time.time()
  182. try:
  183. candidates = [
  184. (stamp, stale) for stale in scripts_dir.glob("*.exe.old.*")
  185. if (stamp := _quarantine_stamp_ms(stale)) is not None]
  186. except OSError:
  187. return
  188. # Newest first by PARSED stamp: lexicographic order breaks when a stray ``.old.999`` exists.
  189. candidates.sort(key=lambda pair: pair[0], reverse=True)
  190. for stamp, stale in candidates:
  191. try:
  192. original = stale.with_name(stale.name.rsplit(".old.", 1)[0])
  193. if not original.exists():
  194. # Orphan rescue: last copy of the shim — retry ladder + recovery message.
  195. _early_recovery_mod.restore_quarantined_shims([(original, stale)])
  196. continue
  197. if now - stamp / 1000.0 < _QUARANTINE_GRACE_SECONDS:
  198. continue # may be a live quarantine from a concurrent update
  199. stale.unlink()
  200. except OSError:
  201. pass # still locked or in use — try again next run
  202. def _configured_features_missing_deps() -> list[tuple[str, str, str]]:
  203. """Check configured platforms/MCP in the fresh, selected update-build child.
  204. PM preserves recorded extras atomically, but configuration can reference an
  205. unselected SDK. Never call this in the updater's stale import graph (#10651).
  206. Rows are ``(label, hint, candidate extra)``: a platform's SDK is the extra named after it.
  207. """
  208. missing: list[tuple[str, str, str]] = []
  209. try:
  210. from gateway.config import load_gateway_config
  211. from gateway.platform_registry import platform_registry
  212. for platform in load_gateway_config().get_connected_platforms():
  213. entry = platform_registry.get(platform.value)
  214. if entry is not None and not entry.check_fn():
  215. missing.append((entry.label, entry.install_hint or "Run `hermes setup` to install support.",
  216. entry.name))
  217. except Exception as exc:
  218. logger.debug("configured-platform dependency check skipped: %s", exc)
  219. try:
  220. import importlib.util
  221. from hermes_cli.config import load_config_readonly
  222. if (load_config_readonly().get("mcp_servers") or {}) and importlib.util.find_spec("mcp") is None:
  223. missing.append(("MCP servers", "Run `hermes pm install` to install MCP support.", "mcp"))
  224. except Exception as exc:
  225. logger.debug("configured-MCP dependency check skipped: %s", exc)
  226. return missing
  227. def _install_configured_features_missing_deps(project_root: Path) -> None:
  228. """Add the extras configured features need to the dependency environment (#124228).
  229. Recorded extras never follow config, so an enabled platform whose SDK is not
  230. selected would come up without its adapter after the gateway restart.
  231. """
  232. import pm
  233. from pm.extras import declined_extras, extra_supported
  234. from pm.features import declared_extras
  235. missing = _configured_features_missing_deps()
  236. if not missing:
  237. return
  238. # `hermes pm install --without NAME` outranks a platform still left in config.
  239. declared = set(declared_extras(project_root)) - declined_extras(project_root)
  240. extras = sorted({extra for *_, name in missing
  241. if (extra := name.replace("_", "-")) in declared and extra_supported(extra)})
  242. if extras:
  243. try:
  244. # Config asked for these, not the user: a `--without` landing before the PM lock still wins.
  245. pm.sync_venv(extras, explicit=True, project_root=project_root, evict_incompatible_plugins=True,
  246. automatic=extras)
  247. except Exception as exc:
  248. print(f" ⚠ Could not install {', '.join(extras)} for configured features: {exc}")
  249. else:
  250. installed = set(extras) - declined_extras(project_root)
  251. missing = [row for row in missing if row[2].replace("_", "-") not in installed]
  252. if missing:
  253. print(" ⚠ Configured features whose dependencies are still missing — the gateway will fail to load them on restart:")
  254. for feature, hint, _extra in missing:
  255. print(f" - {feature}: {hint}")
  256. def _load_console_script_names() -> list[str]:
  257. """Return ``[project.scripts]`` entry-point names from pyproject.toml."""
  258. project = _pyproject_project("console script verification: failed to read pyproject.toml: %s")
  259. scripts = (project or {}).get("scripts", {}) or {}
  260. return [str(name) for name in scripts if name]
  261. def _is_termux_env(env: dict[str, str] | None = None) -> bool:
  262. from hermes_cli.main import _is_termux_startup_environment
  263. return _is_termux_startup_environment(env)
  264. def _is_windows_npm_path(npm_path: str) -> bool:
  265. """True if ``npm_path`` points at a Windows npm shim (WSL drive interop, ``.cmd``/``.exe``, UNC).
  266. Callers use this only on a POSIX host — on native Windows ``npm.cmd`` is correct.
  267. """
  268. low = npm_path.lower()
  269. mount = low.split("/", 3)[2] if low.startswith("/mnt/") else ""
  270. return (
  271. low.endswith((".exe", ".cmd", ".bat"))
  272. or (len(mount) == 1 and mount.isalpha())
  273. or "\\" in npm_path
  274. )
  275. def _resolve_node_runtime_npm() -> str | None:
  276. """PM's npm, refused on a POSIX host when it is a Windows shim (EISDIR over WSL UNC paths, #30271).
  277. Never re-scans the user's PATH for another npm: Hermes runs only its PM-managed toolchain.
  278. """
  279. from hermes_constants import find_node_executable
  280. npm = find_node_executable("npm")
  281. if _is_windows() or not npm:
  282. return npm
  283. return None if _is_windows_npm_path(npm) else npm
  284. def _resolve_update_branch(args) -> str:
  285. """Normalize ``args.branch`` to a non-empty name (default ``main``; blank/whitespace = default)."""
  286. return (getattr(args, "branch", None) or "main").strip() or "main"