steward.py 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
  1. """Steward classification and refusal text for sealed install trees.
  2. Adapted from the restack branch's ``installation/tree.py``. Our branch has
  3. no ``installation`` package yet — detection here is rewritten onto the two
  4. facts this branch already ships:
  5. * ``.git`` at the project root says the tree is a checkout the uninstaller
  6. / updater may mutate.
  7. * The build stamp (``install-stamp.json``, written by
  8. ``scripts/write_install_stamp.py``) names the steward in
  9. ``distribution`` (``desktop-app``, ``docker``, ``nix``, or a future
  10. package manager) for sealed trees.
  11. A sealed tree (no ``.git``) belongs to a steward: only the steward removes
  12. or replaces its code. The refusal messages below always leave the user a
  13. working next step for their data (``hermes uninstall --data`` / the
  14. desktop app's Settings -> About page).
  15. """
  16. from __future__ import annotations
  17. import json
  18. import sys
  19. from pathlib import Path
  20. from typing import Optional
  21. UPDATE_MECHANISMS = ("self", "app-installer", "electron-updater", "external", "microsoft-store")
  22. STEWARD_DESKTOP = "desktop-app"
  23. STEWARD_DOCKER = "docker"
  24. STEWARD_NIX = "nix"
  25. STEWARD_APT_TERMUX = "apt-termux"
  26. # What `hermes update` says in a sealed tree, per steward — the refusal
  27. # table shared by the update admission gate. The fallback covers stewards
  28. # this build does not know (a newer package-manager value read by older
  29. # code).
  30. STEWARD_UPDATE_MESSAGES = {
  31. STEWARD_DESKTOP: (
  32. "✗ This Hermes runs from inside the desktop app bundle.\n"
  33. "\n"
  34. "Manage updates from within the desktop app.\n"
  35. "Prefer a self-managed source install? See:\n"
  36. " https://hermes-agent.nousresearch.com/docs/user-guide/switching-to-source"
  37. ),
  38. STEWARD_NIX: (
  39. "✗ This Hermes runs from the Nix store.\n"
  40. "\n"
  41. "The store path is immutable. Update through your flake:\n"
  42. " nix flake update && rebuild your profile or system"
  43. ),
  44. STEWARD_APT_TERMUX: (
  45. "✗ This Hermes runs from a Termux APT package.\n"
  46. "\n"
  47. "The package manager owns the code tree. Update with:\n"
  48. " pkg upgrade hermes-agent"
  49. ),
  50. }
  51. # A git checkout on a Termux host is not ours to update either: the lock
  52. # pins a bionic CPython with no Android wheels, so a source sync would
  53. # build sdists on the phone. The APT package is the only supported shape.
  54. SOURCE_ON_TERMUX_UPDATE_MESSAGE = (
  55. "✗ This Hermes is a source checkout running under Termux.\n"
  56. "\n"
  57. "Source installs are not supported on Termux — `hermes update` would\n"
  58. "build Python packages on the device. Switch to the APT package:\n"
  59. " pkg install hermes-agent"
  60. )
  61. SOURCE_ON_TERMUX_UPDATE_COMMAND = "pkg install hermes-agent"
  62. _STEWARD_UPDATE_FALLBACK = (
  63. "✗ This Hermes install is managed by {steward}.\n"
  64. "\n"
  65. "The tree has no git checkout, so `hermes update` cannot update it.\n"
  66. "Update it with the tool that installed it."
  67. )
  68. # What the uninstaller says when it refuses to remove code from a sealed
  69. # tree. The steward put the code there; the steward removes it. The
  70. # desktop-app message is per-OS because each OS owns app removal
  71. # differently.
  72. _STEWARD_DELETE_DATA_PREAMBLE = "To delete your Hermes data (chats, configuration, etc),\n"
  73. _STEWARD_DELETE_DATA_CLI = "run:\n$ hermes uninstall --data\n"
  74. _STEWARD_DELETE_DATA_DESKTOP = "Open Hermes Desktop, go to Settings -> About, and delete your data from there.\n"
  75. _STEWARD_UNINSTALL_MESSAGES = {
  76. STEWARD_DOCKER: (
  77. "✗ This Hermes runs from a Docker image.\n"
  78. "\n"
  79. "There is no code to uninstall — remove the container and image:\n"
  80. " docker rm <container> && docker rmi nousresearch/hermes-agent\n"
  81. "\n" +
  82. _STEWARD_DELETE_DATA_PREAMBLE +
  83. _STEWARD_DELETE_DATA_CLI
  84. ),
  85. STEWARD_APT_TERMUX: (
  86. "✗ This Hermes was installed by a Termux APT package.\n"
  87. "\n"
  88. "The package manager owns the code tree — uninstall it with:\n"
  89. " pkg uninstall hermes-agent\n"
  90. "\n" +
  91. _STEWARD_DELETE_DATA_PREAMBLE +
  92. _STEWARD_DELETE_DATA_CLI
  93. ),
  94. STEWARD_NIX: (
  95. "✗ This Hermes was installed by Nix.\n"
  96. "\n"
  97. "The store path is immutable — uninstall it the same way you\n"
  98. "installed it: remove hermes-agent from your flake / profile\n"
  99. "(e.g. `nix profile remove`), then rebuild.\n"
  100. "\n" +
  101. _STEWARD_DELETE_DATA_PREAMBLE +
  102. _STEWARD_DELETE_DATA_CLI
  103. ),
  104. }
  105. _STEWARD_MANAGED_BY_DESKTOP = "✗ Hermes is managed by the desktop app.\n"
  106. _STEWARD_DESKTOP_UNINSTALL_BY_PLATFORM = {
  107. "win32": (
  108. _STEWARD_MANAGED_BY_DESKTOP +
  109. "\n"
  110. "Remove the app from Windows Settings → Apps → Installed apps.\n" +
  111. _STEWARD_DELETE_DATA_PREAMBLE +
  112. _STEWARD_DELETE_DATA_DESKTOP
  113. ),
  114. "darwin": (
  115. _STEWARD_MANAGED_BY_DESKTOP +
  116. "\n"
  117. "Quit the app and drag Hermes.app from Applications to the Trash.\n" +
  118. _STEWARD_DELETE_DATA_PREAMBLE +
  119. _STEWARD_DELETE_DATA_DESKTOP
  120. ),
  121. }
  122. _STEWARD_DESKTOP_UNINSTALL_DEFAULT = (
  123. _STEWARD_MANAGED_BY_DESKTOP +
  124. "\n"
  125. "Delete the Hermes AppImage (or app directory) from wherever you\n"
  126. "saved it.\n" +
  127. _STEWARD_DELETE_DATA_PREAMBLE +
  128. _STEWARD_DELETE_DATA_DESKTOP
  129. )
  130. _STEWARD_UNINSTALL_FALLBACK = (
  131. "✗ Hermes is managed by {steward}.\n"
  132. "\n"
  133. "The tree has no git checkout, so the uninstaller will not remove it.\n"
  134. "Remove it with the tool that installed it.\n"
  135. "\n" +
  136. # A generic package-manager steward has no desktop app, and this
  137. # refusal prints in a CLI context — point at the CLI data path.
  138. _STEWARD_DELETE_DATA_PREAMBLE +
  139. _STEWARD_DELETE_DATA_CLI
  140. )
  141. def steward_update_message(steward: str) -> str:
  142. """The `hermes update` refusal text for a sealed tree."""
  143. message = STEWARD_UPDATE_MESSAGES.get(steward)
  144. if message is not None:
  145. return message
  146. return _STEWARD_UPDATE_FALLBACK.format(steward=steward)
  147. def steward_uninstall_message(steward: str, platform: str | None = None) -> str:
  148. """The uninstall refusal text for a sealed tree."""
  149. if steward == STEWARD_DESKTOP:
  150. key = platform if platform is not None else sys.platform
  151. return _STEWARD_DESKTOP_UNINSTALL_BY_PLATFORM.get(key, _STEWARD_DESKTOP_UNINSTALL_DEFAULT)
  152. message = _STEWARD_UNINSTALL_MESSAGES.get(steward)
  153. if message is not None:
  154. return message
  155. return _STEWARD_UNINSTALL_FALLBACK.format(steward=steward)
  156. def read_install_stamp(project_root: Path) -> dict:
  157. """The build stamp of ``project_root``, or ``{}``.
  158. Tolerant by design: steward classification must not crash a refusal
  159. path on a malformed stamp — a tree we cannot prove is ours still
  160. refuses (see :func:`sealed_steward`), so garbage degrades safely.
  161. """
  162. from pm.paths import install_stamp_path
  163. try:
  164. data = json.loads(install_stamp_path(project_root).read_text(encoding="utf-8-sig"))
  165. except (OSError, ValueError):
  166. return {}
  167. return data if isinstance(data, dict) else {}
  168. def is_bundled_payload(project_root: Path) -> bool:
  169. """True when ``project_root`` is a bundled desktop payload's ``repo/``.
  170. THE shape predicate for the sealed-bundle branch, and a mirror of the
  171. Electron shell's ``installShape() === 'bundled'``: the build stamp is
  172. the authority, so filesystem coincidences (a sibling ``bin/``, a
  173. surviving ``apps/desktop/package.json``) can never promote a checkout
  174. into it. A missing, foreign, or unreadable stamp means NOT bundled.
  175. """
  176. try:
  177. return read_install_stamp(Path(project_root)).get("payload") == "bundled"
  178. except Exception:
  179. return False
  180. def sealed_steward(project_root: Path) -> Optional[str]:
  181. """The steward owning the sealed tree at ``project_root``, or ``None``.
  182. ``None`` means the tree is a git checkout (``.git`` present — a
  183. directory, or a worktree/submodule gitfile) and is ours to mutate.
  184. Everything else is sealed: the stamp's ``distribution`` names the
  185. steward, and a missing or unreadable stamp gives ``"unknown"`` —
  186. a tree we cannot prove is ours is not ours to remove.
  187. """
  188. root = Path(project_root)
  189. if (root / ".git").exists():
  190. return None
  191. distribution = read_install_stamp(root).get("distribution")
  192. return distribution if isinstance(distribution, str) and distribution else "unknown"
  193. def classify_install(project_root: Path) -> tuple[str, bool]:
  194. """(steward, code_removal_allowed) for the tree at ``project_root``.
  195. A git checkout reports ``("git", True)``; a sealed tree reports its
  196. steward and ``False``. Used by ``gui_install_summary`` so the desktop
  197. UI can gate its destructive options on the same ladder the CLI uses.
  198. """
  199. steward = sealed_steward(project_root)
  200. if steward is None:
  201. return ("git", True)
  202. return (steward, False)