plugins_cmd_update.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411
  1. """``hermes plugins update`` plus the provenance verbs around it: ``adopt``, ``trust-update-url`` and the
  2. read-only ``check-updates``; the dashboard update path shares the same pull/re-clone core.
  3. Sibling of :mod:`hermes_cli.plugins_cmd` (the facade re-exports the names other modules use and is
  4. imported late here, never at module level).
  5. """
  6. from __future__ import annotations
  7. import json
  8. import shutil
  9. import sys
  10. from pathlib import Path
  11. from typing import Any
  12. def _pc():
  13. """The facade, read at call time: tests patch ``plugins_cmd.<name>`` and sibling calls must see it."""
  14. from hermes_cli import plugins_cmd
  15. return plugins_cmd
  16. def _pull_plugin_update(target: Path, pinned_msg, not_git_msg, before_pull=None, *, interactive: bool = False,
  17. force: bool = False, scan_decision_cb=None, surface_gate=None) -> str:
  18. """Shared ``update`` core: refuse pinned checkouts, ``git pull`` (or re-install from the
  19. recorded source when the tree carries no ``.git`` — subdirectory installs), record the new
  20. revision. Returns the pull output; raises :class:`PluginOperationError` on any refusal.
  21. *pinned_msg(install_record)* / *not_git_msg()* build the caller-specific error text. Both paths
  22. scan the candidate tree the same way: *force* or a truthy *scan_decision_cb* accepts a caution
  23. verdict, nothing accepts a dangerous one. *surface_gate(manifest, tree)* may refuse the candidate
  24. before publication (unattended updates: :func:`~hermes_cli.plugins_auto_update.unattended_gate`)."""
  25. metadata = _pc()._read_install_metadata()
  26. install_record = metadata.get(target.name, {})
  27. if install_record.get("pinned") is True:
  28. raise _pc().PluginOperationError(pinned_msg(install_record))
  29. # A URL install whose name/repo later landed on the kill list must not keep pulling or
  30. # re-cloning new code, including subdirectory installs that carry no local .git directory.
  31. from hermes_cli import plugins_cmd_catalog as catalog
  32. catalog.refuse_if_installed_removed(target.name, target)
  33. if not (target / ".git").exists():
  34. source = install_record.get("source")
  35. if not isinstance(source, str) or not source:
  36. raise _pc().PluginOperationError(not_git_msg())
  37. if before_pull is not None:
  38. before_pull()
  39. return _reclone_plugin_update(target, source, install_record.get("revision"),
  40. force=force, scan_decision_cb=scan_decision_cb, surface_gate=surface_gate)
  41. if before_pull is not None:
  42. before_pull()
  43. from hermes_cli.plugins_transaction import update_plugin
  44. return update_plugin(target, interactive=interactive, force=force, scan_decision_cb=scan_decision_cb,
  45. **({"surface_gate": surface_gate} if surface_gate else {}))
  46. def _reclone_plugin_update(target: Path, source: str, previous_revision: object, *, force: bool = False,
  47. scan_decision_cb=None, surface_gate=None) -> str:
  48. """Update a subdirectory install by re-cloning its source and atomically replacing the tree.
  49. These installs carry no local ``.git``, so the staged replacement also carries user-owned
  50. config/data from *target* before publication instead of silently deleting it (#122006).
  51. Replacing the tree needs the install core's ``force``; accepting a caution scan is a separate
  52. decision (*force* / *scan_decision_cb*), the same as the git-pull path.
  53. """
  54. from hermes_cli.plugins_cmd_catalog import _carry_user_files
  55. def _before_swap(manifest, tree):
  56. if surface_gate is not None:
  57. surface_gate(manifest, tree)
  58. return _carry_user_files(target, tree, None)
  59. new_target, _manifest, _name = _pc()._install_plugin_core(
  60. source,
  61. force=True,
  62. accept_caution=force,
  63. scan_decision_cb=scan_decision_cb,
  64. before_swap=_before_swap,
  65. )
  66. revision = str(_pc()._read_install_metadata().get(new_target.name, {}).get("revision") or "")
  67. previous = previous_revision if isinstance(previous_revision, str) else ""
  68. if revision and revision == previous:
  69. return "Already up to date."
  70. return f"Re-installed from {source}: {previous[:8]}..{revision[:8]}"
  71. def update_one(name: str, target: Path, console, *, interactive: bool = True, force: bool = False,
  72. unattended: bool = False) -> bool:
  73. """:func:`_update_one_locked` under the plugin's one-updater lock (a terminal update, the gateway's
  74. auto-apply and a Desktop click never pull the same plugin at once; the loser changes nothing).
  75. *unattended* (the auto-apply tick) applies :func:`~hermes_cli.plugins_auto_update.unattended_gate`
  76. inside the lock: a hold recorded during the check, or a Git update that widens the plugin, refuses."""
  77. from hermes_cli.plugins_auto_update import plugin_update_lock, unattended_gate
  78. with plugin_update_lock(target):
  79. gate = unattended_gate(name, target) if unattended else None
  80. return _update_one_locked(name, target, console, interactive=interactive, force=force, surface_gate=gate)
  81. def _update_one_locked(name: str, target: Path, console, *, interactive: bool = True, force: bool = False,
  82. surface_gate=None) -> bool:
  83. """Update one installed plugin, printing progress and consent prompts; True when it moved.
  84. Every update is scanned. A caution verdict on a git update asks ``Update anyway? [y/N]`` when
  85. *interactive*; *force* (``--force``) accepts it without asking. A dangerous verdict always blocks.
  86. Refusals raise :class:`~hermes_cli.plugins_cmd_catalog.RepinConsentRequired` or
  87. ``PluginOperationError`` with nothing changed; :func:`cmd_update` turns them into exit 1 and
  88. ``hermes plugins update`` with no name records them per plugin and moves on.
  89. """
  90. from rich.markup import escape
  91. from hermes_cli import plugins_cmd_catalog as catalog
  92. from hermes_cli.plugins_cmd_install import interactive_scan_decision
  93. sidecar = catalog.catalog_install_record(target)
  94. if sidecar: # catalog installs re-pin to the reviewed SHA — never `git pull`
  95. return catalog.cmd_update_catalog(name, target, sidecar, console, interactive=interactive)
  96. output = _pull_plugin_update(
  97. target,
  98. lambda rec: (
  99. f"Plugin '{name}' is pinned to {rec.get('revision')}. To move it, run "
  100. f"`hermes plugins install {escape(str(rec.get('source', '<source>')))} --force "
  101. "--ref <40-character commit SHA>`."),
  102. lambda: f"Plugin '{name}' was not installed from git (no .git directory). Cannot update.",
  103. before_pull=lambda: console.print(f"[dim]Updating {name}...[/dim]"),
  104. interactive=interactive,
  105. force=force,
  106. scan_decision_cb=interactive_scan_decision(console, "Update") if interactive else None,
  107. surface_gate=surface_gate)
  108. _post_pull_housekeeping(target, console)
  109. # Update-time re-consent (#64228): if the new version declares
  110. # capabilities the granted set lacks, surface the diff and require
  111. # re-consent for the additions. The stored consent hash detects a
  112. # changed declaration; additions stay ungranted until the user says yes
  113. # (non-interactive updates leave them ungranted — fail closed).
  114. updated_manifest = _pc()._read_manifest(target)
  115. plugin_id = updated_manifest.get("name") or target.name
  116. declared_caps = _pc()._declared_capabilities_from_manifest(updated_manifest, plugin_id)
  117. if declared_caps:
  118. from hermes_cli.plugin_capabilities import declared_set_changed, pending_capabilities
  119. if pending_capabilities(plugin_id, declared_caps) or declared_set_changed(plugin_id, declared_caps):
  120. if interactive:
  121. _pc()._run_capability_consent(console, plugin_id, declared_caps, context="update")
  122. else:
  123. console.print(f"[yellow]Plugin {plugin_id} has new capabilities; review them with `hermes plugins capabilities {plugin_id}`.[/yellow]")
  124. out = output.strip()
  125. if "Already up to date" in out:
  126. console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] is already up to date.")
  127. return False
  128. console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] updated.")
  129. console.print(f"[dim]{out}[/dim]")
  130. return True
  131. def cmd_update(name: str, *, interactive: bool = True, force: bool = False) -> None:
  132. """``hermes plugins update <name> [--force]``: :func:`update_one`, exit 1 on a refusal."""
  133. from hermes_cli.plugins_cmd_catalog import RepinConsentRequired
  134. console = _pc()._console()
  135. target = _pc()._require_installed_plugin(name, _pc()._plugins_dir(), console)
  136. try:
  137. update_one(name, target, console, interactive=interactive, force=force)
  138. except RepinConsentRequired as exc:
  139. _pc()._fail(console, f"[yellow]Update of {name} not applied:[/yellow] {exc}")
  140. except _pc().PluginScanBlocked as exc:
  141. _pc()._fail(console, f"[red]Blocked:[/red] {exc}")
  142. except _pc().PluginOperationError as exc:
  143. _pc()._fail(console, f"[red]Error:[/red] {exc}")
  144. def _post_pull_housekeeping(target: Path, console) -> None:
  145. """After publication: drop stale bytecode and copy any new example files."""
  146. # Same stale-bytecode class as the main checkout (#6207/#60242): the pull just changed .py files under
  147. # this plugin dir, so drop any __pycache__ compiled from the previous revision.
  148. _clear_plugin_bytecode(target)
  149. _pc()._copy_example_files(target, console)
  150. def cmd_adopt(name: str) -> None:
  151. """Adopt a self-cloned plugin dir into the provenance sidecar.
  152. Reads the dir's git origin URL, validates it, writes the sidecar row
  153. — from then on a normal git install (check-updates + update). The
  154. ONLY mutation path for self-cloned dirs (settled: explicit verbs).
  155. """
  156. from rich.console import Console
  157. console = Console()
  158. plugins_dir = _pc()._plugins_dir()
  159. target = _pc()._require_installed_plugin(name, plugins_dir, console)
  160. from hermes_cli.plugins_provenance import ProvenanceClass, plugins_provenance
  161. prov = next((p for p in plugins_provenance(plugins_dir) if p.name == target.name), None)
  162. if prov is None:
  163. console.print(f"[red]Error:[/red] Plugin '{name}' not classifiable.")
  164. sys.exit(1)
  165. if prov.klass is not ProvenanceClass.SELF_CLONED:
  166. console.print(
  167. f"[red]Error:[/red] Plugin '{name}' is {prov.klass.value}, not "
  168. "self-cloned — there is nothing to adopt."
  169. )
  170. sys.exit(1)
  171. if not prov.origin_url:
  172. console.print(
  173. f"[red]Error:[/red] Plugin '{name}' has no readable git origin "
  174. "remote. Add one (git remote add origin <url>) and retry."
  175. )
  176. sys.exit(1)
  177. try:
  178. _pc()._resolve_git_url(prov.origin_url)
  179. except ValueError as e:
  180. console.print(f"[red]Error:[/red] The dir's origin url is not installable: {e}")
  181. sys.exit(1)
  182. metadata = _pc()._read_install_metadata()
  183. if target.name in metadata:
  184. console.print(f"[red]Error:[/red] Plugin '{name}' already has a provenance row.")
  185. sys.exit(1)
  186. git_exe = _pc()._resolve_git_executable()
  187. revision = _pc()._git_head_revision(target, git_exe) if git_exe else ""
  188. metadata[target.name] = {
  189. "pinned": False,
  190. "revision": revision,
  191. "source": _pc()._canonical_source(prov.origin_url, None),
  192. }
  193. _pc()._write_install_metadata(metadata)
  194. console.print(
  195. f"[green]✓[/green] Adopted [bold]{name}[/bold] "
  196. f"(source: {prov.origin_url}, revision: {revision[:12] or 'unknown'}). "
  197. "It is now a tracked git install."
  198. )
  199. def cmd_trust_update_url(name: str) -> None:
  200. """The ONLY path that moves a saved update_url tag.
  201. A needs-fixing mismatch (manifest update_url vs the saved tag) is
  202. resolved here: confirms the manifest's url into the sidecar row,
  203. prints old → new. Refuses when there is nothing to trust.
  204. """
  205. from rich.console import Console
  206. console = Console()
  207. plugins_dir = _pc()._plugins_dir()
  208. target = _pc()._require_installed_plugin(name, plugins_dir, console)
  209. from hermes_cli.plugins_provenance import read_sidecar_rows
  210. rows = read_sidecar_rows(plugins_dir)
  211. row = rows.get(target.name)
  212. if not isinstance(row, dict):
  213. console.print(
  214. f"[red]Error:[/red] Plugin '{name}' has no provenance row — "
  215. "nothing to trust. Reinstall it instead."
  216. )
  217. sys.exit(1)
  218. saved = row.get("update_url") or None
  219. manifest = _pc()._read_manifest(target)
  220. claimed = (manifest or {}).get("update_url") or None
  221. if claimed == saved:
  222. console.print(
  223. f"[yellow]Nothing to trust:[/yellow] '{name}' has no "
  224. "update_url mismatch."
  225. )
  226. return
  227. if claimed is not None:
  228. from hermes_cli.plugins_updates import https_update_url
  229. try:
  230. claimed = https_update_url(claimed)
  231. except ValueError as exc:
  232. console.print(f"[red]Error:[/red] Plugin '{name}' {exc}. Not trusted.")
  233. sys.exit(1)
  234. row["update_url"] = claimed
  235. rows[target.name] = row
  236. _pc()._write_install_metadata(rows)
  237. console.print(
  238. f"[green]✓[/green] Trusted [bold]{name}[/bold] update_url:\n"
  239. f" old: {saved or '(none)'}\n"
  240. f" new: {claimed or '(none)'}"
  241. )
  242. def cmd_check_updates(args: Any | None = None) -> None:
  243. """Read-only: is any installed plugin outdated? NEVER mutates."""
  244. from rich.console import Console
  245. from rich.table import Table
  246. console = Console()
  247. plugins_dir = _pc()._plugins_dir()
  248. from hermes_cli.plugins_updates import held_for_newer_hermes, run_checks
  249. from hermes_cli.plugins_cadence import record_check_results, snapshot_installs
  250. checked_installs = snapshot_installs(plugins_dir)
  251. results = run_checks(plugins_dir)
  252. record_check_results(results, checked_installs)
  253. if getattr(args, "json", False):
  254. print(json.dumps([r.to_json() for r in results], indent=2))
  255. return
  256. table = Table(title="Plugin updates", show_lines=False)
  257. table.add_column("Name", style="bold")
  258. table.add_column("Class", style="dim")
  259. table.add_column("Current")
  260. table.add_column("Latest")
  261. table.add_column("Status")
  262. for r in results:
  263. if r.needs_fixing:
  264. status = f"[red]needs fixing[/red]\n[dim]{r.needs_fixing}[/dim]"
  265. elif r.update_available is True and (held := held_for_newer_hermes(r)):
  266. status = f"[yellow]update available after updating Hermes[/yellow]\n[dim]{held}[/dim]"
  267. elif r.update_available is True:
  268. status = "[green]update available[/green]"
  269. elif r.update_available is False:
  270. status = "[dim]up to date[/dim]"
  271. else:
  272. status = f"[yellow]unknown[/yellow]\n[dim]{r.reason}[/dim]"
  273. table.add_row(
  274. r.name, r.klass, (r.current or "-")[:12], r.latest or "-", status
  275. )
  276. console.print()
  277. console.print(table)
  278. console.print()
  279. console.print("[dim]Check-only. Apply with: hermes plugins update <name>, or "
  280. "hermes plugins update to update them all[/dim]")
  281. def dashboard_update_user_plugin(name: str, *, accept_capabilities: bool = False, force: bool = False,
  282. unattended: bool = False) -> dict[str, Any]:
  283. """The one non-interactive update for the dashboard and Desktop: ``git pull`` inside
  284. ``~/.hermes/plugins/<name>``; catalog installs re-pin instead. Nothing changes on a refusal:
  285. a re-pin that widens the plugin returns ``{"ok": False, "consent_required": True, "delta": {...}}``
  286. (retry with *accept_capabilities*), and a git update the security scan blocks returns
  287. ``{"ok": False, "scan_blocked": True, "scan_verdict", "scan_findings"}`` (retry a caution verdict
  288. with *force* after the user saw the findings; a dangerous verdict never updates). *unattended*
  289. (Update all) applies :func:`~hermes_cli.plugins_auto_update.unattended_gate` inside the lock: a hold
  290. recorded after the check returns ``{"ok": False, "held": True}``, a widening Git update
  291. ``consent_required``."""
  292. from hermes_cli.plugins_auto_update import HeldWithRef, plugin_update_lock, unattended_gate
  293. target = _pc()._user_installed_plugin_dir(name)
  294. if target is None:
  295. return {"ok": False, "error": f"Plugin '{name}' was not found under {_pc()._plugins_dir()}."}
  296. try:
  297. with plugin_update_lock(target):
  298. try:
  299. gate = unattended_gate(name, target) if unattended else None
  300. except HeldWithRef as exc:
  301. return {"ok": False, "held": True, "error": str(exc), "name": name}
  302. return _dashboard_update_locked(name, target, accept_capabilities=accept_capabilities, force=force,
  303. surface_gate=gate)
  304. except _pc().PluginOperationError as exc: # the lock is busy: another updater owns this plugin
  305. return {"ok": False, "error": str(exc)}
  306. def _dashboard_update_locked(name: str, target: Path, *, accept_capabilities: bool, force: bool,
  307. surface_gate=None) -> dict[str, Any]:
  308. from hermes_cli import plugins_cmd_catalog as catalog
  309. from hermes_cli.plugins_activation import activate_plugin_now
  310. from hermes_cli.plugins_cmd_install import scan_blocked_result
  311. sidecar = catalog.catalog_install_record(target)
  312. try:
  313. if sidecar:
  314. result = catalog.repin_catalog_plugin(
  315. target, sidecar, consent_cb=(lambda _delta: True) if accept_capabilities else None)
  316. warnings = list(result.warnings)
  317. new_target = target.parent / result.installed_name
  318. deps = _pc()._python_dependency_summary(new_target, warnings) if result.changed else []
  319. activated = activate_plugin_now(result.installed_name) if result.changed else {}
  320. return {"ok": True, "name": result.installed_name, "sha": result.sha, "unchanged": not result.changed,
  321. "python_dependencies": deps, "warnings": warnings, **activated}
  322. msg = _pull_plugin_update(
  323. target,
  324. lambda rec: (
  325. f"Plugin '{name}' is pinned to {rec.get('revision')}; "
  326. f"run `hermes plugins install {rec.get('source', '<source>')} --force "
  327. "--ref <40-character commit SHA>` to move it."),
  328. lambda: f"Plugin '{name}' is not a git checkout; cannot pull updates.",
  329. force=force, surface_gate=surface_gate)
  330. except catalog.RepinConsentRequired as exc:
  331. return {"ok": False, "consent_required": True, "error": str(exc), "name": exc.name, "sha": exc.sha,
  332. "delta": exc.delta, "delta_lines": catalog.surface_delta_lines(exc.delta)}
  333. except _pc().PluginScanBlocked as exc:
  334. return {**scan_blocked_result(exc), "name": name}
  335. except _pc().PluginOperationError as exc:
  336. return {"ok": False, "error": str(exc)}
  337. _post_pull_housekeeping(target, _pc()._console())
  338. unchanged = "Already up to date" in msg
  339. activated = {} if unchanged else activate_plugin_now(target.name)
  340. return {"ok": True, "name": name, "output": msg, "unchanged": unchanged, **activated}
  341. def _clear_plugin_bytecode(target: Path) -> int:
  342. """Remove ``__pycache__`` dirs under a just-updated plugin checkout. Plugin dirs sit outside
  343. the repo, so the launch-time bytecode sweep never covers them and stale bytecode after a pull
  344. can ImportError in the next process. Never raises.
  345. See #60242, #6207.
  346. """
  347. removed = 0
  348. try:
  349. for cache_dir in target.rglob("__pycache__"):
  350. if cache_dir.is_dir():
  351. shutil.rmtree(cache_dir, ignore_errors=True)
  352. removed += 0 if cache_dir.exists() else 1
  353. except OSError:
  354. pass
  355. return removed