post_update.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370
  1. """Home maintenance shared by explicit updates and bounded boot maintenance.
  2. Config migration owns backup/rollback; skills sync owns content merging; the
  3. SQLite guard detects damage without repairing it. Boot bounds these home
  4. steps per revision. The explicit scope CLI also provisions runtimes through
  5. PM. Launcher publication belongs to hermes_cli._launchers.
  6. """
  7. from __future__ import annotations
  8. import logging
  9. import os
  10. import shutil
  11. from datetime import datetime, timezone, UTC
  12. from pathlib import Path
  13. from typing import Iterable
  14. from hermes_cli._launchers import expose_cli
  15. from pm.paths import install_root
  16. logger = logging.getLogger(__name__)
  17. # ---------------------------------------------------------------------------
  18. # config migration (backup / migrate / verify / restore)
  19. # ---------------------------------------------------------------------------
  20. def _backup_path(path: Path, stamp: str) -> Path:
  21. base = path.with_name(f"{path.name}.bak-{stamp}")
  22. if not base.exists():
  23. return base
  24. for index in range(1, 1000):
  25. candidate = path.with_name(f"{path.name}.bak-{stamp}.{index}")
  26. if not candidate.exists():
  27. return candidate
  28. raise RuntimeError(f"could not choose a backup path for {path}")
  29. def _backup_existing(paths: Iterable[Path]) -> dict:
  30. stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
  31. backups: dict = {}
  32. for path in paths:
  33. if not path.is_file():
  34. continue
  35. dest = _backup_path(path, stamp)
  36. shutil.copy2(path, dest)
  37. backups[path] = dest
  38. return backups
  39. def _restore_backups(backups: dict) -> list:
  40. restored = []
  41. for original, backup in backups.items():
  42. if not backup.is_file():
  43. continue
  44. shutil.copy2(backup, original)
  45. restored.append(original)
  46. return restored
  47. def step_migrate_config() -> dict:
  48. """Migrate config.yaml to the current schema, non-interactively.
  49. Same shape as scripts/docker_config_migrate.py: back up config + .env,
  50. migrate, verify the version advanced, restore the backups on failure.
  51. No-op when the on-disk version is current (the 99% case).
  52. """
  53. from hermes_cli.config import (
  54. check_config_version,
  55. get_config_path,
  56. get_env_path,
  57. migrate_config,
  58. )
  59. from hermes_cli.config_migrations import (
  60. SUPPORT_FLOOR_VERSION,
  61. support_floor_message,
  62. )
  63. from hermes_cli.config_migrations_browser import agent_browser_env_pending
  64. from hermes_cli.config_version_stamp import read_config_version_stamp, stamp_missing_config
  65. stamp_missing_config() # a missing config.yaml reads as current below
  66. stamp, latest_ver = read_config_version_stamp()
  67. current_ver = 0 if stamp is None else stamp
  68. if current_ver >= latest_ver:
  69. return {"ok": True, "skipped": "up-to-date"}
  70. if current_ver < SUPPORT_FLOOR_VERSION and not (stamp is None and agent_browser_env_pending()):
  71. # migrate_config() refuses sub-floor configs and leaves the file
  72. # untouched; warn instead of failing the boot. An unstamped config is
  73. # left alone too, unless its .env still holds AGENT_BROWSER_* settings
  74. # nothing reads any more: migrate_config() gives it the legacy-key
  75. # steps (v52's move among them) and a stamp.
  76. logger.warning("config migration skipped: %s", support_floor_message())
  77. return {"ok": True, "skipped": "below-support-floor"}
  78. backups = _backup_existing((get_config_path(), get_env_path()))
  79. try:
  80. results = migrate_config(interactive=False, quiet=True)
  81. except Exception:
  82. _restore_backups(backups)
  83. raise
  84. post_ver, _ = check_config_version()
  85. if post_ver < latest_ver:
  86. restored = _restore_backups(backups)
  87. raise RuntimeError(
  88. f"migration did not advance config version to {latest_ver} "
  89. f"(still {post_ver}); restored: "
  90. + (", ".join(str(p) for p in restored) if restored else "none")
  91. )
  92. # `hermes update` prints what a quiet migration changed; boot has no terminal to print it to.
  93. from hermes_cli.left_core_migration import defer_startup_notice
  94. for notice in results.get("notices") or ():
  95. defer_startup_notice(notice)
  96. return {"ok": True, "migrated": f"{current_ver}->{latest_ver}"}
  97. # ---------------------------------------------------------------------------
  98. # skills sync (this home only — profiles self-serve on their own boot)
  99. # ---------------------------------------------------------------------------
  100. def step_sync_skills() -> dict:
  101. """Sync bundled skills into the active home. Content-diffed, respects
  102. user modifications and deletions; converges on repeat runs."""
  103. from tools.skills_sync import sync_skills
  104. result = sync_skills(quiet=True) or {}
  105. return {
  106. "ok": True,
  107. "copied": len(result.get("copied") or []),
  108. "updated": len(result.get("updated") or []),
  109. }
  110. # ---------------------------------------------------------------------------
  111. # state.db integrity guard (#68474 — check-only variant)
  112. # ---------------------------------------------------------------------------
  113. def step_state_db_guard() -> dict:
  114. """Verify the active home's state.db is intact.
  115. Boot bootstrap has no pre-update snapshot to restore from (that pairing
  116. lives in ``hermes update``), so this is detection: a corrupt db is
  117. surfaced loudly in the log instead of the user silently losing session
  118. search. Read-only, idempotent.
  119. """
  120. from hermes_constants import get_hermes_home
  121. from hermes_cli.backup import verify_sqlite_integrity
  122. state_path = get_hermes_home() / "state.db"
  123. if not state_path.exists():
  124. return {"ok": True, "skipped": "no-state-db"}
  125. result = verify_sqlite_integrity(state_path, check_header=True, run_pragma=True)
  126. if result.get("valid"):
  127. return {"ok": True}
  128. message = result.get("message", "unknown error")
  129. logger.error(
  130. "state.db failed integrity check after a code update: %s — "
  131. "restore a backup with `hermes backup` tooling or contact support",
  132. message,
  133. )
  134. return {"ok": False, "error": message}
  135. def step_drop_live_plugin_catalog() -> dict:
  136. """Drop the active home's cached live plugin catalog after a code change.
  137. Bundled/sealed app updates never run ``hermes update``'s maintenance tail,
  138. so without this a pre-update snapshot out-votes the newer in-tree catalog
  139. for the rest of its TTL (#119340). Per home, like the boot record.
  140. """
  141. from hermes_constants import get_hermes_home
  142. from hermes_cli.plugin_catalog import invalidate_live_cache_for_home
  143. invalidate_live_cache_for_home(get_hermes_home())
  144. return {"ok": True}
  145. def step_adopt_blessed_checkout(project_root: Path | None = None) -> dict:
  146. """One-time adoption of shipped stampless installs (birth certificate).
  147. Main-era curl|sh / Setup installs created a ``.git`` checkout at a
  148. blessed managed root but never wrote a stamp — under the stamp-pure
  149. ladder they would all classify as "somebody's working tree" and
  150. `hermes update` would refuse them. This step writes the missing fact
  151. exactly once: blessed root + ``.git`` + no stamp → a minimal stamp
  152. with ``updateMechanism: self``.
  153. The blessed-root table lives HERE and only here — it is a one-time
  154. birth certificate for shipped installs, not a classification rung
  155. (hermes_cli.steward never path-matches). Once pre-stamp installs
  156. are extinct this step and the table can be deleted.
  157. * ``.git`` anywhere else → never adopted.
  158. * An existing stamp (any content) → untouched.
  159. * nix/docker/sealed populations are excluded by construction: their
  160. update mechanisms replace the tree wholesale with a
  161. build-time-stamped one, and sealed payloads always ship stamps.
  162. * Read-only tree (nix-like) → soft skip with a debug log, no crash.
  163. """
  164. import json
  165. import tempfile
  166. from hermes_constants import get_hermes_home
  167. root = install_root() if project_root is None else Path(project_root)
  168. # The blessed roots: the canonical locations installers create.
  169. blessed = (
  170. get_hermes_home() / "hermes-agent",
  171. Path("/usr/local/lib/hermes-agent"),
  172. )
  173. if not (root / ".git").exists():
  174. return {"ok": True, "skipped": "not-a-checkout"}
  175. from pm.paths import install_stamp_path
  176. stamp_path = install_stamp_path(root)
  177. if stamp_path.exists():
  178. return {"ok": True, "skipped": "already-stamped"}
  179. resolved_root = None
  180. try:
  181. resolved_root = root.resolve()
  182. except OSError:
  183. return {"ok": True, "skipped": "unresolvable-root"}
  184. is_blessed = False
  185. for candidate in blessed:
  186. try:
  187. if resolved_root == candidate.resolve():
  188. is_blessed = True
  189. break
  190. except OSError:
  191. continue
  192. if not is_blessed:
  193. return {"ok": True, "skipped": "not-a-blessed-root"}
  194. from hermes_cli.source_stamp import write_source_stamp
  195. try:
  196. # Full checkout identity when git can answer; the birth-certificate
  197. # minimum below only when it cannot (or the tree is read-only).
  198. identified = write_source_stamp(root, adopted=True)
  199. except OSError as exc:
  200. # A read-only tree (nix-like layouts without their own stamp)
  201. # must not crash the boot — it just stays unadopted.
  202. logger.debug("blessed-checkout adoption skipped (unwritable): %s", exc)
  203. return {"ok": True, "skipped": f"unwritable: {exc}"}
  204. if identified is None:
  205. # No derivable git identity: write the minimal birth certificate.
  206. stamp = {
  207. "schemaVersion": 2,
  208. "updateMechanism": "self",
  209. "source": "adoption",
  210. "adoptedAt": datetime.now(UTC).isoformat(),
  211. }
  212. try:
  213. fd, tmp_name = tempfile.mkstemp(
  214. dir=str(root), prefix=".install-stamp.", suffix=".tmp"
  215. )
  216. with os.fdopen(fd, "w", encoding="utf-8") as handle:
  217. handle.write(json.dumps(stamp, indent=2) + "\n")
  218. os.replace(tmp_name, stamp_path)
  219. except OSError as exc:
  220. logger.debug("blessed-checkout adoption skipped (unwritable): %s", exc)
  221. return {"ok": True, "skipped": f"unwritable: {exc}"}
  222. logger.info("adopted blessed checkout at %s (updateMechanism: self)", root)
  223. return {"ok": True, "adopted": str(root)}
  224. def step_provision_runtimes() -> dict:
  225. """Explicit refresh of PM's drifted packages; never selected by boot.
  226. PM supplies package identities, not diagnostic text to parse. Its own
  227. ensure/sync operations own freshness checks and publication under lock.
  228. """
  229. import pm
  230. from pm.install import lazy_installs_allowed, sealed
  231. problems = pm.drift()
  232. if not problems:
  233. return {"ok": True, "skipped": "current"}
  234. if sealed():
  235. # A sealed payload's tools ship with the artifact; drift here is
  236. # an artifact build problem, not something to repair in place.
  237. return {"ok": True, "skipped": "sealed"}
  238. if not lazy_installs_allowed():
  239. return {"ok": True, "skipped": "lazy-installs-disabled"}
  240. refreshed: list[str] = []
  241. errors: list[str] = []
  242. for name in problems:
  243. try:
  244. if name == "venv":
  245. pm.sync_venv(explicit=True, evict_incompatible_plugins=True)
  246. else:
  247. pm.ensure(name, explicit=True)
  248. refreshed.append(name)
  249. except Exception as exc:
  250. logger.warning("provision_runtimes: %s failed: %s", name, exc)
  251. errors.append(f"{name}: {exc}")
  252. if errors:
  253. return {"ok": False, "error": "; ".join(errors), "refreshed": refreshed}
  254. return {"ok": True, "refreshed": refreshed}
  255. # ---------------------------------------------------------------------------
  256. # step registries — boot_bootstrap gates each list with the matching record
  257. # ---------------------------------------------------------------------------
  258. HOME_STEPS: tuple = (
  259. ("adopt_blessed_checkout", step_adopt_blessed_checkout),
  260. ("migrate_config", step_migrate_config),
  261. ("sync_skills", step_sync_skills),
  262. ("state_db_guard", step_state_db_guard),
  263. ("drop_live_plugin_catalog", step_drop_live_plugin_catalog),
  264. ("expose_cli", expose_cli),
  265. )
  266. # Startup skill syncing belongs to each entry point. Boot bootstrap must
  267. # not repeat it. The explicit scope CLI includes the skills step.
  268. BOOT_HOME_STEPS: tuple = tuple(
  269. step for step in HOME_STEPS if step[0] != "sync_skills"
  270. )
  271. # Only the explicit scope CLI installs runtimes. Boot checks PM at startup.
  272. MACHINE_STEPS: tuple = (
  273. ("provision_runtimes", step_provision_runtimes),
  274. )
  275. def run_steps(steps: Iterable) -> dict:
  276. """Run steps in order; one failure never stops the rest.
  277. Returns ``{name: result_dict}``. A raising step records
  278. ``{"ok": False, "error": str}`` — the caller still writes its record so
  279. a broken step cannot retrigger the slow path on every boot.
  280. """
  281. results: dict = {}
  282. for name, func in steps:
  283. try:
  284. results[name] = func()
  285. except Exception as exc:
  286. logger.warning("post-update step %s failed: %s", name, exc)
  287. results[name] = {"ok": False, "error": str(exc)}
  288. return results
  289. def main(argv: list | None = None) -> int:
  290. """Run the selected maintenance registry and report its failures."""
  291. import argparse
  292. parser = argparse.ArgumentParser(prog="hermes_cli.post_update")
  293. parser.add_argument("--scope", choices=("home", "machine", "all"), default="all")
  294. args = parser.parse_args(argv)
  295. logging.basicConfig(level=logging.INFO, format="%(message)s")
  296. selected: list = []
  297. if args.scope in ("home", "all"):
  298. selected.extend(HOME_STEPS)
  299. if args.scope in ("machine", "all"):
  300. selected.extend(MACHINE_STEPS)
  301. results = run_steps(selected)
  302. failed = [name for name, res in results.items() if not res.get("ok")]
  303. for name, res in results.items():
  304. state = "ok" if res.get("ok") else f"FAILED ({res.get('error')})"
  305. skipped = res.get("skipped")
  306. print(f" post-update {name}: {f'skipped ({skipped})' if skipped else state}")
  307. return 1 if failed else 0
  308. if __name__ == "__main__":
  309. raise SystemExit(main())