skills_sync_bundled_ops.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. """Bundled-skill maintenance ops: reset, diff, list-modified, opt-out, remove-pristine.
  2. Profile-scoped paths and patchable helpers resolve through ``_ss()`` at call time."""
  3. import os
  4. import shutil
  5. from pathlib import Path
  6. from typing import List, Optional, Tuple
  7. from tools.skills_sync_optional import _ignore_runtime_cache, _skill_file_list, _ss
  8. def _bundled_state():
  9. """``(skills_sync, manifest, bundled_dir, {skill_name: bundled_src})`` — shared op preamble."""
  10. ss = _ss()
  11. bundled_dir = ss._get_bundled_dir()
  12. return ss, ss._read_manifest(), bundled_dir, dict(ss._discover_bundled_skills(bundled_dir))
  13. def reset_bundled_skill(name: str, restore: bool = False) -> dict:
  14. """Reset a bundled skill's manifest tracking so future syncs work normally. An edited bundled
  15. skill stays ``user_modified`` forever because the manifest holds the OLD origin hash; clearing
  16. the entry breaks that loop. ``restore`` also deletes the user's copy so the next sync re-copies
  17. bundled. Returns ``{ok, action, message, synced}``; action is manifest_cleared / restored /
  18. not_in_manifest / bundled_missing / not_reset."""
  19. ss, manifest, bundled_dir, bundled_by_name = _bundled_state()
  20. in_manifest = name in manifest
  21. is_bundled = name in bundled_by_name
  22. def _fail(action: str, message: str) -> dict:
  23. return {"ok": False, "action": action, "message": message, "synced": None}
  24. if not in_manifest and not is_bundled:
  25. return _fail("not_in_manifest", f"'{name}' is not a tracked bundled skill. Nothing to reset. "
  26. f"(Hub-installed skills use `hermes skills uninstall`.)")
  27. # Step 1 (optional): delete the user's copy so next sync re-copies bundled. Must happen BEFORE manifest
  28. # deletion so that a failed rmtree does not leave the skill in a manifest-less limbo state (see #34972).
  29. deleted_user_copy = False
  30. if restore: # delete the user's copy BEFORE the manifest so a failed rmtree can't strand it
  31. if not is_bundled:
  32. return _fail("bundled_missing", f"'{name}' has no bundled source — manifest entry preserved "
  33. f"but cannot restore from bundled (skill was removed upstream).")
  34. dest = ss._compute_relative_dest(bundled_by_name[name], bundled_dir)
  35. if deleted_user_copy := dest.exists():
  36. try:
  37. ss._rmtree_writable(dest)
  38. except OSError as e:
  39. return _fail("not_reset", f"Could not delete user copy at {dest}: {e}. "
  40. f"Manifest entry preserved — nothing was changed.")
  41. if in_manifest:
  42. del manifest[name]
  43. ss._write_manifest(manifest)
  44. synced = ss.sync_skills(quiet=True)
  45. if not restore:
  46. action, message = "manifest_cleared", (f"Cleared manifest entry for '{name}'. Future `hermes update` runs "
  47. f"will re-baseline against your current copy and accept upstream changes.")
  48. else:
  49. action = "restored"
  50. message = (f"Restored '{name}' from bundled source." if deleted_user_copy
  51. else f"Restored '{name}' (no prior user copy, re-copied from bundled).")
  52. return {"ok": True, "action": action, "message": message, "synced": synced}
  53. _OWN_REPO_PREFIXES = ("nousresearch/hermes-agent/skills/", "skills-sh/nousresearch/hermes-agent/")
  54. def bundled_skill_for_install(identifier: str) -> Optional[str]:
  55. """Bundled skill name an install identifier means, else None: a bare bundled name, or this
  56. repo's own copy of one (``NousResearch/hermes-agent/skills/<cat>/<name>``, which the Skills Hub
  57. site hands out for built-ins, or its ``skills-sh/nousresearch/hermes-agent/<name>`` mirror).
  58. Fetched from GitHub, that copy is scanned as a community skill and refused — every time."""
  59. ident = identifier.strip().strip("/")
  60. lowered = ident.lower()
  61. if "/" in ident and not lowered.startswith(_OWN_REPO_PREFIXES):
  62. return None
  63. name = ident.rsplit("/", 1)[-1]
  64. return name if name in _bundled_state()[3] else None
  65. def ensure_bundled_skill(name: str) -> dict:
  66. """Make bundled ``name`` active: ``{ok, action, path, message}``, action ``present`` (any active
  67. copy, user edits included, is left alone), ``restored`` (copied from the bundled source and
  68. re-tracked, so an opt-out, curator prune or manual delete no longer hides it), or
  69. ``hub_shadowed`` (a hub install owns the name; it is the user's to remove, never overwritten).
  70. A restore into a leftover dir only adds the missing files (a user file is never overwritten) and
  71. the manifest records the bundled hash, so a dest that kept user files reads as user-modified and
  72. ``hermes update`` leaves it alone: intended, the user's data wins."""
  73. from tools import skill_usage
  74. ss, manifest, bundled_dir, bundled_by_name = _bundled_state()
  75. src = bundled_by_name[name]
  76. dest = ss._compute_relative_dest(src, bundled_dir)
  77. if skill_usage.is_hub_installed(name):
  78. return {"ok": True, "action": "hub_shadowed", "path": None, "message": (
  79. f"'{name}' is a built-in skill, but a skill installed from the hub uses the same name and "
  80. f"shadows it. To get the built-in back: `hermes skills uninstall {name}`, then "
  81. f"`hermes skills install {name}`.")}
  82. # The rglob walk does not descend a symlinked category the loader follows, so the canonical
  83. # SKILL.md counts as present too.
  84. skill_md = dest / "SKILL.md"
  85. active = next((md.parent for md in ss._iter_active_skill_mds()
  86. if ss.read_skill_name(md, md.parent.name) == name), None) or (
  87. dest if skill_md.is_file() and ss.read_skill_name(skill_md, name) == name else None)
  88. if active is not None or name in ss._build_external_skill_index():
  89. return {"ok": True, "action": "present", "path": active, "message": ""}
  90. try: # the hub's containment check: a symlinked category must not carry the copy out of skills/
  91. from pm.filesystem import is_junction
  92. from tools.skills_hub_install import _resolve_lock_install_path
  93. rel = dest.relative_to(ss._skills_dir()).as_posix()
  94. _resolve_lock_install_path(rel, dest.name)
  95. # A dir with no SKILL.md (a delete or earlier copy that died partway) is no skill; filling in
  96. # its missing files beats failing with EEXIST on every retry. A link inside it would carry the
  97. # copy out of skills/, and a SKILL.md there is another skill: refuse both.
  98. if os.path.lexists(skill_md):
  99. raise ValueError("the directory holds a different skill's SKILL.md")
  100. if dest.exists() and any(p.is_symlink() or is_junction(p) for p in dest.rglob("*")):
  101. raise ValueError("the leftover directory contains a symlink or junction")
  102. dest.parent.mkdir(parents=True, exist_ok=True)
  103. shutil.copytree(src, dest, ignore=_ignore_runtime_cache, dirs_exist_ok=True,
  104. copy_function=lambda s, d: d if os.path.lexists(d) else shutil.copy2(s, d))
  105. except (OSError, ValueError) as e:
  106. return {"ok": False, "action": "not_restored", "path": dest,
  107. "message": f"Could not copy the built-in skill '{name}' to {dest}: {e}"}
  108. manifest[name] = ss.dir_hash(src)
  109. ss._write_manifest(manifest)
  110. skill_usage._toggle_suppressed_name(name, add=False) # lift a curator prune the way restore_skill does
  111. skill_usage.set_state(name, skill_usage.STATE_ACTIVE)
  112. return {"ok": True, "action": "restored", "path": dest, "message": ""}
  113. def list_user_modified_bundled_skills() -> list[dict]:
  114. """Bundled skills ``hermes update`` keeps because the user edited them (same test the sync
  115. loop uses). Name-sorted ``{"name", "dest", "bundled_src"}`` dicts."""
  116. ss = _ss()
  117. if not (manifest := ss._read_manifest()):
  118. return []
  119. bundled_dir = ss._get_bundled_dir()
  120. modified: list[dict] = []
  121. for skill_name, skill_dir in ss._discover_bundled_skills(bundled_dir):
  122. origin_hash = manifest.get(skill_name, "") # empty = untracked/un-baselined v1: next sync handles it
  123. dest = ss._compute_relative_dest(skill_dir, bundled_dir)
  124. if origin_hash and dest.exists() and not ss._matches_origin_hash(dest, origin_hash):
  125. modified.append({"name": skill_name, "dest": dest, "bundled_src": skill_dir})
  126. return sorted(modified, key=lambda e: e["name"])
  127. def _read_for_diff(path: Path) -> tuple[Optional[bytes], Optional[str]]:
  128. """``(raw_bytes, text)`` for diffing; ``text=None`` for binary, ``(None, None)`` if unreadable."""
  129. try:
  130. data = path.read_bytes()
  131. except OSError:
  132. return None, None
  133. try:
  134. return data, (None if b"\x00" in data else data.decode("utf-8"))
  135. except UnicodeDecodeError:
  136. return data, None
  137. def diff_bundled_skill(name: str) -> dict:
  138. """Diff a user's copy of a bundled skill against stock. Returns ``{ok, name, found, modified,
  139. message, diffs}``; each diff is ``{"path", "status", "diff"}`` with status modified / added
  140. (only in user copy) / removed (only in bundled) / binary."""
  141. import difflib
  142. ss, _, bundled_dir, bundled_by_name = _bundled_state()
  143. def _fail(found: bool, message: str) -> dict:
  144. return {"ok": False, "name": name, "found": found, "modified": False, "diffs": [], "message": message}
  145. if (bundled_src := bundled_by_name.get(name)) is None:
  146. return _fail(False, f"'{name}' is not a tracked bundled skill (no stock version to "
  147. f"diff against). Hub-installed skills use `hermes skills inspect`.")
  148. dest = ss._compute_relative_dest(bundled_src, bundled_dir)
  149. if not dest.exists():
  150. return _fail(True, f"No local copy of '{name}' found at {dest}.")
  151. user_files = set(_skill_file_list(dest))
  152. stock_files = set(_skill_file_list(bundled_src))
  153. diffs: list[dict] = []
  154. for rel in sorted(user_files | stock_files):
  155. if rel not in stock_files:
  156. diffs.append({"path": rel, "status": "added", "diff": f"+ only in your copy: {rel}"})
  157. continue
  158. if rel not in user_files:
  159. diffs.append({"path": rel, "status": "removed", "diff": f"- only in stock: {rel}"})
  160. continue
  161. user_bytes, user_text = _read_for_diff(dest / rel)
  162. stock_bytes, stock_text = _read_for_diff(bundled_src / rel)
  163. if user_text is None or stock_text is None: # a binary side: report only if bytes differ
  164. if user_bytes != stock_bytes:
  165. diffs.append({"path": rel, "status": "binary", "diff": "<binary file differs>"})
  166. elif user_text != stock_text:
  167. text = "".join(difflib.unified_diff(
  168. stock_text.splitlines(keepends=True), user_text.splitlines(keepends=True),
  169. fromfile=f"stock/{rel}", tofile=f"yours/{rel}"))
  170. diffs.append({"path": rel, "status": "modified", "diff": text})
  171. message = (f"'{name}' differs from the stock version in {len(diffs)} file(s)." if diffs
  172. else f"'{name}' matches the stock version.")
  173. return {"ok": True, "name": name, "found": True, "modified": bool(diffs), "diffs": diffs, "message": message}
  174. _OPT_OUT_MESSAGES = { # (enabled, changed) -> message
  175. (True, True): "Opted out of bundled skills. Future install / update / sync runs will not seed bundled skills into this profile.",
  176. (True, False): "Already opted out — marker was already present.",
  177. (False, True): "Opted back in. The next `hermes update` (or `hermes skills opt-in --sync`) will re-seed bundled skills.",
  178. (False, False): "Not opted out — no marker to remove."}
  179. def set_bundled_skills_opt_out(enabled: bool) -> dict:
  180. """Toggle the .no-bundled-skills marker (on-disk half of ``hermes skills opt-out`` / ``opt-in``;
  181. removing present skills is ``remove_pristine_bundled_skills``)."""
  182. ss = _ss()
  183. marker = ss._hermes_home() / ss.NO_BUNDLED_SKILLS_MARKER
  184. existed = marker.exists()
  185. try:
  186. if enabled:
  187. ss._hermes_home().mkdir(parents=True, exist_ok=True)
  188. marker.write_text(
  189. "This profile opted out of bundled-skill seeding (`hermes skills opt-out`).\n"
  190. "Delete this file to re-enable sync on the next `hermes update`.\n",
  191. encoding="utf-8")
  192. elif existed:
  193. marker.unlink()
  194. except OSError as e:
  195. return {"ok": False, "changed": False, "marker": str(marker),
  196. "message": f"Could not update opt-out marker at {marker}: {e}"}
  197. changed = enabled != existed
  198. return {"ok": True, "changed": changed, "marker": str(marker), "message": _OPT_OUT_MESSAGES[(enabled, changed)]}
  199. def remove_pristine_bundled_skills(dry_run: bool = False) -> dict:
  200. """Delete bundled skills that are manifest-tracked, still in the bundled source AND
  201. byte-identical to the origin hash; everything else lands in ``skipped``. Removed skills lose
  202. their manifest entry so a later opt-in re-seed treats them as new.
  203. Returns ``{ok, removed, skipped: [{name, reason}], dry_run, message}``."""
  204. ss, manifest, bundled_dir, bundled_by_name = _bundled_state()
  205. removed: list[str] = []
  206. skipped: list[dict] = []
  207. for name, origin_hash in sorted(manifest.items()):
  208. src = bundled_by_name.get(name)
  209. if src is None:
  210. skipped.append({"name": name, "reason": "no bundled source (removed upstream)"})
  211. continue
  212. dest = ss._compute_relative_dest(src, bundled_dir)
  213. if not dest.exists():
  214. if not dry_run: # already gone from disk; forget the stale manifest entry
  215. manifest.pop(name, None)
  216. continue
  217. if not ss._matches_origin_hash(dest, origin_hash):
  218. skipped.append({"name": name, "reason": "user-modified (kept)"})
  219. continue
  220. if not dry_run:
  221. try:
  222. ss._rmtree_writable(dest)
  223. except OSError as e:
  224. skipped.append({"name": name, "reason": f"delete failed: {e}"})
  225. continue
  226. manifest.pop(name, None)
  227. removed.append(name)
  228. if not dry_run and removed:
  229. ss._write_manifest(manifest)
  230. verb = "Would remove" if dry_run else "Removed"
  231. return {"ok": True, "removed": removed, "skipped": skipped, "dry_run": dry_run,
  232. "message": f"{verb} {len(removed)} pristine bundled skill(s); kept {len(skipped)}."}