pets.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428
  1. """CLI subcommand: ``hermes pets <subcommand>``."""
  2. from __future__ import annotations
  3. import argparse
  4. import sys
  5. from utils import is_truthy_value
  6. def _err(msg: str) -> None:
  7. print(msg, file=sys.stderr)
  8. def _cmd_list(args) -> int:
  9. """List gallery pets (or only installed ones with ``--installed``)."""
  10. from agent.pet import store
  11. if args.installed:
  12. pets = store.installed_pets()
  13. if not pets:
  14. print("No pets installed. Try: hermes pets install boba")
  15. return 0
  16. print(f"Installed pets ({len(pets)}):")
  17. for pet in pets:
  18. print(f" {pet.slug:<24} {pet.display_name}")
  19. return 0
  20. from agent.pet.manifest import ManifestError, fetch_manifest
  21. try:
  22. entries = fetch_manifest()
  23. except ManifestError as exc:
  24. _err(f"✗ {exc}")
  25. return 1
  26. query = (args.query or "").strip().lower()
  27. if query:
  28. entries = [e for e in entries if query in e.slug.lower() or query in e.display_name.lower()]
  29. limit = args.limit or 0
  30. shown = entries[:limit] if limit > 0 else entries
  31. installed = {p.slug for p in store.installed_pets()}
  32. print(f"petdex gallery — {len(entries)} pet(s){' matching ' + repr(query) if query else ''}:")
  33. for entry in shown:
  34. mark = "✓" if entry.slug in installed else " "
  35. print(f" {mark} {entry.slug:<28} {entry.display_name} ({entry.kind})")
  36. if limit and len(entries) > limit:
  37. print(f" … {len(entries) - limit} more (use --limit 0 or --query to filter)")
  38. print("\nInstall one with: hermes pets install <slug>")
  39. return 0
  40. def _cmd_install(args) -> int:
  41. from agent.pet import store
  42. from agent.pet.manifest import ManifestError
  43. slug = args.slug.strip()
  44. try:
  45. pet = store.install_pet(slug, force=args.force)
  46. except (store.PetStoreError, ManifestError) as exc:
  47. _err(f"✗ install failed: {exc}")
  48. return 1
  49. print(f"✓ installed {pet.display_name} → {pet.directory}")
  50. if args.select or not _has_active_pet():
  51. _set_active(slug)
  52. print(f"✓ {pet.display_name} is now the active pet (display.pet.slug={slug}, enabled)")
  53. else:
  54. print(f" Make it active with: hermes pets select {slug}")
  55. return 0
  56. def _cmd_remove(args) -> int:
  57. from agent.pet import store
  58. slug = args.slug.strip()
  59. if store.remove_pet(slug):
  60. print(f"✓ removed {slug}")
  61. return 0
  62. _err(f"✗ '{slug}' is not installed")
  63. return 1
  64. def _cmd_select(args) -> int:
  65. from agent.pet import store
  66. slug = (args.slug or "").strip()
  67. if not slug:
  68. pets = store.installed_pets()
  69. if not pets:
  70. _err("✗ no pets installed — run: hermes pets install boba")
  71. return 1
  72. slug = _interactive_pick(pets)
  73. if not slug:
  74. return 1
  75. pet = store.load_pet(slug)
  76. if pet is None or not pet.exists:
  77. _err(f"✗ '{slug}' is not installed — run: hermes pets install {slug}")
  78. return 1
  79. _set_active(slug)
  80. print(f"✓ active pet set to {pet.display_name} (display.pet.slug={slug}, enabled)")
  81. return 0
  82. def _cmd_off(args) -> int:
  83. _set_enabled(False)
  84. print("✓ pet disabled (display.pet.enabled=false)")
  85. return 0
  86. def _cmd_scale(args) -> int:
  87. """Persist ``display.pet.scale`` — one knob resizes every surface."""
  88. scale, err = set_pet_scale(args.factor)
  89. if err:
  90. _err(f"✗ {err}")
  91. return 1
  92. print(f"✓ pet scale set to {scale:g} (display.pet.scale)")
  93. return 0
  94. def _cmd_show(args) -> int:
  95. """Animate the active (or named) pet in the terminal via the shared PetRenderer
  96. (kitty/iTerm2/sixel when supported, else truecolor half-block fallback). Ctrl+C stops."""
  97. import shutil
  98. import time
  99. from agent.pet import store
  100. from agent.pet.constants import DEFAULT_SCALE, LOOP_MS, STATE_ROWS, PetState, resolve_cols
  101. from agent.pet.render import build_renderer
  102. cfg = _pet_config()
  103. slug = (args.slug or "").strip() or str(cfg.get("slug", "") or "")
  104. pet = store.resolve_active_pet(slug)
  105. if pet is None:
  106. _err("✗ no pet to show — run: hermes pets install boba")
  107. return 1
  108. mode_cfg = args.mode or str(cfg.get("render_mode", "auto") or "auto")
  109. scale = float(args.scale or cfg.get("scale", DEFAULT_SCALE) or DEFAULT_SCALE)
  110. cols = resolve_cols(scale, cfg.get("unicode_cols", 0))
  111. renderer = build_renderer(pet.spritesheet, configured_mode=mode_cfg, scale=scale, unicode_cols=cols)
  112. if not renderer.available:
  113. _err(f"✗ cannot render here (no TTY / graphics disabled). Effective mode: {renderer.mode}.")
  114. return 1
  115. # Which states to play: one named state, or cycle the driveable rows.
  116. requested = (args.state or "").strip().lower()
  117. if requested:
  118. states = [requested]
  119. elif args.cycle:
  120. states = [s for s in STATE_ROWS if s in {e.value for e in PetState}]
  121. else:
  122. states = [PetState.IDLE.value]
  123. is_unicode = renderer.mode == "unicode"
  124. frame_delay = max(0.05, (LOOP_MS / 1000.0) / max(1, renderer.frame_count(states[0]) or 1))
  125. # Right-align against the terminal's right edge — half-blocks by indenting each row, graphics
  126. # protocols by padding the cursor (kitty/iTerm/sixel all render at the cursor).
  127. term_cols = shutil.get_terminal_size((80, 24)).columns
  128. sprite_cols = cols if is_unicode else max(1, int(renderer.frame_w * renderer.scale) // 8)
  129. indent = " " * max(0, term_cols - sprite_cols - 1)
  130. out = sys.stdout
  131. out.write("\x1b[?25l") # hide cursor
  132. out.flush()
  133. prev_lines = 0
  134. try:
  135. print(f"{pet.display_name} — mode={renderer.mode} (Ctrl+C to stop)")
  136. loops = 0
  137. while True:
  138. for state in states:
  139. for i in range(renderer.frame_count(state) or 1):
  140. encoded = renderer.frame(state, i)
  141. if is_unicode:
  142. if indent:
  143. encoded = "\n".join(indent + ln for ln in encoded.split("\n"))
  144. if prev_lines:
  145. out.write(f"\x1b[{prev_lines}F") # cursor up to redraw in place
  146. out.write(encoded)
  147. out.write("\x1b[0m\n")
  148. # Lines drawn = sprite rows + trailing newline; the next frame overwrites.
  149. prev_lines = encoded.count("\n") + 1
  150. else:
  151. out.write("\x1b[2J\x1b[3J\x1b[H") # clear for image protocols
  152. out.write(f"{pet.display_name} [{state}]\n")
  153. out.write(indent + encoded + "\n")
  154. out.flush()
  155. time.sleep(frame_delay)
  156. loops += 1
  157. if args.once and loops >= len(states):
  158. break
  159. except KeyboardInterrupt:
  160. pass
  161. finally:
  162. out.write("\x1b[?25h") # show cursor
  163. out.write("\x1b[0m\n")
  164. out.flush()
  165. return 0
  166. def _cmd_doctor(args) -> int:
  167. """Report install state, active pet, config, and terminal capability."""
  168. from agent.pet import store
  169. from agent.pet.render import resolve_mode
  170. from agent.terminal_image import detect_terminal_graphics
  171. cfg = _pet_config()
  172. enabled = _pet_enabled(cfg)
  173. configured_slug = str(cfg.get("slug", "") or "")
  174. mode_cfg = str(cfg.get("render_mode", "auto") or "auto")
  175. pets = store.installed_pets()
  176. active = store.resolve_active_pet(configured_slug)
  177. print("petdex doctor")
  178. print(f" pets dir: {store.pets_dir()}")
  179. print(f" installed: {len(pets)} ({', '.join(p.slug for p in pets) or 'none'})")
  180. print(f" display.pet.enabled: {enabled}")
  181. print(f" display.pet.slug: {configured_slug or '(unset)'}")
  182. print(f" active (resolved): {active.slug if active else '(none)'}")
  183. print(f" display.pet.render_mode: {mode_cfg}")
  184. print(f" detected graphics: {detect_terminal_graphics()}")
  185. print(f" effective mode (TTY): {resolve_mode(mode_cfg)}")
  186. ok = True
  187. if not pets:
  188. print(" → no pets installed. Run: hermes pets install boba")
  189. ok = False
  190. elif active is None:
  191. print(" → active pet unresolved. Run: hermes pets select <slug>")
  192. ok = False
  193. elif not enabled:
  194. print(" → pet display is disabled. Run: hermes pets select " + active.slug)
  195. try:
  196. import PIL
  197. except ImportError:
  198. print(" ✗ Pillow not importable — sprite decoding will be unavailable")
  199. ok = False
  200. print(" ✓ ready" if ok and enabled else " (run the suggestions above to finish setup)")
  201. return 0
  202. # ── config helpers ────────────────────────────────────────────────────────
  203. def _pet_config() -> dict:
  204. from hermes_cli.config import load_config
  205. cfg = load_config()
  206. display = cfg.get("display", {}) if isinstance(cfg.get("display"), dict) else {}
  207. pet = display.get("pet", {})
  208. return pet if isinstance(pet, dict) else {}
  209. def _has_active_pet() -> bool:
  210. cfg = _pet_config()
  211. return _pet_enabled(cfg) and bool(cfg.get("slug"))
  212. def _pet_enabled(cfg: dict) -> bool:
  213. return is_truthy_value(cfg.get("enabled"), default=False)
  214. def _update_pet_config(when_slug: str | None = None, **values) -> bool:
  215. """Write ``display.pet.*`` keys and save config; returns whether anything was written.
  216. With ``when_slug`` the write only happens when the configured slug equals it (remove/rename
  217. must never disturb a different active pet).
  218. """
  219. from hermes_cli.config import load_config, save_config
  220. cfg = load_config()
  221. pet = cfg.setdefault("display", {}).setdefault("pet", {})
  222. if when_slug is not None and (not isinstance(pet, dict) or str(pet.get("slug", "") or "") != when_slug):
  223. return False
  224. pet.update(values)
  225. save_config(cfg)
  226. return True
  227. def _set_active(slug: str) -> None:
  228. _update_pet_config(slug=slug, enabled=True)
  229. def _set_enabled(enabled: bool) -> None:
  230. _update_pet_config(enabled=enabled)
  231. def set_pet_scale(value: float | str) -> tuple[float, str | None]:
  232. """Set ``display.pet.scale`` (clamped). Returns ``(applied, error)``; *error* is set (and
  233. nothing written) only when *value* isn't a number. Single write path behind ``/pet scale``
  234. and the desktop slider."""
  235. from agent.pet.constants import clamp_scale
  236. try:
  237. scale = clamp_scale(float(value))
  238. except (TypeError, ValueError):
  239. return 0.0, f"not a number: {value!r} — try a value like 0.5"
  240. _update_pet_config(scale=scale)
  241. return scale, None
  242. def toggle_pet_display() -> tuple[bool, str | None, str | None]:
  243. """Toggle ``display.pet.enabled``."""
  244. from agent.pet import store
  245. cfg = _pet_config()
  246. pet = store.resolve_active_pet(str(cfg.get("slug", "") or ""))
  247. if _pet_enabled(cfg):
  248. _set_enabled(False)
  249. return False, pet.display_name if pet else None, None
  250. if pet is None:
  251. installed = store.installed_pets()
  252. if not installed:
  253. return False, None, "no pets installed — /pet list to browse, or /pet <slug> to adopt"
  254. pet = installed[0]
  255. _set_active(pet.slug)
  256. else:
  257. _set_enabled(True)
  258. return True, pet.display_name, None
  259. def print_pet_gallery(*, limit: int = 20) -> None:
  260. """Print a slice of the public petdex gallery (CLI/TUI text fallback)."""
  261. from agent.pet import store
  262. from agent.pet.manifest import ManifestError, fetch_manifest
  263. try:
  264. entries = fetch_manifest()
  265. except ManifestError as exc:
  266. print(f"(._.) Couldn't reach the petdex gallery: {exc}")
  267. return
  268. installed = {p.slug for p in store.installed_pets()}
  269. shown = entries[:limit] if limit > 0 else entries
  270. print(f"(^o^)/ petdex gallery — first {len(shown)} of {len(entries)}:")
  271. for entry in shown:
  272. mark = "●" if entry.slug in installed else "○"
  273. print(f" {mark} {entry.slug:<24} {entry.display_name}")
  274. print(" /pet <slug> to adopt · /pet to toggle")
  275. def _clear_active_if(slug: str) -> bool:
  276. """Disable + unset the active pet iff it's ``slug`` (e.g. after removal)."""
  277. return _update_pet_config(when_slug=slug, slug="", enabled=False)
  278. def _rename_active_if(old_slug: str, new_slug: str) -> bool:
  279. """Repoint the active pet from ``old_slug`` to ``new_slug`` iff it's active (a rename moves
  280. the dir; config must follow). Preserves ``enabled``."""
  281. if not new_slug or old_slug == new_slug:
  282. return False
  283. return _update_pet_config(when_slug=old_slug, slug=new_slug)
  284. def _interactive_pick(pets) -> str:
  285. """Minimal numbered picker (avoids curses dep for a tiny list)."""
  286. print("Installed pets:")
  287. for i, pet in enumerate(pets, 1):
  288. print(f" {i}. {pet.slug:<24} {pet.display_name}")
  289. try:
  290. idx = int(input("Select a pet [1]: ").strip() or "1") - 1
  291. except (EOFError, KeyboardInterrupt, ValueError):
  292. _err("✗ cancelled")
  293. return ""
  294. if 0 <= idx < len(pets):
  295. return pets[idx].slug
  296. _err("✗ invalid selection")
  297. return ""
  298. # ── argparse wiring ───────────────────────────────────────────────────────
  299. # (name, help, handler, [((flags...), add_argument kwargs), ...]) — registration order is menu order.
  300. _SUBCOMMANDS = (
  301. ("list", "Browse the petdex gallery", _cmd_list, (
  302. (("query",), dict(nargs="?", default="", help="Filter by slug/name substring")),
  303. (("--installed",), dict(action="store_true", help="Only show installed pets")),
  304. (("--limit",), dict(type=int, default=40, help="Max rows (0 = all)")),
  305. )),
  306. ("install", "Install a pet from the gallery", _cmd_install, (
  307. (("slug",), dict(help="Pet slug (e.g. boba)")),
  308. (("--force",), dict(action="store_true", help="Re-download even if present")),
  309. (("--select",), dict(action="store_true", help="Make it the active pet")),
  310. )),
  311. ("select", "Set the active pet (writes display.pet.*)", _cmd_select, (
  312. (("slug",), dict(nargs="?", default="", help="Pet slug (omit for picker)")),
  313. )),
  314. ("show", "Animate the active pet in the terminal", _cmd_show, (
  315. (("slug",), dict(nargs="?", default="", help="Pet slug (default: active)")),
  316. (("--state",), dict(default="", help="Single state: idle/run/review/failed/wave/jump")),
  317. (("--cycle",), dict(action="store_true", help="Cycle through all states")),
  318. (("--once",), dict(action="store_true", help="Play once instead of looping")),
  319. (("--mode",), dict(default=None, help="Override render mode (kitty/iterm/sixel/unicode/auto)")),
  320. (("--scale",), dict(type=float, default=0, help="Override scale (0 = config)")),
  321. )),
  322. ("off", "Disable the pet display", _cmd_off, ()),
  323. ("scale", "Resize the pet everywhere (display.pet.scale)", _cmd_scale, (
  324. (("factor",), dict(help="Scale factor, e.g. 0.5 (clamped 0.1–3.0)")),
  325. )),
  326. ("remove", "Delete an installed pet", _cmd_remove, (
  327. (("slug",), dict(help="Pet slug")),
  328. )),
  329. ("doctor", "Check pet setup + terminal graphics support", _cmd_doctor, ()),
  330. )
  331. def register_cli(parent: argparse.ArgumentParser) -> None:
  332. """Attach ``pets`` subcommands to *parent* (called by main.py)."""
  333. parent.set_defaults(func=lambda a: (parent.print_help(), 0)[1])
  334. subs = parent.add_subparsers(dest="pets_command")
  335. for name, help_text, func, arguments in _SUBCOMMANDS:
  336. sub = subs.add_parser(name, help=help_text)
  337. for flags, kwargs in arguments:
  338. sub.add_argument(*flags, **kwargs)
  339. sub.set_defaults(func=func)