plugin_catalog.py 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534
  1. """Plugin catalog — curated, Nous-approved Hermes plugins shipped with the repo.
  2. Mirrors the ``optional-mcps/`` MCP-catalog pattern: one YAML file per entry under the in-tree
  3. ``plugin-catalog/`` directory, pinned to an exact 40-character commit SHA. Presence in the directory IS
  4. the human-merged approval gate; SHA bumps are new, re-reviewed PRs; ``removed.yaml`` is the kill list
  5. (installs of a removed name/repo are refused with the recorded reason). Full policy:
  6. ``plugin-catalog/README.md``.
  7. Live refresh: the docs build publishes the same data as ONE JSON document
  8. (``website/scripts/extract-plugins.py`` → ``/docs/api/plugin-catalog.json``, like the skills index), so
  9. an installed Hermes sees new entries and removals without updating. A fetch failure reuses the last valid
  10. cached copy regardless of age, then falls back to the in-tree copy when no valid cache exists.
  11. """
  12. from __future__ import annotations
  13. import dataclasses
  14. import json
  15. import logging
  16. import re
  17. import time
  18. from dataclasses import dataclass, field
  19. from pathlib import Path
  20. from typing import Any, Dict, List, Optional
  21. import hermes_yaml as yaml
  22. from datetime import UTC
  23. logger = logging.getLogger(__name__)
  24. CATALOG_TIERS = ("official", "verified", "community")
  25. # Browse taxonomy for the catalog page / picker. Entries without one land on the Desktop shelf
  26. # (the common case for community submissions); "general" is for plugins that fit no shelf.
  27. CATALOG_CATEGORIES = ("desktop", "memory", "platform", "web", "tools", "voice", "automation", "models", "general")
  28. LIVE_CATALOG_URL = "https://hermes-agent.nousresearch.com/docs/api/plugin-catalog.json"
  29. LIVE_CATALOG_TTL_SECONDS = 6 * 60 * 60
  30. # Offline pins expire, but cached removals remain a permanent kill list.
  31. LIVE_CATALOG_MAX_STALE_SECONDS = 24 * 60 * 60
  32. LIVE_CATALOG_FAILURE_TTL_SECONDS = 60.0
  33. _REQUEST_TIMEOUT = 5.0
  34. _MAX_LIVE_BYTES = 2 * 1024 * 1024
  35. _SHA_RE = re.compile(r"^[0-9a-f]{40}$")
  36. _VERSION_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]{0,31}$")
  37. # Catalog images may only come from GitHub: the Desktop catalog browser never fans out to
  38. # third-party hosts, and a raw URL pinned to the entry's commit is as immutable as the sha.
  39. IMAGE_HOSTS = ("raw.githubusercontent.com", "github.com")
  40. IMAGE_HOST_SUFFIX = ".githubusercontent.com"
  41. def is_allowed_image_url(url: str) -> bool:
  42. from urllib.parse import urlsplit
  43. parts = urlsplit(url)
  44. host = (parts.hostname or "").lower()
  45. return parts.scheme == "https" and bool(host) and (host in IMAGE_HOSTS or host.endswith(IMAGE_HOST_SUFFIX))
  46. _NAME_RE = re.compile(r"^[a-z0-9_-]{1,64}$")
  47. @dataclass
  48. class RemovedEntry:
  49. name: str
  50. repo: str = ""
  51. reason: str = ""
  52. date: str = ""
  53. @dataclass
  54. class CatalogCapabilities:
  55. provides_tools: list[str] = field(default_factory=list)
  56. provides_hooks: list[str] = field(default_factory=list)
  57. provides_middleware: list[str] = field(default_factory=list)
  58. requires_env: list[str] = field(default_factory=list)
  59. @dataclass
  60. class PluginCatalogEntry:
  61. name: str # catalog key, [a-z0-9_-]{1,64}
  62. repo: str # https:// git URL
  63. sha: str # 40-hex pinned commit — mandatory
  64. description: str
  65. maintainer: str
  66. tier: str = "community"
  67. category: str = "desktop"
  68. requires_hermes: str = ""
  69. subdir: str = ""
  70. docs_url: str = ""
  71. version: str = "" # human label for the pinned sha ("1.4.0"); cosmetic, never parsed
  72. image: str = "" # https image URL on a GitHub host; shown on catalog cards
  73. screenshots: list[str] = field(default_factory=list) # GitHub-hosted https URLs; gallery on /docs/plugins/<name>
  74. readme: bool = False # docs site renders the README from the pinned commit on the entry's page
  75. platforms: list[str] = field(default_factory=list) # empty = all OSes
  76. title: str = "" # human name ("NVIDIA App"); empty = derived from ``name``
  77. onboarding: bool = False # curated: offered on the desktop onboarding card
  78. capabilities: CatalogCapabilities = field(default_factory=CatalogCapabilities)
  79. known_issues: list[str] = field(default_factory=list) # #124058: informational; drivers come from plugin-catalog/*.yaml
  80. @property
  81. def install_identifier(self) -> str:
  82. """``_install_plugin_core`` identifier (``repo#subdir`` for monorepo entries)."""
  83. return f"{self.repo}#{self.subdir}" if self.subdir else self.repo
  84. def to_dict(self) -> dict[str, Any]:
  85. caps = self.capabilities
  86. return {
  87. "name": self.name, "repo": self.repo, "sha": self.sha, "description": self.description,
  88. "maintainer": self.maintainer, "tier": self.tier, "category": self.category,
  89. "requires_hermes": self.requires_hermes,
  90. "subdir": self.subdir, "docs_url": self.docs_url, "version": self.version, "image": self.image,
  91. "screenshots": list(self.screenshots), "readme": self.readme,
  92. "platforms": list(self.platforms), "title": self.title, "onboarding": self.onboarding,
  93. "capabilities": {
  94. "provides_tools": list(caps.provides_tools), "provides_hooks": list(caps.provides_hooks),
  95. "provides_middleware": list(caps.provides_middleware), "requires_env": list(caps.requires_env),
  96. },
  97. "known_issues": list(self.known_issues),
  98. }
  99. def get_catalog_dir() -> Path:
  100. """The ``plugin-catalog/`` directory shipped with this checkout."""
  101. return Path(__file__).resolve().parent.parent / "plugin-catalog"
  102. # ── Parsing ──────────────────────────────────────────────────────────────────
  103. def _str_list(raw: Any) -> list[str]:
  104. return [str(x) for x in raw if isinstance(x, (str, int, float))] if isinstance(raw, list) else []
  105. def entry_from_mapping(data: Any, label: str) -> Optional[PluginCatalogEntry]:
  106. """Validate one entry mapping (YAML file or live-JSON element); ``None`` + warning on any failure."""
  107. if not isinstance(data, dict):
  108. logger.warning("Plugin catalog: %s: entry must be a mapping", label)
  109. return None
  110. name = str(data.get("name") or "")
  111. repo = str(data.get("repo") or "")
  112. sha = str(data.get("sha") or "").strip().lower()
  113. tier = str(data.get("tier") or "community")
  114. category = str(data.get("category") or "desktop")
  115. problem = (
  116. f"invalid name {name!r} (must match [a-z0-9_-]{{1,64}})" if not _NAME_RE.match(name)
  117. else f"repo must be an https:// URL (got {repo!r})" if not repo.startswith("https://")
  118. else f"sha must be a full 40-character hex commit SHA (got {data.get('sha')!r})" if not _SHA_RE.match(sha)
  119. else f"tier must be one of {'/'.join(CATALOG_TIERS)} (got {tier!r})" if tier not in CATALOG_TIERS
  120. else f"category must be one of {'/'.join(CATALOG_CATEGORIES)} (got {category!r})"
  121. if category not in CATALOG_CATEGORIES
  122. else None)
  123. if problem:
  124. logger.warning("Plugin catalog: %s: %s", label, problem)
  125. return None
  126. caps_raw = data.get("capabilities")
  127. caps: dict[str, Any] = caps_raw if isinstance(caps_raw, dict) else {}
  128. version = str(data.get("version") or "").strip()
  129. if version and not _VERSION_RE.match(version):
  130. logger.warning("Plugin catalog: %s: ignoring version %r (max 32 chars of [A-Za-z0-9._+-])", label, version)
  131. version = ""
  132. image = str(data.get("image") or "").strip()
  133. if image and not is_allowed_image_url(image):
  134. logger.warning("Plugin catalog: %s: ignoring image %r (must be https on a GitHub host)", label, image)
  135. image = ""
  136. screenshots = [s for s in _str_list(data.get("screenshots")) if is_allowed_image_url(s)]
  137. if len(screenshots) != len(_str_list(data.get("screenshots"))):
  138. logger.warning("Plugin catalog: %s: ignoring screenshots off GitHub hosts", label)
  139. return PluginCatalogEntry(
  140. name=name, repo=repo, sha=sha,
  141. description=str(data.get("description") or "").strip(),
  142. maintainer=str(data.get("maintainer") or "").strip(), tier=tier, category=category,
  143. requires_hermes=str(data.get("requires_hermes") or "").strip(),
  144. subdir=str(data.get("subdir") or "").strip(), docs_url=str(data.get("docs_url") or "").strip(),
  145. version=version, image=image, screenshots=screenshots, readme=data.get("readme") is not False,
  146. platforms=_str_list(data.get("platforms")),
  147. title=str(data.get("title") or "").strip(), onboarding=data.get("onboarding") is True,
  148. known_issues=_str_list(data.get("known_issues")),
  149. capabilities=CatalogCapabilities(
  150. provides_tools=_str_list(caps.get("provides_tools")), provides_hooks=_str_list(caps.get("provides_hooks")),
  151. provides_middleware=_str_list(caps.get("provides_middleware")),
  152. requires_env=_str_list(caps.get("requires_env"))),
  153. )
  154. def _read_yaml(path: Path) -> Any:
  155. try:
  156. return yaml.safe_load(path.read_text(encoding="utf-8-sig")) or {}
  157. except Exception as exc:
  158. logger.warning("Plugin catalog: failed to read %s: %s", path, exc)
  159. return None
  160. def _removed_from_list(raw_list: Any) -> list[RemovedEntry]:
  161. if not isinstance(raw_list, list):
  162. return []
  163. return [
  164. RemovedEntry(name=str(r["name"]), repo=str(r.get("repo") or ""), reason=str(r.get("reason") or ""),
  165. date=str(r.get("date") or ""))
  166. for r in raw_list if isinstance(r, dict) and r.get("name")]
  167. # ── In-tree catalog ──────────────────────────────────────────────────────────
  168. def load_catalog(catalog_dir: Optional[Path] = None) -> list[PluginCatalogEntry]:
  169. """Every valid ``*.yaml`` entry in the catalog dir (``removed.yaml`` excluded), sorted by file name.
  170. Malformed entries are skipped with a warning — never raises."""
  171. root = catalog_dir or get_catalog_dir()
  172. if not root.is_dir():
  173. return []
  174. entries = []
  175. for path in sorted(root.glob("*.yaml")):
  176. if path.name == "removed.yaml":
  177. continue
  178. data = _read_yaml(path)
  179. entry = entry_from_mapping(data, str(path)) if data is not None else None
  180. if entry is not None:
  181. entries.append(entry)
  182. return entries
  183. def load_removed_list(catalog_dir: Optional[Path] = None) -> list[RemovedEntry]:
  184. """``removed.yaml``'s ``removed:`` list; missing/malformed → empty."""
  185. path = (catalog_dir or get_catalog_dir()) / "removed.yaml"
  186. data = _read_yaml(path) if path.is_file() else None
  187. return _removed_from_list(data.get("removed")) if isinstance(data, dict) else []
  188. def get_catalog_entry(name: str, catalog_dir: Optional[Path] = None) -> Optional[PluginCatalogEntry]:
  189. return next((e for e in load_catalog(catalog_dir) if e.name == name), None)
  190. def filter_entries(entries: list[PluginCatalogEntry], query: str) -> list[PluginCatalogEntry]:
  191. """Case-insensitive substring match over name, description and declared tools; empty query = all."""
  192. q = (query or "").strip().lower()
  193. if not q:
  194. return entries
  195. return [e for e in entries
  196. if any(q in h.lower() for h in (e.name, e.description, *e.capabilities.provides_tools))]
  197. def search_catalog(query: str) -> list[PluginCatalogEntry]:
  198. return filter_entries(load_catalog(), query)
  199. # ── Removed / blocklist ──────────────────────────────────────────────────────
  200. _SCP_URL_RE = re.compile(r"^(?:[^@/\s]+@)?([^:/\s]+):(?!//)(.+)$") # git@host:owner/repo
  201. def _normalize_repo(url: str) -> str:
  202. """Canonical ``host/path`` for a repo URL: scheme, user, ``www.``, ``.git`` and trailing slashes are
  203. spelling, not identity — the kill list must match ``git@github.com:Evil/Bad.git`` when it names
  204. ``https://github.com/evil/bad``."""
  205. from urllib.parse import urlsplit
  206. text = url.strip()
  207. scp = _SCP_URL_RE.match(text)
  208. if scp:
  209. host, path = scp.group(1), scp.group(2)
  210. elif "://" in text:
  211. parts = urlsplit(text)
  212. host, path = parts.hostname or "", parts.path
  213. else:
  214. host, path = "", text
  215. host = host.lower().removeprefix("www.")
  216. path = path.strip("/").removesuffix(".git").rstrip("/").lower()
  217. return f"{host}/{path}" if host else path
  218. def find_removed(name_or_repo: str, catalog_dir: Optional[Path] = None) -> Optional[RemovedEntry]:
  219. """Match a catalog name or repo URL (``.git``/trailing-slash insensitive) against the kill list.
  220. The in-tree list and the live-fetched list are UNIONED: a removal published after this checkout
  221. shipped must still block, and a stale live cache must not un-block an in-tree removal.
  222. """
  223. if not name_or_repo:
  224. return None
  225. entries = load_removed_list(catalog_dir)
  226. if catalog_dir is None:
  227. entries = entries + live_removed_list()
  228. return match_removed(name_or_repo, entries)
  229. def resolved_removed_entries() -> list[RemovedEntry]:
  230. """The full kill list (in-tree UNION live) in one resolution. Callers that match many candidates
  231. — e.g. a plugins-hub rebuild annotating every installed plugin — resolve the list once instead
  232. of paying a live-catalog fetch per candidate."""
  233. return load_removed_list() + live_removed_list()
  234. def cached_removed_entries() -> list[RemovedEntry]:
  235. """In-tree list UNION the last fetched live copy, with NO network round-trip — for the load-time and
  236. ``enable`` checks that run in every process and must never block on a dead catalog host."""
  237. cached = _stale_live_cache(_live_cache_path()) or {}
  238. return load_removed_list() + _removed_from_list(cached.get("removed"))
  239. def match_removed(
  240. candidate: str, entries: list[RemovedEntry]
  241. ) -> Optional[RemovedEntry]:
  242. """One candidate against a pre-resolved kill list: exact name or normalized repo URL match."""
  243. if not candidate:
  244. return None
  245. text = candidate.strip()
  246. text_repo = _normalize_repo(text)
  247. for entry in entries:
  248. if text == entry.name or (
  249. entry.repo and text_repo == _normalize_repo(entry.repo)
  250. ):
  251. return entry
  252. return None
  253. # ── Live catalog ─────────────────────────────────────────────────────────────
  254. def _live_cache_path() -> Path:
  255. from hermes_constants import get_hermes_home
  256. return get_hermes_home() / "cache" / "plugin-catalog.json"
  257. def invalidate_live_cache_for_home(home: Path) -> None:
  258. """Best-effort removal of the cached live catalog under *home* (any profile's home).
  259. ``hermes update`` drops it for every profile after the checkout changes: a snapshot fetched
  260. before the bump would otherwise out-vote the newer in-tree catalog (pins the update just
  261. changed, entries it just added) for the rest of :data:`LIVE_CATALOG_TTL_SECONDS` (#119340).
  262. The next :func:`fetch_live_catalog` re-fetches the published doc, or falls back to the
  263. in-tree catalog while the network is down — both newer than what was deleted. Safe when the
  264. cache is absent (first run, other profiles that never opened the plugins hub).
  265. """
  266. try:
  267. (Path(home) / "cache" / "plugin-catalog.json").unlink(missing_ok=True)
  268. except Exception as exc:
  269. logger.debug("Plugin catalog: could not drop the live cache under %s: %s", home, exc)
  270. # Wall-clock deadline of the last failed live fetch. Without it a dead catalog host costs one
  271. # full request timeout PER CALL (the plugins hub and ``plugins list`` used to ask once per
  272. # installed plugin), so the dashboard event loop stalled for minutes.
  273. _live_fetch_failed_until = 0.0
  274. def _stale_live_cache(cache: Path) -> Optional[dict[str, Any]]:
  275. """A previously fetched copy still beats the in-tree one when the network is down — for
  276. :data:`LIVE_CATALOG_MAX_STALE_SECONDS`. Past that its pins may trail the checkout's own catalog
  277. (a 90-day-old cache outranked a freshly updated in-tree pin), so the entries are dropped and the
  278. caller falls back to in-tree; the removals are kept."""
  279. try:
  280. if not cache.is_file():
  281. return None
  282. data = json.loads(cache.read_text(encoding="utf-8-sig"))
  283. if time.time() - cache.stat().st_mtime > LIVE_CATALOG_MAX_STALE_SECONDS:
  284. data = {**data, "entries": []}
  285. return data
  286. except Exception:
  287. return None
  288. def fetch_live_catalog(*, force: bool = False) -> Optional[dict[str, Any]]:
  289. """The published ``plugin-catalog.json`` (``{"entries": [...], "removed": [...]}``), cached under
  290. ``HERMES_HOME/cache`` for :data:`LIVE_CATALOG_TTL_SECONDS`. ``None`` on ANY failure — callers fall
  291. back to the in-tree catalog. A failed network attempt is remembered for
  292. :data:`LIVE_CATALOG_FAILURE_TTL_SECONDS` so a dead host costs one timeout per TTL window, not one
  293. per call (``force`` bypasses both caches)."""
  294. global _live_fetch_failed_until
  295. cache = _live_cache_path()
  296. try:
  297. if not force and cache.is_file() and time.time() - cache.stat().st_mtime < LIVE_CATALOG_TTL_SECONDS:
  298. return json.loads(cache.read_text(encoding="utf-8-sig"))
  299. except Exception as exc:
  300. logger.debug("Plugin catalog: unreadable live cache %s: %s", cache, exc)
  301. if not force and time.time() < _live_fetch_failed_until:
  302. return _stale_live_cache(cache)
  303. try:
  304. import httpx
  305. from hermes_constants import mkdir_under_hermes_home
  306. from utils import atomic_write_text
  307. resp = httpx.get(LIVE_CATALOG_URL, timeout=_REQUEST_TIMEOUT, follow_redirects=True)
  308. resp.raise_for_status()
  309. if len(resp.content) > _MAX_LIVE_BYTES:
  310. raise ValueError("live catalog payload too large")
  311. data = resp.json()
  312. if not isinstance(data, dict) or not isinstance(data.get("entries"), list):
  313. raise ValueError("unexpected live catalog payload")
  314. mkdir_under_hermes_home(cache.parent)
  315. # Atomic: a concurrent reader (gateway, TUI, a second CLI) must never see a half-written
  316. # document, which would read as a fetch failure and start its own 60 s failure window.
  317. atomic_write_text(cache, json.dumps(data), tmp_prefix=f"{cache.name}.tmp-")
  318. return data
  319. except Exception as exc:
  320. logger.debug("Plugin catalog: live fetch failed: %s", exc)
  321. _live_fetch_failed_until = time.time() + LIVE_CATALOG_FAILURE_TTL_SECONDS
  322. return _stale_live_cache(cache)
  323. _in_tree_catalog_time: Optional[float] = -1.0 # -1 = not resolved yet; None = no usable in-tree time
  324. def in_tree_catalog_time() -> Optional[float]:
  325. """Commit time (epoch) of the last change to this checkout's ``plugin-catalog/``, or ``None`` when
  326. the install is not a git checkout (a release/pip install cannot be newer than the published doc).
  327. On a git checkout whose path history is unreadable without network — the treeless ``tree:0`` layout
  328. ``hermes update`` produces — the newest checked-out catalog file's mtime stands in for it, so a
  329. freshly updated checkout still outranks a doc fetched before the bump. Resolved once per process."""
  330. global _in_tree_catalog_time
  331. if _in_tree_catalog_time != -1.0:
  332. return _in_tree_catalog_time
  333. root = get_catalog_dir().parent
  334. resolved: Optional[float] = None
  335. if (root / ".git").exists():
  336. try:
  337. from hermes_cli._subprocess_compat import bounded_git_probe
  338. # Path history needs missing trees on tree:0 clones. The shared probe disables
  339. # lazy fetch only for its child and bounds timeout cleanup on every platform.
  340. out = bounded_git_probe(
  341. ["git", "-C", str(root), "log", "-1", "--format=%ct", "--", "plugin-catalog"],
  342. timeout=10,
  343. )
  344. resolved = float(out) if out else None
  345. except Exception as exc:
  346. logger.debug("Plugin catalog: could not date the in-tree catalog: %s", exc)
  347. if resolved is None:
  348. # "History unreadable without network" must not collapse into "not a git checkout":
  349. # ``None`` feeds the frozen-copy rule that defers to the live doc, which would let a
  350. # cache fetched before ``hermes update`` re-pin the old sha on exactly the installs
  351. # that just bumped it. A treeless clone still has its checked-out files — only the
  352. # historical trees are missing — and their mtime dates the checkout that wrote them.
  353. resolved = _catalog_worktree_mtime()
  354. _in_tree_catalog_time = resolved
  355. return resolved
  356. def _catalog_worktree_mtime() -> Optional[float]:
  357. """Newest mtime under the checkout's ``plugin-catalog/``: a no-network freshness signal for clones
  358. whose path history is unreachable (treeless or offline). ``None`` when nothing is checked out."""
  359. try:
  360. times = [p.stat().st_mtime for p in get_catalog_dir().rglob("*") if p.is_file()]
  361. except OSError:
  362. return None
  363. return max(times) if times else None
  364. def _live_generated_time(data: dict[str, Any]) -> Optional[float]:
  365. raw = data.get("generated_at")
  366. if not isinstance(raw, str) or not raw:
  367. return None
  368. try:
  369. from datetime import datetime, timezone
  370. parsed = datetime.fromisoformat(raw)
  371. return (parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)).timestamp()
  372. except ValueError:
  373. return None
  374. def _prefer_in_tree_entry(tree: PluginCatalogEntry, live: PluginCatalogEntry, tree_is_newer: Optional[bool]) -> bool:
  375. """For one entry present in both sources with a different pin: the newer catalog wins. Newer is
  376. decided by the checkout's catalog commit time vs the doc's ``generated_at`` when both resolve;
  377. otherwise by the entries' ``version`` labels when both parse; otherwise the live doc wins (a release
  378. install's in-tree copy is frozen at release time)."""
  379. if tree.sha == live.sha:
  380. return False
  381. if tree_is_newer is not None:
  382. return tree_is_newer
  383. if tree.version and live.version:
  384. try:
  385. from packaging.version import Version
  386. return Version(tree.version) > Version(live.version)
  387. except Exception:
  388. return False
  389. return False
  390. def load_catalog_live() -> list[PluginCatalogEntry]:
  391. """Entries from the live (or cached) catalog, else the in-tree catalog. When both name an entry at
  392. different pins the NEWER source supplies it — right after ``hermes update`` bumps an in-tree pin,
  393. a cache fetched before the bump must not re-install the old one (see :func:`_prefer_in_tree_entry`)."""
  394. data = fetch_live_catalog()
  395. if data is None:
  396. return load_catalog()
  397. entries = [e for i, raw in enumerate(data["entries"])
  398. if (e := entry_from_mapping(raw, f"{LIVE_CATALOG_URL}#{i}")) is not None]
  399. if not entries:
  400. return load_catalog()
  401. in_tree = {e.name: e for e in load_catalog()}
  402. live_t, tree_t = _live_generated_time(data), in_tree_catalog_time()
  403. tree_is_newer = (tree_t > live_t) if (live_t is not None and tree_t is not None) else None
  404. raw_by_name = {str(raw.get("name")): raw for raw in data["entries"] if isinstance(raw, dict)}
  405. return [in_tree[e.name] if e.name in in_tree and _prefer_in_tree_entry(in_tree[e.name], e, tree_is_newer)
  406. else _with_curated_fields(e, in_tree.get(e.name), raw_by_name.get(e.name) or {})
  407. for e in entries]
  408. # Curated display fields a published doc older than the field does not carry. ``generated_at`` is the
  409. # docs build time, not the content time, so a rebuild of an older catalog outranks a checkout that added
  410. # the field; a doc that has the key (even ``false``) decides.
  411. _CURATED_FIELDS = ("onboarding", "title")
  412. def _with_curated_fields(live: PluginCatalogEntry, tree: Optional[PluginCatalogEntry], raw: dict[str, Any]
  413. ) -> PluginCatalogEntry:
  414. if tree is None or tree.sha != live.sha:
  415. return live
  416. missing = {key: getattr(tree, key) for key in _CURATED_FIELDS if key not in raw}
  417. return dataclasses.replace(live, **missing) if missing else live
  418. def live_removed_list() -> list[RemovedEntry]:
  419. data = fetch_live_catalog()
  420. return _removed_from_list(data.get("removed")) if data else []
  421. def get_live_catalog_entry(name: str) -> Optional[PluginCatalogEntry]:
  422. return next((e for e in load_catalog_live() if e.name == name), None)
  423. # ── Human summaries ──────────────────────────────────────────────────────────
  424. def entry_capability_summary(entry: PluginCatalogEntry) -> str:
  425. """One paragraph shown at install/enable prompts: what the user is granting."""
  426. caps = entry.capabilities
  427. parts = [f"{label} {', '.join(items)}" for label, items in (
  428. ("registers tool(s):", caps.provides_tools), ("hook(s):", caps.provides_hooks),
  429. ("middleware:", caps.provides_middleware), ("requires env var(s):", caps.requires_env)) if items]
  430. bits = [f"{entry.name} ({entry.tier}, maintained by {entry.maintainer})"]
  431. if entry.description:
  432. bits.append(entry.description)
  433. bits.append(f"This plugin {'; '.join(parts) if parts else 'declares no tools, hooks, middleware, or env vars'}.")
  434. if entry.platforms:
  435. bits.append(f"Platforms: {', '.join(entry.platforms)}.")
  436. if entry.requires_hermes:
  437. bits.append(f"Requires Hermes {entry.requires_hermes}.")
  438. if entry.known_issues:
  439. # #124058: informational — the catalog documents traps (unsupported
  440. # install-method/mode combinations); surface them at install prompts
  441. # without blocking the install.
  442. bits.append(f"Known issues: {'; '.join(entry.known_issues)}.")
  443. return " ".join(bits)