"""Build and launch plumbing for the browser-hosted Desktop workspace. The browser surface shares Hermes' hardened dashboard server. This module owns only the separate renderer artifact and the one-way handoff into that server; it never creates a second HTTP/WebSocket stack. The renderer is compiled by the shared product builders (``apps/desktop/scripts/build-webapp.mjs``), whose receipt inside ``dist-webapp`` decides freshness. """ from __future__ import annotations from contextlib import contextmanager import os from pathlib import Path import subprocess # Serialize renderer publication with Dashboard builds in this checkout. _LOCK_NAME = ".web_ui_build.lock" _LOCK_WAIT_SECONDS = 30 * 60 # Written into the bundle when `hermes update` could not rebuild it, so the gateways serving it report # the Webapp unavailable instead of serving it against the updated backend. Publishing a build # replaces the whole folder, and the receipt's output hash covers this file, so a marked bundle is # never reused as current. STALE_MARKER = ".hermes-stale" # A packaged bundle (the Nix package), like HERMES_WEB_DIST for the dashboard: the packager # builds it, so Hermes serves it as it is and never builds or marks it. DIST_ENV = "HERMES_WEBAPP_DIST" class WebappBuildError(RuntimeError): """The browser-hosted Desktop renderer could not be prepared.""" def packaged_webapp_dist() -> Path | None: """The bundle :data:`DIST_ENV` names, or None when Hermes builds its own.""" value = os.environ.get(DIST_ENV) return Path(value).expanduser() if value else None def webapp_dist_dir(project_root: Path) -> Path: return packaged_webapp_dist() or project_root / "apps" / "desktop" / "dist-webapp" def mark_webapp_stale(project_root: Path) -> bool: """Mark the built bundle in *project_root* out of date, after a rebuild that failed. False when no bundle is built: nothing serves one, and the build output folder stays the builder's. Also False for a packaged bundle, which is the packager's.""" dist = webapp_dist_dir(project_root) if packaged_webapp_dist() is not None or not (dist / "index.html").is_file(): return False (dist / STALE_MARKER).write_text("hermes update could not rebuild this bundle\n", encoding="utf-8") return True def webapp_bundle_stale(dist: Path) -> bool: """Whether the bundle in *dist* is marked out of date (:func:`mark_webapp_stale`).""" return (Path(dist) / STALE_MARKER).is_file() def _clear_stale_mark(dist: Path) -> None: try: (dist / STALE_MARKER).unlink(missing_ok=True) except OSError as exc: raise WebappBuildError(f"Could not mark the Webapp renderer at {dist} current: {exc}") from exc @contextmanager def _exclusive_build_lock(path: Path): """Cross-platform exclusive lock for one renderer generation.""" from pm.filesystem import lock_fd, unlock_fd try: path.parent.mkdir(parents=True, exist_ok=True) handle = path.open("a+b") except OSError as exc: raise WebappBuildError(f"Could not open Webapp build lock {path}: {exc}") from exc try: try: if not lock_fd(handle.fileno(), wait=False): print("→ Another Hermes Webapp build is running; waiting for it...") if not lock_fd(handle.fileno(), wait=True, timeout=_LOCK_WAIT_SECONDS): raise WebappBuildError(f"Timed out waiting for another Webapp build ({path})") except OSError as exc: raise WebappBuildError(f"Could not lock Webapp build {path}: {exc}") from exc yield finally: unlock_fd(handle.fileno()) handle.close() def prepare_webapp_renderer( project_root: Path, *, force: bool = False, skip_build: bool = False, explicit: bool = False, ) -> Path: """Return a verified browser renderer, serializing concurrent builds. ``explicit`` (a requested build) may install dependencies even when lazy installs are disabled, like ``hermes desktop --build-only``. """ from hermes_cli.source_build import build_source_webapp, source_build_env, source_product_current project_root = project_root.resolve() dist = webapp_dist_dir(project_root) if packaged_webapp_dist() is not None: # The packager built it into a read-only store; there is nothing here to rebuild. if not (dist / "index.html").is_file(): raise WebappBuildError(f"{DIST_ENV} is set but no Webapp renderer exists at {dist}") if force: raise WebappBuildError(f"The Webapp renderer at {dist} comes from {DIST_ENV} and cannot be rebuilt here") print(f"→ Using Hermes Webapp renderer from {DIST_ENV}: {dist}") return dist if skip_build: # Reuse takes no build lock, like `hermes dashboard --skip-build`: the # lock lives in the install root, which a read-only install cannot write. if not (dist / "index.html").is_file(): raise WebappBuildError( f"--skip-build was passed but no Webapp renderer exists at {dist}" ) print(f"→ Reusing Hermes Webapp renderer at {dist} (--skip-build)") return dist # A current, unmarked bundle needs no lock either, so a read-only install # (the Docker image) reuses the one baked at build time. if not force and not webapp_bundle_stale(dist) and source_product_current(project_root, "webapp", dist): print(f"✓ Hermes Webapp renderer is up to date: {dist}") return dist with _exclusive_build_lock(project_root / _LOCK_NAME): if not force and source_product_current(project_root, "webapp", dist): _clear_stale_mark(dist) print(f"✓ Hermes Webapp renderer is up to date: {dist}") return dist try: build_source_webapp(project_root, env=source_build_env(explicit=explicit), explicit=explicit) except (OSError, subprocess.SubprocessError, RuntimeError) as exc: raise WebappBuildError(f"Browser-hosted Desktop build failed: {exc}") from exc _clear_stale_mark(dist) print(f"✓ Hermes Webapp renderer built: {dist}") return dist