workspace.py 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749
  1. """Resolve core plus plugin requirements in a writable build snapshot.
  2. Shipped source and locks are inputs, never mutation targets. Candidate
  3. failure propagates without changing plugin configuration or the live venv.
  4. """
  5. from __future__ import annotations
  6. import hashlib
  7. import json
  8. import os
  9. import shutil
  10. from collections.abc import Iterable, Mapping
  11. from pathlib import Path
  12. from typing import TYPE_CHECKING, Optional
  13. if TYPE_CHECKING:
  14. from pm.environment import PythonEnvironment
  15. from pm import paths
  16. from pm.package import InstallError
  17. from pm.plugin_declarations import read_python_declaration, manifest_version_error
  18. _MEMBER_EXCLUDE = frozenset({".git", ".venv", "venv", "node_modules", "__pycache__"})
  19. def _member_ignored(directory, names):
  20. return [name for name in names if name in _MEMBER_EXCLUDE or name.endswith(".egg-info")]
  21. # The uv failure classifier lives beside the uv runner (stdlib-only imports): the bootstrap
  22. # runner streams uv output from a pre-3.11 system python where this module's tomllib import
  23. # cannot load. Workspace callers keep reaching it from here.
  24. from pm.environment import ResolutionConflict, classify_uv_failure
  25. def member_sources(plugin_dirs) -> dict[Path, Path]:
  26. """Map installed identities to build inputs, including staged plugin updates."""
  27. rows = plugin_dirs.items() if isinstance(plugin_dirs, Mapping) else ((path, path) for path in plugin_dirs)
  28. return {Path(identity).resolve(): Path(source).resolve() for identity, source in rows}
  29. def members_stamp(plugin_dirs) -> str:
  30. """Hash the member inputs copied into a generation, independent of staging paths."""
  31. h = hashlib.sha256()
  32. for identity, entry in sorted(member_sources(plugin_dirs).items()):
  33. h.update(str(identity).encode("utf-8"))
  34. h.update(b"\0")
  35. declaration = read_python_declaration(entry)
  36. for source in declaration.files:
  37. h.update(source.name.encode("utf-8"))
  38. h.update(source.read_bytes())
  39. h.update(b"\0")
  40. if (entry / "pyproject.toml").is_file():
  41. for directory, dirs, files in os.walk(entry):
  42. dirs[:] = sorted(set(dirs) - set(_member_ignored(directory, dirs)))
  43. for name in sorted(set(files) - set(_member_ignored(directory, files))):
  44. path = Path(directory) / name
  45. h.update(path.relative_to(entry).as_posix().encode())
  46. h.update(b"\0")
  47. h.update(os.readlink(path).encode() if path.is_symlink() else path.read_bytes())
  48. h.update(b"\0")
  49. return h.hexdigest()
  50. def _published_store_entries(directory: Path) -> frozenset[str]:
  51. """Names of the PM tool-store entries published in *directory*, if it is a store root.
  52. The container image keeps its store in the ``tools`` package directory, so the snapshot would
  53. otherwise copy every pinned interpreter, browser and media binary (about 1.5 GB) into each
  54. dependency generation. Nothing builds from them: the build runs the store's own tools in
  55. place. A directory counts as a store only when its ``facts.json`` records published entries,
  56. and only those entries (plus hash-keyed fetch caches) are left out.
  57. """
  58. try:
  59. facts = json.loads((directory / "facts.json").read_text(encoding="utf-8-sig"))
  60. except (OSError, ValueError):
  61. return frozenset()
  62. packages = facts.get("packages") if isinstance(facts, dict) else None
  63. if not isinstance(packages, dict):
  64. return frozenset()
  65. names = {fact["entry"] for fact in packages.values()
  66. if isinstance(fact, dict) and isinstance(fact.get("entry"), str)}
  67. names = {name for name in names if name and Path(name).name == name}
  68. names.update(child.name for child in directory.glob("fetch-*") if child.is_dir())
  69. return frozenset(name for name in names if (directory / name).is_dir())
  70. def _copy_core_inputs(source: Path, destination: Path) -> None:
  71. """Build from a writable snapshot, never from signed/read-only source."""
  72. import fnmatch
  73. import tomllib
  74. metadata = tomllib.loads((source / "pyproject.toml").read_text(encoding="utf-8-sig"))
  75. project = metadata.get("project", {})
  76. setuptools = metadata.get("tool", {}).get("setuptools", {})
  77. patterns = setuptools.get("packages", {}).get("find", {}).get("include", ["*"])
  78. package_roots = {pattern.split(".", 1)[0] for pattern in patterns}
  79. files = {"pyproject.toml", "setup.py", "setup.cfg"}
  80. readme = project.get("readme")
  81. if isinstance(readme, str):
  82. files.add(readme)
  83. elif isinstance(readme, dict) and "file" in readme:
  84. files.add(readme["file"])
  85. for pattern in project.get("license-files", []):
  86. files.update(str(p.relative_to(source)) for p in source.glob(pattern))
  87. files.update(p.name for p in source.glob("*.py"))
  88. # uv.lock is not excluded: the root lock is never copied (only ``files`` are; lock_and_sync
  89. # seeds or resolves it), and pm/uv.lock is the PM runtime's input (pm/runtime.py::_inputs).
  90. excluded = {".git", ".venv", "venv", "node_modules", "__pycache__", "build", "dist", "release"}
  91. # A root dist/ is build output, but below a package root it is shipped: the managed
  92. # environment runs from this snapshot and serves bundled plugins' dashboard/dist/.
  93. nested_excluded = excluded - {"dist"}
  94. def ignore(directory, names):
  95. published = _published_store_entries(Path(directory))
  96. return [name for name in names if name in nested_excluded or name.startswith(".")
  97. or name in published or name.endswith(".egg-info") or (Path(directory) / name).is_symlink()]
  98. for entry in source.iterdir():
  99. if (entry.is_dir() and not entry.is_symlink() and entry.name not in excluded
  100. and not entry.name.startswith(".") and entry.resolve() != destination.resolve()
  101. and any(fnmatch.fnmatchcase(entry.name, pattern) for pattern in package_roots)):
  102. target = destination / entry.name
  103. shutil.copytree(entry, target, ignore=ignore)
  104. for name in files:
  105. entry = source / name
  106. if not entry.is_file() or entry.is_symlink():
  107. continue
  108. if not entry.resolve().is_relative_to(source.resolve()):
  109. raise InstallError("venv", f"build input escapes the core project: {name}")
  110. target = destination / name
  111. target.parent.mkdir(parents=True, exist_ok=True)
  112. shutil.copy2(entry, target)
  113. def _generate_pyproject(plugin_dirs: list[Path] | Mapping[Path, Path], root: Path, *, source: Path,
  114. python: Path, extras: Iterable[str] = ()) -> None:
  115. """Snapshot core and plugin build inputs into a fresh generation for the *python* that installs it."""
  116. source = source.resolve()
  117. if root.resolve() == source or source.is_relative_to(root.resolve()):
  118. raise InstallError("venv", "workspace must not replace the core source")
  119. root.mkdir(parents=True)
  120. core_pyproject = source / "pyproject.toml"
  121. core_text = core_pyproject.read_text(encoding="utf-8-sig")
  122. candidates = {identity: source for identity, source in member_sources(plugin_dirs).items()
  123. if _is_member_candidate(source)}
  124. target = _target_environment(python) if candidates else {}
  125. members = [_workspace_member(source, root, identity=identity, extras=extras, target=target)
  126. .relative_to(root).as_posix() for identity, source in candidates.items()]
  127. if members:
  128. import tomllib
  129. import tomli_w
  130. document = tomllib.loads(core_text)
  131. uv_policy = document.setdefault("tool", {}).setdefault("uv", {})
  132. # Release age is checked when Hermes locks; users trust that lock (#135589).
  133. uv_policy.pop("exclude-newer", None)
  134. uv_policy.pop("exclude-newer-package", None)
  135. uv_policy["workspace"] = {"members": sorted(members)}
  136. # A member requirement naming core (a selected extra's ``hermes-agent[x] @ git+…``)
  137. # names a workspace member, which uv refuses without a source; root sources apply
  138. # to every member, renamed virtual ones included.
  139. uv_policy.setdefault("sources", {})[document["project"]["name"]] = {"workspace": True}
  140. _solve_only_for(uv_policy, target)
  141. text = tomli_w.dumps(document)
  142. else:
  143. # A member-less generation syncs frozen against core's own lock.
  144. text = core_text.rstrip("\n") + "\n"
  145. target = root / "pyproject.toml"
  146. text = _without_release_age(text)
  147. _copy_core_inputs(source, root)
  148. target.write_text(text, encoding="utf-8")
  149. def _without_release_age(text: str) -> str:
  150. """Drop ``[tool.uv] exclude-newer`` from a generated root's pyproject text.
  151. The lock already holds checked versions; on the user's machine the cutoff only gates the
  152. build tools uv fetches for source builds (setuptools for Hermes itself), and a mirror that
  153. serves no upload times rejects all of them (#135589). Text-level so the pre-3.11 bootstrap
  154. python, which has no tomllib, can run it.
  155. """
  156. import re
  157. return re.sub(r"(?m)^exclude-newer\s*=.*\n", "", text)
  158. # packaging.markers.default_environment(), computed by the target interpreter itself; stdlib
  159. # only, because that interpreter need not have packaging installed.
  160. _MARKER_ENVIRONMENT_PROBE = """
  161. import json, os, platform, sys
  162. v = sys.implementation.version
  163. level = "" if v.releaselevel == "final" else f"{v.releaselevel[0]}{v.serial}"
  164. print(json.dumps({
  165. "implementation_name": sys.implementation.name,
  166. "implementation_version": f"{v.major}.{v.minor}.{v.micro}{level}",
  167. "os_name": os.name,
  168. "platform_machine": platform.machine(),
  169. "platform_release": platform.release(),
  170. "platform_system": platform.system(),
  171. "platform_version": platform.version(),
  172. "python_full_version": platform.python_version(),
  173. "platform_python_implementation": platform.python_implementation(),
  174. "python_version": ".".join(platform.python_version_tuple()[:2]),
  175. "sys_platform": sys.platform,
  176. }))
  177. """
  178. def _target_environment(python: Path) -> dict[str, str]:
  179. """The PEP 508 marker environment of the interpreter that installs the generation.
  180. Asked of *python* rather than taken from this process, because PM can run under a
  181. bootstrap Python (an older Termux interpreter reports ``linux``) while uv evaluates
  182. markers against *python*.
  183. """
  184. import subprocess
  185. from pm.filesystem import native
  186. probe = subprocess.run([native(python), "-I", "-c", _MARKER_ENVIRONMENT_PROBE],
  187. capture_output=True, text=True, encoding="utf-8", check=True, timeout=60)
  188. return json.loads(probe.stdout)
  189. def _solve_only_for(uv_policy: dict, target: Mapping[str, str]) -> None:
  190. """Narrow ``tool.uv.environments`` to the platform of the interpreter that installs the generation.
  191. uv solves every platform the environments admit, and since uv 0.12.14 it fails the whole
  192. lock when one fork has no wheels for a dependency: onnxruntime and torch ship none for
  193. Android, so a Linux or macOS update evicted the plugin over a platform it never runs on.
  194. A generation installs into one interpreter on one machine (*target*, from
  195. ``_target_environment``); only core's committed lock has to cover every platform, and it
  196. never passes through here.
  197. """
  198. host = f"sys_platform == {target['sys_platform']!r} and platform_machine == {target['platform_machine']!r}"
  199. uv_policy["environments"] = [f"({entry}) and {host}" for entry in uv_policy.get("environments") or []] or [host]
  200. def _is_member_candidate(plugin_dir: Path) -> bool:
  201. return read_python_declaration(plugin_dir).installs_packages
  202. def enabled_plugin_entries(*, proposed_home=None, enabled=None, disabled=None,
  203. installing: Path | None = None,
  204. skip_invalid_secondary: bool = False) -> list[tuple[Path, str, Path]]:
  205. """``(home plugins dir, selection key, plugin dir)`` for every selected plugin, in config order.
  206. The key is what the home's config names, so a caller can edit that home's selection.
  207. """
  208. from pm.plugins_state import enabled_plugins_ordered
  209. selection = enabled_plugins_ordered(
  210. proposed_home=proposed_home, enabled=enabled, disabled=disabled, installing=installing,
  211. skip_invalid_secondary=skip_invalid_secondary,
  212. )
  213. entries = []
  214. for plugins_dir, names in selection.items():
  215. for name in names:
  216. plugin_dir = selected_plugin_dir(plugins_dir, name, installing=installing)
  217. if plugin_dir is not None:
  218. entries.append((plugins_dir, name, plugin_dir))
  219. return entries
  220. def selected_plugin_dir(plugins_dir: Path, name: str, *, installing: Path | None = None) -> Path | None:
  221. """The tree a home's selection key names: its own plugins dir first, then core's, else None."""
  222. from pm.plugins_state import _is_directory
  223. relative = Path(name)
  224. if relative.is_absolute() or ".." in relative.parts:
  225. raise InstallError("venv", f"invalid plugin key: {name}")
  226. plugin_dir = plugins_dir / relative
  227. if installing is not None and plugin_dir.resolve() == installing.resolve():
  228. return plugin_dir
  229. if not _is_directory(plugin_dir):
  230. plugin_dir = paths.repo_root() / "plugins" / relative
  231. return plugin_dir if _is_directory(plugin_dir) else None
  232. def enabled_plugin_dirs(*, proposed_home=None, enabled=None, disabled=None,
  233. installing: Path | None = None, skip_invalid_secondary: bool = False) -> list[Path]:
  234. """Resolve the effective plugin selection without filtering dependency declarations."""
  235. entries = enabled_plugin_entries(proposed_home=proposed_home, enabled=enabled, disabled=disabled,
  236. installing=installing, skip_invalid_secondary=skip_invalid_secondary)
  237. return list(dict.fromkeys(plugin_dir for _plugins_dir, _name, plugin_dir in entries))
  238. def enabled_member_dirs(*, proposed_home=None, enabled=None, disabled=None) -> list[Path]:
  239. """Keep every selected member or refuse an incompatible selection.
  240. A member that does not accept the running Hermes (``hermes_fit_error``) sits out instead:
  241. the verdict is only as good as our version identity (an untagged source checkout reads
  242. as an older release), the loader skips that plugin anyway, and the member rejoins as
  243. soon as the verdict flips. Enabling one is still refused at admission. Judged with no
  244. core extra selected; ``build_member_dirs`` adds the extras a build selects.
  245. """
  246. selected = enabled_plugin_dirs(proposed_home=proposed_home, enabled=enabled, disabled=disabled,
  247. skip_invalid_secondary=proposed_home is None)
  248. members = []
  249. for path in selected:
  250. declaration = read_python_declaration(path)
  251. if hermes_fit_error(declaration, ()):
  252. continue
  253. reason = manifest_version_error(declaration.manifest, path.name)
  254. if reason:
  255. raise InstallError("venv", reason)
  256. if declaration.installs_packages:
  257. members.append(path)
  258. return members
  259. def build_member_dirs(extras: Iterable[str], python: Path | None = None) -> list[Path]:
  260. """``enabled_member_dirs`` for a build selecting core *extras*: a plugin extra they select
  261. can add a ``hermes-agent`` requirement the running Hermes misses, which sits out too.
  262. A build passes its interpreter *python*, whose markers the generation (and so the loader)
  263. sees; PM itself may run under a bootstrap Python."""
  264. extras, members = list(extras), enabled_member_dirs()
  265. target = _target_environment(python) if members and python is not None else None
  266. return [path for path in members
  267. if not core_requirement_error(read_python_declaration(path), extras, target)]
  268. def _member_key(identity: Path) -> str:
  269. """``<plugin dir name>-<sha256(path)[:16]>``: the hash keeps two same-named plugins from
  270. different homes apart; the name is what a user sees in uv's conflict text
  271. (``hermes-plugin-<key> depends on …``) — a bare hash told them nothing to disable."""
  272. import re
  273. digest = hashlib.sha256(str(identity.resolve()).encode()).hexdigest()[:16]
  274. name = re.sub(r"[^a-z0-9._-]+", "-", identity.name.lower()).strip("-.") or "plugin"
  275. return f"{name}-{digest}"
  276. def _selected_member_extras(document: dict, extras: Iterable[str],
  277. target: Mapping[str, str] | None = None) -> tuple[set[str], set[str]]:
  278. """The member's extras this generation installs, and those it only names.
  279. Installed: those ``uv sync --extra`` names (it applies a name to every member declaring
  280. it), closed over the member's own ``name[extra]`` references, which install whatever
  281. references them. A reference is evaluated on *target* (the installing interpreter's
  282. marker environment) under every extra this sync installs, so a base dependency
  283. ``plugin[feature]; extra == 'runtime'`` installs ``feature`` once ``runtime`` is in, and
  284. ``plugin[windows]; sys_platform == 'win32'`` installs no ``windows`` on Linux; that extra
  285. is returned as named, because the build backend still validates the reference against
  286. the extras table. With no *target*, or a marker it cannot evaluate, the reference installs.
  287. """
  288. from packaging.utils import canonicalize_name
  289. from pm.install import _extra_key
  290. project = document.get("project", {})
  291. declared = {_extra_key(key): specs for key, specs in project.get("optional-dependencies", {}).items()}
  292. own = canonicalize_name(str(project.get("name", "")))
  293. selected = {_extra_key(extra) for extra in extras} & declared.keys()
  294. references = {"": _self_references(project.get("dependencies", []), own)}
  295. while True:
  296. for key in selected - references.keys():
  297. references[key] = _self_references(declared[key], own)
  298. contexts = ("", *sorted(selected))
  299. reached = {key for requirements in references.values() for requirement in requirements
  300. if _reference_active(requirement, contexts, target)
  301. for key in {_extra_key(name) for name in requirement.extras} & declared.keys()}
  302. if reached <= selected:
  303. break
  304. selected |= reached
  305. named = {key for requirements in references.values() for requirement in requirements
  306. for key in {_extra_key(name) for name in requirement.extras} & declared.keys()}
  307. return selected, named - selected
  308. def _self_references(specs: Iterable[str], own: str) -> list:
  309. """The requirements among *specs* that name the project *own* itself."""
  310. from packaging.requirements import InvalidRequirement, Requirement
  311. from packaging.utils import canonicalize_name
  312. references = []
  313. for spec in specs:
  314. try:
  315. requirement = Requirement(spec)
  316. except InvalidRequirement:
  317. continue # uv reports it; this pass only decides what to keep.
  318. if canonicalize_name(requirement.name) == own:
  319. references.append(requirement)
  320. return references
  321. def _reference_active(requirement, contexts: Iterable[str], target: Mapping[str, str] | None) -> bool:
  322. """Whether *requirement* applies on *target* under any of the installed extra *contexts*.
  323. uv lowers an extra's requirements to ``marker and extra == '<that extra>'``, and that extra
  324. is among *contexts* once it is reached, so one evaluation per installed extra covers base
  325. and extra requirements alike; a conjunction over two extras is kept, never dropped.
  326. """
  327. from packaging.markers import UndefinedComparison, UndefinedEnvironmentName
  328. if requirement.marker is None or target is None:
  329. return True
  330. try:
  331. return any(requirement.marker.evaluate({**target, "extra": extra}) for extra in contexts)
  332. except (UndefinedComparison, UndefinedEnvironmentName):
  333. return True
  334. def _prune_member_sources(settings: dict, installed: set[str]) -> bool:
  335. """Drop ``tool.uv.sources`` alternatives for an extra or group this generation removed.
  336. uv refuses a source qualified by an extra or group the project no longer declares
  337. ("Source entry ... only applies to extra `dev`, but the `dev` extra does not exist"), so a
  338. pruned development extra must take its sources with it. An extra declared but left empty
  339. installs nothing, so its sources go too. A package keeps its key while any alternative
  340. remains; unqualified (runtime) alternatives always stay.
  341. """
  342. from pm.install import _extra_key
  343. sources = settings.get("sources")
  344. if not isinstance(sources, dict):
  345. return False
  346. def applies(spec) -> bool:
  347. if not isinstance(spec, dict):
  348. return True
  349. if "group" in spec:
  350. return False
  351. return "extra" not in spec or _extra_key(str(spec["extra"])) in installed
  352. pruned = {}
  353. for package, entry in sources.items():
  354. if isinstance(entry, list):
  355. alternatives = [spec for spec in entry if applies(spec)]
  356. if alternatives:
  357. pruned[package] = alternatives
  358. elif applies(entry):
  359. pruned[package] = entry
  360. if pruned == sources:
  361. return False
  362. if pruned:
  363. settings["sources"] = pruned
  364. else:
  365. settings.pop("sources")
  366. return True
  367. def _rename_virtual_member(document: dict, name: str) -> None:
  368. """Give a virtual member its unique workspace *name*, its self-references included.
  369. ``dependencies = ["myplugin[runtime]"]`` in a project named ``myplugin`` installs the
  370. member's own ``runtime`` extra. Left on the declared name after the rename, uv reads it as
  371. a different package: a lock failure when no index has that name, or someone else's
  372. package installed in place of the extra when one does. Extras, specifiers and markers
  373. stay as written; only the leading name changes.
  374. """
  375. import re
  376. from packaging.requirements import InvalidRequirement, Requirement
  377. from packaging.utils import canonicalize_name
  378. project = document.setdefault("project", {})
  379. own = canonicalize_name(str(project.get("name", "")))
  380. project["name"] = name
  381. if not own:
  382. return
  383. def renamed(spec):
  384. try:
  385. if not isinstance(spec, str) or canonicalize_name(Requirement(spec).name) != own:
  386. return spec
  387. except InvalidRequirement:
  388. return spec # uv reports it; renaming cannot make it valid.
  389. return re.sub(r"^\s*[A-Za-z0-9][A-Za-z0-9._-]*", name, spec, count=1)
  390. if "dependencies" in project:
  391. project["dependencies"] = [renamed(spec) for spec in project["dependencies"]]
  392. for extra, specs in project.get("optional-dependencies", {}).items():
  393. project["optional-dependencies"][extra] = [renamed(spec) for spec in specs]
  394. for conflict in document.get("tool", {}).get("uv", {}).get("conflicts", []):
  395. for item in conflict:
  396. if isinstance(item, dict) and canonicalize_name(str(item.get("package", ""))) == own:
  397. item["package"] = name
  398. def _runtime_member_metadata(document: dict, extras: Iterable[str],
  399. target: Mapping[str, str] | None = None) -> bool:
  400. """Keep what this generation installs, not a plugin checkout's development environment.
  401. uv locks every declared group and extra of every member even when sync excludes it, so a
  402. test pin (``dev = ["httpx<0.28"]``) would fail the lock against core's runtime pins. Sync
  403. never installs a member's groups (core's ``default-groups = []`` covers the workspace) and
  404. installs only the extras named by ``--extra``. The original plugin source stays untouched.
  405. """
  406. from pm.install import _extra_key
  407. changed = "dependency-groups" in document
  408. document.pop("dependency-groups", None)
  409. project = document.get("project", {})
  410. optional = project.get("optional-dependencies")
  411. keep: set[str] = set()
  412. if optional:
  413. keep, named = _selected_member_extras(document, extras, target)
  414. # A named-only extra stays declared but empty: its pins cannot reach the lock.
  415. kept = {key: specs if _extra_key(key) in keep else [] for key, specs in optional.items()
  416. if _extra_key(key) in keep | named}
  417. if kept != optional:
  418. changed = True
  419. if kept:
  420. project["optional-dependencies"] = kept
  421. else:
  422. project.pop("optional-dependencies")
  423. kept_extras = {_extra_key(key) for key in project.get("optional-dependencies", {})}
  424. settings = document.get("tool", {}).get("uv", {})
  425. changed = _prune_member_sources(settings, keep) or changed
  426. for key in ("default-groups", "dependency-groups", "dev-dependencies"):
  427. if key in settings:
  428. settings.pop(key)
  429. changed = True
  430. if "conflicts" in settings:
  431. conflicts = [[spec for spec in conflict
  432. if "group" not in spec and ("extra" not in spec or _extra_key(spec["extra"]) in kept_extras)]
  433. for conflict in settings["conflicts"]]
  434. conflicts = [conflict for conflict in conflicts if len(conflict) > 1]
  435. if conflicts != settings["conflicts"]:
  436. if conflicts:
  437. settings["conflicts"] = conflicts
  438. else:
  439. settings.pop("conflicts")
  440. changed = True
  441. return changed
  442. def _recorded_extras() -> list[str]:
  443. """The extras of the generation this install selected: what a gate asked outside a build
  444. (admission, the loader) evaluates a plugin's extras under."""
  445. from pm.environments import runtime_facts_path
  446. from pm.lock import Facts
  447. extras = (Facts(runtime_facts_path(paths.repo_root())).get("venv") or {}).get("extras")
  448. return [extra for extra in extras if isinstance(extra, str)] if isinstance(extras, list) else []
  449. def core_requirement_error(declaration, extras: Iterable[str] | None = None,
  450. target: Mapping[str, str] | None = None) -> Optional[str]:
  451. """Why the plugin's applicable requirement on ``hermes-agent`` rejects the running Hermes.
  452. PM satisfies ``hermes-agent`` from the checkout itself: a runtime requirement naming it is
  453. dropped, and a selected extra naming it binds to the workspace root, where uv ignores the
  454. specifier. So the specifier is judged here, PEP 440 like any requirement, under *extras*
  455. (the core extras the build selects; ``None`` reads the recorded selection) and the markers
  456. of *target* (the installing interpreter; ``None`` is this process, which the loader runs
  457. in). The identity is the one ``requires_hermes`` reads (the committed pyproject version is
  458. a placeholder); with none (``unknown``) nothing is judged. It is read only for a plugin
  459. that names core: the read walks git, and every plugin passes here at startup.
  460. """
  461. import tomllib
  462. from packaging.markers import default_environment
  463. from packaging.version import InvalidVersion, Version
  464. from hermes_cli.plugins_manifest import running_hermes_version
  465. from pm.install import _extra_key
  466. if declaration.external:
  467. return None
  468. environment = default_environment() if target is None else target
  469. specs, installed = list(declaration.requirements), set()
  470. if declaration.pyproject is not None:
  471. document = tomllib.loads(declaration.pyproject.read_text(encoding="utf-8-sig"))
  472. installed = _selected_member_extras(document, _recorded_extras() if extras is None else extras, environment)[0]
  473. specs += [spec for name, values in document["project"].get("optional-dependencies", {}).items()
  474. if _extra_key(name) in installed for spec in values]
  475. pins = [requirement for requirement in _self_references(specs, "hermes-agent")
  476. if requirement.specifier and _reference_active(requirement, ("", *sorted(installed)), environment)]
  477. if not pins:
  478. return None
  479. current = running_hermes_version()
  480. try:
  481. Version(current)
  482. except InvalidVersion:
  483. return None
  484. rejected = [str(requirement) for requirement in pins
  485. if not requirement.specifier.contains(current, prereleases=True)]
  486. return f"requires {rejected[0]}, running {current}" if rejected else None
  487. def hermes_fit_error(declaration, extras: Iterable[str] | None = None) -> Optional[str]:
  488. """Why this Hermes is not one the plugin accepts: its ``requires_hermes`` or an applicable
  489. ``hermes-agent`` requirement rejects the running version. Either verdict is only as good as
  490. our version identity, so a selected misfit sits out of the build (config untouched) and
  491. rejoins once it flips; admission refuses it."""
  492. from hermes_cli.plugins_manifest import requires_hermes_error
  493. return requires_hermes_error(declaration.manifest) or core_requirement_error(declaration, extras)
  494. def _workspace_member(plugin_dir: Path, root: Path, *, identity: Path, extras: Iterable[str] = (),
  495. target: Mapping[str, str] | None = None) -> Path:
  496. """Keep workspace members with their generation, not a temporary install clone."""
  497. import json
  498. import tomllib
  499. key = _member_key(identity)
  500. declaration = read_python_declaration(plugin_dir)
  501. pyproject = declaration.pyproject
  502. if pyproject is not None:
  503. member = root / "plugin-sources" / key
  504. shutil.copytree(plugin_dir, member, symlinks=True,
  505. ignore=_member_ignored)
  506. document = tomllib.loads(pyproject.read_text(encoding="utf-8-sig"))
  507. # uv identifies a workspace member by [project].name, so the same virtual
  508. # plugin enabled in two profiles would declare one name twice and fail
  509. # `uv lock`. A member with no build backend is metadata-only: it can carry
  510. # the unique key in its name, as manifest-only members already do. A
  511. # buildable member keeps its declared name — uv verifies it against the
  512. # package metadata its backend produces.
  513. # tool.uv.package = true opts into uv package mode: real build metadata, so buildable.
  514. virtual = "build-system" not in document and document.get("tool", {}).get("uv", {}).get("package") is not True
  515. changed = False
  516. if declaration.install_requirements != declaration.requirements:
  517. document["project"]["dependencies"] = list(declaration.install_requirements)
  518. changed = True
  519. if virtual:
  520. # Before the extras pass, so its self-reference closure reads the names uv will see.
  521. _rename_virtual_member(document, f"hermes-plugin-{key}")
  522. changed = _runtime_member_metadata(document, extras, target) or changed
  523. for sources in document.get("tool", {}).get("uv", {}).get("sources", {}).values():
  524. for spec in sources if isinstance(sources, list) else [sources]:
  525. if not isinstance(spec, dict) or "path" not in spec:
  526. continue
  527. relative = Path(spec["path"])
  528. if relative.is_absolute():
  529. continue
  530. resolved = (plugin_dir / relative).resolve()
  531. if resolved.is_relative_to(plugin_dir.resolve()):
  532. continue # The referenced tree was copied with this member.
  533. spec["path"] = (identity / relative).resolve().as_posix()
  534. changed = True
  535. project = document.get("project")
  536. # uv rejects any [project] table whose version is neither set nor dynamic, at
  537. # parse time and for buildable members too, so a version-less member would abort
  538. # every `uv lock` of the workspace. Give it the same inert version plugin-deps use.
  539. # PEP 621 forbids a static version while "version" is listed under
  540. # project.dynamic, so an explicitly dynamic version is left alone.
  541. if project is not None and "version" not in project and "version" not in project.get("dynamic", ()):
  542. project["version"] = "0.0.0"
  543. changed = True
  544. if virtual or changed:
  545. import tomli_w
  546. (member / "pyproject.toml").write_text(tomli_w.dumps(document), encoding="utf-8")
  547. return member
  548. specs = declaration.install_requirements
  549. member = root / "plugin-deps" / key
  550. member.mkdir(parents=True)
  551. (member / "pyproject.toml").write_text(
  552. f'[project]\nname = "hermes-plugin-{key}"\nversion = "0.0.0"\n'
  553. 'requires-python = ">=3.11"\n'
  554. f'dependencies = {json.dumps(specs)}\n[tool.uv]\npackage = false\n',
  555. encoding="utf-8",
  556. )
  557. return member
  558. def install_node_sidecar(
  559. plugin_dir: Path,
  560. *,
  561. explicit: bool = False,
  562. ) -> Optional[str]:
  563. """Install plugin-local dependencies using PM's paired npm/Node context.
  564. Explicit user consent permits acquisition even when on-demand installs
  565. are disabled. Returns None on success, otherwise a diagnostic.
  566. """
  567. package_json = plugin_dir / "package.json"
  568. if not package_json.is_file():
  569. return None # nothing to install
  570. import pm
  571. from pm.install import lazy_installs_allowed
  572. # Tool availability does not authorize mutation of the sidecar itself.
  573. if not explicit and not lazy_installs_allowed():
  574. return "lazy installs are disabled — run `hermes plugins install` and approve Node dependencies"
  575. # a lockfile means reproducible `npm ci`; plain `npm install` otherwise
  576. install_cmd = ["ci"] if (plugin_dir / "package-lock.json").is_file() else ["install"]
  577. try:
  578. runner = pm.ensure("npm", explicit=explicit)
  579. # Resolve inside the composed context, including npm.cmd on Windows;
  580. # CreateProcess does not search a child's replacement PATH itself.
  581. npm = shutil.which("npm", path=runner.env.get("PATH", ""))
  582. if npm is None:
  583. return "npm is missing from the prepared PM environment"
  584. proc = runner.run(
  585. [npm, *install_cmd, "--no-audit", "--no-fund"],
  586. cwd=str(plugin_dir),
  587. capture_output=True,
  588. text=True,
  589. encoding="utf-8",
  590. errors="replace",
  591. timeout=900,
  592. )
  593. except Exception as exc:
  594. return f"npm {install_cmd[0]} failed to run: {exc}"
  595. if proc.returncode != 0:
  596. tail = (proc.stderr or proc.stdout or "").strip()[-300:]
  597. return f"npm {install_cmd[0]} exited {proc.returncode}: {tail}"
  598. return None
  599. def lock_and_sync(
  600. plugin_dirs: list[Path] | Mapping[Path, Path],
  601. extras: list[str],
  602. *,
  603. root: Path,
  604. source: Path,
  605. seed_lock: Path | None,
  606. environment: PythonEnvironment,
  607. frozen: bool = False,
  608. replay: Path | None = None,
  609. ) -> None:
  610. """Prepare a fresh generation using explicit inputs and a prepared engine.
  611. The caller selects the seed; uv retains its compatible versions. Repair
  612. copies the recorded build inputs and never reads current manifests.
  613. Resolver conflicts remain distinct from download/build failures.
  614. """
  615. if root.exists() or root.is_symlink():
  616. raise InstallError("venv", f"workspace must be fresh: {root}")
  617. if replay is None:
  618. _generate_pyproject(plugin_dirs, root, source=source, python=environment.python, extras=extras)
  619. if seed_lock is not None:
  620. (root / "uv.lock").write_bytes(seed_lock.read_bytes())
  621. else:
  622. if not (replay / "pyproject.toml").is_file() or not (replay / "uv.lock").is_file():
  623. raise InstallError("venv", f"recorded workspace is missing: {replay}")
  624. # Sibling generations keep external relative paths at the same depth;
  625. # snapshotted members and their exact lock travel with the workspace.
  626. # Use the snapshot's exclusions: build/ may hold an in-tree backend.
  627. shutil.copytree(replay, root, symlinks=True, ignore=_member_ignored)
  628. # A generation recorded before the cutoff left the user's machine still carries it.
  629. manifest = root / "pyproject.toml"
  630. manifest.write_text(_without_release_age(manifest.read_text(encoding="utf-8-sig")), encoding="utf-8")
  631. frozen = True
  632. environment.sync(root, extras=extras, frozen=frozen)