install.py 51 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157
  1. """ensure(): make the installed state match the lockfile for a package,
  2. and hand back its composed environment."""
  3. from __future__ import annotations
  4. import json
  5. import logging
  6. import os
  7. import shutil
  8. import threading
  9. from contextlib import ExitStack, contextmanager, nullcontext
  10. from dataclasses import dataclass
  11. from pathlib import Path
  12. from typing import Optional
  13. from pm import paths
  14. from pm.downloader import DownloadPaused, ProgressFn
  15. from pm.filesystem import native, remove_tree, retry_held
  16. from pm.lock import Facts, Lockfile
  17. from pm.package import InstallError, Package, Runner, StatePackage, compose_env
  18. from pm.plugin_inputs import Candidates, Members, PluginInput, Selection, StagedUpdate
  19. from pm.registry import get_package, walk
  20. from pm.store import Store, current_target, digest_matches, merge_tree, tree_digest
  21. LOG = logging.getLogger(__name__)
  22. # ``progress(stage, done, total, label)`` reports download/unpack/verify;
  23. # multi-archive labels follow lockfile order.
  24. def _prepare_artifacts(package, store, scratch, artifacts, version, target, *,
  25. progress=None, pause_event=None, download_progress=None):
  26. def tick(done, total, ranges):
  27. if progress is not None:
  28. active = next(reversed(ranges))
  29. index = next(i for i, artifact in enumerate(artifacts) if artifact["url"] == active)
  30. label = f"{index + 1}/{len(artifacts)}" if len(artifacts) > 1 else ""
  31. progress("download", done, total, label)
  32. if download_progress is not None:
  33. download_progress(done, total, ranges)
  34. staged = scratch / "tree"
  35. archives = store.fetch_many(artifacts, scratch, progress=tick, pause_event=pause_event)
  36. for index, archive in enumerate(archives):
  37. if pause_event is not None and pause_event.is_set():
  38. raise DownloadPaused("install paused")
  39. if progress is not None:
  40. label = f"{index + 1}/{len(artifacts)}" if len(artifacts) > 1 else ""
  41. progress("unpack", 0, 0, label)
  42. # unpack empties its destination; extract additional archives separately.
  43. destination = staged if index == 0 else scratch / f"extra-{index}"
  44. package.unpack(archive, destination, target)
  45. if index:
  46. merge_tree(destination, staged)
  47. package.stage(store, staged, version, target)
  48. return staged
  49. def _lockfile() -> Lockfile:
  50. return Lockfile(paths.lockfile_path())
  51. def _facts() -> Facts:
  52. return Facts(paths.facts_path())
  53. def _store() -> Store:
  54. return Store(paths.store_root())
  55. def _heal_exec_bit(binary: Path, *, heal: bool = True) -> bool:
  56. """Store entries staged from archives that drop the exec bit sit at 0644 and fail every
  57. launch with PermissionError. Modes are not part of the pinned digest, so restore it in place;
  58. an entry we cannot chmod (sealed store), or may not (``heal=False``), is treated as not
  59. installed."""
  60. if os.name == "nt" or os.access(binary, os.X_OK):
  61. return True
  62. if not heal:
  63. return False
  64. try:
  65. binary.chmod(binary.stat().st_mode | 0o111)
  66. except OSError:
  67. return False
  68. return os.access(binary, os.X_OK)
  69. def _installed_location(package: Package, lockfile: Lockfile, target: str, *,
  70. verify: bool = False, allow_outdated: bool = False,
  71. roots: tuple[Path, ...] | None = None, heal: bool = True):
  72. """Prefer the current pin. An explicit read may retain a prior PM install. ``heal=False``
  73. keeps the lookup read-only (scripts/tool_store_pins.py asks it about a store it must not touch)."""
  74. search_roots = dict.fromkeys(roots if roots is not None else (paths.store_root(), paths.writable_store_root()))
  75. fallback = None
  76. for root in search_roots:
  77. store = Store(root)
  78. facts = _facts() if root == paths.store_root() else Facts(root / "facts.json")
  79. fact = facts.get(package.name)
  80. if not fact or not facts.installed(package.name, None, store.root):
  81. continue
  82. binary = package.binary(store.entry(fact["entry"]), target)
  83. if binary is not None and not binary.is_file():
  84. continue
  85. if binary is not None and target == current_target() and not _heal_exec_bit(binary, heal=heal):
  86. continue
  87. if verify and not _entry_verified(package, fact, store, target):
  88. continue
  89. if facts.installed(package.name, lockfile.version(package.name), store.root,
  90. _identity(lockfile, package.name, target)):
  91. return facts, store
  92. if (allow_outdated and fact.get("target") == target
  93. and fact.get("artifacts") and fact.get("digest")):
  94. fallback = facts, store
  95. return fallback
  96. @dataclass(frozen=True)
  97. class InstalledPackage:
  98. path: Path
  99. version: str
  100. binary: Path | None
  101. def installed_package(name: str, *, allow_outdated: bool = False) -> InstalledPackage | None:
  102. """Read the selected PM entry without installing or changing its facts."""
  103. package = get_package(name)
  104. if package.internal:
  105. raise ValueError(f"{name} is internal PM tooling, not an application package")
  106. target = current_target()
  107. location = _installed_location(package, _lockfile(), target, allow_outdated=allow_outdated)
  108. if location is None:
  109. return None
  110. facts, store = location
  111. fact = facts.get(name)
  112. entry = store.entry(fact["entry"])
  113. binary = package.binary(entry, target)
  114. # Callers execute and compare these paths outside PM: the ordinary spelling, not the store's.
  115. return InstalledPackage(Path(native(entry)), fact["version"],
  116. Path(native(binary)) if binary is not None else None)
  117. def uv_launcher(name: str) -> Path | None:
  118. """PM's installed ``uv``/``uvx`` for a user-declared MCP stdio ``command:``, so a bare
  119. ``uvx`` server runs the packaged uv, never the user's. Read-only; Hermes's own Python
  120. work still goes through PM operations, not this executable."""
  121. if name not in ("uv", "uvx"):
  122. raise ValueError(f"{name!r} is not a uv launcher")
  123. package = get_package("uv")
  124. target = current_target()
  125. location = _installed_location(package, _lockfile(), target)
  126. if location is None:
  127. return None
  128. facts, store = location
  129. binary = package.binary(store.entry(facts.get("uv")["entry"]), target)
  130. launcher = binary.with_name(name + binary.suffix) if binary is not None else None
  131. return Path(native(launcher)) if launcher is not None and launcher.is_file() else None
  132. def _identity(lockfile: Lockfile, name: str, target: str):
  133. """The identity the lock currently pins for `name` on `target`:
  134. (target, tuple(artifact sha256s)) — or None when the lock pins no
  135. artifacts (nothing digest-bound to compare)."""
  136. artifacts = lockfile.artifacts(name, target)
  137. if not artifacts:
  138. return None
  139. return (target, tuple(a["sha256"] for a in artifacts))
  140. def lazy_installs_allowed() -> bool:
  141. """Policy: may pm install things on demand right now?
  142. HERMES_DISABLE_LAZY_INSTALLS is an internal bridge var set by the
  143. official Docker image and the hermetic test harness. The user-facing
  144. setting is security.allow_lazy_installs in config.yaml; a config
  145. system that fails to load counts as ALLOWED only when hermes_cli is
  146. genuinely absent (bootstrap) — config errors fail closed.
  147. """
  148. import os
  149. if os.environ.get("HERMES_DISABLE_LAZY_INSTALLS", "").strip().lower() in (
  150. "1",
  151. "true",
  152. "yes",
  153. ):
  154. return False
  155. try:
  156. from hermes_cli.config import cfg_get, load_config_readonly, require_readable_config_before_write
  157. except ModuleNotFoundError as exc:
  158. return exc.name in {"hermes_cli", "hermes_cli.config"}
  159. except ImportError:
  160. return False
  161. try:
  162. # The normal loader falls back to defaults on invalid YAML. A broken
  163. # security policy must not grant permission to acquire dependencies.
  164. require_readable_config_before_write()
  165. return cfg_get(load_config_readonly(), "security", "allow_lazy_installs", default=True) is True
  166. except Exception:
  167. return False
  168. def enabled_extras() -> list[str]:
  169. """The venv extras recorded in the installed state."""
  170. fact = Facts(paths.runtime_facts_path()).get("venv") or _facts().get("venv") or {}
  171. return list(fact.get("extras", []))
  172. def is_installed(name: str) -> bool:
  173. return _installed_location(get_package(name), _lockfile(), current_target()) is not None
  174. def sealed() -> bool:
  175. """Sealed = bundled LAYOUT only: the store sits beside the bundle
  176. manifest and is read-only as shipped."""
  177. return (paths.store_root().parent / "manifest.json").is_file()
  178. def _refuse_lazy(name: str, what: str) -> InstallError:
  179. from pm import receipt
  180. error = InstallError(
  181. name,
  182. f"not installed and lazy installs are disabled: {what}",
  183. "enable security.allow_lazy_installs or run `hermes pm install`",
  184. )
  185. receipt.record_refusal("lazy-install", str(error))
  186. return error
  187. def _remove_entry(store: Store, entry_name: str, *, attempts: int = 5) -> None:
  188. """Remove a replaced or failed entry, retrying transient Windows holds.
  189. Corruption may leave a file where the directory belonged. Failure
  190. must propagate so recovery never claims to have removed surviving bytes.
  191. """
  192. import time
  193. entry = store.entry(entry_name)
  194. for attempt in range(attempts):
  195. try:
  196. if entry.is_symlink() or not entry.is_dir():
  197. entry.unlink(missing_ok=True)
  198. else:
  199. remove_tree(entry)
  200. return
  201. except FileNotFoundError:
  202. return
  203. except OSError:
  204. if attempt == attempts - 1:
  205. raise
  206. time.sleep(0.2 * (attempt + 1))
  207. _SET_ASIDE_PREFIX = ".reclaim-"
  208. def _discard_entry(store: Store, entry_name: str) -> None:
  209. """Drop a tree a finished publish or restore left behind as garbage.
  210. A running Hermes process can keep the replaced interpreter's DLLs mapped
  211. far past the retry window, and failing here reports a completed install
  212. as broken (#124807). Windows still allows renaming a tree with mapped
  213. images, so it moves to a `.reclaim-*` name: its slot is free for the next
  214. publish, no restore ever picks it up, and the next install or
  215. `hermes pm gc` deletes it once the hold is gone.
  216. """
  217. import uuid
  218. try:
  219. _remove_entry(store, entry_name)
  220. return
  221. except OSError as e:
  222. error = e
  223. try:
  224. store.entry(entry_name).rename(store.entry(f"{_SET_ASIDE_PREFIX}{uuid.uuid4().hex}"))
  225. except OSError:
  226. LOG.warning("could not remove or set aside %s: %s", entry_name, error)
  227. return
  228. LOG.warning("%s is still in use (%s); set aside for the next install or `hermes pm gc`",
  229. entry_name, error)
  230. def _reclaim_set_aside(store: Store) -> int:
  231. """Delete set-aside trees whose hold is gone; the caller holds the store lock."""
  232. removed = 0
  233. for item in sorted(store.root.glob(f"{_SET_ASIDE_PREFIX}*")):
  234. try:
  235. _remove_entry(store, item.name, attempts=1)
  236. except OSError:
  237. continue
  238. removed += 1
  239. return removed
  240. def _remove_downloads(store: Store, artifacts: list[dict]) -> None:
  241. """Release this package's archives after publication, under its store lock."""
  242. for artifact in artifacts:
  243. _discard_entry(store, f"fetch-{artifact['sha256']}")
  244. def _entry_verified(package: Package, fact: dict, store: Store, target: str) -> bool:
  245. """Explicit installs re-check realized bytes; startup keeps its cheap facts check."""
  246. entry = store.entry(fact["entry"])
  247. try:
  248. return not package.verify(entry, target) and digest_matches(entry, fact.get("digest"))
  249. except OSError:
  250. return False
  251. def _restore_previous_entry(store: Store, entry, previous) -> None:
  252. """Keep both versions recoverable until the restore rename succeeds."""
  253. import uuid
  254. displaced = store.entry(f".displaced-{uuid.uuid4().hex}")
  255. had_entry = entry.exists() or entry.is_symlink()
  256. if had_entry:
  257. retry_held(lambda: entry.rename(displaced))
  258. try:
  259. retry_held(lambda: previous.rename(entry))
  260. except BaseException:
  261. if had_entry:
  262. retry_held(lambda: displaced.rename(entry))
  263. raise
  264. if had_entry:
  265. _discard_entry(store, displaced.name)
  266. @contextmanager
  267. def _publish_entry(package, store, staged, entry, previous_entry, target):
  268. """Keep rollback live through the caller's native facts commit, if any."""
  269. kept_live = False
  270. if entry.exists() or entry.is_symlink():
  271. try:
  272. retry_held(lambda: entry.rename(previous_entry))
  273. except OSError as rename_error:
  274. try:
  275. matches_staged = (not package.verify(entry, target)
  276. and tree_digest(entry) == tree_digest(staged))
  277. except OSError:
  278. raise rename_error
  279. if not matches_staged:
  280. raise
  281. LOG.warning("%s entry is in use but already matches the staged bytes; keeping it live",
  282. package.name)
  283. kept_live = True
  284. try:
  285. if not kept_live:
  286. store.publish(staged, entry.name)
  287. reason = package.verify(entry, target)
  288. if reason:
  289. raise InstallError(package.name, f"published entry failed verification: {reason}")
  290. yield
  291. except BaseException:
  292. if previous_entry.exists():
  293. _restore_previous_entry(store, entry, previous_entry)
  294. raise
  295. if previous_entry.exists():
  296. _discard_entry(store, previous_entry.name)
  297. def _settle_previous_entry(package, store, entry, previous_entry, previous, target) -> None:
  298. """Finish or undo a publication an earlier install left behind."""
  299. if not previous_entry.exists():
  300. return
  301. # Facts commit last. Stages have no host-side commit record, so
  302. # an interrupted stage always restores its prior usable bytes.
  303. if (previous and previous.get("entry") == entry.name
  304. and _entry_verified(package, previous, store, target)):
  305. _discard_entry(store, previous_entry.name)
  306. else:
  307. _restore_previous_entry(store, entry, previous_entry)
  308. def _entry_current(package, lockfile, facts, store, entry, previous, version, pin, target) -> bool:
  309. if facts is not None:
  310. return previous is not None and facts.installed(
  311. package.name, version, store.root, _identity(lockfile, package.name, target)
  312. ) and _entry_verified(package, previous, store, target)
  313. try:
  314. recorded = (entry / ".pm-stage-pin.json").read_text(encoding="utf-8-sig")
  315. except OSError:
  316. recorded = None
  317. return recorded == pin and not package.verify(entry, target)
  318. def _refresh_recorded_env(package, facts, store, entry, previous, target) -> None:
  319. """An entry's env is derived from the package code, not its bytes: when the code changes it (a
  320. variable renamed or retired), re-record it so stores installed earlier match what admission
  321. compares against. The recorded digest still vouches for the bytes, so nothing is re-fetched."""
  322. env = package.env(entry, target)
  323. if facts.env_for(package.name, store.root) != env:
  324. facts.record(package.name, previous["version"], previous["entry"], env, store.root,
  325. target=previous.get("target"), artifacts=previous.get("artifacts"),
  326. digest=previous.get("digest"))
  327. def _refresh_found_env(package, location, target, operation) -> None:
  328. """:func:`_refresh_recorded_env` for an entry ``ensure`` found installed: `hermes update` skips
  329. installed defaults, so no install would re-record it. Only the writable store is re-recorded, under
  330. its install lock (a sealed store's facts ship with the artifact)."""
  331. facts, store = location
  332. entry = store.entry(facts.get(package.name)["entry"])
  333. if (facts.env_for(package.name, store.root) == package.env(entry, target)
  334. or store.root != Store(paths.writable_store_root()).root):
  335. return
  336. with nullcontext() if operation is not None else store.install_lock():
  337. facts.reload()
  338. previous = facts.get(package.name)
  339. if previous and previous.get("entry") == entry.name:
  340. _refresh_recorded_env(package, facts, store, entry, previous, target)
  341. def _copy_verified_source(package, lockfile, copy_from, staged, version, target) -> None:
  342. source_facts, source_store = copy_from
  343. source = source_facts.get(package.name)
  344. if (not source_facts.installed(package.name, version, source_store.root,
  345. _identity(lockfile, package.name, target))
  346. or not _entry_verified(package, source, source_store, target)):
  347. raise InstallError(package.name, "bundled copy source failed verification")
  348. shutil.copytree(source_store.entry(source["entry"]), staged, symlinks=True)
  349. if not digest_matches(staged, source["digest"]):
  350. raise InstallError(package.name, "copied bytes do not match the bundled source")
  351. def _log_repair(package, previous, version, artifacts) -> None:
  352. """Work item 6: replacing an ESTABLISHED fact is a repair — log it,
  353. no transaction system, no receipt file."""
  354. if not previous or "entry" not in previous:
  355. return
  356. old_artifact = (previous.get("artifacts") or ["?"])[0]
  357. old = f"{previous.get('version', '?')}/{str(old_artifact)[:12]}"
  358. new = f"{version}/{artifacts[0]['sha256'][:12]}" if artifacts else version
  359. LOG.info("repair: %s re-realized %s -> %s", package.name, old, new)
  360. def _install(
  361. package: Package,
  362. lockfile: Lockfile,
  363. facts: Facts | None,
  364. store: Store,
  365. target: str,
  366. progress=None,
  367. pause_event: threading.Event | None = None,
  368. download_progress: ProgressFn | None = None,
  369. *,
  370. copy_from: tuple[Facts, Store] | None = None,
  371. _lock_held: bool = False,
  372. _fresh_copy: bool = False,
  373. ) -> Path:
  374. """Realize one pin. Host installs commit facts; cross-target stages carry a marker."""
  375. version = lockfile.version(package.name)
  376. if version is None:
  377. raise InstallError(
  378. package.name, "not in the lockfile", "add it with `hermes pm lock --bump`"
  379. )
  380. reason = package.missing_reason(target)
  381. if reason is not None:
  382. raise InstallError(package.name, f"unavailable on {target}: {reason}", "none")
  383. entry_name = package.store_entry(version, target)
  384. entry = store.entry(entry_name)
  385. if getattr(package, "pin_only", False):
  386. return entry
  387. artifacts = lockfile.artifacts(package.name, target)
  388. pin = json.dumps({"target": target, "sha256": [a["sha256"] for a in artifacts]})
  389. with nullcontext() if _lock_held else store.install_lock():
  390. if pause_event is not None and pause_event.is_set():
  391. raise DownloadPaused("install paused")
  392. if facts is not None:
  393. facts.reload()
  394. previous = facts.get(package.name) if facts is not None else None
  395. previous_entry = store.entry(f".previous-{'stage-' if facts is None else ''}{entry_name}")
  396. _settle_previous_entry(package, store, entry, previous_entry, previous, target)
  397. _reclaim_set_aside(store)
  398. if (_entry_current(package, lockfile, facts, store, entry, previous, version, pin, target)
  399. and not _fresh_copy):
  400. if facts is not None:
  401. _refresh_recorded_env(package, facts, store, entry, previous, target)
  402. _remove_downloads(store, artifacts)
  403. return entry
  404. if not artifacts:
  405. raise InstallError(
  406. package.name,
  407. f"no artifact for {target} in the lockfile",
  408. "run `hermes pm lock --bump` for this package",
  409. )
  410. with store.scratch() as scratch:
  411. staged = scratch / "tree"
  412. try:
  413. if copy_from is not None:
  414. _copy_verified_source(package, lockfile, copy_from, staged, version, target)
  415. else:
  416. staged = _prepare_artifacts(package, store, scratch, artifacts, version, target,
  417. progress=progress, pause_event=pause_event,
  418. download_progress=download_progress)
  419. if pause_event is not None and pause_event.is_set():
  420. raise DownloadPaused("install paused")
  421. if progress is not None:
  422. progress("verify", 0, 0, "")
  423. reason, remedy = package.verify(staged, target), ""
  424. if reason:
  425. reason, remedy = package.repair_staged_verification(staged, target, reason)
  426. if reason:
  427. raise InstallError(package.name, f"staged entry failed verification: {reason}", remedy)
  428. if facts is None:
  429. (staged / ".pm-stage-pin.json").write_text(pin, encoding="utf-8")
  430. with _publish_entry(package, store, staged, entry, previous_entry, target):
  431. if facts is not None:
  432. facts.record(
  433. package.name, version, entry_name, package.env(entry, target), store.root,
  434. target=target, artifacts=[a["sha256"] for a in artifacts],
  435. digest=tree_digest(entry),
  436. )
  437. _remove_downloads(store, artifacts)
  438. except (InstallError, DownloadPaused):
  439. raise
  440. except Exception as e:
  441. raise InstallError(package.name, f"install failed: {e}") from e
  442. _log_repair(package, previous, version, artifacts)
  443. return entry
  444. def stage_only(
  445. name: str, target: str, progress=None, *,
  446. pause_event: threading.Event | None = None,
  447. download_progress: ProgressFn | None = None,
  448. ) -> Path:
  449. """Realize a cross-target pin without host facts or an executable Runner."""
  450. return _install(get_package(name), _lockfile(), None, _store(), target,
  451. progress=progress, pause_event=pause_event, download_progress=download_progress)
  452. class _InstallOperation:
  453. """Validity lasts only while this operation holds the publication lock."""
  454. def __init__(self) -> None:
  455. self.stack = ExitStack()
  456. self.store: Store | None = None
  457. self.checked: set[tuple[str, str | None, str, str]] = set()
  458. def lock(self) -> Store:
  459. if self.store is None:
  460. self.store = Store(paths.writable_store_root())
  461. self.stack.enter_context(self.store.install_lock())
  462. return self.store
  463. def close(self) -> None:
  464. self.checked.clear()
  465. self.store = None
  466. self.stack.close()
  467. @contextmanager
  468. def _install_operation():
  469. operation = _InstallOperation()
  470. try:
  471. yield operation
  472. finally:
  473. operation.close()
  474. def ensure(
  475. name: str,
  476. *,
  477. base_env: Optional[dict] = None,
  478. explicit: bool = False,
  479. verify: bool = True,
  480. progress=None,
  481. pause_event: threading.Event | None = None,
  482. download_progress: ProgressFn | None = None,
  483. _operation: _InstallOperation | None = None,
  484. ) -> Runner:
  485. """``explicit`` marks a deliberate install command (`hermes pm
  486. install`, `hermes pm bundle`) — those ARE the remedy the lazy-install
  487. policy names, so the policy does not apply to them.
  488. ``verify`` re-hashes an already-recorded entry and repairs it when the
  489. bytes moved. A deliberate install keeps that check. Shell activation
  490. and the source-build tail (moments after the install/update's own PM
  491. step) pass ``False``. It trusts the recorded digest, the same check
  492. startup uses, because hashing every tool tree costs seconds per call.
  493. ``progress(stage, done, total, label)`` reports the slow parts of an
  494. install to a UI, including ordered multi-archive labels.
  495. """
  496. if isinstance(get_package(name), StatePackage):
  497. if _operation is not None:
  498. # Python construction can provision tools itself. Drop both the
  499. # lock and its validity before entering that independent operation.
  500. _operation.close()
  501. sync_venv(explicit=explicit)
  502. return Runner(name, compose_env([], base=base_env))
  503. lockfile = _lockfile()
  504. target = current_target()
  505. chain = walk([name])
  506. checked = _operation.checked if _operation is not None else set()
  507. if _operation is not None:
  508. _operation.lock()
  509. missing = []
  510. for package in chain:
  511. identity = (package.name, lockfile.version(package.name), target,
  512. json.dumps(_identity(lockfile, package.name, target), sort_keys=True))
  513. if identity in checked:
  514. continue
  515. location = _installed_location(package, lockfile, target, verify=explicit and verify)
  516. if location is None:
  517. missing.append(package)
  518. else:
  519. _refresh_found_env(package, location, target, _operation)
  520. checked.add(identity)
  521. if missing and not explicit and not lazy_installs_allowed():
  522. raise _refuse_lazy(name, ", ".join(p.name for p in missing))
  523. if missing:
  524. store = _operation.lock() if _operation is not None else Store(paths.writable_store_root())
  525. facts = _facts() if store.root == _store().root else Facts(store.root / "facts.json")
  526. for package in missing:
  527. # Publication may change entries; do not carry observations across it.
  528. checked.clear()
  529. _install(package, lockfile, facts, store, target, progress=progress,
  530. pause_event=pause_event, download_progress=download_progress,
  531. _lock_held=_operation is not None)
  532. return Runner(name, env_for(name, base_env=base_env))
  533. def env_for(*names: str, base_env: Optional[dict] = None) -> dict[str, str]:
  534. """Composed env of already-installed packages only. Never installs,
  535. never raises on missing packages — they contribute nothing."""
  536. lockfile = _lockfile()
  537. target = current_target()
  538. diffs: list[dict] = []
  539. for name in names:
  540. try:
  541. chain = walk([name])
  542. except KeyError:
  543. continue
  544. for package in chain:
  545. if package.internal:
  546. continue
  547. location = _installed_location(package, lockfile, target)
  548. if location:
  549. facts, store = location
  550. diffs.append(facts.env_for(package.name, store.root))
  551. return compose_env(diffs, base=base_env)
  552. def _runtime_state_matches(fact: dict, stamp: str, *, project_root: Path | None = None) -> bool:
  553. if not isinstance(fact, dict) or fact.get("stamp") != stamp:
  554. return False
  555. from pm.environments import selected_venv
  556. try:
  557. environment = selected_venv(paths.repo_root() if project_root is None else project_root)
  558. except (OSError, RuntimeError, ValueError):
  559. return False
  560. recorded = fact.get("environment")
  561. if recorded is not None and (not isinstance(recorded, str) or Path(recorded).resolve() != environment):
  562. return False
  563. return (environment / "pyvenv.cfg").is_file()
  564. def _member_inputs(plugins: PluginInput | None) -> dict:
  565. """The ``plugin_dirs`` argument of the venv package; empty means config discovery."""
  566. from pm.publication import candidate_members
  567. if isinstance(plugins, Candidates):
  568. return {"plugin_dirs": candidate_members(plugins.dirs)}
  569. if isinstance(plugins, Members):
  570. return {"plugin_dirs": plugins.dirs}
  571. if plugins is None:
  572. return {}
  573. raise TypeError(f"{type(plugins).__name__} changes plugin state; only a sync may carry it")
  574. def _extra_key(name: str) -> str:
  575. """The PEP 685 name uv matches an extra by (``foo_bar`` is ``foo-bar``)."""
  576. import re
  577. return re.sub(r"[-_.]+", "-", name).lower()
  578. def _still_declared(package, recorded: list[str]) -> list[str]:
  579. """The recorded extras this tree still declares.
  580. An extra the source removed (``hindsight``) would otherwise ride the ledger
  581. into every later ``uv sync`` and fail it with "Extra is not defined". Only
  582. recorded extras are pruned; an explicitly requested unknown extra still fails.
  583. Membership uses PEP 685 names (uv matches ``foo_bar`` to ``foo-bar``); the
  584. recorded spelling is what reaches uv.
  585. """
  586. from pm.features import declared_extras
  587. root = package.project_root()
  588. if not (root / "pyproject.toml").is_file():
  589. return list(recorded)
  590. declared = {_extra_key(extra) for extra in declared_extras(root)}
  591. return [extra for extra in recorded if _extra_key(extra) in declared]
  592. def _carried(package, recorded: list[str]) -> list[str]:
  593. """The recorded extras a sync carries forward: still declared and not dropped by the user
  594. (`hermes pm install --without NAME`). An explicit request still enables a declined extra."""
  595. from pm.extras import declined_extras
  596. refused = declined_extras(package.project_root())
  597. return [extra for extra in _still_declared(package, recorded) if _extra_key(extra) not in refused]
  598. def venv_is_current(*, extras: list[str] | None = None, plugins: Members | Candidates | None = None,
  599. project_root: Path | None = None) -> bool:
  600. """Probe the requested union without changing recorded dependency state."""
  601. from pm.environments import runtime_facts_path
  602. from pm.packages import Venv
  603. root = paths.repo_root() if project_root is None else Path(project_root).absolute()
  604. package = get_package("venv") if project_root is None else Venv(root)
  605. fact = Facts(runtime_facts_path(root), strict=True).get("venv")
  606. if fact is None:
  607. fact = Facts(paths.facts_path(), strict=True).get("venv")
  608. if fact is None:
  609. return False
  610. if (not isinstance(fact, dict) or not isinstance(fact.get("stamp"), str) or not fact["stamp"]
  611. or not isinstance(fact.get("extras"), list)
  612. or any(not isinstance(extra, str) for extra in fact["extras"])):
  613. raise ValueError("invalid recorded dependency state")
  614. enabled = sorted(set(_carried(package, fact["extras"])) | set(extras or []))
  615. stamp = package.expected_stamp(enabled, **_member_inputs(plugins))
  616. return _runtime_state_matches(fact, stamp, project_root=root)
  617. def _feature_policy(extras: Optional[list[str]], *, repair: bool) -> tuple[list[str] | None, list[str] | None]:
  618. """Refuse extras this platform or a frozen bundle cannot carry; return (shipped, frozen)."""
  619. from pm.features import read_features
  620. if extras:
  621. from pm.extras import extra_supported
  622. unsupported = [extra for extra in extras
  623. if not extra_supported(extra, importable=lambda _: False)]
  624. if unsupported:
  625. raise InstallError("venv", f"extras {unsupported} are not supported by this Python/platform",
  626. "choose a supported provider; no dependency environment was changed")
  627. shipped = read_features()
  628. frozen = shipped
  629. # Without a frozen declaration, explicit source setup needs no policy
  630. # read: the config loader initializes/chmods unrelated user state.
  631. if frozen is not None and not repair and lazy_installs_allowed():
  632. frozen = None
  633. if frozen is not None and extras:
  634. outside = sorted(set(extras) - set(frozen))
  635. if outside:
  636. raise _refuse_lazy(
  637. "venv",
  638. f"extras {outside} are outside this bundle's frozen feature "
  639. "set (security.allow_lazy_installs is false)",
  640. )
  641. return shipped, frozen
  642. @contextmanager
  643. def _venv_install_lock(*, patient: bool):
  644. """Hold the dependency lock, or refuse when an impatient caller would queue."""
  645. from pm import receipt
  646. from hermes_cli.runtime_state import INSTALL_LOCK_TIMEOUT_SECONDS, runtime_lock
  647. # Holding this lock means rebuilding the whole dependency environment, which takes tens of
  648. # seconds on a bundle. Only an install the user asked for may queue for it; an opportunistic
  649. # one (a lazy extra at first use, the only non-explicit caller) refuses instead of holding
  650. # a sibling profile's backend off its port behind a rebuild it did not request.
  651. with runtime_lock(paths.repo_root(), timeout=None if patient else INSTALL_LOCK_TIMEOUT_SECONDS) as held:
  652. if not held:
  653. error = InstallError(
  654. "venv",
  655. f"another Hermes process is installing dependencies (waited {INSTALL_LOCK_TIMEOUT_SECONDS:.0f}s)",
  656. "retry in a moment, or run `hermes pm install` to install explicitly",
  657. )
  658. receipt.record_refusal("install-busy", str(error))
  659. raise error
  660. yield
  661. def _publication(plugins: PluginInput | None):
  662. """Snapshot a plugin state change under the held lock, or None for member-only inputs."""
  663. from pm.publication import PluginSelection, StagedPlugin
  664. if isinstance(plugins, Selection):
  665. return PluginSelection(dict(plugins.data))
  666. if isinstance(plugins, StagedUpdate):
  667. return StagedPlugin(dict(plugins.data))
  668. return None
  669. def _publish_inactive(change) -> None:
  670. """A disabled plugin's code changes without touching the dependency environment."""
  671. from pm import receipt
  672. from hermes_cli.runtime_state import finish_publication, recover_publication
  673. try:
  674. change.publish(paths.repo_root())
  675. finish_publication(paths.repo_root())
  676. except BaseException:
  677. recover_publication(paths.repo_root())
  678. raise
  679. receipt.record_venv_rebuild(False, "inactive plugin")
  680. def _target_selection(package, fact: dict, *, extras, inputs: dict, repair: bool, shipped, frozen):
  681. """Return (enabled extras, expected stamp, package inputs) this sync must reach."""
  682. if repair:
  683. if fact and (not isinstance(fact.get("extras"), list)
  684. or any(not isinstance(extra, str) for extra in fact["extras"])
  685. or not isinstance(fact.get("stamp"), str) or not fact["stamp"]):
  686. raise InstallError("venv", "recorded dependency selection is incomplete; refusing to change its graph")
  687. enabled = list(fact.get("extras", frozen if frozen is not None else ["all"]))
  688. stamp = fact.get("stamp") or package.expected_stamp(enabled, plugin_dirs=[])
  689. return enabled, stamp, {"repair": True}
  690. # The first writable generation replaces, rather than layers on,
  691. # the payload. Retain its extras until a recorded selection owns them.
  692. enabled = sorted(set(_carried(package, fact.get("extras", shipped or []))) | set(extras or []))
  693. return enabled, package.expected_stamp(enabled, **inputs), inputs
  694. def _commit_selection(package, facts: Facts, change, *, enabled: list[str], stamp: str, inputs: dict,
  695. current: bool, repair: bool, explicit: bool, skip_invalid_secondary: bool = False) -> None:
  696. """Build (unless current), publish the plugin change, then record the selection."""
  697. from pm import receipt
  698. from hermes_cli.runtime_state import finish_publication, recover_publication
  699. try:
  700. result = {} if current else (package.apply(enabled, explicit=explicit,
  701. skip_invalid_secondary=skip_invalid_secondary, **inputs) or {})
  702. if not repair and package.expected_stamp(enabled, **inputs) != stamp:
  703. raise ValueError("Dependency inputs changed while preparing publication; retry.")
  704. if change is not None:
  705. change.publish(paths.repo_root())
  706. if not current:
  707. if result.get("environment") is not None:
  708. from pm.environments import flush_before_selecting
  709. flush_before_selecting()
  710. facts.record_state("venv", stamp, enabled, **result)
  711. if change is not None:
  712. finish_publication(paths.repo_root())
  713. receipt.record_venv_rebuild(not current, "already in sync" if current else "")
  714. except BaseException:
  715. recover_publication(paths.repo_root())
  716. raise
  717. def _refuse_declined(package, extras: Optional[list[str]], *, explicit: bool) -> None:
  718. """A lazy install (first use of a feature) never re-adds an extra the user dropped."""
  719. if not extras or explicit:
  720. return
  721. from pm.extras import declined_extras, declined_reasons, install_hint
  722. refused = declined_extras(package.project_root())
  723. dropped = [extra for extra in extras if _extra_key(extra) in refused]
  724. if dropped:
  725. reasons = declined_reasons(package.project_root())
  726. why = "; ".join(f"an update left {extra!r} out because {reasons[_extra_key(extra)]}" for extra in dropped
  727. if _extra_key(extra) in reasons)
  728. raise InstallError("venv", why or f"extras {dropped} were removed with `hermes pm install --without`",
  729. "run `" + "`, `".join(install_hint(extra) for extra in dropped) + "` to enable them again")
  730. def _without_new_declines(package, extras: Optional[list[str]], automatic) -> Optional[list[str]]:
  731. """*extras* minus the *automatic* entries the user has declined, read under the dependency lock.
  732. An automatic entry (configured-platform repair, the main-era venv carry, a container's shipped
  733. baseline) was chosen before this sync took the lock, from a decline record a concurrent
  734. `hermes pm install --without NAME` may since have changed; only the lock-held read counts.
  735. """
  736. if not extras or not automatic:
  737. return extras
  738. from pm.extras import declined_extras
  739. refused = declined_extras(package.project_root())
  740. derived = {_extra_key(extra) for extra in automatic}
  741. return [extra for extra in extras if _extra_key(extra) not in derived or _extra_key(extra) not in refused]
  742. def decline_extras(names: list[str]) -> None:
  743. """Record ``hermes pm install --without NAME`` for extras, under the dependency lock: an
  744. in-flight `--extra NAME` sync clears its decline before releasing it, so an unlocked write
  745. landing mid-sync would be erased."""
  746. if not names:
  747. return
  748. from pm.extras import record_declined_extras
  749. with _venv_install_lock(patient=True):
  750. record_declined_extras(add=names, project_root=paths.repo_root())
  751. def _sync_locked(extras, *, package, plugins, repair: bool, explicit: bool, shipped, frozen,
  752. evict_incompatible_plugins: bool) -> None:
  753. """sync_venv's body under the held dependency lock."""
  754. from pm import receipt
  755. from pm.publication import StagedPlugin
  756. change = _publication(plugins)
  757. if isinstance(change, StagedPlugin) and not change.active:
  758. _publish_inactive(change)
  759. elif evict_incompatible_plugins:
  760. from pm.plugin_eviction import sync_evicting
  761. facts = Facts(paths.runtime_facts_path())
  762. fact = facts.get("venv") or _facts().get("venv") or {}
  763. sync_evicting(package, facts, fact, extras=extras, shipped=shipped, frozen=frozen, explicit=explicit)
  764. else:
  765. inputs = {"plugin_dirs": change.members} if change is not None else _member_inputs(plugins)
  766. facts = Facts(paths.runtime_facts_path(), strict=repair)
  767. fact = facts.get("venv") or _facts().get("venv") or {}
  768. enabled, stamp, inputs = _target_selection(package, fact, extras=extras, inputs=inputs,
  769. repair=repair, shipped=shipped, frozen=frozen)
  770. current = not repair and _runtime_state_matches(fact, stamp)
  771. if not current and not repair and not explicit and not lazy_installs_allowed():
  772. raise _refuse_lazy("venv", str(extras) if extras else "venv out of sync")
  773. receipt.record_feature_list(enabled)
  774. _commit_selection(package, facts, change, enabled=enabled, stamp=stamp, inputs=inputs,
  775. current=current, repair=repair, explicit=explicit)
  776. def sync_venv(extras: Optional[list[str]] = None, *, explicit: bool = False,
  777. plugins: PluginInput | None = None, repair: bool = False,
  778. evict_incompatible_plugins: bool = False, automatic: Optional[list[str]] = None,
  779. carried: Optional[list[str]] = None) -> None:
  780. """Make the venv match uv.lock + the enabled extras. Extras union into
  781. the installed state (one ledger); no-op when the stamp already matches.
  782. ``repair`` restores the recorded dependency graph into a fresh generation,
  783. bypassing both that shortcut and config discovery. It cannot add features.
  784. ``explicit`` marks a deliberate install command (`hermes pm install`,
  785. `hermes update`) — those are the remedy the lazy-install policy points
  786. at, so the policy does not apply to them. ``plugins`` names the one
  787. source of plugin members (see pm.plugin_inputs); None discovers them from config.
  788. ``evict_incompatible_plugins`` is the update's contract: a discovered plugin that
  789. keeps the environment from building is disabled instead of failing the sync
  790. (see pm.plugin_eviction). ``automatic`` names the entries of ``extras`` Hermes chose
  791. on the user's behalf: one the user declined is left out, and none of them opts a
  792. declined extra back in; every other requested extra does (``--extra NAME``).
  793. ``carried`` names the automatic entries this sync carries over from a pre-PM venv:
  794. one that keeps the environment from building is left out, recorded and reported
  795. (see pm.carried_extras).
  796. Lazy installs OFF = the frozen feature set: when
  797. security.allow_lazy_installs is false AND the bundle's
  798. enabled-features.json exists, the feature list is FROZEN to that file
  799. — requested extras outside it are refused, and plugin members are
  800. never installed (the bundle IS the install).
  801. Receipt contract: EVERY outcome writes a receipt. ``begin`` fires
  802. BEFORE the frozen/lazy refusals (a refusal is a recorded ``failed``
  803. outcome, not a silent raise); finalize runs in FINALLY — no-op syncs
  804. ("ok" with ``venv_rebuild`` false) and refusals ("failed") both get
  805. a receipt. Plugin selection data is discovered and published by the worker
  806. under this lock; no executable transaction phases cross the process boundary."""
  807. from pm import receipt
  808. token = receipt.begin("sync")
  809. outcome = "failed"
  810. try:
  811. if repair and (extras is not None or plugins is not None):
  812. raise ValueError("repair restores the recorded environment; it cannot change features or plugins")
  813. if evict_incompatible_plugins and (repair or plugins is not None or not explicit):
  814. raise ValueError("only an explicit sync of the discovered plugin selection may disable plugins")
  815. if carried and (repair or plugins is not None or not set(carried) <= set(extras or ())):
  816. raise ValueError("carried extras belong to a feature sync of the discovered selection")
  817. shipped, frozen = _feature_policy(extras, repair=repair)
  818. package = get_package("venv")
  819. from hermes_cli.runtime_state import recover_publication
  820. from functools import partial
  821. sync = partial(_sync_locked, package=package, plugins=plugins, repair=repair, explicit=explicit,
  822. shipped=shipped, frozen=frozen, evict_incompatible_plugins=evict_incompatible_plugins)
  823. automatic = [*(automatic or ()), *(carried or ())] # a carried extra is automatic too
  824. with _venv_install_lock(patient=explicit or repair):
  825. extras = _without_new_declines(package, extras, automatic)
  826. _refuse_declined(package, extras, explicit=explicit)
  827. recover_publication(paths.repo_root())
  828. try:
  829. sync(extras)
  830. except Exception as failure:
  831. from pm.carried_extras import BUILD_VERDICTS, failing_carried, record_left_out, refuse_transient
  832. if not carried or not extras or not isinstance(failure, BUILD_VERDICTS):
  833. raise
  834. fact = Facts(paths.runtime_facts_path()).get("venv") or _facts().get("venv") or {}
  835. failing = failing_carried(package, failure, extras=extras, carried=carried, fact=fact,
  836. shipped=shipped, frozen=frozen, explicit=explicit)
  837. refuse_transient(failing, failure)
  838. extras = [extra for extra in extras if extra not in failing]
  839. sync(extras)
  840. record_left_out(package, failing)
  841. derived = {_extra_key(extra) for extra in automatic}
  842. opted_in = [extra for extra in extras or () if _extra_key(extra) not in derived]
  843. if opted_in and explicit and not repair:
  844. from pm.extras import record_declined_extras
  845. # An explicit request is the opt-back-in. Cleared before the lock is released, or a
  846. # sync queued behind this one still reads the decline and publishes without the extra.
  847. record_declined_extras(remove=opted_in, project_root=package.project_root())
  848. outcome = "ok"
  849. except BaseException as exc:
  850. receipt.record_step("dependency-sync", False, f"{type(exc).__name__}: {exc}")
  851. raise
  852. finally:
  853. receipt.finalize(outcome, 0 if outcome == "ok" else 1, token=token)
  854. def drift(*, include_venv: bool = True) -> dict[str, str]:
  855. """Cheap stamp comparisons of the installed state
  856. against the lockfile. Maps package names to reasons; empty means healthy. Never
  857. installs, never touches the network. An install pm has never touched
  858. (no installed-state file) reports nothing — pm only vouches for what
  859. it installed. Lockfile packages this build doesn't know (version skew
  860. during a partial update) are skipped, not fatal."""
  861. if not paths.facts_path().is_file() and not paths.runtime_facts_path().is_file():
  862. return {}
  863. problems: dict[str, str] = {}
  864. lockfile = _lockfile()
  865. facts = _facts()
  866. target = current_target()
  867. for name in lockfile.names():
  868. try:
  869. package = get_package(name)
  870. except KeyError:
  871. continue
  872. if package.optional or package.internal:
  873. continue
  874. if package.missing_reason(target) is not None:
  875. continue
  876. if _installed_location(package, lockfile, target) is None:
  877. problems[name] = "not installed or outdated"
  878. try:
  879. venv = get_package("venv")
  880. except KeyError:
  881. venv = None
  882. if include_venv and venv is not None and (paths.runtime_facts_path().is_file() or facts.get("venv") is not None):
  883. try:
  884. if not venv_is_current():
  885. problems["venv"] = "out of sync with uv.lock"
  886. except (OSError, RuntimeError, ValueError) as exc:
  887. problems["venv"] = str(exc)
  888. return problems
  889. def check(*, include_venv: bool = True) -> list[str]:
  890. """Human-readable startup diagnostics. Use drift() for package identities."""
  891. return [f"{name}: {reason}" for name, reason in drift(include_venv=include_venv).items()]
  892. def _dependents_first(names: list[str]) -> list[str]:
  893. """*names* with each package moved ahead of the packages it depends on.
  894. A package that extends its dependency must win on PATH: node's own dir also holds node's
  895. bundled npm and npx, so with node first every ``npm`` ran that copy, not the pinned npm.
  896. Unrelated packages keep their order.
  897. """
  898. order = list(names)
  899. for name in names:
  900. try:
  901. deps = {package.name for package in walk([name])} - {name}
  902. except KeyError:
  903. continue
  904. positions = [order.index(dep) for dep in deps if dep in order]
  905. if positions and min(positions) < order.index(name):
  906. order.remove(name)
  907. order.insert(min(positions), name)
  908. return order
  909. def _store_path_dirs() -> list[str]:
  910. """Composed PATH dirs of all installed (non-internal, on_path) store
  911. packages, each package ahead of its dependencies (``_dependents_first``),
  912. deduped. Includes optional packages that are
  913. *installed* (facts say so) — an installed git/gh must be on PATH even
  914. though it's not in the root closure. A package whose dependency chain is
  915. not fully installed contributes nothing: store npm over a missing store
  916. node would run the user's node, a partial toolchain. Never installs."""
  917. lockfile = _lockfile()
  918. target = current_target()
  919. locations: dict[str, object] = {}
  920. def located(package):
  921. if package.name not in locations:
  922. locations[package.name] = _installed_location(package, lockfile, target)
  923. return locations[package.name]
  924. dirs: list[str] = []
  925. for name in _dependents_first(lockfile.names()):
  926. try:
  927. package = get_package(name)
  928. chain = walk([name])
  929. except KeyError:
  930. continue
  931. if package.internal:
  932. continue
  933. if not getattr(package, "on_path", True):
  934. continue
  935. if package.missing_reason(target) is not None:
  936. continue
  937. location = located(package)
  938. if location is None or any(located(dep) is None for dep in chain
  939. if dep.missing_reason(target) is None):
  940. continue
  941. facts, store = location
  942. env = facts.env_for(name, store.root)
  943. path_dirs = env.get("PATH") or []
  944. if isinstance(path_dirs, str):
  945. path_dirs = [path_dirs]
  946. for directory in path_dirs:
  947. if directory and native(directory) not in dirs:
  948. dirs.append(native(directory))
  949. return dirs
  950. def activate(*, allow_incomplete: bool = False) -> list[str]:
  951. """Make the installed store usable: put its tool dirs at the FRONT of
  952. os.environ['PATH'] so reactive `shutil.which('git'|'node'|'ffmpeg'|...)`
  953. resolves the bundled binaries, never a user copy that sorts earlier.
  954. Return `check()`'s problems, or an empty list on success, so startup
  955. callers can report the verdict without checking the store twice.
  956. Drift still activates every package whose whole chain is installed
  957. (`_store_path_dirs`): refusing all of them handed every tool to the
  958. user's PATH copies. A damaged package, and anything depending on it,
  959. stays off PATH so no toolchain is served half from the store.
  960. ``allow_incomplete`` is the install-time exception: tools are published
  961. before the venv sync, so the venv verdict is not computed at all.
  962. This is the ONE sanctioned global PATH write: PATH is the discovery
  963. contract every `which` reads, not a tool-specific env leak. Store-first
  964. unconditionally — pinned bundled versions win on dev machines too.
  965. """
  966. import os
  967. # The venv verdict is discarded here, and computing it imports application
  968. # config readers (ruamel) that the bare update interpreter does not carry.
  969. problems = check(include_venv=not allow_incomplete)
  970. path = os.environ.get("PATH", "")
  971. first = store_first_path(path)
  972. if first != path:
  973. os.environ["PATH"] = first
  974. return problems
  975. def store_first_path(path: str) -> str:
  976. """``path`` with the installed store's tool dirs moved to the front, for
  977. Hermes's own children whose PATH gets other dirs prepended after activate."""
  978. import os
  979. dirs = _store_path_dirs()
  980. if not dirs:
  981. return path
  982. store = {d.lower() for d in dirs}
  983. rest = [p for p in path.split(os.pathsep) if p and p.lower() not in store]
  984. return os.pathsep.join([*dirs, *rest])