install.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324
  1. """Auto-installation of LSP server binaries.
  2. Installs go to a Hermes-owned staging dir, ``<HERMES_HOME>/lsp/bin/``, so the
  3. user's global toolchain stays untouched. Strategies: ``auto`` (install with
  4. the best available package manager), ``manual`` / ``off`` (probe only; a
  5. missing binary skips the server and ``hermes lsp status`` reports it).
  6. Installs run synchronously the first time a server is needed, serialized
  7. per-package; every failure path returns ``None`` so the tool layer falls
  8. back to its in-process syntax checker.
  9. """
  10. from __future__ import annotations
  11. import logging
  12. import os
  13. import shutil
  14. import subprocess
  15. import threading
  16. from pathlib import Path
  17. from typing import Any, Callable, Dict, Optional
  18. from hermes_cli._subprocess_compat import windows_hide_flags
  19. from hermes_constants import find_node_executable, with_hermes_node_path
  20. logger = logging.getLogger("agent.lsp.install")
  21. def _recipe(strategy: str, pkg: str, bin_name: str, **extra: Any) -> dict[str, Any]:
  22. return {"strategy": strategy, "pkg": pkg, "bin": bin_name, **extra}
  23. def _npm(pkg: str, bin_name: str, **extra: Any) -> dict[str, Any]:
  24. return _recipe("npm", pkg, bin_name, **extra)
  25. def _manual(bin_name: str) -> dict[str, Any]:
  26. return _recipe("manual", "", bin_name)
  27. # TypeScript 7+ is the Go-native port and ships no ``lib/tsserver.js`` /
  28. # ``lib/typescript.js``, so JS-based servers cannot load it as their SDK.
  29. TYPESCRIPT_SDK_PKG = "typescript@6"
  30. # Recipe key → {strategy, pkg, bin[, extra_pkgs]}. After install we look for
  31. # ``bin`` in ``<HERMES_HOME>/lsp/bin/`` first, then on PATH. ``extra_pkgs``
  32. # are sibling npm packages a server needs in the same node_modules tree.
  33. INSTALL_RECIPES: dict[str, dict[str, Any]] = {
  34. "pyright": _npm("pyright", "pyright-langserver"),
  35. # tsserver must be importable from the same node_modules tree or
  36. # initialize() fails with "Could not find a valid TypeScript installation".
  37. "typescript-language-server": _npm("typescript-language-server", "typescript-language-server", extra_pkgs=[TYPESCRIPT_SDK_PKG]),
  38. # 3.x forwards every TypeScript request to a client-hosted tsserver
  39. # (``tsserver/request`` tunnel) that a generic LSP client does not run, so
  40. # it never publishes diagnostics; 2.x self-hosts TypeScript from
  41. # ``initializationOptions.typescript.tsdk`` (see servers._spawn_vue).
  42. "@vue/language-server": _npm("@vue/language-server@2", "vue-language-server", extra_pkgs=[TYPESCRIPT_SDK_PKG]),
  43. "svelte-language-server": _npm("svelte-language-server", "svelteserver"),
  44. "@astrojs/language-server": _npm("@astrojs/language-server", "astro-ls"),
  45. "yaml-language-server": _npm("yaml-language-server", "yaml-language-server"),
  46. "bash-language-server": _npm("bash-language-server", "bash-language-server"),
  47. "intelephense": _npm("intelephense", "intelephense"),
  48. "dockerfile-language-server-nodejs": _npm("dockerfile-language-server-nodejs", "docker-langserver"),
  49. "gopls": _recipe("go", "golang.org/x/tools/gopls@latest", "gopls"),
  50. # Manual: rust-analyzer (via rustup) and clangd (ships with LLVM) are far too
  51. # heavy to bootstrap; LuaLS is platform-specific GitHub release binaries.
  52. "rust-analyzer": _manual("rust-analyzer"),
  53. "clangd": _manual("clangd"),
  54. "lua-language-server": _manual("lua-language-server"),
  55. # laravel-lsp ships via composer (`composer global require laravel/lsp`), not npm.
  56. "laravel-lsp": _manual("laravel-lsp"),
  57. # PowerShellEditorServices is a release-zip bundle driven by pwsh; we probe
  58. # the host so `hermes lsp status` reports its presence.
  59. "powershell": _manual("pwsh"),
  60. }
  61. _install_locks: dict[str, threading.Lock] = {}
  62. _install_results: dict[str, Optional[str]] = {}
  63. _install_lock_meta = threading.Lock()
  64. _WINDOWS_WRAPPER_SUFFIXES = (".cmd", ".exe", ".bat")
  65. def _is_windows() -> bool:
  66. return os.name == "nt"
  67. def hermes_lsp_bin_dir() -> Path:
  68. """Return the Hermes-owned bin staging dir for LSP servers."""
  69. from hermes_constants import get_hermes_home
  70. p = get_hermes_home() / "lsp" / "bin"
  71. p.mkdir(parents=True, exist_ok=True)
  72. return p
  73. def _native_binary_candidates(base: Path, *, is_windows: Optional[bool] = None) -> list[Path]:
  74. """Return platform-native executable candidates for a staged binary, most runnable first.
  75. On Windows the ``.cmd``/``.exe``/``.bat`` wrappers come BEFORE the bare name: npm writes a
  76. POSIX ``#!/bin/sh`` shim under the bare name next to its ``.cmd``, ``os.access(X_OK)`` is
  77. always true there, and ``CreateProcess`` on the shim fails with WinError 193. The bare name
  78. stays as a last resort for genuinely extension-less executables.
  79. """
  80. if not (_is_windows() if is_windows is None else is_windows):
  81. return [base]
  82. cands: dict[str, Path] = {}
  83. for c in (*(Path(str(base) + s) for s in _WINDOWS_WRAPPER_SUFFIXES), base):
  84. cands.setdefault(str(c).lower(), c)
  85. return list(cands.values())
  86. def _first_existing(*bases: Path, is_windows: Optional[bool] = None) -> Optional[Path]:
  87. """First platform-native candidate of any ``base`` that exists on disk."""
  88. return next((c for base in bases for c in _native_binary_candidates(base, is_windows=is_windows) if c.exists()), None)
  89. def _npm_bin_dir() -> Path:
  90. """npm's own ``node_modules/.bin`` under the staging tree, where its ``%~dp0``-relative wrappers work."""
  91. return hermes_lsp_bin_dir().parent / "node_modules" / ".bin"
  92. def _existing_binary(name: str, *, is_windows: Optional[bool] = None) -> Optional[str]:
  93. """Probe the staging dir (+ npm's bin dir on Windows) then PATH for a binary named ``name``.
  94. ``is_windows`` overrides the host check so the Windows resolution is testable as data on every lane.
  95. """
  96. win = _is_windows() if is_windows is None else is_windows
  97. bases = [hermes_lsp_bin_dir() / name] + ([_npm_bin_dir() / name] if win else [])
  98. for staged in (c for base in bases for c in _native_binary_candidates(base, is_windows=win)):
  99. if staged.exists() and os.access(staged, os.X_OK):
  100. return str(staged)
  101. if any(r.get("strategy") == "pip" and r.get("bin") == name for r in INSTALL_RECIPES.values()):
  102. import pm
  103. try:
  104. binary = pm.python_tool(f"lsp-{name}", name)
  105. except RuntimeError as exc:
  106. logger.warning("[install] cannot read Python server %s: %s", name, exc)
  107. else:
  108. if binary is not None:
  109. return str(binary)
  110. suffixes = (*_WINDOWS_WRAPPER_SUFFIXES, "") if win else ("",)
  111. return next((p for s in suffixes if (p := shutil.which(f"{name}{s}"))), None)
  112. def try_install(pkg: str, strategy: str = "auto") -> Optional[str]:
  113. """Try to install ``pkg``; return the binary path or ``None``.
  114. Only ``"auto"`` installs; ``"manual"``/``"off"`` just probe for an existing
  115. binary. Results are cached per package and concurrent calls are serialized.
  116. """
  117. if strategy != "auto":
  118. return _existing_binary(INSTALL_RECIPES.get(pkg, {}).get("bin", pkg))
  119. if pkg in _install_results:
  120. return _install_results[pkg]
  121. with _install_lock_meta:
  122. lock = _install_locks.setdefault(pkg, threading.Lock())
  123. with lock:
  124. if pkg not in _install_results:
  125. _install_results[pkg] = _do_install(pkg)
  126. return _install_results[pkg]
  127. def _do_install(pkg: str) -> Optional[str]:
  128. recipe = INSTALL_RECIPES.get(pkg)
  129. if recipe is None:
  130. return shutil.which(pkg) # not in our registry — best-effort: just probe PATH
  131. strategy = recipe.get("strategy", "manual")
  132. bin_name = recipe.get("bin", pkg)
  133. if existing := _existing_binary(bin_name):
  134. return existing
  135. if strategy == "manual":
  136. logger.debug("[install] %s requires manual install (recipe=%s)", pkg, recipe)
  137. return None
  138. installer = _INSTALLERS.get(strategy)
  139. if installer is None:
  140. logger.warning("[install] unknown strategy %r for %s", strategy, pkg)
  141. return None
  142. return installer(recipe, bin_name)
  143. def _run_installer(tool: str, pkg: str, cmd: list, *, timeout: int, env: Optional[dict] = None) -> bool:
  144. """Run one install subprocess; log and return False on non-zero exit or error."""
  145. try:
  146. proc = subprocess.run(
  147. cmd, check=False, capture_output=True, text=True, encoding="utf-8", errors="replace",
  148. timeout=timeout, env=env, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags(),
  149. )
  150. if proc.returncode != 0:
  151. # pnpm reports ERR_PNPM_* on stdout with an empty stderr; log whichever stream carries the reason.
  152. detail = (proc.stderr.strip() or proc.stdout.strip())[:500]
  153. logger.warning("[install] %s install failed for %s: %s", tool, pkg, detail)
  154. return False
  155. except (subprocess.TimeoutExpired, OSError) as e:
  156. logger.warning("[install] %s install errored for %s: %s", tool, pkg, e)
  157. return False
  158. return True
  159. def _link_into_bin(target: Path) -> str:
  160. """Symlink (or copy, where symlinks fail) ``target`` into ``lsp/bin/`` and return the path to use."""
  161. link = hermes_lsp_bin_dir() / target.name
  162. if not link.exists():
  163. try:
  164. link.symlink_to(target)
  165. except (OSError, NotImplementedError):
  166. # Symlinks fail on some Windows setups — copy instead.
  167. try:
  168. shutil.copy2(target, link)
  169. except OSError:
  170. return str(target)
  171. return str(link if link.exists() else target)
  172. # Node package manager → argv that installs into ``<staging>/node_modules`` (``lsp.package_manager``).
  173. # Every manager keeps the staging-dir semantics: nothing touches the user's project or global tree.
  174. _NODE_PM_ARGV: dict[str, Callable[[str], list]] = {
  175. "npm": lambda staging: ["install", "--prefix", staging, "--silent", "--no-fund", "--no-audit"],
  176. "pnpm": lambda staging: ["add", "--dir", staging],
  177. # Global ``--cwd`` (before the command) is accepted by both Yarn Classic and Yarn Berry; Berry's
  178. # default PnP linker writes no ``node_modules/.bin``, so the staging dir needs ``nodeLinker: node-modules``.
  179. "yarn": lambda staging: ["--cwd", staging, "add"],
  180. }
  181. def _node_package_manager() -> Optional[str]:
  182. """``lsp.package_manager`` from config (npm default); an unknown value fails closed (``None``)."""
  183. try:
  184. from hermes_cli.config import load_config_readonly
  185. lsp_cfg = load_config_readonly().get("lsp") or {}
  186. except Exception:
  187. return "npm"
  188. pm = str(lsp_cfg.get("package_manager") or "npm").strip().lower() if isinstance(lsp_cfg, dict) else "npm"
  189. if pm not in _NODE_PM_ARGV:
  190. # Fail closed: a typo must not silently bypass a pnpm/yarn supply-chain policy by running npm.
  191. logger.warning("[install] lsp.package_manager=%r is not one of %s; skipping install", pm, sorted(_NODE_PM_ARGV))
  192. return None
  193. return pm
  194. def _install_npm(pkg: str, bin_name: str, extra_pkgs: Optional[list] = None) -> Optional[str]:
  195. """Install with the configured Node package manager into ``<staging>`` and link
  196. ``node_modules/.bin/<bin_name>`` into ``lsp/bin/``."""
  197. pm = _node_package_manager()
  198. if pm is None:
  199. return None
  200. # npm is Hermes's own PM-managed copy, never the user's; pnpm/yarn are an explicit user choice.
  201. pm_bin = find_node_executable(pm)
  202. if pm_bin is None and pm == "npm":
  203. try:
  204. import pm as pm_store
  205. pm_store.ensure("npm")
  206. pm_bin = find_node_executable("npm")
  207. except Exception as exc:
  208. logger.warning("[install] cannot install %s: managed npm unavailable (%s)", pkg, exc)
  209. return None
  210. if pm_bin is None:
  211. # Deliberately no silent fallback to npm: a pnpm/yarn choice is usually a supply-chain policy.
  212. logger.warning("[install] cannot install %s: lsp.package_manager is %r but no usable %s was found "
  213. "(install it, or set lsp.package_manager: npm)", pkg, pm, pm)
  214. return None
  215. staging = hermes_lsp_bin_dir().parent # <HERMES_HOME>/lsp/
  216. install_targets = [pkg] + list(extra_pkgs or [])
  217. cmd = [pm_bin, *_NODE_PM_ARGV[pm](str(staging)), *install_targets]
  218. logger.info("[install] %s %s", pm, " ".join(cmd[1:]))
  219. from tools.environments.local import hermes_subprocess_env
  220. # Package install scripts are third-party code: scrubbed env, never Hermes' credentials.
  221. if not _run_installer(pm, pkg, cmd, timeout=300, env=with_hermes_node_path(hermes_subprocess_env())):
  222. return None
  223. found = _first_existing(staging / "node_modules" / ".bin" / bin_name)
  224. if found is not None:
  225. # npm's Windows wrappers resolve their payload via ``%~dp0\..\<pkg>``, so a copy or symlink
  226. # in ``lsp/bin/`` points at nothing; use them where npm put them (``_existing_binary`` probes there).
  227. return str(found) if _is_windows() and found.suffix.lower() in (".cmd", ".bat") else _link_into_bin(found)
  228. logger.warning("[install] %s install for %s succeeded but bin %s not found", pm, pkg, bin_name)
  229. return None
  230. def _install_go(pkg: str, bin_name: str) -> Optional[str]:
  231. """Install a Go module to GOBIN=<staging>."""
  232. go = shutil.which("go")
  233. if go is None:
  234. logger.info("[install] cannot install %s: go not on PATH", pkg)
  235. return None
  236. staging = hermes_lsp_bin_dir()
  237. logger.info("[install] go install %s (GOBIN=%s)", pkg, staging)
  238. from tools.environments.local import hermes_subprocess_env
  239. env = {**hermes_subprocess_env(), "GOBIN": str(staging)}
  240. if not _run_installer("go", pkg, [go, "install", pkg], timeout=600, env=env):
  241. return None
  242. bin_path = (staging / bin_name).with_suffix(".exe") if _is_windows() else staging / bin_name
  243. if bin_path.exists():
  244. return str(bin_path)
  245. logger.warning("[install] go install for %s succeeded but bin %s not found", pkg, bin_name)
  246. return None
  247. def _install_pip(pkg: str, bin_name: str) -> Optional[str]:
  248. """Provision a Python server in its own PM-managed environment."""
  249. try:
  250. import pm
  251. return str(pm.ensure_python_tool(f"lsp-{bin_name}", [pkg], bin_name, timeout=300))
  252. except Exception as exc:
  253. logger.warning("[install] Python server install failed for %s: %s", pkg, exc)
  254. return None
  255. # strategy → installer(recipe, bin_name). ``manual`` is handled before dispatch.
  256. _INSTALLERS: dict[str, Callable[[dict[str, Any], str], Optional[str]]] = {
  257. "npm": lambda r, b: _install_npm(r["pkg"], b, extra_pkgs=r.get("extra_pkgs") or []),
  258. "go": lambda r, b: _install_go(r["pkg"], b),
  259. "pip": lambda r, b: _install_pip(r["pkg"], b),
  260. }
  261. def detect_status(pkg: str) -> str:
  262. """Return ``installed``, ``missing``, or ``manual-only`` (for ``hermes lsp status``; spawns nothing)."""
  263. recipe = INSTALL_RECIPES.get(pkg)
  264. if _existing_binary(recipe.get("bin", pkg) if recipe else pkg):
  265. return "installed"
  266. return "manual-only" if recipe and recipe.get("strategy") == "manual" else "missing"
  267. __all__ = ["INSTALL_RECIPES", "detect_status", "hermes_lsp_bin_dir", "try_install"]