plugins_updates.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467
  1. """Plugin update checks — the standard, read-only 'is it outdated?' verb.
  2. Address resolution per plugin, in order, no derivation ever (settled
  3. 2026-09-03, plugin-auto-update plan):
  4. 1. saved sidecar tag + matching manifest update_url → fetch the feed yml
  5. 2. manifest update_url differs from the saved tag (or appeared where
  6. none was saved) → NEEDS-FIXING: fetch refused, tag untouched
  7. 3. no update_url anywhere + git row → git ls-remote vs revision
  8. 4. neither → manual/unupdatable
  9. Plus the pip world, stateless: entry-point discovery → installed version
  10. vs PyPI latest. NEVER mutates anything — no pulls, no row writes, no
  11. saved-tag changes.
  12. """
  13. from __future__ import annotations
  14. import importlib.metadata
  15. import json
  16. import re
  17. import subprocess
  18. from dataclasses import dataclass
  19. from pathlib import Path
  20. from typing import Any, Callable, Optional
  21. from packaging.version import InvalidVersion, Version
  22. from hermes_cli.plugins_provenance import (
  23. Provenance,
  24. ProvenanceClass,
  25. plugins_provenance,
  26. )
  27. _FETCH_TIMEOUT = 10.0
  28. _MAX_FEED_BYTES = 1 * 1024 * 1024
  29. _FULL_GIT_SHA_RE = re.compile(r"[0-9a-fA-F]{40}")
  30. def _version_is_newer(latest: str, current: str) -> Optional[bool]:
  31. """Invalid versions are unknown, not evidence of an update."""
  32. try:
  33. return Version(latest) > Version(current)
  34. except InvalidVersion:
  35. return None
  36. @dataclass
  37. class CheckResult:
  38. name: str
  39. klass: str # provenance class value ('git', ...)
  40. current: Optional[str] = None
  41. latest: Optional[str] = None
  42. update_available: Optional[bool] = None # None = unknown/uncheckable
  43. needs_fixing: Optional[str] = None # mismatch reason when set
  44. min_hermes: Optional[str] = None # feed floor / catalog requires_hermes, if any
  45. reason: str = ""
  46. def to_json(self) -> dict:
  47. return {
  48. "name": self.name,
  49. "class": self.klass,
  50. "current": self.current,
  51. "latest": self.latest,
  52. "update_available": self.update_available,
  53. "needs_fixing": self.needs_fixing,
  54. "min_hermes": self.min_hermes,
  55. "reason": self.reason,
  56. }
  57. def _read_manifest_field(plugin_dir: Path, key: str) -> Optional[str]:
  58. """One field from the installed plugin.yaml (claims, not provenance)."""
  59. import hermes_yaml as yaml
  60. manifest = plugin_dir / "plugin.yaml"
  61. if not manifest.is_file():
  62. return None
  63. try:
  64. with manifest.open(encoding="utf-8-sig") as f:
  65. data = yaml.safe_load(f) or {}
  66. except Exception:
  67. return None
  68. if not isinstance(data, dict):
  69. return None
  70. value = data.get(key)
  71. return value.strip() if isinstance(value, str) and value.strip() else None
  72. def check_local_provenance(prov: Provenance) -> CheckResult:
  73. """Check installed provenance without fetching remote metadata."""
  74. result = CheckResult(name=prov.name, klass=prov.klass.value)
  75. if prov.klass is ProvenanceClass.MANUAL:
  76. result.reason = "no provenance; not auto-updatable"
  77. return result
  78. if prov.klass is ProvenanceClass.DRIFT:
  79. result.reason = (
  80. f"provenance drift — sidecar records {prov.row.get('source')!r} "
  81. "but the dir has no .git; reinstall from the recorded source"
  82. )
  83. return result
  84. if prov.klass is ProvenanceClass.SELF_CLONED:
  85. result.reason = "self-cloned; run `hermes plugins adopt` first"
  86. return result
  87. row = prov.row or {}
  88. result.current = row.get("revision") or None
  89. if row.get("pinned") is True:
  90. result.update_available = False
  91. result.reason = f"pinned @ {(result.current or '')[:12] or 'sha'}"
  92. return result
  93. # ── the saved-tag comparison (the security heart) ──────────────
  94. saved = row.get("update_url") or None
  95. claimed = _read_manifest_field(prov.path, "update_url")
  96. if saved is None and claimed is not None:
  97. # a pulled commit introduced a url where none was saved — same
  98. # threat class as a swap; never adopt silently
  99. result.needs_fixing = (
  100. f"manifest declares update_url {claimed!r} but no url was saved "
  101. "at install; run `hermes plugins trust-update-url` after review"
  102. )
  103. return result
  104. if saved is not None and claimed != saved:
  105. result.needs_fixing = (
  106. f"update_url mismatch: saved {saved!r}, manifest declares "
  107. f"{claimed!r}; run `hermes plugins trust-update-url` after review"
  108. )
  109. return result
  110. return result
  111. def held_for_newer_hermes(result: CheckResult) -> Optional[str]:
  112. """``needs Hermes <spec>; this is <version>`` when the update's ``min_hermes`` (a feed floor or the
  113. catalog entry's ``requires_hermes``) rejects the running Hermes, else ``None``. The update path refuses
  114. such an update, so listings name it as waiting on a Hermes update instead of offering it."""
  115. if not result.min_hermes:
  116. return None
  117. from hermes_cli.plugins_manifest import requires_hermes_error, running_hermes_version
  118. if not requires_hermes_error({"requires_hermes": result.min_hermes}):
  119. return None
  120. return f"needs Hermes {result.min_hermes}; this is {running_hermes_version()}"
  121. def check_provenanced(
  122. prov: Provenance,
  123. *,
  124. fetch: Callable[[str], str],
  125. ls_remote: Callable[[str], str],
  126. ) -> CheckResult:
  127. """Check local provenance before contacting its approved update source."""
  128. row = prov.row or {}
  129. catalog_value = row.get("catalog")
  130. catalog: dict = catalog_value if isinstance(catalog_value, dict) else {}
  131. catalog_name = catalog.get("name") or row.get("catalog_name")
  132. if catalog_name:
  133. from hermes_cli.plugin_catalog import find_removed, get_live_catalog_entry
  134. result = CheckResult(name=prov.name, klass="catalog", current=row.get("revision"))
  135. removed = None if row.get("allow_removed") is True else (
  136. find_removed(str(catalog_name))
  137. or find_removed(str(catalog.get("repo") or row.get("source", "")).split("#", 1)[0])
  138. )
  139. if removed:
  140. result.reason = f"removed from catalog: {removed.reason}"
  141. return result
  142. entry = get_live_catalog_entry(str(catalog_name))
  143. if entry is None:
  144. result.reason = "catalog entry is unavailable; installed pin retained"
  145. return result
  146. result.latest = entry.sha
  147. result.update_available = result.current != entry.sha
  148. result.min_hermes = entry.requires_hermes or None
  149. return result
  150. result = check_local_provenance(prov)
  151. if result.reason or result.needs_fixing:
  152. return result
  153. row = prov.row or {}
  154. saved = row.get("update_url") or None
  155. # ── 1. matching saved tag → fetch the feed ─────────────────────
  156. if saved is not None:
  157. try:
  158. feed_text = fetch(saved)
  159. except Exception as exc:
  160. result.reason = f"feed fetch failed: {exc}"
  161. return result
  162. try:
  163. feed = parse_feed_yml(feed_text)
  164. except ValueError as exc:
  165. result.reason = f"feed unparseable: {exc}"
  166. return result
  167. result.latest = feed.get("version")
  168. result.min_hermes = feed.get("min_hermes")
  169. # Like-for-like identity only (audit C17): a feed that ships a full
  170. # git SHA compares SHA vs recorded revision; otherwise the feed's
  171. # semantic version compares against the installed manifest's
  172. # version. A SHA is never compared to a semantic version, and an
  173. # uncomparable pair reads as unknown — not as an update.
  174. feed_git = (feed.get("artifacts") or {}).get("git")
  175. if feed_git and _FULL_GIT_SHA_RE.fullmatch(feed_git):
  176. if not result.current or not _FULL_GIT_SHA_RE.fullmatch(
  177. str(result.current)
  178. ):
  179. result.update_available = None
  180. result.reason = (
  181. "feed declares a git sha but the install records no "
  182. "full revision sha to compare"
  183. )
  184. return result
  185. # Case-equivalent hex only after format validation.
  186. result.latest = feed_git.lower()
  187. result.update_available = feed_git.lower() != result.current.lower()
  188. return result
  189. installed_version = _read_manifest_field(prov.path, "version")
  190. if installed_version is None:
  191. result.update_available = None
  192. result.reason = (
  193. f"feed declares version {result.latest!r} but the installed "
  194. "plugin.yaml records no version to compare"
  195. )
  196. return result
  197. # Like-for-like fields: the semantic branch compares version vs
  198. # version, so `current` reports the installed version, not the
  199. # recorded revision sha.
  200. result.current = installed_version
  201. result.update_available = _version_is_newer(result.latest, installed_version)
  202. if result.update_available is None:
  203. result.reason = (
  204. f"cannot compare feed version {result.latest!r} with "
  205. f"installed version {installed_version!r}"
  206. )
  207. return result
  208. # ── 3. no update_url anywhere + git row → ls-remote ────────────
  209. source = row.get("source") or ""
  210. if not source:
  211. result.reason = "no recorded source"
  212. return result
  213. try:
  214. head = ls_remote(source)
  215. except Exception as exc:
  216. result.reason = f"ls-remote failed: {exc}"
  217. return result
  218. result.latest = head
  219. result.update_available = bool(head) and head != result.current
  220. return result
  221. def parse_feed_yml(text: str) -> dict:
  222. """The electron-updater-derived feed shape: version, released,
  223. min_hermes, artifacts{git,bundle,bundle_sha256}, notes_url."""
  224. import hermes_yaml as yaml
  225. try:
  226. data = yaml.safe_load(text)
  227. except yaml.YAMLError as exc:
  228. raise ValueError(f"invalid feed YAML: {exc}") from exc
  229. if not isinstance(data, dict):
  230. raise ValueError("feed must be a YAML mapping")
  231. version = data.get("version")
  232. if not isinstance(version, str) or not version.strip():
  233. raise ValueError("feed missing 'version'")
  234. out: dict[str, Any] = {"version": version.strip()}
  235. for key in ("min_hermes", "notes_url"):
  236. value = data.get(key)
  237. if isinstance(value, str) and value.strip():
  238. out[key] = value.strip()
  239. artifacts = data.get("artifacts")
  240. if isinstance(artifacts, dict):
  241. git = artifacts.get("git")
  242. if git is not None and not isinstance(git, str):
  243. raise ValueError("feed artifacts.git must be a string")
  244. out["artifacts"] = {
  245. k: v for k, v in artifacts.items() if isinstance(v, str)
  246. }
  247. return out
  248. def _owning_distribution(ep) -> Optional[str]:
  249. """The name of the distribution the entry point belongs to — metadata,
  250. never a guess derived from the import module (audit C17)."""
  251. dist = getattr(ep, "dist", None)
  252. if dist is None:
  253. return None
  254. try:
  255. return dist.metadata.get("Name") or None
  256. except Exception:
  257. return None
  258. def check_pip_plugins(
  259. *,
  260. installed_version: Callable[[str], str], # dist name -> version
  261. pypi_latest: Callable[[str], Optional[str]], # dist name -> latest
  262. entry_points: Optional[list] = None, # injectable for tests
  263. ) -> list[CheckResult]:
  264. """The pip world, stateless: entry-point dists vs PyPI. Nothing
  265. recorded, nothing to drift."""
  266. if entry_points is None:
  267. entry_points = list(
  268. importlib.metadata.entry_points().select(group="hermes_agent.plugins")
  269. )
  270. results: list[CheckResult] = []
  271. for ep in entry_points:
  272. dist_name = getattr(ep, "dist_name", None) or _owning_distribution(ep)
  273. if not dist_name:
  274. results.append(
  275. CheckResult(
  276. name=ep.name,
  277. klass="pip",
  278. reason=(
  279. "entry point has no owning distribution metadata; "
  280. "cannot determine what to check"
  281. ),
  282. )
  283. )
  284. continue
  285. try:
  286. current = installed_version(dist_name)
  287. except importlib.metadata.PackageNotFoundError:
  288. results.append(
  289. CheckResult(
  290. name=ep.name,
  291. klass="pip",
  292. reason=f"distribution {dist_name!r} not importable",
  293. )
  294. )
  295. continue
  296. latest = pypi_latest(dist_name)
  297. # None (unknown / not on PyPI) must read as unknown — not False
  298. if latest is None:
  299. results.append(
  300. CheckResult(
  301. name=ep.name,
  302. klass="pip",
  303. current=current,
  304. latest=None,
  305. update_available=None,
  306. reason="unknown (not on PyPI)",
  307. )
  308. )
  309. continue
  310. update_available = _version_is_newer(latest, current)
  311. results.append(
  312. CheckResult(
  313. name=ep.name,
  314. klass="pip",
  315. current=current,
  316. latest=latest,
  317. update_available=update_available,
  318. reason=(
  319. f"cannot compare PyPI version {latest!r} with installed {current!r}"
  320. if update_available is None else ""
  321. ),
  322. )
  323. )
  324. return results
  325. def https_update_url(url: object) -> str:
  326. """Normalize a manifest ``update_url``; raises ValueError unless it is ``https://``.
  327. The feed picks which commit of the trusted origin gets installed and the gateway fetches
  328. it unattended every check interval, so a plaintext ``http://`` (MITM → an old vulnerable
  329. commit), ``file://`` or ``ftp://`` feed is refused at install, at trust-update-url AND at
  330. the fetch itself (rows saved before this rule existed).
  331. """
  332. text = str(url or "").strip()
  333. if not text.lower().startswith("https://"):
  334. raise ValueError(f"update_url must be an https:// URL, got {text!r}")
  335. return text
  336. def default_fetch(url: str) -> str:
  337. """The real feed fetcher: url -> text (raises on failure).
  338. ONE implementation shared by the manual ``hermes plugins
  339. check-updates`` and the cadence tick — callers never re-derive it.
  340. """
  341. import urllib.request
  342. class HTTPSFeedRedirectHandler(urllib.request.HTTPRedirectHandler):
  343. def redirect_request(self, req, fp, code, msg, headers, newurl):
  344. redirected = super().redirect_request(req, fp, code, msg, headers, newurl)
  345. if redirected is not None and not redirected.full_url.lower().startswith("https://"):
  346. fp.close()
  347. raise ValueError("update_url redirect must use https://")
  348. return redirected
  349. opener = urllib.request.build_opener(HTTPSFeedRedirectHandler())
  350. with opener.open(https_update_url(url), timeout=_FETCH_TIMEOUT) as resp:
  351. data = resp.read(_MAX_FEED_BYTES)
  352. return data.decode("utf-8", errors="replace")
  353. def default_ls_remote(source: str) -> str:
  354. """The real git probe: source -> HEAD sha (raises on failure).
  355. Uses the same resolved git executable the CLI path resolves. Lazily
  356. imports plugins_cmd (which lazily imports this module) — no import
  357. cycle at module load.
  358. """
  359. from hermes_cli.plugins_cmd import _resolve_git_executable
  360. proc = subprocess.run(
  361. [_resolve_git_executable() or "git", "ls-remote", source, "HEAD"],
  362. capture_output=True,
  363. text=True, encoding="utf-8", errors="replace",
  364. timeout=30,
  365. check=False,
  366. )
  367. if proc.returncode != 0:
  368. raise RuntimeError((proc.stderr or "ls-remote failed").strip()[:200])
  369. # 'sha\trefs/heads/...' or empty
  370. out = (proc.stdout or "").strip()
  371. return out.split("\t")[0] if out else ""
  372. def run_checks(
  373. plugins_dir: Path,
  374. *,
  375. fetch: Optional[Callable[[str], str]] = None,
  376. ls_remote: Optional[Callable[[str], str]] = None,
  377. include_pip: bool = True,
  378. pip_installed_version: Callable[[str], str] = importlib.metadata.version,
  379. pip_pypi_latest: Optional[Callable[[str], Optional[str]]] = None,
  380. pip_entry_points: Optional[list] = None,
  381. ) -> list[CheckResult]:
  382. """All checks for one plugins dir. NEVER mutates anything.
  383. ``fetch``/``ls_remote`` default to :func:`default_fetch` /
  384. :func:`default_ls_remote` — the single shared network implementation
  385. the manual command and the cadence tick both ride.
  386. """
  387. if fetch is None:
  388. fetch = default_fetch
  389. if ls_remote is None:
  390. ls_remote = default_ls_remote
  391. results = [
  392. check_provenanced(p, fetch=fetch, ls_remote=ls_remote)
  393. for p in plugins_provenance(plugins_dir)
  394. ]
  395. if include_pip:
  396. if pip_pypi_latest is None:
  397. pip_pypi_latest = _default_pypi_latest
  398. results.extend(
  399. check_pip_plugins(
  400. installed_version=pip_installed_version,
  401. pypi_latest=pip_pypi_latest,
  402. entry_points=pip_entry_points,
  403. )
  404. )
  405. return results
  406. def _default_pypi_latest(dist: str) -> Optional[str]:
  407. """PyPI JSON API — the real fetcher (injectable in tests)."""
  408. import urllib.request
  409. url = f"https://pypi.org/pypi/{dist}/json"
  410. try:
  411. with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT) as resp:
  412. data = json.loads(resp.read(_MAX_FEED_BYTES))
  413. return (data.get("info") or {}).get("version")
  414. except Exception:
  415. return None