| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180 |
- """Where the running BUNDLED desktop app lives, and how to start it.
- A bundled artifact runs its agent out of ``<app>/resources/agent-payload``,
- so a Python process inside that payload sits at a known offset from the app
- the user double-clicks. This module turns that offset into the launcher path
- and starts it — the two things every in-bundle caller needs and each one
- used to work out for itself.
- The shape authority is the build stamp (``payload: bundled``, read through
- :func:`hermes_cli.steward.is_bundled_payload`), never a filesystem probe: a
- probe answers "is this artifact intact?", not "which shape am I?". Callers
- gate on the stamp, then ask here WHERE the app is. A stamp that says bundled
- over a tree that is not one is damage, and :func:`resolve_bundle_layout`
- says so instead of degrading to a checkout.
- Two consumers today: ``hermes desktop`` (start the app this CLI ships
- inside) and the sealed self-updater (stop the app, then relaunch it).
- """
- from __future__ import annotations
- import os
- import subprocess
- import sys
- from dataclasses import dataclass
- from pathlib import Path
- __all__ = [
- "PAYLOAD_DIR_NAME",
- "BundleLayout",
- "NotBundledApp",
- "launch_detached",
- "resolve_bundle_layout",
- ]
- #: The resources-resident payload directory every bundled artifact ships.
- PAYLOAD_DIR_NAME = "agent-payload"
- #: Executables that sit beside a Linux Electron launcher without being one.
- #: AppRun is the AppImage entry stub, which re-execs the launcher below.
- _LINUX_NON_LAUNCHERS = frozenset({"AppRun", "chrome-sandbox", "chrome_crashpad_handler"})
- class NotBundledApp(Exception):
- """Raised when a tree is not a bundled desktop payload."""
- @dataclass(frozen=True)
- class BundleLayout:
- """The three directories and the launcher of a bundled desktop app.
- ``launcher`` is None when the app directory holds no single obvious
- executable. That is a real state on a damaged or unusual install, and
- both callers would rather report it than act on a guess.
- """
- app_root: Path
- resources: Path
- payload: Path
- launcher: Path | None
- def resolve_bundle_layout(
- project_root: Path | str, *, platform: str | None = None
- ) -> BundleLayout:
- """Locate the desktop app that contains the payload at *project_root*.
- *project_root* is the payload's ``repo/`` tree — the install root a
- bundled backend runs from. The app sits two directories above the
- payload on Windows and Linux, and four above it on macOS, where the
- payload lands in ``Hermes.app/Contents/Resources``.
- The macOS offset is detected from the directory names themselves
- rather than from *platform*, so a layout can be resolved for any host
- from any host. *platform* (default :data:`sys.platform`) only decides
- the launcher-naming rule.
- Raises :class:`NotBundledApp` when the tree is not a bundled payload —
- a source checkout, or the docker/nix sealed shape, which has no app.
- """
- repo = Path(project_root).resolve()
- payload = repo.parent
- if payload.name != PAYLOAD_DIR_NAME:
- raise NotBundledApp(
- f"{repo} is not inside a {PAYLOAD_DIR_NAME}/ payload — no desktop app contains it"
- )
- resources = payload.parent
- app_root = resources.parent
- # macOS: .../Hermes.app/Contents/Resources/agent-payload/repo
- if (
- resources.name == "Resources"
- and app_root.name == "Contents"
- and app_root.parent.suffix == ".app"
- ):
- app_root = app_root.parent
- if not app_root.is_dir():
- raise NotBundledApp(f"no app directory above the payload at {payload}")
- return BundleLayout(
- app_root=app_root,
- resources=resources,
- payload=payload,
- launcher=_resolve_launcher(app_root, platform or sys.platform),
- )
- def _resolve_launcher(app_root: Path, platform: str) -> Path | None:
- """The executable that starts the app, or None when it is ambiguous.
- One rule per platform, each one "the single launcher among files that
- are not launchers":
- * macOS — the one file in ``Contents/MacOS``.
- * Windows — the one top-level ``.exe`` that is not the uninstaller.
- * Linux — the one top-level executable that is not an Electron helper
- or a shared library.
- """
- if platform == "darwin":
- return _only(_files(app_root / "Contents" / "MacOS"))
- if platform == "win32":
- return _only(
- [
- p
- for p in _files(app_root)
- if p.suffix.lower() == ".exe"
- and not p.name.lower().startswith("uninstall")
- ]
- )
- return _only(
- [
- p
- for p in _files(app_root)
- if p.name not in _LINUX_NON_LAUNCHERS
- and ".so" not in p.name
- and os.access(p, os.X_OK)
- ]
- )
- def _files(directory: Path) -> list[Path]:
- """Regular files directly in *directory*; empty when it is unreadable."""
- try:
- return sorted(p for p in directory.iterdir() if p.is_file())
- except OSError:
- return []
- def _only(candidates: list[Path]) -> Path | None:
- return candidates[0] if len(candidates) == 1 else None
- def launch_detached(
- argv: list[str], *, env: dict[str, str] | None = None, cwd: Path | str | None = None
- ) -> int:
- """Start *argv* as its own process and return its pid.
- The child outlives this process: it leads a new session on POSIX, and
- on Windows it gets the detach creation flags (new process group, own
- hidden console, breakaway from any job object). Its stdio goes to the
- null device, because the terminal that ran ``hermes desktop`` is free
- to close the moment this call returns.
- """
- from hermes_cli._subprocess_compat import windows_detach_popen_kwargs
- child = subprocess.Popen(
- argv,
- cwd=str(cwd) if cwd is not None else None,
- env=env,
- stdin=subprocess.DEVNULL,
- stdout=subprocess.DEVNULL,
- stderr=subprocess.DEVNULL,
- close_fds=True,
- # detached-spawn: ok — the desktop app launch, meant to outlive the CLI that opens it
- **windows_detach_popen_kwargs(),
- )
- return child.pid
|