checkpoints.py 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. """`hermes checkpoints` CLI subcommand.
  2. None of these require the agent to be running. Safe to call any time.
  3. """
  4. from __future__ import annotations
  5. import argparse
  6. import time
  7. from pathlib import Path
  8. from typing import Any, Optional
  9. from hermes_cli.sizefmt import format_bytes as _fmt_bytes
  10. def _fmt_age(ts: Any) -> str:
  11. try:
  12. age = time.time() - float(ts)
  13. except (TypeError, ValueError):
  14. return "—"
  15. if age < 0:
  16. return "now"
  17. for bound, div, unit in ((60, 1, "s"), (3600, 60, "m"), (86400, 3600, "h")):
  18. if age < bound:
  19. return f"{int(age / div)}{unit} ago"
  20. return f"{int(age / 86400)}d ago"
  21. def cmd_status(args: argparse.Namespace) -> int:
  22. from tools.checkpoint_maintenance import store_status
  23. info = store_status()
  24. base = info["base"]
  25. print(f"Checkpoint base: {base}")
  26. print(f"Total size: {_fmt_bytes(info['total_size_bytes'])}")
  27. print(f" store/ {_fmt_bytes(info['store_size_bytes'])}")
  28. print(f" legacy-* {_fmt_bytes(info['legacy_size_bytes'])}")
  29. print(f"Projects: {info['project_count']}")
  30. projects = sorted(info["projects"], key=lambda p: (p.get("last_touch") or 0), reverse=True)
  31. if projects:
  32. print()
  33. print(f" {'WORKDIR':<60} {'COMMITS':>7} {'LAST TOUCH':>12} STATE")
  34. for p in projects[: getattr(args, "limit", None) or 20]:
  35. wd = p.get("workdir") or "(unknown)"
  36. if len(wd) > 60:
  37. wd = "…" + wd[-59:]
  38. state = "live" if p.get("exists") else "orphan"
  39. print(f" {wd:<60} {p.get('commits', 0):>7} {_fmt_age(p.get('last_touch')):>12} {state}")
  40. legacy = info.get("legacy_archives", [])
  41. if legacy:
  42. print()
  43. print(f"Legacy archives ({len(legacy)}):")
  44. _print_archives(sorted(legacy, key=lambda a: a.get("mtime", 0), reverse=True))
  45. print()
  46. print("Clear with: hermes checkpoints clear-legacy")
  47. return 0
  48. def _print_archives(archives) -> None:
  49. for arch in archives:
  50. print(f" {arch['name']:<40} {_fmt_bytes(arch['size_bytes']):>10}")
  51. def cmd_prune(args: argparse.Namespace) -> int:
  52. from tools.checkpoint_maintenance import prune_checkpoints, store_status
  53. delete_orphans = not args.keep_orphans
  54. # Restricts orphan deletion to exactly the identities shown in the confirmation preview
  55. # (v2 project hashes / pre-v2 shadow repo paths). `None` = no restriction (--force: no
  56. # preview to bind to).
  57. orphan_allowlist: Optional[set] = None
  58. if delete_orphans and not args.force:
  59. info = store_status()
  60. orphans = [p for p in info.get("projects", []) if not p.get("exists")]
  61. pre_v2_orphans = [p for p in info.get("pre_v2_projects", []) if not p.get("exists")]
  62. if orphans or pre_v2_orphans:
  63. print(f"This will permanently delete {len(orphans) + len(pre_v2_orphans)} "
  64. "orphan checkpoint project(s) whose workdir is not currently reachable:")
  65. print()
  66. for p in orphans:
  67. print(f" {p.get('workdir') or '(unknown)'} ({p.get('commits', 0)} commit(s))")
  68. for p in pre_v2_orphans:
  69. print(f" {p.get('workdir') or '(unknown)'} (pre-v2 shadow repo)")
  70. print()
  71. print("A workdir can be unreachable because the project was deleted,")
  72. print("or because an external volume / network share / VPN is down.")
  73. print("Pass --keep-orphans to prune stale entries only.")
  74. if not _confirm("Delete these orphan projects?"):
  75. print("Aborted.")
  76. return 1
  77. # Bind deletion to exactly what was displayed/confirmed: a project that goes orphan
  78. # only *after* the preview (workdir vanishes while waiting on input()) must not be
  79. # swept up. Set unconditionally for every non-force run — an EMPTY preview binds an
  80. # EMPTY allowlist, so it can never authorize orphans found by the later rescan.
  81. orphan_allowlist = {p["hash"] for p in orphans}
  82. orphan_allowlist.update(p["path"] for p in pre_v2_orphans)
  83. print("Pruning checkpoint store…")
  84. print(f" retention_days: {args.retention_days}")
  85. print(f" delete_orphans: {delete_orphans}")
  86. print(f" max_total_size_mb: {args.max_size_mb}")
  87. print()
  88. result = prune_checkpoints(
  89. retention_days=args.retention_days,
  90. delete_orphans=delete_orphans,
  91. max_total_size_mb=args.max_size_mb,
  92. orphan_allowlist=orphan_allowlist)
  93. print(f"Scanned: {result['scanned']}")
  94. print(f"Deleted orphan: {result['deleted_orphan']}")
  95. print(f"Deleted stale: {result['deleted_stale']}")
  96. print(f"Errors: {result['errors']}")
  97. print(f"Bytes reclaimed: {_fmt_bytes(result['bytes_freed'])}")
  98. return 0
  99. def _confirm(prompt: str) -> bool:
  100. try:
  101. return input(f"{prompt} [y/N]: ").strip().lower() in {"y", "yes"}
  102. except (EOFError, KeyboardInterrupt):
  103. print()
  104. return False
  105. def _confirmed(args: argparse.Namespace, prompt: str) -> bool:
  106. """``--force`` or an interactive yes; prints ``Aborted.`` otherwise."""
  107. if args.force or _confirm(prompt):
  108. return True
  109. print("Aborted.")
  110. return False
  111. def cmd_clear(args: argparse.Namespace) -> int:
  112. from tools.checkpoint_manager import CHECKPOINT_BASE
  113. from tools.checkpoint_maintenance import clear_all, store_status
  114. info = store_status()
  115. if info["total_size_bytes"] == 0 and not Path(CHECKPOINT_BASE).exists():
  116. print("Nothing to clear — checkpoint base does not exist.")
  117. return 0
  118. print(f"This will delete the ENTIRE checkpoint base at {info['base']}")
  119. print(f" size: {_fmt_bytes(info['total_size_bytes'])}")
  120. print(f" projects: {info['project_count']}")
  121. print(f" legacy dirs: {len(info.get('legacy_archives', []))}")
  122. print()
  123. print("All /rollback history for every working directory will be lost.")
  124. if not _confirmed(args, "Proceed?"):
  125. return 1
  126. result = clear_all()
  127. if result["deleted"]:
  128. print(f"Cleared. Reclaimed {_fmt_bytes(result['bytes_freed'])}.")
  129. return 0
  130. print("Could not clear checkpoint base (see logs).")
  131. return 2
  132. def cmd_clear_legacy(args: argparse.Namespace) -> int:
  133. from tools.checkpoint_maintenance import clear_legacy, store_status
  134. info = store_status()
  135. legacy = info.get("legacy_archives", [])
  136. if not legacy:
  137. print("No legacy archives to clear.")
  138. return 0
  139. total = sum(a.get("size_bytes", 0) for a in legacy)
  140. print(f"Found {len(legacy)} legacy archive(s), total {_fmt_bytes(total)}:")
  141. _print_archives(legacy)
  142. print()
  143. print("Legacy archives hold pre-v2 per-project shadow repos, moved aside")
  144. print("during the single-store migration. Delete when you're confident")
  145. print("you don't need the old /rollback history.")
  146. if not _confirmed(args, "Delete all legacy archives?"):
  147. return 1
  148. result = clear_legacy()
  149. print(f"Deleted {result['deleted']} archive(s), reclaimed {_fmt_bytes(result['bytes_freed'])}.")
  150. if result["errors"]:
  151. print(f"Could not delete {result['errors']} archive(s) (see logs).")
  152. return 2
  153. return 0
  154. def register_cli(parser: argparse.ArgumentParser) -> None:
  155. """Wire subcommands onto the ``hermes checkpoints`` parser."""
  156. parser.set_defaults(func=cmd_status) # bare `hermes checkpoints` → status
  157. subs = parser.add_subparsers(dest="checkpoints_command", metavar="COMMAND")
  158. p_status = subs.add_parser("status", help="Show total size, project count, and per-project breakdown")
  159. p_status.add_argument("--limit", type=int, default=20, help="Max projects to list (default 20)")
  160. p_status.set_defaults(func=cmd_status)
  161. p_list = subs.add_parser("list", help="Alias for 'status'")
  162. p_list.add_argument("--limit", type=int, default=20)
  163. p_list.set_defaults(func=cmd_status)
  164. p_prune = subs.add_parser("prune", help="Delete orphan/stale checkpoints and GC the store")
  165. p_prune.add_argument("--retention-days", type=int, default=7,
  166. help="Drop projects whose last_touch is older than N days (default 7)")
  167. p_prune.add_argument("--max-size-mb", type=int, default=500,
  168. help="After orphan/stale prune, drop oldest commits "
  169. "per project until total size <= this (default 500)")
  170. p_prune.add_argument("--keep-orphans", action="store_true",
  171. help="Skip deleting projects whose workdir no longer exists")
  172. p_prune.add_argument("-f", "--force", action="store_true",
  173. help="Skip the orphan-deletion confirmation prompt")
  174. p_prune.set_defaults(func=cmd_prune)
  175. for name, help_text, func in (
  176. ("clear", "Delete the entire checkpoint base (all /rollback history)", cmd_clear),
  177. ("clear-legacy", "Delete only the legacy-<ts>/ archives from v1 migration", cmd_clear_legacy),
  178. ):
  179. p_clear = subs.add_parser(name, help=help_text)
  180. p_clear.add_argument("-f", "--force", action="store_true", help="Skip confirmation prompt")
  181. p_clear.set_defaults(func=func)