source_completion.py 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. """The tail every source install and update shares.
  2. A fresh install (``scripts/install.sh`` / ``scripts/install.ps1``) and a finished
  3. update must land in the same state: launchers published, product builds current,
  4. and the post-build maintenance (skills sync, config migration) applied. One
  5. implementation, two callers -- an install and an update cannot drift apart.
  6. ``main()`` is the installer entry. It is handed the bootstrap interpreter the
  7. installer happens to have (uv, PM and no application dependencies), so it
  8. re-executes itself in PM's selected interpreter before touching any product.
  9. """
  10. from __future__ import annotations
  11. import argparse
  12. import subprocess
  13. import sys
  14. from pathlib import Path
  15. # The installers run this file directly under an isolated interpreter, which
  16. # leaves the checkout off sys.path. Same idiom as hermes_cli/_launchers.py.
  17. if __name__ == "__main__":
  18. sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
  19. #: Second-phase marker: the re-executed interpreter, not the bootstrap one.
  20. _PREPARED = "--prepared"
  21. def complete_source_checkout(
  22. root: Path,
  23. *,
  24. desktop: bool,
  25. assume_yes: bool,
  26. gateway_mode: bool = False,
  27. pre_update_snapshot_id: str | None = None,
  28. pre_update_version: str | None = None,
  29. completion_message: str | None = None,
  30. announce: str | None = None,
  31. followups: list[tuple[str, str]] | None = None,
  32. before_build=None,
  33. ) -> bool:
  34. """Publish commands, build the products, then run post-build maintenance.
  35. ``before_build`` (an update's paused-gateway restart) runs once the launchers are published:
  36. dependencies are already synced, the long product builds have not started.
  37. Every step runs even when an earlier one failed; each failure is printed as ``⚠``,
  38. recorded on the open update receipt and appended to ``followups`` as ``(step, reason)``.
  39. Returns True only when every step finished and the SQLite runtime is not unsafe.
  40. """
  41. from hermes_cli.update_lock import UpdateLock, describe_holder
  42. root = Path(root)
  43. # This tail is the last mutating step of an install or update, and its product
  44. # builds run for minutes. A gateway restarted while it runs (launchd KeepAlive,
  45. # a service manager, a second `hermes` launch) reaches the same tail through
  46. # venv_sync, and `hermes update` runs its own: two completions then build the
  47. # same output directories concurrently and race on install-stamp.json (#123376).
  48. # Claim the shared update lock so stacked completions serialize. A tail whose
  49. # orchestrator already holds the lock (venv_sync's interrupted-update finish,
  50. # the updater's completion child) runs under its parent's claim, exactly as
  51. # `hermes update` does under the desktop handoff pid. The CHECKOUT lock is acquired, not
  52. # sampled (R2): a completion from another home must not build a checkout an update owns;
  53. # one inside the update's tree joins the lock it inherited.
  54. lock = UpdateLock(install_root=root)
  55. if not lock.acquire():
  56. raise RuntimeError(
  57. f"an update is still running ({describe_holder(lock.holder)}); "
  58. "wait for it to exit, then relaunch Hermes"
  59. )
  60. try:
  61. return _complete_locked(
  62. root, desktop=desktop, assume_yes=assume_yes, gateway_mode=gateway_mode,
  63. pre_update_snapshot_id=pre_update_snapshot_id,
  64. pre_update_version=pre_update_version,
  65. completion_message=completion_message, announce=announce, followups=followups,
  66. before_build=before_build,
  67. )
  68. finally:
  69. lock.release()
  70. def _complete_locked(
  71. root: Path,
  72. *,
  73. desktop: bool,
  74. assume_yes: bool,
  75. gateway_mode: bool,
  76. pre_update_snapshot_id: str | None,
  77. pre_update_version: str | None,
  78. completion_message: str | None,
  79. announce: str | None,
  80. followups: list[tuple[str, str]] | None = None,
  81. before_build=None,
  82. ) -> bool:
  83. """The completion body; callers hold the update lock already."""
  84. from hermes_cli.source_build import build_update_products
  85. from hermes_cli.update_cmd_maint import _run_post_update_maintenance
  86. from hermes_cli.venv_sync import publish_launchers
  87. try:
  88. from hermes_cli._subprocess_compat import expose_pm_git
  89. # The builds, the release-history refresh and the install stamp all run
  90. # git; a fresh Windows machine has only PM's.
  91. expose_pm_git(root)
  92. except Exception as exc:
  93. print(f"⚠ Could not provide git for the source completion: {exc}", file=sys.stderr)
  94. owed: list[tuple[str, str]] = []
  95. def step(name: str, run) -> None:
  96. # Each step is independent: a failed launcher publish or web build must not skip the
  97. # config migration, the maintenance, or (in an update) the gateway restart after it.
  98. try:
  99. run()
  100. except (Exception, SystemExit) as exc: # health: allow BLE001 -- reported as an owed follow-up
  101. from hermes_cli.update_receipt import record_followup
  102. reason = str(exc) or type(exc).__name__
  103. record_followup(name, reason)
  104. owed.append((name, reason))
  105. step("launchers", lambda: publish_launchers(root))
  106. if before_build is not None:
  107. before_build() # never raises: a failed restart stays owed and is retried after the build
  108. step("build", lambda: build_update_products(root, desktop=desktop))
  109. if announce:
  110. print(announce)
  111. verdict: list[bool] = []
  112. step("maintenance", lambda: verdict.append(_run_post_update_maintenance(
  113. assume_yes=assume_yes,
  114. gateway_mode=gateway_mode,
  115. pre_update_snapshot_id=pre_update_snapshot_id,
  116. had_desktop_app_before_update=desktop,
  117. pre_update_version=pre_update_version,
  118. completion_message=completion_message,
  119. followups=owed,
  120. )))
  121. tail_done = not owed
  122. if tail_done:
  123. from hermes_cli.source_stamp import write_source_stamp
  124. try:
  125. write_source_stamp(root)
  126. except (OSError, ValueError) as exc:
  127. print(f"⚠ Source update completed, but the install stamp could not be written: {exc}",
  128. file=sys.stderr)
  129. if followups is not None:
  130. followups.extend(owed)
  131. # The SQLite verdict is not tail work (re-running the tail cannot fix the interpreter); it
  132. # is reported by the maintenance step itself and only withholds an install's success.
  133. return tail_done and all(verdict)
  134. def _bootstrap_command(root: Path, argv: list[str]) -> list[str]:
  135. """Re-enter the checkout on PM's selected interpreter with its environment."""
  136. from pm.environments import project_python
  137. return [str(project_python(root)), "-I", "-B", "-u",
  138. str(Path(__file__).resolve()), "--source", str(root), *argv, _PREPARED]
  139. def main(argv: list[str] | None = None) -> int:
  140. argv = list(sys.argv[1:] if argv is None else argv)
  141. prepared = _PREPARED in argv
  142. parser = argparse.ArgumentParser(description=__doc__)
  143. parser.add_argument("--source", type=Path, required=True)
  144. parser.add_argument("--desktop", action="store_true",
  145. help="Also build the packaged desktop app.")
  146. parser.add_argument("--interactive", action="store_true",
  147. help="Allow prompts; installers pass no flag and stay unattended.")
  148. parser.add_argument("--finish-update", action="store_true",
  149. help="Complete a source UPDATE tail instead of an install: the "
  150. "same launchers/products/maintenance with update wording.")
  151. args = parser.parse_args([argument for argument in argv if argument != _PREPARED])
  152. root = args.source.resolve()
  153. if not (root / "hermes_cli/source_completion.py").is_file():
  154. print(f"✗ {root} is not a Hermes source checkout", file=sys.stderr)
  155. return 1
  156. if prepared:
  157. # Dependencies are selected before any application import: this is the
  158. # same ordering the update completion guarantees.
  159. from pm.environments import activate_dependencies
  160. activate_dependencies(root)
  161. if args.finish_update:
  162. # A source update that never reached its own completion -- a
  163. # pre-handoff release cannot flip during `hermes update`, so its
  164. # update ends with the tree at HEAD and nothing built -- lands here
  165. # on the next ordinary startup. Same tail as an install, so the two
  166. # states cannot drift apart. Only owed TAIL work keeps it pending: an
  167. # unsafe SQLite runtime is reported, but re-running the tail cannot fix it.
  168. owed: list[tuple[str, str]] = []
  169. complete_source_checkout(
  170. root, desktop=args.desktop, assume_yes=True,
  171. completion_message=None, announce="\n✓ Code updated!", followups=owed,
  172. )
  173. ok = not owed
  174. else:
  175. ok = complete_source_checkout(
  176. root, desktop=args.desktop, assume_yes=not args.interactive,
  177. completion_message="✓ Install complete!",
  178. )
  179. return 0 if ok else 1
  180. from pm.environments import activation_environment
  181. # This interpreter is a bootstrap one: the work happens in the re-exec, so
  182. # every flag that decides WHICH tail runs has to survive into it. Losing
  183. # --finish-update here silently reports an update as an install.
  184. passthrough = (["--desktop"] if args.desktop else []) + \
  185. (["--finish-update"] if args.finish_update else [])
  186. command = _bootstrap_command(root, passthrough)
  187. from hermes_cli.update_lock import checkout_lock_fds
  188. # Called inside an update tree (venv_sync's interrupted-update finish), the prepared child
  189. # keeps the checkout lock this bootstrap inherited.
  190. fds = checkout_lock_fds(root)
  191. return subprocess.call(command, cwd=root, env=activation_environment(root),
  192. **({"pass_fds": fds} if fds else {}))
  193. if __name__ == "__main__":
  194. raise SystemExit(main())