plugin_dev.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503
  1. """Runtime-backed validation behind ``hermes plugins doctor``: every manifest/import/registration
  2. check routes through the real runtime contracts instead of a parallel scanner."""
  3. from __future__ import annotations
  4. import inspect
  5. import json
  6. import os
  7. import shutil
  8. import socket
  9. import sys
  10. import tempfile
  11. from contextlib import ExitStack, contextmanager
  12. from dataclasses import dataclass, field
  13. from pathlib import Path, PurePath
  14. from types import SimpleNamespace
  15. from typing import Any, Literal
  16. from unittest.mock import patch
  17. from hermes_constants import get_hermes_home
  18. class _DoctorLoadError(RuntimeError):
  19. """Raised when the real plugin runtime cannot load the target."""
  20. def _deny_network(*_args: Any, **_kwargs: Any) -> None:
  21. raise RuntimeError("network access is disabled while Plugin Doctor runs")
  22. def _stage_copy(source: Path, staged: Path) -> None:
  23. """Copy *source* to *staged*, refusing any directory that leads into the destination.
  24. TMPDIR can sit inside the plugin being checked, or a symlink/junction inside the plugin can
  25. point at TMPDIR; either way the copy walks its own output until the path is too long or the
  26. disk is full. Paths are resolved so link aliases cannot hide the overlap.
  27. """
  28. dest = staged.resolve()
  29. skipped = shutil.ignore_patterns(*_STAGING_SKIPPED_DIRS, "*.pyc")
  30. def _refuse_overlap(path: Path) -> None:
  31. real = path.resolve()
  32. if dest.is_relative_to(real) or real.is_relative_to(dest):
  33. raise _DoctorLoadError(
  34. f"Refusing to stage {source}: {path} leads into Doctor's temporary directory "
  35. f"{staged.parent}, so the copy would recurse into itself. Point TMPDIR outside "
  36. "the plugin and remove links to it.")
  37. def _ignore(directory: str, names: list[str]) -> set[str]:
  38. for name in names:
  39. if os.path.isdir(os.path.join(directory, name)):
  40. _refuse_overlap(Path(directory, name))
  41. return skipped(directory, names)
  42. _refuse_overlap(source)
  43. shutil.copytree(source, staged, ignore=_ignore)
  44. @contextmanager
  45. def _doctor_runtime(plugin_path: Path):
  46. """Load one plugin through the real runtime and restore global state afterwards.
  47. Private Doctor machinery, not a plugin test framework. Registration code runs under a temporary
  48. HERMES_HOME with outbound socket connects blocked.
  49. """
  50. stack = ExitStack()
  51. try:
  52. # The temp dir enters the stack FIRST so any failure below (ENOSPC / KeyboardInterrupt in
  53. # copytree) removes it instead of stranding a hermes-plugin-doctor-* directory.
  54. home = Path(stack.enter_context(tempfile.TemporaryDirectory(prefix="hermes-plugin-doctor-")))
  55. bundled = home / "bundled-plugins"
  56. plugins_root = home / "plugins"
  57. bundled.mkdir(parents=True)
  58. plugins_root.mkdir(parents=True)
  59. staging_root = plugins_root / plugin_path.name
  60. if _has_manifest(plugin_path):
  61. staged = staging_root
  62. _stage_copy(plugin_path, staged)
  63. else:
  64. # A category: stage only its plugin under the category name (discovery keys it
  65. # ``category/plugin``), never the loose files or skipped dirs beside it.
  66. members = _category_plugins(plugin_path)
  67. if len(members) != 1:
  68. names = ", ".join(member.name for member in members)
  69. raise _DoctorLoadError(
  70. f"{plugin_path} holds {len(members)} plugins ({names}); point Doctor at one of them")
  71. staged = staging_root / members[0].name
  72. _stage_copy(members[0], staged)
  73. stack.enter_context(patch.dict(os.environ, {
  74. "HERMES_HOME": str(home),
  75. "HERMES_BUNDLED_PLUGINS": str(bundled),
  76. "HERMES_ENABLE_PROJECT_PLUGINS": "0",
  77. }, clear=False))
  78. stack.enter_context(patch.object(socket, "create_connection", _deny_network))
  79. stack.enter_context(patch.object(socket.socket, "connect", _deny_network))
  80. stack.enter_context(patch.object(socket.socket, "connect_ex", _deny_network))
  81. except BaseException:
  82. stack.close()
  83. raise
  84. from hermes_cli.plugins import PluginManager
  85. from tools.registry import registry
  86. entries_before = {entry.name: entry for entry in registry._snapshot_entries()}
  87. policy_before = dict(registry._plugin_override_policy)
  88. modules_before = {name for name in sys.modules if _is_plugin_module(name)}
  89. manager = PluginManager()
  90. try:
  91. manifests = manager._scan_directory(plugins_root, source="user")
  92. if not manifests:
  93. raise _DoctorLoadError(f"Hermes discovery found no valid plugin manifest under {staging_root}")
  94. if len(manifests) != 1:
  95. raise _DoctorLoadError(
  96. f"Expected one plugin manifest, discovered {len(manifests)} under {staging_root}")
  97. manifest = manifests[0]
  98. if manifest.kind == "model-provider":
  99. with _load_model_provider(staged, manifest) as registered:
  100. yield SimpleNamespace(manifest=manifest, manager=manager, registered_tools=(),
  101. registered_hooks=(), registered_providers=registered)
  102. return
  103. manager._load_plugin(manifest)
  104. loaded = manager._plugins.get(manifest.key or manifest.name)
  105. if loaded is None:
  106. raise _DoctorLoadError("Plugin registration produced no runtime record")
  107. if loaded.error:
  108. raise _DoctorLoadError(f"Plugin registration failed: {loaded.error}")
  109. if not loaded.enabled:
  110. raise _DoctorLoadError("Plugin registration did not enable the runtime record")
  111. yield SimpleNamespace(
  112. manifest=manifest, manager=manager, registered_tools=tuple(sorted(loaded.tools_registered)),
  113. registered_hooks=tuple(loaded.hooks_registered), registered_providers=())
  114. finally:
  115. # Dispose the plugin's own registrations FIRST, while the temporary
  116. # HERMES_HOME still exists. This runs the host-owned ctx.on_unload(...)
  117. # callbacks — e.g. closing a SQLite handle a context-engine plugin
  118. # opened under that home. Without it the DB stays open and stack.close()
  119. # below (TemporaryDirectory removal) fails with WinError 32 on Windows
  120. # (#99918). Best-effort: the snapshot restore below remains the
  121. # authoritative registry cleanup, so an unload hiccup never masks it or
  122. # the original exception.
  123. try:
  124. manager.unload()
  125. except Exception:
  126. pass
  127. entries_after = {entry.name: entry for entry in registry._snapshot_entries()}
  128. changed_names = {
  129. name
  130. for name in set(entries_before) | set(entries_after)
  131. if entries_after.get(name) is not entries_before.get(name)
  132. }
  133. with registry._lock:
  134. for name in changed_names:
  135. previous = entries_before.get(name)
  136. if previous is None:
  137. registry._tools.pop(name, None)
  138. else:
  139. registry._tools[name] = previous
  140. registry._plugin_override_policy.clear()
  141. registry._plugin_override_policy.update(policy_before)
  142. if changed_names:
  143. registry._generation += 1
  144. for name in list(sys.modules):
  145. if name not in modules_before and _is_plugin_module(name):
  146. sys.modules.pop(name, None)
  147. stack.close()
  148. def _is_plugin_module(name: str) -> bool:
  149. return name == "hermes_plugins" or name.startswith("hermes_plugins.")
  150. @contextmanager
  151. def _load_model_provider(plugin_dir: Path, manifest):
  152. """Doctor path for ``kind: model-provider``: those register a ProviderProfile at import through
  153. providers/ discovery (PluginManager skips the kind), so demanding ``register(ctx)`` would fail
  154. every valid provider plugin. Registry additions are undone on exit."""
  155. import providers
  156. # The live install may already have imported this very plugin (same directory name) during
  157. # startup discovery; import the copy fresh and put the live module/profiles back afterwards.
  158. module_name = providers._user_module_name(plugin_dir, "")
  159. prior_module = sys.modules.pop(module_name, None)
  160. before = dict(providers._REGISTRY)
  161. before_aliases = dict(providers._ALIASES)
  162. try:
  163. providers._import_plugin_dir(plugin_dir, "user")
  164. registered = tuple(sorted(
  165. name for name, profile in providers._REGISTRY.items() if before.get(name) is not profile))
  166. if not registered:
  167. raise _DoctorLoadError(
  168. "model-provider plugin registered no ProviderProfile at import (see the warning above)")
  169. yield registered
  170. finally:
  171. for name in [n for n, p in providers._REGISTRY.items() if before.get(n) is not p]:
  172. providers._REGISTRY.pop(name)
  173. providers._SOURCES.pop(name, None)
  174. providers._REGISTRY.update(before)
  175. providers._ALIASES.clear()
  176. providers._ALIASES.update(before_aliases)
  177. providers._PROVIDER_LIST_CACHE = None
  178. sys.modules.pop(module_name, None)
  179. if prior_module is not None:
  180. sys.modules[module_name] = prior_module
  181. @dataclass(frozen=True)
  182. class DoctorFinding:
  183. level: Literal["error", "warning"]
  184. message: str
  185. @dataclass
  186. class DoctorReport:
  187. path: Path
  188. manifest: Any | None = None
  189. findings: list[DoctorFinding] = field(default_factory=list)
  190. registered_tools: tuple[str, ...] = ()
  191. registered_hooks: tuple[str, ...] = ()
  192. registered_providers: tuple[str, ...] = ()
  193. @property
  194. def ok(self) -> bool:
  195. return all(finding.level != "error" for finding in self.findings)
  196. def error(self, message: str) -> None:
  197. self.findings.append(DoctorFinding("error", message))
  198. def warning(self, message: str) -> None:
  199. self.findings.append(DoctorFinding("warning", message))
  200. def format_text(self) -> str:
  201. lines = [f"Plugin Doctor: {self.path}"]
  202. if self.manifest is not None:
  203. lines.append(
  204. f" manifest: {self.manifest.name} "
  205. f"{self.manifest.version or '(no version)'} ({self.manifest.kind})")
  206. for finding in self.findings:
  207. lines.append(f" {'ERROR' if finding.level == 'error' else 'WARN'}: {finding.message}")
  208. if self.ok:
  209. lines.append(" OK: runtime discovery, manifest parsing, import, and registration passed")
  210. lines.append(
  211. f" registrations: {len(self.registered_tools)} tool(s), {len(self.registered_hooks)} hook(s)"
  212. + (f", provider(s): {', '.join(self.registered_providers)}" if self.registered_providers else ""))
  213. return "\n".join(lines)
  214. _MANIFEST_NAMES = ("plugin.yaml", "plugin.yml", "plugin.json")
  215. def _has_manifest(path: Path) -> bool:
  216. return any((path / name).exists() or (path / name).is_symlink() for name in _MANIFEST_NAMES)
  217. # Dirs the staging copy drops, so a category may hold them beside its plugins.
  218. _STAGING_SKIPPED_DIRS = (".git", "__pycache__", ".pytest_cache")
  219. def _candidate_dirs(path: Path) -> list[Path]:
  220. """Subdirectories of *path* that could be plugins: not skipped by discovery or the staging copy."""
  221. from hermes_cli.plugins_discovery import is_skipped_plugin_dir
  222. try:
  223. return sorted(
  224. child for child in path.iterdir()
  225. if child.is_dir()
  226. and child.name not in _STAGING_SKIPPED_DIRS
  227. and not is_skipped_plugin_dir(child.name)
  228. )
  229. except OSError:
  230. return []
  231. def _category_plugins(path: Path) -> list[Path]:
  232. """The plugin subdirectories of a manifest-less *path* when it is a category, else ``[]``.
  233. A category is a directory whose candidate subdirectories (:func:`_candidate_dirs`) all hold
  234. a manifest. A plugin checkout next to other directories (``$HOME`` beside ``.hermes``, a repo
  235. root beside ``tests/``) is not a category."""
  236. children = _candidate_dirs(path)
  237. return children if children and all(_has_manifest(child) for child in children) else []
  238. def _holds_plugin(path: Path) -> bool:
  239. """True when *path* holds a manifest or is a category (:func:`_category_plugins`). Stricter
  240. than discovery on purpose: resolving an arbitrary directory (e.g. the default ``.``) would
  241. send Doctor to validate whatever plugin happens to sit inside it."""
  242. return path.is_dir() and (_has_manifest(path) or bool(_category_plugins(path)))
  243. def _is_plugin_id(raw: str) -> bool:
  244. """True when *raw* can name an installed plugin (relative, maybe ``category/name``). Dot
  245. components are excluded: ``.`` joined onto a plugins root would hand Doctor every plugin."""
  246. if not raw or PurePath(raw).is_absolute():
  247. return False
  248. parts = PurePath(raw).parts
  249. return bool(parts) and all(part not in {os.curdir, os.pardir} for part in parts)
  250. def resolve_plugin_path(target: str | os.PathLike[str] | None = None) -> Path:
  251. """Resolve an explicit path or an installed/bundled plugin id."""
  252. raw = os.fspath(target or ".")
  253. direct = Path(raw).expanduser()
  254. direct_is_dir = direct.is_dir()
  255. if direct_is_dir and _holds_plugin(direct):
  256. return direct.resolve()
  257. candidates: list[Path] = []
  258. if _is_plugin_id(raw):
  259. candidates.append(get_hermes_home() / "plugins" / raw)
  260. try:
  261. from hermes_cli.plugins import get_bundled_plugins_dir
  262. bundled = get_bundled_plugins_dir()
  263. candidates += [bundled / raw, bundled / "platforms" / raw, bundled / "model-providers" / raw]
  264. except Exception:
  265. pass
  266. candidates.append(Path.cwd() / ".hermes" / "plugins" / raw)
  267. for candidate in candidates:
  268. if _holds_plugin(candidate):
  269. return candidate.resolve()
  270. if direct_is_dir:
  271. nested = [os.path.join(raw, c.name) for c in _candidate_dirs(direct) if _has_manifest(c)]
  272. if nested:
  273. hint = f"Point Doctor at a plugin directory inside it: {', '.join(nested)}."
  274. else:
  275. hint = "Point Doctor at a plugin directory."
  276. raise FileNotFoundError(
  277. f"{direct.resolve()} holds no plugin manifest "
  278. f"({', '.join(_MANIFEST_NAMES)}), and {raw!r} is not an installed "
  279. f"plugin id. {hint}")
  280. raise FileNotFoundError(f"Plugin {raw!r} was not found as a path or installed plugin id")
  281. def _accepts_var_kwargs(callback: Any) -> bool:
  282. try:
  283. parameters = inspect.signature(callback).parameters.values()
  284. except (TypeError, ValueError):
  285. return False
  286. return any(parameter.kind is inspect.Parameter.VAR_KEYWORD for parameter in parameters)
  287. def _check_manifest_v2(report: DoctorReport, manifest: Any) -> None:
  288. """Manifest v2 checks: versions, deps, pip declarations, config schema."""
  289. import importlib.metadata
  290. import re as _re
  291. from hermes_cli.plugins import SUPPORTED_MANIFEST_VERSION
  292. mv = getattr(manifest, "manifest_version", 1)
  293. if mv > SUPPORTED_MANIFEST_VERSION:
  294. report.warning(
  295. f"manifest_version {mv} is newer than this Hermes supports "
  296. f"({SUPPORTED_MANIFEST_VERSION}); unknown fields are ignored")
  297. api_version = getattr(manifest, "api_version", None)
  298. if api_version is not None and api_version < 1:
  299. report.warning(f"api_version {api_version} is not a valid API generation (>= 1)")
  300. for dep in getattr(manifest, "requires_plugins", []) or []:
  301. dep_id = dep.get("id") if isinstance(dep, dict) else None
  302. if not dep_id:
  303. report.warning(f"requires_plugins entry {dep!r} has no plugin id")
  304. continue
  305. vr = dep.get("version_range")
  306. if vr:
  307. report.warning(
  308. f"requires plugin {dep_id!r} ({vr}) — version ranges are "
  309. "advisory; a missing dependency logs a warning at load")
  310. pydeps = getattr(manifest, "python_dependencies", []) or []
  311. missing: list[str] = []
  312. unpinned: list[str] = []
  313. for req in pydeps:
  314. dist = _re.split(r"[<>=!~\[;\s]", req, maxsplit=1)[0].strip()
  315. if not _re.search(r"<|==|~=", req):
  316. unpinned.append(req)
  317. if not dist:
  318. continue
  319. try:
  320. importlib.metadata.version(dist)
  321. except importlib.metadata.PackageNotFoundError:
  322. missing.append(req)
  323. except Exception:
  324. continue
  325. for req in unpinned:
  326. report.warning(
  327. f"python_dependencies entry {req!r} has no upper bound — "
  328. "pin an upper bound (e.g. 'pkg>=1.0,<2') per the dependency policy")
  329. if missing:
  330. report.warning(
  331. "declared python_dependencies not installed: " + ", ".join(missing)
  332. + " — install and enable the plugin with hermes plugins. "
  333. "For an enabled plugin, run hermes pm repair, then restart Hermes.")
  334. schema = getattr(manifest, "config_schema", {}) or {}
  335. if schema:
  336. from hermes_cli.plugins import _CONFIG_SCHEMA_TYPES
  337. for skey, spec in schema.items():
  338. stype = spec.get("type") if isinstance(spec, dict) else None
  339. if stype is not None and str(stype).lower() not in _CONFIG_SCHEMA_TYPES:
  340. report.warning(f"config_schema key {skey!r} declares unknown type {stype!r}")
  341. def _check_desktop_half_copy(report: DoctorReport, path: Path) -> None:
  342. """Warn when the Desktop app runs a stale copy of this package's desktop ``plugin.js``.
  343. Electron copies a unified package's desktop half to ``<root>/desktop-plugins/<name>/`` and loads
  344. THAT copy, so editing the package in place changes nothing on screen until the copy is refreshed.
  345. The copy carries a ``.hermes-package.json`` marker whose ``source`` names the folder it came from.
  346. """
  347. from hermes_cli.desktop_plugin_halves import desktop_source
  348. source_dir = desktop_source(path)
  349. if source_dir is None:
  350. return
  351. source = source_dir / "plugin.js"
  352. shown = source.relative_to(path).as_posix()
  353. from hermes_constants import get_default_hermes_root
  354. app_root = get_default_hermes_root() / "desktop-plugins"
  355. try:
  356. copies = sorted(app_root.glob("*/.hermes-package.json"))
  357. except OSError:
  358. return
  359. for marker_file in copies:
  360. try:
  361. marker = json.loads(marker_file.read_text(encoding="utf-8-sig"))
  362. if Path(marker["source"]).resolve() != source.parent.resolve():
  363. continue
  364. if (marker_file.parent / "plugin.js").read_bytes() == source.read_bytes():
  365. return
  366. except (OSError, ValueError, KeyError, TypeError):
  367. continue
  368. report.warning(
  369. f"Desktop runs a stale copy of {shown} ({marker_file.parent}); your edits are not "
  370. "loaded. Refresh it with Capabilities → Plugins → Rescan in the Desktop app (or restart it). "
  371. "To develop in place, symlink the checkout into plugins/ instead: the Desktop then re-syncs "
  372. "the copy on every save.")
  373. return
  374. def doctor_plugin(target: str | os.PathLike[str] | None = None) -> DoctorReport:
  375. """Validate one plugin through Hermes' real scanner and registration path."""
  376. try:
  377. path = resolve_plugin_path(target)
  378. except FileNotFoundError as exc:
  379. report = DoctorReport(Path(os.fspath(target or ".")).expanduser())
  380. report.error(str(exc))
  381. return report
  382. report = DoctorReport(path)
  383. try:
  384. with _doctor_runtime(path) as host:
  385. report.manifest = host.manifest
  386. report.registered_tools = host.registered_tools
  387. report.registered_hooks = host.registered_hooks
  388. report.registered_providers = host.registered_providers
  389. from hermes_cli.plugins import VALID_HOOKS
  390. declared_hooks = host.manifest.provides_hooks
  391. declared_tools = host.manifest.provides_tools
  392. if not isinstance(declared_hooks, list):
  393. report.error("provides_hooks must be a list")
  394. declared_hooks = []
  395. if not isinstance(declared_tools, list):
  396. report.error("provides_tools must be a list")
  397. declared_tools = []
  398. for name in declared_hooks:
  399. if not isinstance(name, str):
  400. report.error("provides_hooks entries must be strings")
  401. elif name not in VALID_HOOKS:
  402. report.error(f"unknown hook {name!r} in provides_hooks")
  403. for hook_name, callbacks in host.manager._hooks.items():
  404. if hook_name not in VALID_HOOKS:
  405. report.error(f"registered unknown hook {hook_name!r}")
  406. for callback in callbacks:
  407. if not _accepts_var_kwargs(callback):
  408. callback_name = getattr(callback, "__name__", repr(callback))
  409. report.error(
  410. f"hook callback {callback_name!r} for {hook_name!r} "
  411. "must accept **kwargs for forward compatibility")
  412. for kind, declared, registered in (
  413. ("hook", declared_hooks, host.registered_hooks),
  414. ("tool", declared_tools, host.registered_tools),
  415. ):
  416. declared_names = {name for name in declared if isinstance(name, str)}
  417. registered_names = set(registered)
  418. for name in sorted(declared_names - registered_names):
  419. report.warning(f"manifest declares {kind} {name!r} but registration did not add it")
  420. for name in sorted(registered_names - declared_names):
  421. report.warning(f"registration adds {kind} {name!r} not listed in provides_{kind}s")
  422. _check_manifest_v2(report, host.manifest)
  423. except _DoctorLoadError as exc:
  424. report.error(str(exc))
  425. except Exception as exc:
  426. report.error(f"unexpected validation failure: {type(exc).__name__}: {exc}")
  427. # Outside the runtime sandbox: it swaps HERMES_HOME for a temp dir, and the copy lives in the real one.
  428. _check_desktop_half_copy(report, path)
  429. return report
  430. __all__ = ["DoctorFinding", "DoctorReport", "doctor_plugin", "resolve_plugin_path"]