environments.py 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601
  1. """Dependency-environment layout: where a project's venv generations live, which one
  2. is selected, and the interpreter inside any venv. Shared by PM and pre-import launchers.
  3. Only stdlib and hermes_constants: environment selection must work before
  4. any dependency from that environment has been imported.
  5. """
  6. from __future__ import annotations
  7. import argparse
  8. import hashlib
  9. import json
  10. import os
  11. import re
  12. import shlex
  13. from pathlib import Path
  14. from hermes_constants import get_default_hermes_root, project_venv_dir
  15. def install_key(project_root: Path) -> str:
  16. canonical = str(Path(project_root).resolve())
  17. return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]
  18. def dependency_home_root() -> Path:
  19. """Scope dependency state like a process launched in the active home."""
  20. from hermes_constants import get_default_hermes_root, get_hermes_home_override
  21. override = get_hermes_home_override()
  22. return get_default_hermes_root(home=override) if override else get_default_hermes_root()
  23. def installs_root() -> Path:
  24. return dependency_home_root() / "installs"
  25. def install_state_dir(project_root: Path) -> Path:
  26. return installs_root() / install_key(project_root)
  27. def owning_home_root(project_root: Path) -> Path | None:
  28. """The data root that owns this checkout when the active root only borrows it, else ``None``.
  29. Dependency state is scoped per data root (``<root>/installs/<install_key>``), but a source
  30. checkout -- its launchers, product builds and install stamp -- exists once. A launch under
  31. another root (a test's temporary ``HERMES_HOME``, a per-task home, a CI service home) borrows
  32. it: the root that installed it already holds committed state for it, under the root the
  33. checkout sits in (``<root>/hermes-agent``) or else the platform default root. ``None`` when
  34. the active root's state is that state (the owner itself, or one of its profiles), and when no
  35. such root has state for this checkout -- a fresh install, or a custom root that owns its own
  36. tree -- so those keep today's behaviour (#123238).
  37. A borrowing launch's own sync leaves ``facts.json`` under the borrower too, so state alone
  38. cannot name the owner. The checkout's ``hermes`` launcher can: only the owner publishes it,
  39. and it execs the owner's store Python. With no live launcher to ask, the root the checkout
  40. sits in outranks the platform default.
  41. """
  42. from hermes_constants import _get_platform_default_hermes_home
  43. root = Path(project_root).resolve()
  44. key = install_key(root)
  45. candidates = [candidate for candidate in dict.fromkeys((root.parent, _get_platform_default_hermes_home()))
  46. if (candidate / "installs" / key / "facts.json").is_file()]
  47. if not candidates:
  48. return None
  49. owner = _launcher_bound_root(root, candidates) or candidates[0]
  50. try:
  51. if (owner / "installs" / key).resolve() == install_state_dir(root).resolve():
  52. return None
  53. except OSError:
  54. pass
  55. return owner
  56. def _launcher_bound_root(project_root: Path, candidates: list[Path]) -> Path | None:
  57. """The candidate whose ``tools/`` holds the live interpreter the checkout's launcher execs."""
  58. from hermes_cli._launchers import _launcher_python
  59. local = project_root / ".hermes" / "bin"
  60. for name in (("hermes.exe", "hermes.cmd") if os.name == "nt" else ("hermes",)):
  61. python = _launcher_python(local / name)
  62. if python is None or not python.is_file():
  63. continue
  64. for candidate in candidates:
  65. try:
  66. store = (candidate / "tools").resolve()
  67. if any(parent.resolve() == store for parent in python.parents):
  68. return candidate
  69. except (OSError, RuntimeError, ValueError):
  70. continue
  71. return None
  72. def install_state_permission_message(project_root: Path, exc: PermissionError) -> str | None:
  73. """Describe an access failure inside this install's dependency state."""
  74. if not exc.filename:
  75. return None
  76. denied = Path(exc.filename).resolve()
  77. if not denied.is_relative_to(install_state_dir(project_root).resolve()):
  78. return None
  79. return (f"install state is not writable by this user ({denied}); "
  80. "run as the install owner or grant write access")
  81. def runtime_facts_path(project_root: Path) -> Path:
  82. return install_state_dir(project_root) / "facts.json"
  83. # The files that decide the dependency set. `scripts/run-in-hermes-env` re-syncs
  84. # when any of them differs in mtime from its stamp under activation_inputs_dir.
  85. ACTIVATION_INPUTS = ("uv.lock", "pyproject.toml", "pm/lock.json")
  86. def activation_inputs_dir(project_root: Path) -> Path:
  87. """Beside facts.json, so the runner finds it from ``$__HERMES_ACTIVATED``."""
  88. return install_state_dir(project_root) / "inputs"
  89. def activation_input_mtimes(project_root: Path) -> dict[str, int]:
  90. """Snapshot before installing, so an input edited mid-install records its
  91. pre-install mtime and the next run re-activates."""
  92. root = Path(project_root)
  93. return {name: (root / name).stat().st_mtime_ns for name in ACTIVATION_INPUTS if (root / name).is_file()}
  94. def record_activation_inputs(stamps: Path, mtimes: dict[str, int], project_root: Path, *, test_environment: bool) -> None:
  95. """Give each stamp the exact mtime of the input the install was verified against.
  96. Recorded on every successful install, including no-op syncs: a checkout that
  97. rewrites an input without changing it moves the mtime, and only this record
  98. brings the stamp back to equal. The runner compares for equality, not order,
  99. because switching branches can move an input's mtime in either direction.
  100. """
  101. import shutil
  102. shutil.rmtree(stamps, ignore_errors=True)
  103. # The sentinel is inherited by child shells; equal input mtimes in another
  104. # checkout must never make their test interpreter appear current here.
  105. stamps.mkdir(parents=True, exist_ok=True)
  106. (stamps / ".project-root").write_text(str(Path(project_root).resolve()), encoding="utf-8")
  107. if test_environment:
  108. (stamps / ".test-environment").touch()
  109. for name, mtime in mtimes.items():
  110. stamp = stamps / name
  111. stamp.parent.mkdir(parents=True, exist_ok=True)
  112. stamp.touch()
  113. os.utime(stamp, ns=(mtime, mtime))
  114. def _payload_manifest(root: Path) -> tuple[dict, Path] | None:
  115. """The manifest of the sealed payload whose tree is the resolved *root*, with the
  116. payload directory its entries resolve from, or ``None``.
  117. The manifest sits at the payload root: beside the tree, or on the tree itself when
  118. the tree IS the payload root (the Docker image's in-place ``repo: "."`` assembly).
  119. Every install asks, so a ``manifest.json`` that some other tool left beside a
  120. checkout, or one with a mistyped field, must read as "not a payload", never as an
  121. error. Readers then take each field with ``.get`` and treat an absent one as unset.
  122. """
  123. for path in (root.parent / "manifest.json", root / "manifest.json"):
  124. try:
  125. manifest = json.loads(path.read_text(encoding="utf-8-sig"))
  126. except (OSError, ValueError):
  127. continue
  128. if not isinstance(manifest, dict) or not isinstance(manifest.get("repo"), str):
  129. continue
  130. runtime = manifest.get("runtime", {})
  131. commands = runtime.get("commands", {}) if isinstance(runtime, dict) else None
  132. well_formed = (isinstance(commands, dict)
  133. and isinstance(commands.get("hermes", ""), str)
  134. and all(isinstance(manifest.get(key, ""), str) for key in ("venv", "store")))
  135. if well_formed and (path.parent / manifest["repo"]).resolve() == root:
  136. return manifest, path.parent
  137. return None
  138. def _payload_path(payload_root: Path, relative: str, what: str) -> Path:
  139. """*relative* resolved from the payload root its manifest was read from; a manifest
  140. may not point outside it."""
  141. path = (payload_root / relative).resolve()
  142. if not path.is_relative_to(payload_root):
  143. raise RuntimeError(f"payload {what} escapes its root")
  144. return path
  145. def payload_venv(project_root: Path) -> Path | None:
  146. """The environment a sealed payload ships with its tree, or ``None``."""
  147. root = Path(project_root).resolve()
  148. payload = _payload_manifest(root)
  149. venv = payload[0].get("venv") if payload else None
  150. return _payload_path(payload[1], venv, "environment") if venv else None
  151. def _payload_hermes_command(root: Path) -> Path | None:
  152. payload = _payload_manifest(root)
  153. command = payload[0].get("runtime", {}).get("commands", {}).get("hermes") if payload else None
  154. return _payload_path(payload[1], command, "launcher") if command else None
  155. def payload_command_dir(project_root: Path) -> Path | None:
  156. """The directory holding a sealed payload's own launchers (``<payload>/bin``), or ``None``."""
  157. command = _payload_hermes_command(Path(project_root).resolve())
  158. return command.parent if command else None
  159. def cli_command_name(project_root: Path) -> str:
  160. """The name a person types to run this install's CLI.
  161. A desktop channel build publishes its launcher under a qualified name
  162. (``hermes-canary``) so it never shadows another install's ``hermes``.
  163. """
  164. command = _payload_hermes_command(Path(project_root).resolve())
  165. return command.name.removesuffix(".exe") if command else "hermes"
  166. def base_venv(project_root: Path) -> Path:
  167. return payload_venv(project_root) or project_venv_dir(Path(project_root).resolve()) or Path(project_root).resolve() / "venv"
  168. def store_root(project_root: Path, *, honor_runtime_override: bool = True) -> Path:
  169. """Resolve a payload-relative or stamped store before PM imports.
  170. ``HERMES_RUNTIME_DIR`` exists so a running process can point PM at a
  171. non-default runtime location. Publication paths must pass
  172. ``honor_runtime_override=False``: a persisted artifact (an installed
  173. launcher) has to bind the store of the tree it serves, never a runtime
  174. directory inherited through the environment.
  175. """
  176. if honor_runtime_override:
  177. override = os.environ.get("HERMES_RUNTIME_DIR")
  178. if override:
  179. return Path(override).resolve()
  180. root = Path(project_root).resolve()
  181. payload = _payload_manifest(root)
  182. store = payload[0].get("store") if payload else None
  183. if store:
  184. return _payload_path(payload[1], store, "store")
  185. from pm.paths import install_stamp_path
  186. for directory in (root, *root.parents):
  187. stamp = install_stamp_path(directory)
  188. if stamp.is_file():
  189. try:
  190. data = json.loads(stamp.read_text(encoding="utf-8-sig"))
  191. except (OSError, ValueError):
  192. return _unstamped_store(root)
  193. value = data.get("runtimeDir") if isinstance(data, dict) else None
  194. return Path(value).resolve() if value else _unstamped_store(root)
  195. return get_default_hermes_root() / "tools"
  196. def _unstamped_store(project_root: Path) -> Path:
  197. """The store of a stamp that names none (source stamps never do): the owning root's.
  198. The data root's ``tools/`` is the default, but a borrowing root's would be a new store per
  199. temporary home -- a full tool download on its first launch, and an interpreter that dies
  200. with the home. The checkout's own launchers exec the owner's interpreter, so a borrowing
  201. launch resolves the same one (#123238).
  202. """
  203. return (owning_home_root(project_root) or get_default_hermes_root()) / "tools"
  204. def flush_before_selecting() -> None:
  205. """Make a finished generation tree durable before a selection record names it.
  206. The selection record (the install's facts.json, a side environment's
  207. active.json) is written last, atomically and fsynced, so it doubles as the
  208. generation's completion marker -- but only if every file it vouches for
  209. reached the disk first. Otherwise a power loss can persist the record while
  210. the tree's data is still in the page cache, selecting a half-written venv.
  211. One filesystem-wide sync instead of an fsync per file: a venv holds tens of
  212. thousands of files, and per-file flushes cost minutes on slow disks.
  213. Windows has no whole-filesystem flush reachable from Python (os.sync does
  214. not exist there), and FlushFileBuffers per file is the slow path rejected
  215. above. There the record's atomic write is the only guarantee: it is never
  216. torn, but NTFS journals metadata, not file contents, so power loss right
  217. after a publish can still leave the selected tree with incomplete files.
  218. """
  219. sync = getattr(os, "sync", None)
  220. if sync is not None:
  221. sync()
  222. def selected_venv(project_root: Path) -> Path:
  223. """Use the committed environment, or the original install before first sync.
  224. A broken committed selection is an error, not permission to load an older
  225. dependency set silently. Reading this function never creates user state.
  226. The record itself is the completion marker: it is only written after
  227. ``flush_before_selecting``, so the ``pyvenv.cfg`` probe below is a sanity
  228. check against a vanished tree, not the durability guarantee.
  229. """
  230. return _recorded_venv(project_root) or base_venv(project_root)
  231. def committed_venv(project_root: Path) -> Path | None:
  232. """The environment PM committed for this install (or a sealed payload's own), else ``None``.
  233. Unlike ``selected_venv`` this never answers with the in-tree ``venv``/``.venv``: that tree
  234. predates PM and is built for whichever interpreter created it, so loading it from PM's store
  235. Python mixes ABIs (compiled modules vanish). PM never deletes it: ``legacy_selection`` reads its
  236. site-packages again whenever this install has no dependency facts.
  237. """
  238. return _recorded_venv(project_root) or payload_venv(project_root)
  239. def _recorded_venv(project_root: Path) -> Path | None:
  240. path = runtime_facts_path(project_root)
  241. try:
  242. data = json.loads(path.read_text(encoding="utf-8-sig"))
  243. except FileNotFoundError:
  244. return None
  245. except (OSError, ValueError) as exc:
  246. raise RuntimeError(f"cannot read dependency environment: {path}") from exc
  247. try:
  248. fact = data.get("packages", {}).get("venv", {})
  249. value = fact.get("environment")
  250. except AttributeError as exc:
  251. raise RuntimeError(f"invalid dependency environment record: {path}") from exc
  252. if value is None:
  253. return None
  254. if not isinstance(value, str):
  255. raise RuntimeError("invalid dependency environment path")
  256. environment = Path(value).resolve()
  257. generations = install_state_dir(project_root) / "environments"
  258. if not environment.is_relative_to(generations.resolve()) or not (environment / "pyvenv.cfg").is_file():
  259. raise RuntimeError(f"dependency environment is missing or outside this install: {environment}")
  260. return environment
  261. def venv_bin_dir(venv: Path, *, windows: bool | None = None) -> Path:
  262. """``Scripts`` on Windows, ``bin`` elsewhere. Returned unconditionally — callers
  263. differ on whether a missing venv is an error. *windows* lets a POSIX process
  264. reason about a Windows layout (update hand-off, launcher repair)."""
  265. if windows is None:
  266. windows = os.name == "nt"
  267. return Path(venv) / ("Scripts" if windows else "bin")
  268. def venv_python(venv: Path, *, windows: bool | None = None) -> Path:
  269. """The interpreter inside *venv* (may not exist)."""
  270. bin_dir = venv_bin_dir(venv, windows=windows)
  271. return bin_dir / ("python.exe" if bin_dir.name == "Scripts" else "python")
  272. def project_python(project_root: Path) -> Path:
  273. """The interpreter of the committed dependency environment for *project_root*."""
  274. return venv_python(selected_venv(project_root))
  275. def _payload_store_python(root: Path) -> Path | None:
  276. """A sealed payload's own interpreter when a venv must not be entered through its own."""
  277. payload = _payload_manifest(root)
  278. if payload is None or str(payload[0].get("target", "")).endswith("-bionic"):
  279. return None # Termux payloads launch through their venv interpreter by design.
  280. relative = payload[0].get("runtime", {}).get("storePython")
  281. if not isinstance(relative, str) or not relative:
  282. return None
  283. return _payload_path(payload[1], relative, "interpreter")
  284. def venv_command(project_root: Path, venv: Path, options: tuple[str, ...] | list[str] = ()) -> list[str]:
  285. """The argv prefix that runs Python inside *venv*; append a script, ``-c`` or ``-m``.
  286. A sealed payload never enters a venv through ``Scripts\\python.exe``. That redirector sits
  287. outside the package and starts PM's writable copy of the Python (``pm._uv._toolchain``),
  288. and a process on that copy has no package identity, so Windows refuses it the package's
  289. git, rg and PM worker (WinError 5). Instead the payload's own interpreter attaches the
  290. venv's site-packages (``pm/_venv_entry.py``): the same contract as the payload's
  291. launchers and its PM worker. Elsewhere the venv's interpreter runs as is. *options* are
  292. interpreter flags (``-I``, ``-u``, ``-X …``).
  293. """
  294. root = Path(project_root).resolve()
  295. store_python = _payload_store_python(root)
  296. if store_python is None:
  297. return [str(venv_python(venv)), *options]
  298. entry = Path(__file__).resolve().with_name("_venv_entry.py")
  299. flags = [*options, *([] if "-S" in options else ["-S"])]
  300. return [str(store_python), *flags, str(entry), str(site_packages(Path(venv)))]
  301. def venv_python_version(venv: Path) -> tuple[int, int] | None:
  302. """The interpreter version a POSIX venv actually holds, or ``None``.
  303. ``site_packages`` must not date the tree from the CALLER's ``sys.version_info``:
  304. an update can rebuild the dependency environment with a different Python than
  305. the launcher that later imports it. Observed on an app-driven upgrade -- PM
  306. built the environment with CPython 3.14 while the PATH shim ran 3.11, so the
  307. shim composed ``lib/python3.11/site-packages`` inside a 3.14 venv, found no
  308. tree, and failed *after* a successful update.
  309. """
  310. try:
  311. for line in (venv / "pyvenv.cfg").read_text(encoding="utf-8-sig").splitlines():
  312. key, _, value = line.partition("=")
  313. if key.strip() not in ("version", "version_info"): # venv / uv, virtualenv
  314. continue
  315. major, _, rest = value.strip().partition(".")
  316. minor, _, _ = rest.partition(".")
  317. if major.isdigit() and minor.isdigit():
  318. return int(major), int(minor)
  319. except OSError:
  320. pass
  321. try:
  322. candidates = sorted((venv / "lib").glob("python3*"))
  323. except OSError:
  324. return None
  325. for candidate in candidates:
  326. major, _, rest = candidate.name.removeprefix("python").partition(".")
  327. minor, _, _ = rest.partition(".")
  328. if major.isdigit() and minor.isdigit():
  329. return int(major), int(minor)
  330. return None
  331. def site_packages(venv: Path) -> Path:
  332. import sys
  333. if os.name == "nt":
  334. return venv / "Lib/site-packages"
  335. version = venv_python_version(venv) or (sys.version_info.major, sys.version_info.minor)
  336. return venv / f"lib/python{version[0]}.{version[1]}/site-packages"
  337. def running_from_selected_environment(project_root: Path) -> bool:
  338. """Does this process run on the environment PM selected for the install (base venv or committed
  339. generation)?
  340. A lazy sync from any other interpreter — a build_environment test venv, a developer's own venv,
  341. a Nix store Python — must not commit the install's selection: activation is a boot decision, so
  342. this process keeps running unchanged while every process booted afterwards swaps onto a
  343. generation that lacks whatever the foreign interpreter carried.
  344. activate_dependencies puts the selection's site-packages on sys.path without changing
  345. sys.prefix, so sys.path is the signal (the same one ensure_import reads after a sync).
  346. """
  347. import sys
  348. try:
  349. selected = site_packages(selected_venv(project_root)).resolve()
  350. except (OSError, RuntimeError, ValueError):
  351. return False
  352. return any(Path(entry).resolve() == selected for entry in sys.path if entry)
  353. class NoCommittedEnvironment(RuntimeError):
  354. """PM's store Python with no committed generation: no retry fixes it, only `hermes pm repair`."""
  355. def _require_own_dependencies(project_root: Path) -> None:
  356. """With nothing committed, an interpreter keeps the packages it booted with.
  357. PM's store Python boots with none, so for it there is nothing to keep: refuse instead of
  358. running on whatever PYTHONPATH it inherited (historically the pre-PM in-tree venv).
  359. """
  360. import sys
  361. if sys.prefix != sys.base_prefix:
  362. return # a venv interpreter (developer .venv, test env) carries its own packages
  363. if Path(sys.base_prefix).resolve().is_relative_to(store_root(project_root).resolve()):
  364. raise NoCommittedEnvironment("no dependency environment is committed for this install")
  365. def activate_dependencies(project_root: Path) -> None:
  366. """Select the committed tree at process boot, before third-party imports.
  367. A process with no extension selection keeps its original launch contract.
  368. Already-running processes are never switched after a dependency install.
  369. """
  370. import sys
  371. state = install_state_dir(project_root)
  372. if state.is_dir():
  373. from hermes_cli.runtime_state import runtime_lock, recover_publication, lease_generation
  374. # The lock's holder may be another profile's backend running a full dependency rebuild;
  375. # this process only reads the committed selection, so it proceeds without waiting rather
  376. # than leaving the backend unbound (see runtime_lock).
  377. with runtime_lock(project_root) as held:
  378. if held:
  379. recover_publication(project_root)
  380. environment = committed_venv(project_root)
  381. if environment is None:
  382. return _require_own_dependencies(project_root)
  383. release = lease_generation(environment)
  384. # Without the lock, an installer may commit a new generation between the
  385. # read and the lease, leaving the leased one unselected and collectable.
  386. while not held and (current := committed_venv(project_root)) not in (None, environment):
  387. release()
  388. environment, release = current, lease_generation(current)
  389. selected = site_packages(environment)
  390. if not selected.is_dir() and not runtime_facts_path(project_root).is_file():
  391. return
  392. else:
  393. # Sealed payloads still select once, before imports.
  394. # Never consult VIRTUAL_ENV: it can describe the invoking shell's Python.
  395. environment = payload_venv(project_root)
  396. if environment is None:
  397. return _require_own_dependencies(project_root)
  398. selected = site_packages(environment)
  399. if not selected.is_dir():
  400. return # External/Nix interpreter owns its original sys.path.
  401. if not selected.is_dir():
  402. raise RuntimeError(f"dependency environment has no site-packages: {selected}")
  403. import site
  404. sys.path[:] = [entry for entry in sys.path
  405. if Path(entry).name not in ("site-packages", "dist-packages")
  406. and Path(entry).resolve() != project_root.resolve()]
  407. # uv editable members are activated by .pth files, not by sys.path alone.
  408. site.addsitedir(str(selected))
  409. sys.path[:] = [str(project_root.resolve()), str(selected),
  410. *[entry for entry in sys.path if Path(entry).resolve() != selected.resolve()]]
  411. os.environ["PYTHONPATH"] = os.pathsep.join([str(project_root.resolve()), str(selected)])
  412. os.environ.pop("VIRTUAL_ENV", None)
  413. # The venv's own `hermes`/`hermes-acp` console scripts are editable installs bound to
  414. # the build-time source snapshot, not this checkout (#124627): a child that resolves
  415. # `hermes` off PATH must hit the checkout's own launcher first, never the venv's copy.
  416. # A sealed payload's launchers live in <payload>/bin instead.
  417. directories = [payload_command_dir(project_root) or project_root.resolve() / ".hermes" / "bin"]
  418. # A sealed payload's Windows venv redirectors never go on PATH: a shipped venv's still
  419. # names the build machine, and a generation built since names PM's writable Python copy,
  420. # which cannot start the package's executables (see venv_command).
  421. if not (os.name == "nt" and _payload_manifest(project_root.resolve()) is not None):
  422. directories.append(venv_bin_dir(environment))
  423. prefix = [str(path) for path in directories if path.is_dir()]
  424. if prefix:
  425. os.environ["PATH"] = os.pathsep.join([*prefix, os.environ.get("PATH", "")])
  426. def activation_environment(project_root: Path) -> dict[str, str]:
  427. """Read the installed PM environment; do not provision or switch imports."""
  428. from pm.install import env_for
  429. from pm.registry import all_packages
  430. env = env_for(*all_packages())
  431. environment = committed_venv(project_root)
  432. env.pop("PYTHONHOME", None)
  433. env.pop("VIRTUAL_ENV", None)
  434. # Nothing committed: the child's own hermes_bootstrap decides (a bare store Python refuses),
  435. # rather than inheriting the pre-PM in-tree venv from here.
  436. env["PYTHONPATH"] = os.pathsep.join([str(project_root.resolve()),
  437. *([str(site_packages(environment))] if environment else [])])
  438. # The child-process sentinel. Its VALUE is the installed-state file this
  439. # environment was composed against, so a consumer learns that it inherited
  440. # an activated shell and which checkout/profile that shell came from. Its
  441. # directory also holds activation_inputs_dir, the input-mtime stamps
  442. # `scripts/_activation.sh` compares against to decide staleness.
  443. env["__HERMES_ACTIVATED"] = str(runtime_facts_path(project_root))
  444. # The suite's interpreter (pm.testenv): an isolated side environment, so it
  445. # never appears on PYTHONPATH/PATH above. scripts/run_tests.sh reads it.
  446. from pm.testenv import testenv_python
  447. test_python = testenv_python(project_root)
  448. if test_python is not None:
  449. env["__HERMES_TEST_PYTHON"] = str(test_python)
  450. return env
  451. def _fish_quote(value: str) -> str:
  452. """Inside fish single quotes only backslash and the quote itself are special."""
  453. return "'" + value.replace("\\", "\\\\").replace("'", "\\'") + "'"
  454. # fish refuses to assign these, and each is either inherited unchanged from the
  455. # invoking shell (PWD, SHLVL, _) or fish's own state, so skipping loses nothing.
  456. _FISH_READ_ONLY = frozenset({
  457. "PWD", "SHLVL", "_", "status", "version", "hostname", "fish_pid", "history",
  458. "pipestatus", "status_generation", "umask", "FISH_VERSION",
  459. })
  460. # dialect -> (export statement, names the shell cannot assign). fish splits
  461. # values of variables named *PATH on colons when they are set from a single
  462. # word, so PATH stays a list.
  463. _SHELL_DIALECTS = {
  464. "sh": (lambda name, value: f"export {name}={shlex.quote(value)}", frozenset()),
  465. "fish": (lambda name, value: f"set -gx {name} {_fish_quote(value)}", _FISH_READ_ONLY),
  466. }
  467. _SHELL_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
  468. def shell_exports(env: dict[str, str], dialect: str) -> str:
  469. """The composed environment as a script a shell of ``dialect`` can evaluate.
  470. Windows carries names like ``ProgramFiles(ARM)`` that no shell can assign;
  471. they pass through untouched instead of failing the whole script.
  472. """
  473. statement, read_only = _SHELL_DIALECTS[dialect]
  474. return "\n".join(statement(name, str(value)) for name, value in env.items()
  475. if _SHELL_IDENTIFIER.fullmatch(name) and name not in read_only)
  476. def main(argv: list[str] | None = None) -> None:
  477. parser = argparse.ArgumentParser(description="Print the composed activation environment.")
  478. parser.add_argument("--format", choices=["json", *_SHELL_DIALECTS], default="json")
  479. options = parser.parse_args(argv)
  480. env = activation_environment(Path(__file__).resolve().parents[1])
  481. print(json.dumps(env) if options.format == "json" else shell_exports(env, options.format))
  482. if __name__ == "__main__":
  483. main()