plugins_cmd_git.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374
  1. """Plugin install metadata (``.install-metadata.json`` source/revision/pin records) and the git plumbing
  2. behind clone, exact-revision checkout, credential scrubbing and the autostashing ``git pull``.
  3. Sibling of :mod:`hermes_cli.plugins_cmd` (the facade re-exports the names other modules use and is
  4. imported late here, never at module level).
  5. """
  6. from __future__ import annotations
  7. import json
  8. import re
  9. import subprocess
  10. import threading
  11. import urllib.parse
  12. from contextlib import contextmanager
  13. from pathlib import Path
  14. from typing import Callable, Optional
  15. from hermes_cli._subprocess_compat import noninteractive_git_env
  16. from hermes_constants import get_hermes_home
  17. from utils import atomic_write_text
  18. def _pc():
  19. """The facade, read at call time: tests patch ``plugins_cmd.<name>`` and sibling calls must see it."""
  20. from hermes_cli import plugins_cmd
  21. return plugins_cmd
  22. _EXACT_COMMIT_RE = re.compile(r"^[0-9a-fA-F]{40}$")
  23. def _install_metadata_path() -> Path:
  24. return get_hermes_home() / "plugins" / ".install-metadata.json"
  25. def _read_install_metadata() -> dict[str, dict[str, object]]:
  26. """Read profile-local, non-secret plugin source metadata from disk."""
  27. path = _install_metadata_path()
  28. if not path.exists():
  29. return {}
  30. try:
  31. value = json.loads(path.read_text(encoding="utf-8-sig"))
  32. except (OSError, json.JSONDecodeError) as exc:
  33. raise _pc().PluginOperationError(f"Could not read plugin install metadata: {exc}") from exc
  34. if not isinstance(value, dict):
  35. raise _pc().PluginOperationError("Plugin install metadata must be a JSON object.")
  36. return value
  37. def _write_install_metadata(metadata: dict[str, dict[str, object]]) -> None:
  38. """Atomically replace the profile-local plugin install metadata sidecar."""
  39. path = _install_metadata_path()
  40. atomic_write_text(
  41. path, json.dumps(metadata, indent=2, sort_keys=True) + "\n", tmp_prefix=f"{path.name}.tmp-")
  42. _INSTALL_METADATA_LOCK_HOLDER = threading.local()
  43. @contextmanager
  44. def _install_metadata_lock():
  45. """Serialize read-modify-write of the sidecar across threads and processes. Installs overlap (the
  46. Desktop install card runs its rows a second apart); each held a snapshot read before its clone, so
  47. the later write dropped the earlier plugin's record."""
  48. from hermes_cli.auth import _file_lock
  49. path = _install_metadata_path()
  50. with _file_lock(path.with_name(f"{path.name}.lock"), _INSTALL_METADATA_LOCK_HOLDER, 10.0,
  51. "Timed out waiting for the plugin install metadata lock"):
  52. yield
  53. def _update_install_record(name: str, update: Callable[[Optional[dict]], Optional[dict]]) -> None:
  54. """Rewrite one plugin's record in the CURRENT sidecar, under the lock. *update* maps the current
  55. record (None when absent) to the new one (None removes it); every other record is re-read here,
  56. never carried over from a caller's earlier snapshot."""
  57. with _install_metadata_lock():
  58. metadata = _pc()._read_install_metadata()
  59. record = update(metadata.get(name))
  60. if record is None:
  61. if name not in metadata:
  62. return
  63. del metadata[name]
  64. else:
  65. metadata[name] = record
  66. _pc()._write_install_metadata(metadata)
  67. def pinned_revision(name: str, metadata: Optional[dict] = None) -> Optional[str]:
  68. """Full SHA a ``--ref`` install of *name* is pinned to, else ``None``."""
  69. entry = (metadata if metadata is not None else _pc()._read_install_metadata()).get(name)
  70. if isinstance(entry, dict) and entry.get("pinned") is True and isinstance(entry.get("revision"), str):
  71. return entry["revision"]
  72. return None
  73. def _pin_annotation(name: str, metadata: dict) -> Optional[str]:
  74. sha = pinned_revision(name, metadata)
  75. return f"git pinned@{sha[:8]}" if sha else None
  76. def _normalize_exact_revision(ref: str) -> str:
  77. """Lowercase a full 40-hex commit SHA; anything else is a PluginOperationError."""
  78. if not isinstance(ref, str) or not _EXACT_COMMIT_RE.fullmatch(ref):
  79. raise _pc().PluginOperationError("--ref must be a full 40-character commit SHA.")
  80. return ref.lower()
  81. def _safe_git_error(result: subprocess.CompletedProcess, source_url: str = "") -> str:
  82. """Diagnosable Git output without echoing embedded credentials."""
  83. from agent.redact import redact_sensitive_text
  84. error = (result.stderr or result.stdout or "").strip()
  85. if source_url:
  86. error = error.replace(source_url, _scrub_git_url(source_url))
  87. return redact_sensitive_text(error)
  88. def _git_or_raise(
  89. git_exe: str, repo: Path, *args: str, failure_prefix: str, timeout: int = 60, source_url: str = "",
  90. auth_url: str = "",
  91. ) -> subprocess.CompletedProcess:
  92. """Run git in *repo*; on a non-zero exit raise PluginOperationError(prefix + scrubbed error)."""
  93. result = _pc()._run_plugin_git(git_exe, repo, *args, timeout=timeout, auth_url=auth_url)
  94. if result.returncode != 0:
  95. raise _pc().PluginOperationError(failure_prefix + _safe_git_error(result, source_url),
  96. failure_class="clone_failed")
  97. return result
  98. def _git_head_revision(repo: Path, git_exe: str) -> str:
  99. return _git_or_raise(
  100. git_exe, repo, "rev-parse", "HEAD", timeout=15,
  101. failure_prefix="Could not determine installed Git revision:\n",
  102. ).stdout.strip().lower()
  103. def _git_resolve_commit(repo: Path, git_exe: str, revision: str) -> str:
  104. """The COMMIT a revision names, peeling annotated tags.
  105. A catalog pin is 40 hex, but that does not make it a commit: a tag object
  106. has a sha of its own, and a pin recorded as `git rev-parse <tag>` names the
  107. tag object, not the commit it points at. Git detaches at the commit, so
  108. comparing HEAD against the tag object's sha refuses a correct checkout
  109. (and the catalog installer then cannot install that entry at all). Peeling
  110. first keeps the guard — HEAD must still BE that commit — while admitting
  111. the pins authors actually publish. Returns `revision` unchanged when it
  112. resolves to nothing, so the mismatch guard below still fires.
  113. """
  114. try:
  115. result = _pc()._run_plugin_git(
  116. git_exe, repo, "rev-parse", "--verify", "--quiet", f"{revision}^{{commit}}", timeout=15,
  117. )
  118. except (OSError, subprocess.TimeoutExpired):
  119. return revision
  120. resolved = result.stdout.strip().lower()
  121. return resolved if result.returncode == 0 and resolved else revision
  122. def _checkout_exact_revision(repo: Path, git_exe: str, revision: str, source_url: str = "") -> None:
  123. """Fetch and detach at one immutable commit, then verify the resulting HEAD. The checkout is
  124. a network verb too: in a partial (subdirectory) clone it downloads the file contents."""
  125. timeout = _pc()._clone_timeout_seconds()
  126. for verb, args, failure_prefix in (
  127. ("fetch", ("fetch", "--depth", "1", "origin", revision), f"Git commit '{revision}' could not be fetched:\n"),
  128. ("checkout", ("checkout", "--detach", revision), f"Git checkout of commit '{revision}' failed:\n"),
  129. ):
  130. try:
  131. _git_or_raise(git_exe, repo, *args, failure_prefix=failure_prefix, source_url=source_url,
  132. auth_url=source_url, timeout=timeout)
  133. except subprocess.TimeoutExpired as exc:
  134. raise _pc().PluginOperationError(
  135. f"Git {verb} of commit '{revision}' timed out after {timeout} seconds. {_pc()._CLONE_TIMEOUT_HINT}",
  136. failure_class="clone_failed") from exc
  137. actual = _pc()._git_head_revision(repo, git_exe)
  138. if actual != _git_resolve_commit(repo, git_exe, revision):
  139. raise _pc().PluginOperationError(
  140. f"Checked-out revision '{actual}' does not match requested commit '{revision}'.",
  141. failure_class="clone_failed")
  142. def _scrub_git_url(git_url: str) -> str:
  143. """Strip credentials and query/fragment data from an HTTP Git URL."""
  144. parsed = urllib.parse.urlsplit(git_url)
  145. if parsed.scheme in {"http", "https"} and parsed.hostname:
  146. host = f"[{parsed.hostname}]" if ":" in parsed.hostname else parsed.hostname
  147. if parsed.port is not None:
  148. host = f"{host}:{parsed.port}"
  149. return urllib.parse.urlunsplit((parsed.scheme, host, parsed.path, "", ""))
  150. return git_url
  151. def _canonical_source(git_url: str, subdir: Optional[str]) -> str:
  152. scrubbed = _scrub_git_url(git_url)
  153. return f"{scrubbed}#{subdir}" if subdir else scrubbed
  154. def _scrub_cloned_origin(repo: Path, git_exe: str, git_url: str) -> None:
  155. """Ensure credentials used for cloning do not survive in ``.git/config``."""
  156. scrubbed = _scrub_git_url(git_url)
  157. if scrubbed != git_url:
  158. _git_or_raise(
  159. git_exe, repo, "remote", "set-url", "origin", scrubbed, timeout=15,
  160. failure_prefix="Could not sanitize installed Git remote:\n", source_url=git_url)
  161. def _restrict_checkout_to_subdir(repo: Path, git_exe: str, subdir: str) -> None:
  162. """Sparse-check-out only *subdir*. Written as the classic ``info/sparse-checkout`` file
  163. rather than ``git sparse-checkout set`` so older Git clients work too."""
  164. _git_or_raise(git_exe, repo, "config", "core.sparseCheckout", "true", timeout=15,
  165. failure_prefix="Could not enable sparse checkout:\n")
  166. pattern_file = repo / ".git" / "info" / "sparse-checkout"
  167. pattern_file.parent.mkdir(parents=True, exist_ok=True)
  168. escaped = re.sub(r"([\\*?\[])", r"\\\1", subdir.strip("/"))
  169. pattern_file.write_text(f"/{escaped}/\n", encoding="utf-8")
  170. def _clone_plugin_repo(tmp_clone: Path, git_url: str, revision: Optional[str],
  171. subdir: Optional[str] = None) -> str:
  172. """Shallow-clone *git_url* into *tmp_clone* (detached at *revision* when given), scrub any
  173. credentials from the recorded origin, and return the installed HEAD SHA.
  174. A *subdir* install is a blobless clone with a sparse checkout of that subdirectory: a plugin
  175. living in a monorepo (Hindsight: 170 MB at depth 1, 2 MB for its plugin folder) otherwise
  176. downloads every file in the repository, which times out on slow connections."""
  177. git_exe = _pc()._resolve_git_executable()
  178. if not git_exe:
  179. raise _pc().PluginOperationError("git is not installed or not in PATH.", failure_class="git_missing")
  180. clone_timeout = _pc()._clone_timeout_seconds()
  181. partial = ["--filter=blob:none"] if subdir else []
  182. no_checkout = ["--no-checkout"] if revision or subdir else []
  183. clone_args = ["clone", "--depth", "1", *partial, *no_checkout, git_url, str(tmp_clone)]
  184. try:
  185. result = _pc()._run_plugin_git(git_exe, tmp_clone.parent, *clone_args, auth_url=git_url,
  186. timeout=clone_timeout)
  187. except FileNotFoundError as e:
  188. raise _pc().PluginOperationError("git is not installed or not in PATH.", failure_class="git_missing") from e
  189. except subprocess.TimeoutExpired as e:
  190. raise _pc().PluginOperationError(f"Git clone timed out after {clone_timeout} seconds. {_pc()._CLONE_TIMEOUT_HINT}",
  191. failure_class="clone_failed") from e
  192. if result.returncode != 0:
  193. raise _pc().PluginOperationError(_pc()._clone_failure_message(git_url, _safe_git_error(result, git_url)),
  194. failure_class="clone_failed")
  195. _scrub_cloned_origin(tmp_clone, git_exe, git_url)
  196. if subdir:
  197. _restrict_checkout_to_subdir(tmp_clone, git_exe, subdir)
  198. if revision:
  199. _checkout_exact_revision(tmp_clone, git_exe, revision, source_url=git_url)
  200. elif subdir:
  201. try:
  202. _git_or_raise(git_exe, tmp_clone, "checkout", "HEAD", timeout=clone_timeout, source_url=git_url,
  203. auth_url=git_url, failure_prefix="Git checkout of the plugin subdirectory failed:\n")
  204. except subprocess.TimeoutExpired as e:
  205. raise _pc().PluginOperationError(
  206. f"Git checkout timed out after {clone_timeout} seconds. {_pc()._CLONE_TIMEOUT_HINT}",
  207. failure_class="clone_failed") from e
  208. return _pc()._git_head_revision(tmp_clone, git_exe)
  209. def _run_plugin_git(
  210. git_exe: str, target: Path, *args: str, timeout: int = 60, auth_url: str = "",
  211. ) -> subprocess.CompletedProcess:
  212. """Run one git command inside a plugin checkout (non-interactive). *auth_url* names the remote
  213. a network verb talks to; it runs anonymously first and a stored user credential for that host
  214. is attached only when the remote refuses anonymous access (private repos)."""
  215. from hermes_cli.git_credentials import run_git_with_credential_fallback
  216. return run_git_with_credential_fallback(
  217. [git_exe, *args], auth_url, env=noninteractive_git_env(), capture_output=True, text=True,
  218. encoding='utf-8', errors='replace', timeout=timeout, cwd=str(target))
  219. def _stash_ref(git_exe: str, target: Path) -> str:
  220. """Current ``refs/stash`` commit, or empty string when no stash exists."""
  221. probe = _pc()._run_plugin_git(git_exe, target, "rev-parse", "--verify", "refs/stash")
  222. return probe.stdout.strip() if probe.returncode == 0 else ""
  223. def _reapply_stash(git_exe: str, target: Path, stash_sha: str) -> bool:
  224. """``stash apply`` the autostash commit *stash_sha*; drop it on a clean apply. False when it
  225. applied with errors or left unmerged paths (the stash entry is kept in that case).
  226. Git is addressed by the stash's commit sha, never a ``stash@{N}`` selector: on native Windows
  227. the MSYS runtime re-parses git.exe's argv and strips the braces, so ``stash@{0}`` reaches git
  228. as ``stash@0`` and both the apply and the drop fail (#87542)."""
  229. restore = _pc()._run_plugin_git(git_exe, target, "stash", "apply", stash_sha)
  230. unmerged = _pc()._run_plugin_git(git_exe, target, "diff", "--name-only", "--diff-filter=U")
  231. if restore.returncode != 0 or unmerged.stdout.strip():
  232. return False
  233. # `stash drop` only takes a selector; a bare `drop` targets the newest entry, so drop
  234. # positionally only while the newest entry is still our autostash.
  235. if _stash_ref(git_exe, target) == stash_sha:
  236. _pc()._run_plugin_git(git_exe, target, "stash", "drop")
  237. return True
  238. def _autostash_dirty_tree(git_exe: str, target: Path) -> tuple[str, str]:
  239. """Stash local edits before a pull. Returns ``(stash_sha, error)``; *stash_sha* is empty when
  240. the tree was clean, and a non-empty error means the tree is dirty but nothing was saved, so
  241. the pull must not run."""
  242. status = _pc()._run_plugin_git(git_exe, target, "status", "--porcelain", "-z")
  243. if status.returncode != 0 or not status.stdout.strip():
  244. return "", ""
  245. # `git add -N` entries make `git stash push` fail outright (see update_cmd_stash), so promote them
  246. # to real staged adds first; the checkout's own local edits are otherwise unstashable.
  247. from hermes_cli.update_cmd_stash import _intent_to_add_paths
  248. intent_to_add = _intent_to_add_paths(status.stdout)
  249. if intent_to_add:
  250. _pc()._run_plugin_git(git_exe, target, "add", "--", *intent_to_add)
  251. pre_stash = _stash_ref(git_exe, target)
  252. push = _pc()._run_plugin_git(
  253. git_exe, target, "stash", "push", "--include-untracked", "-m", "hermes-plugin-update-autostash")
  254. post_stash = _stash_ref(git_exe, target)
  255. if not post_stash or post_stash == pre_stash:
  256. err = _safe_git_error(push)
  257. return "", (
  258. "Local changes in the plugin checkout could not be "
  259. "stashed; update aborted before touching the checkout."
  260. + (f"\n{err}" if err else ""))
  261. if push.returncode != 0:
  262. # Saved-but-couldn't-clean (undeletable untracked files): the stash entry is complete;
  263. # reset tracked mods so the pull isn't blocked by a still-dirty tree.
  264. _pc()._run_plugin_git(git_exe, target, "reset", "--hard", "HEAD")
  265. return post_stash, ""
  266. def _git_pull_plugin_dir(target: Path) -> tuple[bool, str]:
  267. """``git pull --ff-only`` a plugin checkout, autostashing local edits (users patch installed
  268. plugins in place, and a plain ff-only pull would then refuse forever).
  269. Users tweak installed plugins in place (config constants, small patches), and a plain ``pull --ff-only``
  270. then aborts with "Your local changes ... would be overwritten by merge" — making the plugin permanently
  271. un-updatable until they hand-run git. Same UX class Factory Droid fixed in v0.188 ("Updating a plugin
  272. marketplace now succeeds when its checkout has local changes"), and the same autostash approach ``hermes
  273. update`` already uses for the main checkout (PR #70161).
  274. """
  275. git_exe = _pc()._resolve_git_executable()
  276. if not git_exe:
  277. return False, "git is not installed or not in PATH."
  278. try:
  279. stash_sha, err = _autostash_dirty_tree(git_exe, target)
  280. if err:
  281. return False, err
  282. origin = _pc()._run_plugin_git(git_exe, target, "remote", "get-url", "origin", timeout=15)
  283. result = _pc()._run_plugin_git(git_exe, target, "pull", "--ff-only", auth_url=origin.stdout.strip())
  284. if result.returncode != 0:
  285. err = _safe_git_error(result) or "git pull failed."
  286. if not stash_sha:
  287. return False, err
  288. # Put the user's edits back before reporting the failure.
  289. if _reapply_stash(git_exe, target, stash_sha):
  290. note = "Local changes were restored."
  291. else:
  292. note = "Local changes are preserved in git stash (restore with: git stash pop)."
  293. return False, f"{err}\n{note}"
  294. pulled = result.stdout.strip()
  295. if not stash_sha:
  296. return True, pulled
  297. if _reapply_stash(git_exe, target, stash_sha):
  298. return True, pulled + "\nLocal changes were re-applied on top of the update."
  299. # Conflicted re-apply: leave the plugin importable on the updated
  300. # revision; the user's edits stay safe in the stash entry.
  301. _pc()._run_plugin_git(git_exe, target, "reset", "--hard", "HEAD")
  302. return True, pulled + (
  303. "\n⚠ Local changes in this plugin conflicted with the update and "
  304. "were NOT re-applied. They are preserved in git stash — inspect "
  305. "with `git stash show -p` and re-apply with "
  306. f"`git stash pop` inside {target}.")
  307. except FileNotFoundError:
  308. return False, "git is not installed or not in PATH."
  309. except subprocess.TimeoutExpired:
  310. return False, "Git operation timed out after 60 seconds."