| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351 |
- """Package definitions for the tools hermes manages. Versions and hashes
- live in pm/lock.json (written by `pm lock`), never here."""
- from __future__ import annotations
- import logging
- import os
- import shutil
- import subprocess
- import sys
- import tempfile
- import uuid
- from pathlib import Path
- from typing import Optional
- from pm.filesystem import long_root, native
- from pm.package import (
- DebPackage,
- InstallError,
- Package,
- StatePackage,
- _entry_listing,
- _probe_reason,
- unpack_deb,
- )
- from pm.registry import register
- from pm.store import ALL_TARGETS, MUSL_TARGETS, Store, current_target, flatten_single_dir, merge_tree
- from pm.update import (
- btbn_index,
- btbn_versions,
- github_release_tags,
- llama_app_bucket_versions,
- llama_app_latest,
- martin_riedl_index,
- martin_riedl_versions,
- node_latest_versions,
- npm_dist_tags,
- pbs_versions,
- )
- LOG = logging.getLogger(__name__)
- _RUST_TRIPLE = {
- "win32-x64": "x86_64-pc-windows-msvc",
- "win32-arm64": "aarch64-pc-windows-msvc",
- "linux-x64": "x86_64-unknown-linux-gnu",
- "linux-arm64": "aarch64-unknown-linux-gnu",
- "linux-x64-musl": "x86_64-unknown-linux-musl",
- "linux-arm64-musl": "aarch64-unknown-linux-musl",
- "darwin-x64": "x86_64-apple-darwin",
- "darwin-arm64": "aarch64-apple-darwin",
- }
- _NODE_PLAT = {
- "win32-x64": "win-x64",
- "win32-arm64": "win-arm64",
- "linux-x64": "linux-x64",
- "linux-arm64": "linux-arm64",
- "linux-x64-musl": "linux-x64-musl",
- "linux-arm64-musl": "linux-arm64-musl",
- "darwin-x64": "darwin-x64",
- "darwin-arm64": "darwin-arm64",
- }
- class BinaryPackage(Package):
- """A downloaded archive exposing one binary. Covers most tools."""
- binary_rel: dict[str, str] = {}
- flatten = True
- probe_version = True
- # argv after the binary for the smoke probe. A package whose binary
- # rejects the GNU double-dash form (ffmpeg's BtbN autobuild) overrides.
- probe_args: list[str] = ["--version"]
- # Run the probe with cwd=binary.parent: dlopen'd backends (llama.cpp's
- # cudart) resolve their shared libraries from the working directory.
- probe_cwd = False
- def _rel(self, target: str) -> Optional[str]:
- win = target.startswith("win32")
- return self.binary_rel.get(target) or self.binary_rel.get(
- "win32" if win else "posix"
- )
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- if self.flatten:
- flatten_single_dir(staged)
- def binary(self, entry: Path, target: str) -> Optional[Path]:
- rel = self._rel(target)
- return entry / rel if rel else None
- def verify(self, entry: Path, target: str) -> str:
- """Check file/architecture evidence for every target, plus a smoke
- probe only on the native target. Never execute cross-staged bytes."""
- binary = self.binary(entry, target)
- if binary is None:
- return "no binary_rel for this target"
- reason = self._binary_reason(binary, entry, target)
- if reason:
- return reason
- if not self.probe_version or target != current_target():
- return ""
- try:
- proc = subprocess.run(
- [native(binary), *self.probe_args],
- capture_output=True,
- timeout=60,
- cwd=native(binary.parent) if self.probe_cwd else None,
- env=self._probe_env(),
- check=False,
- )
- except OSError as e:
- return f"could not exec {native(binary)} {' '.join(self.probe_args)}: {e}"
- except subprocess.TimeoutExpired:
- return f"{native(binary)} {' '.join(self.probe_args)} timed out after 60s"
- if proc.returncode != 0:
- return _probe_reason(binary, proc)
- return ""
- def _probe_env(self) -> dict:
- """Deps' env composed in: npm's shim is `#!/usr/bin/env node` and
- must find the node it extends on PATH."""
- if not self.deps:
- return dict(os.environ)
- from pm.install import env_for
- return env_for(*self.deps)
- @register
- class Dmgbuild(BinaryPackage):
- """Build-only DMG supplier, independently pinned by PM rather than dmg-builder.
- The lock version is <release>+<bundle revision>. Updates are manual: review
- the official electron-builder-binaries bundle and re-pin both Darwin targets.
- Keep the paired Python tree intact for the launcher and diagnostic hook.
- """
- name = "dmgbuild"
- internal = True
- on_path = False
- flatten = False
- probe_version = False
- binary_rel = {"posix": "dmgbuild"}
- gaps = {target: "DMG creation requires macOS" for target in ALL_TARGETS if not target.startswith("darwin-")}
- def fetch_url(self, version: str, target: str) -> str:
- release, _, revision = version.partition("+")
- arch = {"darwin-arm64": "arm64", "darwin-x64": "x86_64"}[target]
- return (
- "https://github.com/electron-userland/electron-builder-binaries/releases/download/"
- f"dmg-builder@{release}/dmgbuild-bundle-{arch}-{revision}.tar.gz"
- )
- def verify(self, entry: Path, target: str) -> str:
- return super().verify(entry, target) or self._binary_reason(entry / "python/bin/python3", entry, target)
- class _BionicDebArm:
- """Shared bionic-arm behavior for the termux tool packages: extract as a
- .deb on the bionic target (DebPackage's hardened ar+tar), as the binary
- package otherwise, and never host-exec-probe a bionic binary (it cannot
- run on the staging host)."""
- def unpack(self, archive: Path, staged: Path, target: str) -> None:
- if target == "linux-arm64-bionic":
- DebPackage.unpack(self, archive, staged, target)
- else:
- BinaryPackage.unpack(self, archive, staged, target)
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- if target != "linux-arm64-bionic":
- BinaryPackage.stage(self, store, staged, version, target)
- def binary(self, entry: Path, target: str) -> Optional[Path]:
- if target == "linux-arm64-bionic":
- # File evidence, not exec: the staged .deb's main binary.
- # Cross-target verify() never probes it; consumers (env PATH,
- # bundle layout) need the real path.
- return entry / self.prefix_rel / self.main_rel(target)
- return BinaryPackage.binary(self, entry, target)
- def verify(self, entry: Path, target: str) -> str:
- # MRO order puts BinaryPackage.verify (exec-probe semantics) ahead of
- # DebPackage.verify (file-evidence semantics); bionic needs the
- # latter -- one dispatch here replaces the per-class copies.
- if target == "linux-arm64-bionic":
- return DebPackage.verify(self, entry, target)
- return BinaryPackage.verify(self, entry, target)
- @register
- class Uv(_BionicDebArm, BinaryPackage, DebPackage):
- """astral's prebuilt tarballs for glibc/musl/mac/win; the Termux main-repo
- uv .deb for bionic (termux builds uv from source -- no astral bionic
- artifact exists). The bionic arm is a runtime tool on the phone (lazy
- plugin installs) and the wheelhouse's resolver in the build container."""
- name = "uv"
- deps = ("python",)
- internal = True
- on_path = False
- binary_rel = {"win32": "uv.exe", "posix": "uv"}
- # The staged .deb's main binary: DebPackage.verify checks it.
- main_bin_rel = "bin/uv"
- def main_rel(self, target: str) -> str:
- return self.main_bin_rel
- deb_package = "uv"
- def fetch_url(self, version: str, target: str) -> str:
- if target == "linux-arm64-bionic":
- return f"https://packages.termux.dev/apt/termux-main/pool/main/u/uv/uv_{version}_aarch64.deb"
- triple = _RUST_TRIPLE[target]
- ext = "zip" if target.startswith("win32") else "tar.gz"
- return f"https://github.com/astral-sh/uv/releases/download/{version}/uv-{triple}.{ext}"
- def latest_versions(self, target: str, locked=None) -> list[str]:
- return github_release_tags("astral-sh/uv")
- # The POSIX interpreter name the pinned Windows Python also answers to (see Python.stage).
- WINDOWS_PYTHON3 = "python3.exe"
- @register
- class Python(_BionicDebArm, BinaryPackage, DebPackage):
- """The pinned interpreter for launchers and every PM-managed uv command.
- Optional when provisioning unrelated tools; required by uv's closure.
- """
- name = "python"
- optional = True
- probe_version = False
- binary_rel = {"win32": "python.exe", "posix": "bin/python3"}
- # The staged .deb's main binary: DebPackage.verify checks it.
- main_bin_rel = "bin/python3.14"
- def main_rel(self, target: str) -> str:
- return self.main_bin_rel
- # termux-main (official termux repo) python deb. It lags python-build-
- # standalone by one patch (3.14.6-1 vs 3.14.7), so the bionic row is a
- # manual pin -- never derived from the node version, and pm update leaves
- # it alone (no bionic resolver).
- deb_package = "python"
- _BIONIC_URL = (
- "https://packages.termux.dev/apt/termux-main/pool/main/p/python/"
- "python_3.14.6-1_aarch64.deb"
- )
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- super().stage(store, staged, version, target)
- binary = self.binary(staged, target)
- if binary is not None and sys.platform == "darwin":
- from hermes_cli.macos_signing import sign_managed_python
- sign_managed_python(binary)
- # python-build-standalone ships the x64 VC runtime (vcruntime140_1.dll)
- # beside ARM64 Windows Python; it cannot load on ARM64 and would fail
- # the arch guard. Drop it HERE, before publish: the tree digest is
- # recorded over the shipped bytes, so a post-publish deletion (as the
- # old bundle-time drop did) makes doctor's re-hash mismatch.
- if target == "win32-arm64":
- (staged / "vcruntime140_1.dll").unlink(missing_ok=True)
- # python-build-standalone's Windows build ships python.exe only, so `python3` (npm and
- # vitest helpers, POSIX-minded scripts) resolves past the activated PATH to the Microsoft
- # Store's App Execution Alias stub, which installs nothing and fails. python.exe is a
- # small launcher of pythonXY.dll that finds its home from its own directory, so a copy
- # under the POSIX name is the same interpreter. Staged before publish, so the recorded
- # tree digest covers it.
- if target.startswith("win32"):
- shutil.copy2(staged / "python.exe", staged / WINDOWS_PYTHON3)
- def verify(self, entry: Path, target: str) -> str:
- reason = super().verify(entry, target)
- if reason or not target.startswith("win32"):
- return reason
- # An entry staged before python3.exe existed fails here, so an explicit install
- # (activation's setup) restages it once; startup's facts check never calls verify.
- alias = entry / WINDOWS_PYTHON3
- try:
- if alias.read_bytes() == (entry / "python.exe").read_bytes():
- return ""
- except OSError:
- return f"{WINDOWS_PYTHON3} is missing beside python.exe"
- return f"{WINDOWS_PYTHON3} differs from python.exe"
- def fetch_url(self, version: str, target: str) -> str:
- if target == "linux-arm64-bionic":
- return self._BIONIC_URL
- # lock version is "<python>+<release tag>", e.g. "3.14.7+20260901"
- pyver, _, tag = version.partition("+")
- if not tag:
- raise InstallError(self.name, f"version {version!r} needs the +<release> tag")
- triple = _RUST_TRIPLE[target]
- return (
- "https://github.com/astral-sh/python-build-standalone/releases/download/"
- f"{tag}/cpython-{pyver}+{tag}-{triple}-install_only.tar.gz"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- # Keep the locked minor line. The advertised asset owns patch and build.
- # Bionic remains a manual pin from a separate supplier.
- if target == "linux-arm64-bionic" or not locked or "+" not in locked:
- return []
- pyver = locked.partition("+")[0]
- minor = ".".join(pyver.split(".")[:2])
- return pbs_versions(minor, _RUST_TRIPLE[target])
- def _uv_lock_digest(path: Path) -> bytes:
- """sha256 of uv.lock, cached on (mtime_ns, size) — check() runs at
- every startup and uv.lock is megabyte-class."""
- import hashlib
- stat = path.stat()
- key = (stat.st_mtime_ns, stat.st_size)
- cached = _uv_lock_digest_cache.get(path)
- if cached and cached[0] == key:
- return cached[1]
- digest = hashlib.sha256(path.read_bytes()).digest()
- _uv_lock_digest_cache[path] = (key, digest)
- return digest
- _uv_lock_digest_cache: dict[Path, tuple] = {}
- def _copy_seed_file(src: str | os.PathLike, dst: str | os.PathLike) -> str | os.PathLike:
- """Copy one payload cache file unless an earlier seed already copied it whole.
- A copy cut short leaves the file in place with too few bytes, so a matching
- size is what counts as done; a finished file is not rewritten.
- """
- try:
- if os.stat(dst).st_size == os.stat(src).st_size:
- return dst
- except FileNotFoundError:
- pass
- # Other profiles share this cache: publish only a complete copy, without
- # truncating the live entry or leaving a failed copy visible to readers.
- fd, staging = tempfile.mkstemp(prefix=".seed-", dir=Path(dst).parent)
- os.close(fd)
- try:
- shutil.copy2(src, staging)
- os.replace(staging, dst)
- finally:
- Path(staging).unlink(missing_ok=True)
- return dst
- def _copy_seed_link(src: str | os.PathLike, dst: str | os.PathLike) -> None:
- """Recreate one payload cache symlink, healing a directory left by an older seed.
- uv caches a wheel as a symlink into ``archive-v0/``; following it (the
- ``copytree`` default) leaves a directory where uv later renames its own
- entry into place, which fails with EISDIR. The payload's targets are
- relative, so the target is copied verbatim, never resolved.
- """
- linkto = os.readlink(src)
- dst = Path(dst)
- staging = dst.parent / f".seed-link-{uuid.uuid4().hex}"
- os.symlink(linkto, staging)
- try:
- if dst.is_dir() and not dst.is_symlink():
- # A pre-fix seed copied the link target's contents here; uv cannot replace it.
- shutil.rmtree(dst)
- os.replace(staging, dst) # atomic: replaces a file or an existing symlink
- finally:
- staging.unlink(missing_ok=True)
- def _seed_tree(src: Path, dst: Path) -> None:
- """Merge one payload bucket, preserving uv's link entries.
- ``is_symlink()`` must be tested before ``is_dir()``: ``is_dir()`` follows
- links, and following them is exactly the bug this walker replaced.
- """
- dst.mkdir(parents=True, exist_ok=True)
- for child in src.iterdir():
- target = dst / child.name
- if child.is_symlink():
- _copy_seed_link(child, target)
- elif child.is_dir():
- _seed_tree(child, target)
- else:
- _copy_seed_file(child, target)
- def uv_cache_path() -> Path:
- """Where the hermes-owned uv cache lives; unlike uv_cache_dir(), never seeds or writes."""
- from hermes_constants import get_default_hermes_root
- return get_default_hermes_root() / "cache" / "uv"
- def uv_cache_dir() -> Path:
- """The hermes-owned uv cache: machine-scoped and shared (keyed by
- content — two profiles reuse one cache), anchored to the DEFAULT
- hermes root like partials_root(). A bundle ships a seeded copy at
- the payload root (uv-cache/); the first call under each uv.lock
- merges it into the writable machine cache (the read-only payload
- can't serve uv's working cache), and a warm `uv sync --offline`
- from it is near-free (probed: 0.4s vs 1.2s cold) — the blow-away-
- on-update contract depends on it. uv's default cache location is
- per-user/platform-opinionated and never used by pm."""
- from pm.paths import repo_root, store_root
- machine_cache = uv_cache_path()
- marker = machine_cache / ".seeded"
- # The marker names the lock whose payload was merged. An update ships a new payload cache for
- # a new lock; a bare "done" marker skipped it forever, so plugin rebuilds fetched the new pins
- # from the network (and built sdists where the index has no wheel for the target).
- lock = repo_root() / "uv.lock"
- seed = _uv_lock_digest(lock).hex() if lock.is_file() else "1"
- # The marker also records whether a payload cache was present. An image without one still
- # writes the marker for its lock, and a later image with the same lock must still merge its
- # seed. Do not drop the suffix: the lock alone cannot tell those two images apart.
- payload_cache = long_root(store_root().parent / "uv-cache")
- if payload_cache.is_dir():
- # The suffix names the seed's copy semantics, not just "a payload exists": it moved to
- # ``payload2`` when the seed stopped following links, so an existing volume re-runs the
- # merge once and the directory-shaped entries the old copy left are healed in place.
- seed += "+payload2"
- try:
- current = marker.read_text(encoding="utf-8-sig").strip() == seed
- except OSError:
- current = False
- if not current:
- # Seed from a shipped bundle cache when present (payload root =
- # store_root().parent on a sealed install). Record completion ONLY after a clean copy: a
- # partial seed that marked itself done would never be retried, and every later offline
- # sync that needs the missing entries fails closed.
- try:
- # uv's cache trees run deep; both roots get the long spelling so
- # the copy is not cut at MAX_PATH. The returned path stays ordinary.
- if payload_cache.is_dir():
- seeded = long_root(machine_cache)
- seeded.mkdir(parents=True, exist_ok=True)
- # archive-v0 first: a wheel link published before its bucket points at nothing,
- # for another profile's uv and, if the seed dies there, until the retry.
- for entry in sorted(payload_cache.iterdir(), key=lambda entry: entry.name != "archive-v0"):
- if entry.name == ".seeded":
- continue
- dest = seeded / entry.name
- # Merge into whatever an earlier failed or killed seed left: skipping
- # an existing directory would record that partial copy as complete.
- if entry.is_symlink():
- _copy_seed_link(entry, dest)
- elif entry.is_dir():
- _seed_tree(entry, dest)
- else:
- _copy_seed_file(entry, dest)
- except OSError as exc:
- LOG.warning("uv cache seed incomplete, retrying on the next install: %s", exc)
- else:
- try:
- marker.parent.mkdir(parents=True, exist_ok=True)
- marker.write_text(seed, encoding="utf-8")
- except OSError:
- pass
- return machine_cache
- @register
- class Venv(StatePackage):
- """The project venv: pyproject.toml + uv.lock + enabled extras.
- Made true by `uv sync --frozen`; uv is its internal dependency."""
- name = "venv"
- deps = ("uv",)
- def __init__(self, project_root: Path | None = None):
- self._project_root = project_root
- def project_root(self) -> Path:
- from pm.paths import repo_root
- return repo_root() if self._project_root is None else self._project_root
- def venv_dir(self) -> Path:
- from pm.environments import selected_venv
- return selected_venv(self.project_root())
- def expected_stamp(self, extras: list[str], *, plugin_dirs=None) -> str:
- import hashlib
- import json
- from pm.lock import Lockfile
- from pm.paths import lockfile_path
- from pm.store import current_target
- lock = Lockfile(lockfile_path())
- target = current_target()
- python = (lock.version("python"), target,
- [artifact["sha256"] for artifact in lock.artifacts("python", target)])
- h = hashlib.sha256()
- h.update(_uv_lock_digest(self.project_root() / "uv.lock"))
- h.update(",".join(sorted(extras)).encode())
- h.update(json.dumps(python).encode())
- # Plugin members union into the venv — a changed member set must
- # re-sync even when extras and core lock are unchanged.
- from pm.workspace import build_member_dirs, members_stamp
- h.update(members_stamp(build_member_dirs(extras) if plugin_dirs is None else plugin_dirs).encode())
- return h.hexdigest()
- def apply(self, extras: list[str], *, plugin_dirs=None, repair: bool = False, explicit: bool = False,
- skip_invalid_secondary: bool = False) -> dict:
- """Prepare one complete environment; the caller commits its selection.
- ``skip_invalid_secondary`` is the update's contract: an unreadable secondary profile
- is left out (the caller reports it) instead of refusing the whole graph.
- """
- import uuid
- from pm.environments import install_state_dir, runtime_facts_path
- from pm.environment import managed_environment
- from pm.lock import Facts
- from pm.native_build import source_build_environment
- from pm.workspace import build_member_dirs, lock_and_sync
- project = self.project_root()
- generation = install_state_dir(project) / "environments" / uuid.uuid4().hex
- candidate = generation / "venv"
- environment = managed_environment(candidate, env=source_build_environment(project),
- explicit=explicit or repair, output=sys.stderr)
- if not repair:
- # Inspection may skip a broken secondary profile, but publishing a replacement
- # graph must not silently evict its recorded members (including passed candidates).
- # An update does evict them, loudly: it must not fail on another profile's config.
- from pm.plugins_state import enabled_plugins_ordered
- enabled_plugins_ordered(skip_invalid_secondary=skip_invalid_secondary)
- members = [] if repair else (build_member_dirs(extras, environment.python) if plugin_dirs is None
- else plugin_dirs)
- try:
- generation.mkdir(parents=True)
- (generation / ".lease-managed").touch()
- environment.create()
- prior = Facts(runtime_facts_path(project), strict=repair).get("venv") or {}
- replay = None
- if repair and ("environment" in prior or "resolved_lock" in prior):
- if not all(isinstance(prior.get(key), str) and prior[key] for key in ("environment", "resolved_lock")):
- raise InstallError(self.name, "recorded dependency paths are incomplete; refusing to drop plugins")
- recorded = Path(prior["resolved_lock"]).resolve()
- previous = Path(prior["environment"]).resolve().parent
- generations = install_state_dir(project) / "environments"
- if (previous.parent != generations.resolve() or recorded != previous / "workspace" / "uv.lock"
- or not recorded.is_file()):
- raise InstallError(self.name, "recorded dependency lock is missing; refusing to drop plugins")
- replay = recorded.parent
- seed = (Path(prior["resolved_lock"]) if members and prior.get("resolved_lock")
- else project / "uv.lock")
- lock_and_sync(members, extras, root=generation / "workspace",
- seed_lock=seed, frozen=repair or not members, replay=replay,
- source=project, environment=environment)
- resolved_lock = generation / "workspace" / "uv.lock"
- environment.check(resolved_lock)
- if repair:
- from pm.environments import venv_command
- from pm.recovery import validate_environment
- validate_environment(venv_command(project, candidate, ("-I",)),
- env=dict(environment.env), cwd=resolved_lock.parent)
- except BaseException:
- shutil.rmtree(generation, ignore_errors=True)
- raise
- (generation / ".lease-managed").touch()
- return {"environment": candidate, "resolved_lock": resolved_lock}
- @register
- class Nodejs(_BionicDebArm, BinaryPackage, DebPackage):
- """nodejs.org tarballs for glibc/mac/win, unofficial-builds for musl;
- the Termux main-repo nodejs .deb for bionic (same major line, termux-built)."""
- name = "node"
- binary_rel = {"win32": "node.exe", "posix": "bin/node"}
- # The staged .deb's main binary: DebPackage.verify checks it.
- main_bin_rel = "bin/node"
- def main_rel(self, target: str) -> str:
- return self.main_bin_rel
- deb_package = "nodejs"
- def fetch_url(self, version: str, target: str) -> str:
- if target == "linux-arm64-bionic":
- # termux's deb carries a -1 revision after the upstream version
- return f"https://packages.termux.dev/apt/termux-main/pool/main/n/nodejs/nodejs_{version}-1_aarch64.deb"
- plat = _NODE_PLAT[target]
- ext = "zip" if target.startswith("win32") else "tar.xz"
- base = (
- "https://unofficial-builds.nodejs.org/download/release"
- if target in MUSL_TARGETS
- else "https://nodejs.org/dist"
- )
- return f"{base}/v{version}/node-v{version}-{plat}.{ext}"
- def latest_versions(self, target: str, locked=None) -> list[str]:
- # Keep one Node version across targets. If unofficial musl publication
- # lags nodejs.org, the later artifact pin/download fails before the
- # lockfile is written rather than selecting glibc bytes on musl.
- return node_latest_versions()
- def repair_staged_verification(self, entry: Path, target: str, reason: str) -> tuple[str, str]:
- """Repair the host library needed by official Linux Node, then re-probe.
- Keep this out of verify(): doctor/status checks call verify and must
- never gain permission to install host packages.
- """
- if target != current_target() or not target.startswith("linux") or "libatomic.so.1" not in reason:
- return reason, ""
- from pm.libatomic import try_install_libatomic
- installed, remedy = try_install_libatomic()
- if not installed:
- return reason, remedy
- retried = self.verify(entry, target)
- if "libatomic.so.1" in retried:
- return retried, "the libatomic package installed, but Node still cannot load libatomic.so.1; check the loader path"
- return retried, ""
- @register
- class TermuxDocker(Package):
- """The termux/termux-docker container image, pinned by registry digest.
- The image is never downloaded or unpacked by pm -- docker pulls it by
- digest reference at build time. The lock row exists so the digest is
- pinned in the single pin authority beside every other third-party
- artifact: consumers read the digest string from the lock's url field
- (termux/termux-docker@sha256:...). verify() is presence-shaped: this
- package stages nothing.
- """
- name = "termux-docker"
- optional = True
- # Pure pin: no bytes are staged, so stage_only()/install skip the store
- # entirely -- the digest's consumers (docker pull) verify it.
- pin_only = True
- def missing_reason(self, target: str) -> Optional[str]:
- return None if target == "linux-arm64-bionic" else "docker image target is linux-arm64-bionic"
- def fetch_url(self, version: str, target: str) -> str:
- return f"docker://termux/termux-docker@{version}"
- def unpack(self, archive: Path, staged: Path, target: str) -> None:
- raise InstallError(self.name, "a docker image digest is a pin, not a downloadable artifact")
- def verify(self, entry: Path, target: str) -> str:
- return ""
- def npm_env(cache_dir: Path, base_env: Optional[dict] = None) -> dict[str, str]:
- """Keep ambient Node and npm options out of PM's child process."""
- env = {
- key: value
- for key, value in (os.environ if base_env is None else base_env).items()
- if not key.lower().startswith("npm_config_")
- and key.upper() not in ("NODE_OPTIONS", "NODE_PATH", "NODE_ENV")
- }
- env["npm_config_cache"] = str(cache_dir)
- return env
- @register
- class Npm(BinaryPackage):
- name = "npm"
- deps = ("node",)
- binary_rel = {"win32": "npm.cmd", "posix": "bin/npm"}
- flatten = False
- probe_version = False
- url = "https://registry.npmjs.org/npm/-/npm-{version}.tgz"
- def unpack(self, archive: Path, staged: Path, target: str) -> None:
- """npm installs itself using the node it extends: a plain unpack
- resolves the cli from dirname(process.execPath) and finds node's
- bundled npm instead. --offline pins the bytes to the verified
- tarball; --ignore-scripts + a sanitized env keep user npm/node
- config out of the staging."""
- if target == "linux-arm64-bionic":
- from pm.store import extract
- unpacked = staged / ".unpacked"
- extract(archive, unpacked)
- package = unpacked / "package"
- lib = staged / "lib/node_modules/npm"
- lib.parent.mkdir(parents=True, exist_ok=True)
- package.rename(lib)
- unpacked.rmdir()
- bindir = staged / "bin"
- bindir.mkdir()
- for name in ("npm", "npx"):
- wrapper = bindir / name
- wrapper.write_text(
- "#!/data/data/com.termux/files/usr/bin/sh\n"
- 'here="$(cd "$(dirname "$0")" && pwd)"\n'
- f'exec node "$here/../lib/node_modules/npm/bin/{name}-cli.js" "$@"\n',
- encoding="utf-8",
- )
- wrapper.chmod(0o755)
- return
- from pm.install import _installed_location, _lockfile
- from pm.registry import get_package
- node = get_package("node")
- location = _installed_location(node, _lockfile(), target)
- if location is None:
- raise InstallError(self.name, "npm extends node, which is not installed")
- facts, store = location
- node_fact = facts.get("node")
- if node_fact is None:
- raise InstallError(self.name, "npm extends node, which is not installed")
- node_bin = node.binary(store.entry(node_fact["entry"]), target)
- if node_bin is None or not node_bin.is_file():
- raise InstallError(self.name, "node's entry is missing its binary")
- win = target.startswith("win32")
- bundled_cli = (
- node_bin.parent / "node_modules" / "npm" / "bin" / "npm-cli.js"
- if win
- else node_bin.parent.parent / "lib" / "node_modules" / "npm" / "bin" / "npm-cli.js"
- )
- if not bundled_cli.is_file():
- raise InstallError(self.name, "node's entry is missing its bundled npm-cli.js")
- staged.mkdir(parents=True, exist_ok=True)
- # npm caches the tarball it installs. The archive's directory is the
- # store's download entry, which must hold only the archive: a cache
- # there turns its removal into a tree delete that fails on Windows
- # while Defender still holds the fresh copy (WinError 145). Cleanup
- # of this throwaway cache must never fail the install.
- with tempfile.TemporaryDirectory(prefix="hermes-npm-cache-", ignore_cleanup_errors=True) as cache:
- proc = subprocess.run(
- [
- native(node_bin), native(bundled_cli), "install", "--global",
- "--prefix", native(staged), "--offline", "--ignore-scripts",
- "--no-audit", "--no-fund", native(archive),
- ],
- capture_output=True,
- text=True,
- timeout=900,
- env=npm_env(Path(cache)),
- check=False,
- )
- if proc.returncode != 0:
- raise InstallError(
- self.name, f"self-install exited {proc.returncode}: {proc.stderr[-400:]}"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- latest = npm_dist_tags("npm").get("latest")
- return [latest] if latest else []
- # The pinned git artifact is a self-extracting 7z: only hosts where PE images
- # execute can stage it (tests patch this flag).
- _HOST_IS_WINDOWS = os.name == "nt"
- @register
- class Git(BinaryPackage):
- """Windows only: Git for Windows carries the bash.exe contract. POSIX
- uses the system git - a deliberate gap, not an oversight. The pin is the
- PortableGit self-extracting 7z: it carries its own extractor (stock
- Windows 10 tar.exe has no bzip2), shows a progress window (-y only drops
- prompts), and runs the vendor post-install, so the staged tree is
- post-install output."""
- name = "git"
- optional = True
- binary_rel = {"win32": "cmd/git.exe"}
- flatten = False
- gaps = {
- "linux-x64": "POSIX uses system git by choice",
- "linux-arm64": "POSIX uses system git by choice",
- "linux-x64-musl": "POSIX uses system git by choice",
- "linux-arm64-musl": "POSIX uses system git by choice",
- "darwin-x64": "POSIX uses system git by choice",
- "darwin-arm64": "POSIX uses system git by choice",
- }
- def fetch_url(self, version: str, target: str) -> str:
- tag, build = version.split("+")
- arch = "arm64" if target.endswith("arm64") else "64-bit"
- return (
- f"https://github.com/git-for-windows/git/releases/download/"
- f"v{tag}.windows.{build}/PortableGit-{tag}.{build}-{arch}.7z.exe"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- # Tag is v2.53.0.windows.3; the lock version is 2.53.0+3.
- out = []
- for tag in github_release_tags("git-for-windows/git", strip_prefix="v"):
- if ".windows." in tag:
- base, _, build = tag.partition(".windows.")
- out.append(f"{base}+{build}")
- return out
- def unpack(self, archive: Path, staged: Path, target: str) -> None:
- if not _HOST_IS_WINDOWS:
- raise InstallError(
- self.name,
- "the pinned artifact is a PortableGit self-extracting 7z, which "
- "only runs on Windows",
- "stage win32 git on a Windows host; POSIX hosts use the system git",
- )
- shutil.rmtree(staged, ignore_errors=True)
- staged.mkdir(parents=True)
- # Execute a scratch copy, never the cached fetch-<sha> bytes: an executed
- # PE can stay handle-held (on-execute AV scan, the RunProgram children)
- # past pm's download-cleanup retry and fail the install (WinError 32).
- with tempfile.TemporaryDirectory(
- prefix=".sfx-", dir=staged.parent, ignore_cleanup_errors=True
- ) as work:
- exe = Path(work) / archive.name
- shutil.copy2(archive, exe)
- # No pipes: RunProgram children would inherit them and hold run()
- # open past the stub's exit. Under -y the stub prints nothing anyway.
- try:
- proc = subprocess.run(
- [native(exe), f"-o{native(staged)}", "-y"],
- stdin=subprocess.DEVNULL,
- stdout=subprocess.DEVNULL,
- stderr=subprocess.DEVNULL,
- timeout=600,
- check=False,
- )
- except subprocess.TimeoutExpired:
- raise InstallError(
- self.name, "PortableGit self-extractor did not finish in 600 s"
- ) from None
- if proc.returncode:
- raise InstallError(
- self.name,
- f"PortableGit self-extractor exited {proc.returncode} (it reports "
- "nothing under -y; usual causes: disk full, path-length limit, "
- "antivirus lock)",
- )
- def env(self, entry: Path, target: str) -> dict:
- return {"PATH": [str(entry / "cmd"), str(entry / "usr" / "bin")]}
- @register
- class Gh(BinaryPackage):
- name = "gh"
- optional = True
- binary_rel = {"win32": "bin/gh.exe", "posix": "bin/gh"}
- def fetch_url(self, version: str, target: str) -> str:
- # GitHub CLI's Linux release matrix is built with CGO_ENABLED=0,
- # so the generic Linux archive is libc-independent.
- lookup_target = target.removesuffix("-musl") if target in MUSL_TARGETS else target
- osname, arch = lookup_target.split("-")
- plat = {"win32": "windows", "linux": "linux", "darwin": "macOS"}[osname]
- arch = {"x64": "amd64", "arm64": "arm64"}[arch]
- ext = "zip" if osname in ("win32", "darwin") else "tar.gz"
- return (
- f"https://github.com/cli/cli/releases/download/v{version}/"
- f"gh_{version}_{plat}_{arch}.{ext}"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- return github_release_tags("cli/cli", strip_prefix="v")
- @register
- class Ffmpeg(_BionicDebArm, BinaryPackage, DebPackage):
- """FFmpeg builds for supported targets; BtbN Linux archives require glibc.
- optional=False: ffmpeg is a required runtime tool where supported. Sealed bundles ship
- it baked into the payload; every `hermes update` and `hermes pm install`
- re-ensures it from the new lockfile before the venv sync
- (pm.client.ensure_tools_for_sync), so a pin bump lands. Windows + Linux:
- BtbN/FFmpeg-Builds (month-end autobuild tag, kept two years; ships ffprobe too).
- macOS: ffmpeg.martin-riedl.de (uniform ZIP, published sha256;
- single-binary — no ffprobe).
- Linux deliberately does NOT use martin-riedl: that build is compiled
- without x11grab (confirmed on the pinned 9.0.1 amd64 binary), and
- x11grab is how screen capture on X11 works."""
- name = "ffmpeg"
- deb_package = "ffmpeg"
- optional = False
- gaps = {target: "BtbN Linux builds link glibc dynamically" for target in MUSL_TARGETS}
- def main_rel(self, target: str) -> str:
- return "bin/ffmpeg"
- # macOS (martin-riedl, the only remaining posix stream) and Windows/Linux
- # (BtbN) have no shared release cadence — they drift in PATCH. The lockfile
- # version label is major.minor; each target's exact patch lives in its
- # artifact urls.
- version_style = "minor"
- # martin-riedl (macOS) zips are a single `ffmpeg` at the zip root; BtbN
- # ships bin/ffmpeg (Linux, .tar.xz) and bin/ffmpeg.exe (Windows, .zip)
- # under one top-level dir that flatten hoists.
- binary_rel = {
- "win32": "bin/ffmpeg.exe",
- "linux-x64": "bin/ffmpeg",
- "linux-arm64": "bin/ffmpeg",
- "posix": "ffmpeg",
- }
- flatten = True
- # BtbN autobuild n9.0.1-11-ge47273f4d9 rejects `--version`
- # ("Unrecognized option '-version'", exit 2880417800); `-version` works
- # and is accepted by every ffmpeg build.
- probe_args = ["-version"]
- def fetch_url(self, version: str, target: str) -> str:
- if target == "linux-arm64-bionic":
- return f"https://packages.termux.dev/apt/termux-main/pool/main/f/ffmpeg/ffmpeg_{version}_aarch64.deb"
- if target in MUSL_TARGETS:
- raise InstallError(self.name, f"unavailable on {target}: {self.missing_reason(target)}")
- osname, arch = target.split("-")
- if osname in ("win32", "linux"):
- artifact = btbn_index().get(target, {}).get(version)
- if artifact is not None:
- tag, asset = artifact
- return f"https://github.com/BtbN/FFmpeg-Builds/releases/download/{tag}/{asset}"
- else:
- epoch = martin_riedl_index().get(target, {}).get(version)
- if epoch is not None:
- source_arch = "amd64" if arch == "x64" else arch
- return f"https://ffmpeg.martin-riedl.de/download/macos/{source_arch}/{epoch}_{version}/ffmpeg.zip"
- # Existing installs read exact URLs from the lockfile. Re-pinning
- # must never silently substitute a different version or target.
- raise InstallError(self.name, f"no advertised {version} artifact for {target}",
- "retry when the upstream index is available, or keep the existing pin")
- def latest_versions(self, target: str, locked=None) -> list[str]:
- if target in MUSL_TARGETS:
- return []
- if target in ("win32-x64", "win32-arm64", "linux-x64", "linux-arm64"):
- return btbn_versions(target)
- return martin_riedl_versions(target)
- @register
- class Ripgrep(BinaryPackage):
- name = "ripgrep"
- binary_rel = {"win32": "rg.exe", "posix": "rg"}
- # The ARM64 Windows release links the VC++ runtime dynamically (the x64
- # one embeds it), and a fresh Windows has no vcruntime140.dll: rg.exe
- # dies with STATUS_DLL_NOT_FOUND. Our pinned Python ships the ARM64 DLL.
- deps = ("python",)
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- super().stage(store, staged, version, target)
- if target != "win32-arm64":
- return
- from pm.install import _installed_location, _lockfile
- from pm.registry import get_package
- python = get_package("python")
- location = _installed_location(python, _lockfile(), target)
- fact = location[0].get("python") if location is not None else None
- if fact is None:
- raise InstallError(self.name, "ARM64 rg.exe needs vcruntime140.dll from python, which is not installed")
- runtime = location[1].entry(fact["entry"]) / "vcruntime140.dll"
- if not runtime.is_file():
- raise InstallError(self.name, f"python's entry has no {runtime.name}")
- # App-local copy: the loader searches the exe's own folder first, and
- # the entry digest is recorded over it.
- shutil.copy2(runtime, staged / runtime.name)
- def verify(self, entry: Path, target: str) -> str:
- if target == "linux-arm64-bionic":
- return Package.verify(self, entry, target)
- return super().verify(entry, target)
- def fetch_url(self, version: str, target: str) -> str:
- if target == "linux-arm64-bionic":
- target = "linux-arm64" # This upstream artifact is a static musl executable.
- triple = _RUST_TRIPLE[target].replace("-unknown-linux-gnu", "-unknown-linux-musl")
- ext = "zip" if target.startswith("win32") else "tar.gz"
- return (
- f"https://github.com/BurntSushi/ripgrep/releases/download/{version}/"
- f"ripgrep-{version}-{triple}.{ext}"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- return github_release_tags("BurntSushi/ripgrep")
- @register
- class CuaDriver(BinaryPackage):
- name = "cua-driver"
- optional = True
- # Computer use's only OS path, so the default install carries it.
- default = True
- gaps = {**{target: "cua-driver does not publish a musl build" for target in MUSL_TARGETS},
- "linux-arm64-bionic": "cua-driver does not publish an Android build"}
- binary_rel = {
- "darwin-arm64": "CuaDriver.app/Contents/MacOS/cua-driver",
- "darwin-x64": "CuaDriver.app/Contents/MacOS/cua-driver",
- "win32": "cua-driver.exe",
- "posix": "cua-driver",
- }
- def fetch_url(self, version: str, target: str) -> str:
- arch = {
- "darwin-x64": "darwin-universal",
- "darwin-arm64": "darwin-universal",
- "linux-x64": "linux-x86_64",
- "linux-arm64": "linux-arm64",
- "win32-x64": "windows-x86_64",
- "win32-arm64": "windows-arm64",
- }[target]
- ext = "zip" if target.startswith("win32") else "tar.gz"
- # Only the directory archive contains the signed macOS app identity
- # needed by TCC and private sessions. Other targets' binary archives
- # already carry their runtime helpers (including Windows UIAccess).
- variant = "" if target.startswith("darwin") else "-binary"
- return (
- f"https://github.com/trycua/cua/releases/download/cua-driver-rs-v{version}/"
- f"cua-driver-rs-{version}-{arch}{variant}.{ext}"
- )
- def latest_versions(self, target: str, locked=None) -> list[str]:
- return github_release_tags("trycua/cua", strip_prefix="cua-driver-rs-v")
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- flatten_single_dir(staged)
- sdk = staged / "sdk"
- if sdk.is_dir():
- shutil.rmtree(sdk, ignore_errors=True)
- def _probe_env(self) -> dict:
- """The probe IS a first run: it must not mint telemetry state."""
- try:
- from tools.computer_use.cua_backend import cua_driver_child_env
- return cua_driver_child_env()
- except Exception:
- return dict(os.environ, CUA_DRIVER_RS_TELEMETRY_ENABLED="0")
- @register
- class Chromium(Package):
- """Playwright resolves browsers by DIRECTORY NAME under one root:
- `<name with '-'→'_'>-<revision>`, no target suffix. The env points
- PLAYWRIGHT_BROWSERS_PATH at the store root itself. The entry carries
- the INSTALLATION_COMPLETE marker playwright checks.
- The version is `<playwright revision>+<chrome version>` — most targets
- download from the Chrome-for-Testing CDN by chrome version, and the
- targets CfT doesn't build (linux-arm64) come from playwright's own
- mirror by revision. The store entry is named by revision only, which
- is all playwright's resolver reads."""
- name = "chromium"
- optional = True
- # browser_exec's launcher drives this build, and its readiness check
- # installs it only once per process, so default-install it like the
- # other OS tools; `install.sh --skip-browser` declines it.
- default = True
- on_path = False
- # Neither Chrome-for-Testing nor Playwright's mirror builds for Android.
- gaps = {
- "linux-arm64-bionic": "no Chromium build for Android/Termux",
- **{target: "Playwright/Chrome-for-Testing publishes no musl build" for target in MUSL_TARGETS},
- }
- emulated_arch_targets = frozenset({"win32-arm64"})
- _CDN = "https://cdn.playwright.dev"
- # Chrome-for-Testing platform names; targets absent here fall back to
- # playwright's dbazure mirror with its own platform names.
- # win32-arm64 uses the win64 (x64) build: CfT publishes no native
- # win-arm64 chromium, and Windows ARM64 runs x64 binaries via built-in
- # emulation.
- _CFT = {
- "linux-x64": "linux64",
- "darwin-x64": "mac-x64",
- "darwin-arm64": "mac-arm64",
- "win32-x64": "win64",
- "win32-arm64": "win64",
- }
- _MIRROR = {"linux-arm64": "linux-arm64"}
- def store_entry(self, version: str, target: str) -> str:
- revision = version.partition("+")[0]
- return f"{self.name.replace('-', '_')}-{revision}"
- def fetch_url(self, version: str, target: str) -> str:
- revision, _, chrome = version.partition("+")
- plat = self._CFT.get(target)
- if plat and chrome:
- return f"{self._CDN}/builds/cft/{chrome}/{plat}/chrome-{plat}.zip"
- mirror_plat = self._MIRROR[target]
- return (
- f"{self._CDN}/dbazure/download/playwright/builds/chromium/"
- f"{revision}/chromium-{mirror_plat}.zip"
- )
- def binary(self, entry: Path, target: str) -> Optional[Path]:
- # CfT and Playwright's ARM Linux archive use different enclosing
- # directories. Resolve the executable within the selected entry.
- names = {"chrome.exe"} if target.startswith("win32") else {"chrome", "chromium", "Google Chrome for Testing", "Chromium"}
- return next((p for p in sorted(entry.rglob("*")) if p.name in names and p.is_file()), None)
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- (staged / "INSTALLATION_COMPLETE").write_text("", encoding="utf-8")
- def verify(self, entry: Path, target: str) -> str:
- marker = entry / "INSTALLATION_COMPLETE"
- if not marker.is_file():
- return f"INSTALLATION_COMPLETE missing under {native(entry)}; {_entry_listing(entry)}"
- binary = self.binary(entry, target)
- if binary is None:
- return f"Chromium executable missing under {native(entry)}"
- return self._binary_reason(binary, entry, target)
- def env(self, entry: Path, target: str) -> dict:
- binary = self.binary(entry, target)
- if binary is None:
- raise InstallError(self.name, f"Chromium executable missing under {native(entry)}")
- # Playwright launches without an executable_path (e.g. the
- # har-derived-api-client skill's `chromium.launch(channel="chromium")`)
- # find this build through the root; Hermes's own launcher asks
- # hermes_cli.browser_runtime.chromium_executable() instead.
- return {"PLAYWRIGHT_BROWSERS_PATH": str(entry.parent)}
- class LlamaCpp(BinaryPackage):
- """One llama.cpp backend build. Backends are dlopen'd plugins, so a
- usable engine is one archive per (target, backend) — plus, for CUDA, the
- cudart archive (end users have no CUDA toolkit), and on Linux the libgomp
- .deb. Every library lands beside llama-server: Windows resolves DLLs from
- the executable's directory, and the Linux builds' RUNPATH is $ORIGIN.
- Backend is a HARDWARE choice, not a target, so each backend is its own
- optional package and the runtime asks for the one this machine can
- use. Version is llama.cpp's rolling release tag without the `b`.
- """
- optional = True
- on_path = False
- binary_rel = {"win32": "llama-server.exe", "posix": "llama-server"}
- flatten = False
- # --version is llama-server's liveness proof AND the check that the
- # backend's shared libraries resolve: a CUDA build with no cudart
- # beside it fails here rather than at first chat.
- probe_cwd = True
- backend: str = ""
- # Release-asset infix per target, or absent where upstream ships none.
- assets: dict[str, str] = {}
- # Upstream's Linux builds (CPU included) link the system OpenMP runtime,
- # which minimal hosts (WSL, containers) lack, and a normal install never
- # touches the system package manager. The $ORIGIN RUNPATH loads this copy
- # ahead of the host's, so its glibc floor must stay at or below every
- # engine's. Ubuntu 22.04's needs glibc 2.34, the floor of the x64 CPU and
- # Vulkan builds, and provides every GOMP version the builds reference. The
- # release-pocket file stays in the pool until 22.04's EOL; the artifact
- # mirror serves the pinned bytes after that.
- _LIBGOMP = {
- "linux-x64": "https://archive.ubuntu.com/ubuntu/pool/main/g/gcc-12/libgomp1_12-20220319-1ubuntu1_amd64.deb",
- "linux-arm64": "https://ports.ubuntu.com/ubuntu-ports/pool/main/g/gcc-12/libgomp1_12-20220319-1ubuntu1_arm64.deb",
- }
- @property
- def gaps(self) -> dict[str, str]: # type: ignore[override]
- return {
- target: f"llama.cpp publishes no {self.backend} build for {target}"
- for target in ALL_TARGETS
- if target not in self.assets
- }
- def _asset_names(self, version: str, target: str) -> list[str]:
- ext = "zip" if target.startswith("win32") else "tar.gz"
- return [f"llama-b{version}-bin-{self.assets[target]}.{ext}"]
- def fetch_urls(self, version: str, target: str) -> list[str]:
- return [
- f"https://github.com/ggml-org/llama.cpp/releases/download/b{version}/{asset}"
- for asset in self._asset_names(version, target)
- ] + ([self._LIBGOMP[target]] if target in self._LIBGOMP else [])
- def fetch_url(self, version: str, target: str) -> str:
- return self.fetch_urls(version, target)[0]
- def latest_versions(self, target: str, locked=None) -> list[str]:
- # Resolve from the llama.app installer bucket (the installer's own
- # updater pointer + version index — no API token, no rate limit):
- # the `latest` pointer is the authoritative "next version"; the
- # bucket tree supplies the full candidate list. Artifacts still
- # come from the llama.cpp GitHub releases (1:1 tag correspondence).
- latest = llama_app_latest()
- if latest is not None:
- return [latest, *llama_app_bucket_versions()]
- return llama_app_bucket_versions() or github_release_tags(
- "ggml-org/llama.cpp", strip_prefix="b"
- )
- def known_sha256(self, version: str, url: str) -> Optional[str]:
- """GitHub's release API serves every asset's digest, so pinning a
- 280 MB engine costs one API call instead of the download."""
- return _github_release_digests("ggml-org/llama.cpp", f"b{version}").get(
- url.rsplit("/", 1)[-1]
- )
- def unpack(self, archive: Path, staged: Path, target: str) -> None:
- if archive.name.endswith(".deb"):
- unpack_deb(self.name, archive, staged)
- else:
- super().unpack(archive, staged, target)
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- """Some archives nest the binaries under build/bin; hoist them so
- binary_rel is one path for every target. The libgomp .deb unpacks
- in its filesystem layout (usr/lib/<triplet>/); only the library
- itself moves beside llama-server."""
- server = self.binary(staged, target).name
- if not (staged / server).is_file():
- found = sorted(staged.rglob(server))
- if not found:
- raise InstallError(self.name, "archive contains no llama-server")
- merge_tree(found[0].parent, staged)
- # The pin decides whether the .deb arrives (test_llamacpp_pins); verify()'s --version
- # probe is what proves the libraries resolve.
- libs = sorted((staged / "usr" / "lib").glob("*/libgomp.so.1"))
- if libs:
- shutil.copyfile(libs[0], staged / "libgomp.so.1")
- shutil.rmtree(staged / "usr")
- def _github_release_digests(repo: str, tag: str) -> dict[str, str]:
- from pm.update import _get_json
- cached = _release_digest_cache.get((repo, tag))
- if cached is not None:
- return cached
- url = f"https://api.github.com/repos/{repo}/releases/tags/{tag}"
- try:
- release = _get_json(url)
- except Exception:
- return {}
- digests = {}
- for asset in release.get("assets", []):
- digest = (asset.get("digest") or "").partition("sha256:")[2]
- if digest:
- digests[asset["name"]] = digest
- _release_digest_cache[(repo, tag)] = digests
- return digests
- _release_digest_cache: dict[tuple, dict] = {}
- @register
- class LlamaCppCuda(LlamaCpp):
- """CUDA 13.4 everywhere upstream builds it: 13.x drivers run any 13.x
- runtime (minor-version compatibility), and 13.4 is the only line upstream
- ships for win-arm64. Linux archives first appeared after b10964, and
- upstream dropped win-cuda-13.3 at the same time.
- The engine archive carries no CUDA libraries (end users have no toolkit),
- so each target pins a second cudart archive too."""
- name = "llamacpp-cuda"
- backend = "cuda"
- assets = {
- "win32-x64": "win-cuda-13.4-x64",
- "win32-arm64": "win-cuda-13.4-arm64",
- "linux-x64": "ubuntu-cuda-13.4-x64",
- "linux-arm64": "ubuntu-cuda-13.4-arm64",
- }
- def _asset_names(self, version: str, target: str) -> list[str]:
- # Upstream names the Windows cudart zip without the build tag and the
- # Linux one with it.
- infix = self.assets[target]
- cudart = (
- f"cudart-llama-bin-{infix}.zip"
- if target.startswith("win32")
- else f"cudart-llama-b{version}-bin-{infix}.tar.gz"
- )
- return super()._asset_names(version, target) + [cudart]
- def stage(self, store: Store, staged: Path, version: str, target: str) -> None:
- """The Linux cudart tarball unpacks into its own top-level dir, but the
- engine's RUNPATH is $ORIGIN, so its libraries must sit beside
- llama-server. The Windows zip is flat and needs no hoist."""
- super().stage(store, staged, version, target)
- for extra in sorted(staged.glob("cudart-*")):
- if extra.is_dir():
- merge_tree(extra, staged)
- shutil.rmtree(extra)
- @register
- class LlamaCppVulkan(LlamaCpp):
- name = "llamacpp-vulkan"
- backend = "vulkan"
- assets = {
- "win32-x64": "win-vulkan-x64",
- "linux-x64": "ubuntu-vulkan-x64",
- "linux-arm64": "ubuntu-vulkan-arm64",
- }
- @register
- class LlamaCppHip(LlamaCpp):
- name = "llamacpp-hip"
- backend = "hip"
- # Upstream renamed the ROCm archives to 10.0 at b10767 (cff184438e).
- assets = {
- "win32-x64": "win-rocm-10.0-x64",
- "linux-x64": "ubuntu-rocm-10.0-x64",
- }
- @register
- class LlamaCppMetal(LlamaCpp):
- """macOS archives are unified builds with Metal compiled in."""
- name = "llamacpp-metal"
- backend = "metal"
- assets = {"darwin-x64": "macos-x64", "darwin-arm64": "macos-arm64"}
- @register
- class LlamaCppCpu(LlamaCpp):
- name = "llamacpp-cpu"
- backend = "cpu"
- assets = {
- "win32-x64": "win-cpu-x64",
- "win32-arm64": "win-cpu-arm64",
- "linux-x64": "ubuntu-x64",
- "linux-arm64": "ubuntu-arm64",
- "darwin-x64": "macos-x64",
- "darwin-arm64": "macos-arm64",
- }
- @register
- class WhisperCppCpu(BinaryPackage):
- """Native local STT for Windows ARM64, where faster-whisper has no wheel."""
- name = "whispercpp-cpu"
- optional = True
- gaps = {target: "uses the existing faster-whisper provider" for target in ALL_TARGETS
- if target != "win32-arm64"}
- binary_rel = {"win32-arm64": "whisper-cli.exe"}
- probe_args = ["--help"]
- url = "https://github.com/ggml-org/whisper.cpp/releases/download/{version}/whisper-bin-win-cpu-arm64.zip"
|