diff --git a/hermes_cli/linux_desktop_entry.py b/hermes_cli/linux_desktop_entry.py index 6cfab8697c..1b3665076e 100644 --- a/hermes_cli/linux_desktop_entry.py +++ b/hermes_cli/linux_desktop_entry.py @@ -1,16 +1,17 @@ """Install and remove the Linux desktop entry (``hermes.desktop``). -Two values must be absolute for the entry to work: - -Cache refresh is best-effort and tool-gated: ``update-desktop-database`` for the freedesktop menu -cache, ``gtk-update-icon-cache`` for the user hicolor tree, and ``kbuildsycoca6``/``kbuildsycoca5`` -for Plasma. Run each tool only when it exists. A missing tool is not an error. +The entry must be launch-context independent: ``Exec=`` is an absolute launcher that survives the +venv (no ``#!/usr/bin/env python3`` escapes, no checkout-internal argv[0]), and ``Icon=`` is the +themed name backed by a copy in the user's hicolor tree. Cache refresh is best-effort and +tool-gated (``update-desktop-database``, ``gtk-update-icon-cache``, ``kbuildsycoca6``/``5``); a +missing tool is not an error. """ from __future__ import annotations import io import os +import re import shutil import struct import subprocess @@ -20,6 +21,8 @@ from typing import Optional DESKTOP_ENTRY_NAME = "hermes.desktop" +_SHELL_NAMES = ("bash", "sh", "dash", "zsh", "ksh") + def is_supported() -> bool: """XDG desktop entries exist only on Linux and BSD.""" @@ -34,7 +37,6 @@ def _xdg_data_home() -> Path: def desktop_entry_path() -> Path: - """Where the ``hermes.desktop`` entry lives.""" return _xdg_data_home() / "applications" / DESKTOP_ENTRY_NAME @@ -44,18 +46,17 @@ def icon_path(project_root: Path) -> Path: def _running_interpreter() -> str: - """The venv-semantic interpreter path for the persisted ``Exec=`` line. ``sys.executable`` inside a - venv is commonly a SYMLINK into a shared base-interpreter tree (uv, pyenv, conda). - ``Path.resolve()`` follows it out of the venv, and CPython discovers ``pyvenv.cfg`` from the - *lexical* argv[0] — so a dereferenced path boots without the venv's site-packages and dies on - the first third-party import (#90292, one level up; identified in #80547's review and confirmed - on real Zorin/uv hardware in this PR's review). + """Venv-semantic interpreter path for the persisted ``Exec=`` line. + + ``sys.executable`` inside a venv is commonly a SYMLINK into a shared base-interpreter tree + (uv, pyenv, conda). ``resolve()`` follows it out of the venv, and CPython discovers + ``pyvenv.cfg`` from the *lexical* argv[0] — so a dereferenced path boots without the venv's + site-packages. Keep the lexical form when any ancestor holds a ``pyvenv.cfg``. """ lexical = os.path.abspath(sys.executable) path = Path(lexical) - for base in (path.parent, *path.parent.parents): - if (base / "pyvenv.cfg").is_file(): - return lexical + if any((base / "pyvenv.cfg").is_file() for base in (path.parent, *path.parent.parents)): + return lexical return str(path.resolve()) @@ -65,10 +66,10 @@ _probe_cache: "dict[str, bool]" = {} def _can_import_hermes_cli(interpreter: Path) -> bool: """Whether *interpreter* can import ``hermes_cli.main`` unaided. - Runs the import in a subprocess under ``-I`` (isolated mode: no user site, no PYTHONPATH - inheritance, no cwd on ``sys.path``) from a neutral cwd, so the answer matches what a cold - desktop environment would get — a checkout cwd or an inherited ``PYTHONPATH`` cannot produce a - false positive. + Runs under ``-I`` (no user site, no PYTHONPATH, no cwd on ``sys.path``) from a neutral cwd, so + the answer matches a cold desktop environment. Cached per process; an unprobeable interpreter + (missing binary, spawn failure, timeout) is assumed capable and deliberately NOT cached, so one + transient hiccup doesn't freeze the assumption for the session. """ key = str(interpreter) cached = _probe_cache.get(key) @@ -83,225 +84,156 @@ def _can_import_hermes_cli(interpreter: Path) -> bool: check=False, timeout=15, ) - ok = result.returncode == 0 except (OSError, subprocess.SubprocessError): - # Unprobeable (missing binary, spawn failure, timeout): do not - # punish the entry on infra hiccups — assume capable and let the - # existing fallback chain handle a genuinely broken interpreter. - # This error-derived answer is deliberately NOT cached: one - # transient hiccup must not freeze the "capable" assumption for - # the whole session; the next install attempt re-probes. return True - _probe_cache[key] = ok + _probe_cache[key] = ok = result.returncode == 0 return ok def _running_interpreter_fallback() -> str: - """The interpreter to persist when the candidate fails the import probe. - - The RUNNING interpreter by definition has ``hermes_cli`` importable (this module is executing), - so the module-form entry under it is the safe landing when every candidate path failed the - capability check. - """ + """The RUNNING interpreter: it has ``hermes_cli`` importable by definition.""" return os.path.abspath(sys.executable) def resolve_exec_command(project_root: Optional[Path] = None) -> str: """Build the absolute ``Exec=`` command line for ``hermes desktop``. - Prefer the real ``hermes`` executable (argv[0] or PATH). When Hermes runs as a module with no - launcher installed, use the current interpreter, also absolute. - - The persisted entry must be launch-context independent: whatever process writes it, the next - launch must read and rewrite the same bytes. + Prefer the real ``hermes`` launcher; fall back to `` -m hermes_cli.main desktop``. """ from hermes_cli.relaunch import resolve_hermes_bin - bin_path = _resolve_hermes_bin_for_desktop_entry( - resolve_hermes_bin, checkout_root=project_root - ) + bin_path = _resolve_hermes_bin_for_desktop_entry(resolve_hermes_bin, checkout_root=project_root) interpreter = _running_interpreter() if not _can_import_hermes_cli(Path(interpreter)): - # The candidate interpreter cannot actually import hermes_cli.main - # (checked in isolated mode from a neutral cwd — so the probe can't - # be fooled by a checkout cwd or an inherited PYTHONPATH). Persisting - # it would write a dead entry: the DE spawns the Exec line in a cold - # environment where exactly this import has to succeed. Fall back to - # the module form under the RUNNING interpreter, which by definition - # has the CLI importable. Probe design follows the isolated-mode - # capability check proposed by @nosliwhtes (#92122 review lineage, - # commit 4150501f641) — cached here per-process so a desktop launch - # pays the subprocess cost at most once. + # Persisting an interpreter that can't import the CLI writes a dead entry (the DE spawns + # Exec in a cold environment where exactly this import must succeed). interpreter = _running_interpreter_fallback() if bin_path: resolved = Path(bin_path).resolve() if _needs_interpreter(resolved): - # The resolved launcher is a Python script whose shebang points at - # a NON-venv interpreter (e.g. the repo's `hermes` script with - # `#!/usr/bin/env python3` when argv[0] came from the shell - # installer's bash wrapper). Launched from the .desktop entry that - # shebang resolves to the SYSTEM python and dies on the first - # third-party import (#90292) — silently, since Terminal=false. - # sys.executable is the interpreter actually running Hermes (the - # venv one), so prefix it explicitly. + # A Python launcher whose shebang points OUTSIDE the venv (e.g. the repo's `hermes` + # script with `#!/usr/bin/env python3`) would die silently on the first third-party + # import under Terminal=false — run it under the venv interpreter explicitly. argv = [interpreter, str(resolved), "desktop"] else: argv = [str(resolved), "desktop"] else: - argv = [ - interpreter, - "-m", - "hermes_cli.main", - "desktop", - ] + argv = [interpreter, "-m", "hermes_cli.main", "desktop"] return " ".join(_quote_exec_arg(a) for a in argv) +def _is_interpreter(candidate: Path) -> bool: + """A python interpreter binary (``bin/python*``), not a launcher. + + Strict basename match — accepts ``python``, ``python3``, ``python3.11``; rejects lookalikes + such as ``python3-config`` and ``pythonw``. The parent-dir guard keeps a script named + ``python`` outside a bin/Scripts tree from being misclassified. + """ + if not re.fullmatch(r"python[23]?(\d+)?(\.\d+)?", candidate.name.lower()): + return False + return candidate.parent.name in {"bin", "scripts"} + + +def _inside_checkout(candidate: str, checkout_root: Path, original_argv0: str) -> bool: + """Whether a launcher candidate is a launch-context artifact rather than a durable launcher.""" + try: + path = Path(candidate).resolve() + except OSError: + return False + # Anything shipped in the tree (e.g. the repo `hermes` script) is checkout-internal. Compare + # against BOTH the lexical and resolved roots: candidates resolve, so a symlinked home needs + # the resolved comparison too. + try: + resolved_root = checkout_root.resolve() + except OSError: + resolved_root = None + for root in {checkout_root, resolved_root}: + if root is not None and (path == root or root in path.parents): + return True + # The `python -m hermes_cli.main` relaunch context surfaces the invoking interpreter as + # argv[0]; an interpreter is never a launchable entry target (it would persist a bare + # ` desktop`). Compare against argv[0]'s own file, not sys.executable — under test + # harnesses they differ. + try: + return path.samefile(original_argv0) and _is_interpreter(path) + except OSError: + return False + + def _resolve_hermes_bin_for_desktop_entry( resolve_fn=None, checkout_root: Optional[Path] = None, ) -> Optional[str]: """Resolve the launcher binary for the persisted ``.desktop`` entry. - Wraps :func:`hermes_cli.relaunch.resolve_hermes_bin` with one rule: an ``argv[0]`` inside - this checkout is a launch-context artifact, not a durable installed launcher — persisting it - makes the entry depend on how the previous launch happened (a bootstrap loop). Skip - argv[0]/relative candidates then and fall through to PATH, where the shell installer's - wrapper lives. ``resolve_fn`` is injectable for tests. + Wraps :func:`hermes_cli.relaunch.resolve_hermes_bin` with one rule: an ``argv[0]`` inside this + checkout is a launch-context artifact, not a durable installed launcher — persisting it makes + the entry depend on how the previous launch happened (a bootstrap loop). Skip such candidates + and fall through to PATH, then to the installer's known wrapper locations. ``resolve_fn`` is + injectable for tests. """ if resolve_fn is None: from hermes_cli.relaunch import resolve_hermes_bin as resolve_fn if checkout_root is None: checkout_root = _project_root() - # Keep the LEXICAL form: _inside_checkout resolves candidates for its - # own comparison anyway, and _wrapper_targets_checkout needs the - # lexical root because the installer writes $INSTALL_DIR lexically - # into the shim text (symlinked homes would otherwise mismatch). - # Production callers pass main.py's realpath'd PROJECT_ROOT; the - # module-lexical root derived from __file__ is added alongside so a - # symlinked home still matches the shim's lexically-written paths. + # Keep the LEXICAL root: the installer writes $INSTALL_DIR lexically into the shim text, so a + # symlinked home would otherwise mismatch. Callers pass main.py's realpath'd PROJECT_ROOT; the + # module-lexical root is tried alongside it. checkout_root = Path(os.path.abspath(checkout_root)) module_lexical_root = _project_root() original_argv0 = sys.argv[0] - def _inside_checkout(candidate: str) -> bool: - try: - path = Path(candidate).resolve() - except OSError: - return False - # The repo `hermes` script and anything else shipped in the tree is - # checkout-internal. Compare against BOTH the lexical and resolved - # roots (checkout_root is kept lexical; candidates resolve, so a - # symlinked home needs the resolved comparison too). - resolved_root = None - try: - resolved_root = checkout_root.resolve() - except OSError: - pass - for root in {checkout_root, resolved_root}: - if root is not None and (path == root or root in path.parents): - return True - # The `python -m hermes_cli.main` relaunch context surfaces the - # invoking interpreter (or a non-executable main.py, which the - # resolver already skips) as argv[0]; an interpreter is never a - # durable, launchable entry target (it would persist a bare - # ` desktop`). Compare against the *invoking* interpreter - # (argv[0]'s own file), not sys.executable — under test harnesses - # they differ. - try: - if path.samefile(original_argv0) and _is_interpreter(path): - return True - except OSError: - pass - return False - - def _is_interpreter(candidate: Path) -> bool: - """A python interpreter binary (``bin/python*``), not a launcher. - - Strict basename match — accepts ``python``, ``python3``, ``python3.11``; rejects lookalikes - such as ``python3-config`` and ``pythonw``. The parent-dir guard keeps a script named - ``python`` outside a bin/Scripts tree from being misclassified. - """ - import re - - name = candidate.name.lower() - if not re.fullmatch(r"python[23]?(\d+)?(\.\d+)?", name): - return False - return candidate.parent.name in {"bin", "scripts"} - - # Resolve the primary FIRST and only rerun the resolver with argv[0] - # hidden when the primary could actually be checkout-internal: for an - # already-external primary the comparison can never change the - # outcome, so skipping the rerun saves a resolver call and shortens - # the window in which a concurrent reader could see the mutated - # sys.argv. + # An external primary (another install's /opt/.../bin/hermes, a venv console script) wins + # BEFORE any known-location probing, which could silently switch the entry to a different + # installation. Only rerun the resolver with argv[0] hidden when the primary could actually + # be checkout-internal (also shortens the window a concurrent reader sees mutated sys.argv). primary = resolve_fn() - - # A primary that is NOT checkout-internal and not the invoking - # interpreter is an external launcher (e.g. /opt/.../bin/hermes from - # another install method, or a venv console script). It must be - # evaluated BEFORE any known-location probing: probing first could - # silently switch the entry to a different installation (#94443 - # review case 3). - if primary and not _inside_checkout(primary): + if primary and not _inside_checkout(primary, checkout_root, original_argv0): return primary - # Only reroute when argv[0] actually drove the resolution: re-run the - # resolver with argv[0] hidden and compare. If PATH yields nothing, - # keep the resolver's original answer (its fallback chain stays - # authoritative; #90492 semantics preserved). sys.argv[0] = "" try: rerouted = resolve_fn() finally: sys.argv[0] = original_argv0 - if primary and _inside_checkout(primary) and rerouted: + if not primary: + return primary + if rerouted: return rerouted + if rerouted is not None: + return primary - if rerouted is None and primary: - # argv[0] was checkout-internal AND PATH had no `hermes` — common - # in stripped systemd user sessions and autostart relaunches. - # The installer's wrapper lives at known locations; probe them - # directly before giving up, otherwise we'd silently persist the - # checkout-internal form this fix exists to prevent. The probe - # runs only after the primary was proven non-durable above, and - # each candidate must itself target THIS checkout (a wrapper - # from another install would make the entry stable-but-wrong — - # same failure class the external-primary-first rule avoids). - probe = _known_wrapper_candidates() - for candidate in probe: - if candidate.is_file() and os.access(candidate, os.X_OK): - if not _wrapper_shebang_safe(candidate): - # The wrapper targets this checkout but its own shebang - # would die in the DE context (e.g. `#!/usr/bin/env - # python3` resolving past the venv): skip it the same - # way a foreign-install wrapper is skipped. Idea - # credited to autumn8's #92122 rung-2 safety check; - # implemented on our ownership machinery. - continue - if _wrapper_targets_checkout( - candidate, checkout_root - ) or _wrapper_targets_checkout(candidate, module_lexical_root): - return str(candidate) - # No durable wrapper for THIS checkout exists anywhere (PATH - # miss, known locations miss or belong to another install). - # Persisting the checkout-internal primary would produce an - # entry that regenerates itself or dies on the venv escape; - # dropping to None lets resolve_exec_command emit its runnable - # module fallback. - return None - return primary + # argv[0] was checkout-internal AND PATH had no `hermes` — common in stripped systemd user + # sessions and autostart relaunches. Probe the installer's known wrapper locations; each + # candidate must be DE-safe and target THIS checkout (a foreign wrapper would make the entry + # stable-but-wrong). No durable wrapper → None, so resolve_exec_command emits its runnable + # module fallback instead of the self-regenerating checkout-internal form. + for candidate in _known_wrapper_candidates(): + if ( + candidate.is_file() + and os.access(candidate, os.X_OK) + and _wrapper_shebang_safe(candidate) + and ( + _wrapper_targets_checkout(candidate, checkout_root) + or _wrapper_targets_checkout(candidate, module_lexical_root) + ) + ): + return str(candidate) + return None + + +def _shebang_tokens(shebang: str) -> "list[str]": + return shebang[2:].strip().split() def _wrapper_shebang_safe(wrapper: Path) -> bool: """Whether an executable wrapper can actually run in the DE context. - A wrapper whose shebang escapes the venv (``#!/usr/bin/env python3`` or a bare interpreter - name) would die exactly like the broken entry this module fixes. Native binaries and shell - launchers are safe by construction; a python-shebang wrapper is safe only when its - interpreter resolves to the RUNNING venv's interpreter directory. + Native binaries and shell launchers are safe by construction (the shell script execs the right + interpreter itself). A python-shebang wrapper is safe only when its interpreter stays inside + the RUNNING venv; anything unknown fails safe toward the module fallback. """ try: with open(wrapper, "rb") as fh: @@ -311,166 +243,115 @@ def _wrapper_shebang_safe(wrapper: Path) -> bool: if head[:4] == b"\x7fELF" or head.startswith(b"MZ"): return True if not head.startswith(b"#!"): - # No shebang: the kernel cannot exec it directly either — but it - # may be sourced or exec'd via `sh` by DE-specific glue. Fail - # safe toward the module fallback. return False shebang = head.decode("utf-8", errors="replace").splitlines()[0] - tokens = shebang[2:].strip().split() + tokens = _shebang_tokens(shebang) if not tokens: return False interp = Path(tokens[0]) - # `#!/usr/bin/env bash` (the installer's own launcher form): `env` - # here is the standard trick to find bash on PATH, and the script - # itself execs the right interpreter. Only python-flavored `env` - # shebangs are the escape hazard. if interp.name == "env": - # Skip env's own flags (-S, -u VAR, ...) and inspect the first - # real token: `env -S bash` is still a shell launcher. - target = next( - (Path(t) for t in tokens[1:] if not t.startswith("-")), - Path(""), - ) - if target.name in ("bash", "sh", "dash", "zsh", "ksh"): - return True - return not _shebang_escapes_running_env(shebang) - if interp.name in ("bash", "sh", "dash", "zsh", "ksh"): - # A shell launcher execs the right interpreter itself. + # `#!/usr/bin/env bash` is the installer's own launcher form; skip env's flags (-S, -u + # VAR) and inspect the first real token. Only python-flavored `env` shebangs escape. + target = next((Path(t) for t in tokens[1:] if not t.startswith("-")), Path("")) + return target.name in _SHELL_NAMES or not _shebang_escapes_running_env(shebang) + if interp.name in _SHELL_NAMES: return True if "python" not in interp.name.lower(): - # Not a python interpreter either — fail safe toward the module - # fallback rather than trusting an unknown interpreter. return False - # Python wrapper: its shebang must stay inside the RUNNING venv. return not _shebang_escapes_running_env(shebang) +_ROOT_TERMINATORS = ('"', "'", " ", "\n", "\t", "\r", "$", "\x00", "/") + + def _wrapper_targets_checkout(wrapper: Path, checkout_root: Path) -> bool: """Whether a candidate launcher script actually launches THIS checkout. - Expects the LEXICAL checkout root (the caller keeps it un-resolved): the installer writes - ``$INSTALL_DIR`` lexically into the shim, so on a symlinked home the shim text and the resolved - root would never match. Both lexical and resolved forms of the root are tried regardless, to - tolerate either caller convention. + Boundary-aware: a bare substring test would also accept sibling paths that EXTEND this + checkout's path (``-old``, ``.bak``), so the root must end at a quote / + whitespace / EOL or continue INTO the tree (``/``). Both lexical and resolved roots are + tried: the installer writes $INSTALL_DIR lexically, so with a symlinked home the shim text + carries the lexical path while the caller may pass a resolved one. """ try: head = wrapper.read_bytes()[:4096] except OSError: return False if b"\x7fELF" in head[:4] or head.startswith(b"MZ"): - # Native binary: cannot verify, and cannot be another checkout's - # bash shim either — accept. + # Native binary: cannot verify, cannot be another checkout's bash shim either — accept. return True - try: - text = head.decode("utf-8", errors="replace") - except Exception: # noqa: BLE001 - defensive decode - return False - # Boundary-aware matching: a bare substring test would also accept - # sibling paths that EXTEND this checkout's path (an old install - # renamed aside as `-old` or `.bak`), silently - # pointing the entry at that other installation. Require the - # reference to end the path (quote, whitespace, or end-of-line - # right after the root) or continue INTO it. - # Compare both the resolved root and its lexical form: the installer - # writes $INSTALL_DIR lexically, so with a symlinked home - # (/home/user -> /mnt/disk/home/user) the shim's text carries the - # lexical path while checkout_root arrives resolved. - roots = {str(checkout_root)} + text = head.decode("utf-8", errors="replace") lexical_root = os.path.abspath(str(checkout_root)) - roots.add(lexical_root) + roots = {str(checkout_root), lexical_root} try: - resolved_lexical = str(Path(lexical_root).resolve()) - roots.add(resolved_lexical) + roots.add(str(Path(lexical_root).resolve())) except OSError: pass - for root in roots: - for terminator in ('"', "'", " ", "\n", "\t", "\r", "$", "\x00"): - if root + terminator in text: - return True - if text.rstrip("\r\n").endswith(root): - return True - # The shim's exec line continues INTO the checkout (…/python - # /hermes …): a path-continuation boundary is also a match. - if root + "/" in text: - return True - return False + stripped = text.rstrip("\r\n") + return any( + stripped.endswith(root) or any(root + t in text for t in _ROOT_TERMINATORS) + for root in roots + ) def _known_wrapper_candidates(): """Durable installed-launcher locations, most likely first. - Mirrors the installer's ``get_command_link_dir()`` layouts: user (``~/.local/bin``), root FHS - (``/usr/local/bin``), and Termux (``$PREFIX/bin``). The wrapper is always named ``hermes``. + Mirrors the installer's ``get_command_link_dir()`` layouts: Termux (``$PREFIX/bin``), root FHS + (``/usr/local/bin``), and user (``~/.local/bin``). The wrapper is always named ``hermes``. """ candidates = [] - home = Path.home() prefix = os.environ.get("PREFIX") if prefix: candidates.append(Path(prefix) / "bin" / "hermes") if hasattr(os, "geteuid") and os.geteuid() == 0: candidates.append(Path("/usr/local/bin/hermes")) - candidates.append(home / ".local" / "bin" / "hermes") + candidates.append(Path.home() / ".local" / "bin" / "hermes") return candidates def _project_root() -> Path: - """This file lives at ``/hermes_cli/linux_desktop_entry.py``. - - Lexical (no .resolve()): callers feed this into shim-text matching where the installer's - lexically-written $INSTALL_DIR must be able to match; symlinked homes would break a resolved - comparison. - """ + """```` from this file's location — lexical (no ``.resolve()``) so shim-text matching + against the installer's lexically-written $INSTALL_DIR works on symlinked homes.""" return Path(os.path.abspath(__file__)).parent.parent def _needs_interpreter(bin_path: Path) -> bool: - """Whether ``bin_path`` is a Python script that must run under - ``sys.executable`` to see Hermes' venv (rather than its own shebang).""" + """Whether ``bin_path`` is a Python script whose shebang escapes the running venv. + + Native binaries (uv shim, PyInstaller, distro package) and shell wrappers (the installer's + bash launcher execs the venv python itself) never need one. + """ try: with open(bin_path, "rb") as fh: head = fh.readline(256) except OSError: return False if not head.startswith(b"#!"): - # Native binary (uv tool shim, PyInstaller, distro package) — its own - # loader is self-sufficient. return False shebang = head.decode("utf-8", errors="replace").strip() if "python" not in shebang.lower(): - # A shell wrapper (e.g. the installer's bash launcher) execs the venv - # python itself — leave it alone. return False return _shebang_escapes_running_env(shebang) def _shebang_escapes_running_env(shebang: str) -> bool: - """Whether a python shebang resolves OUTSIDE the running interpreter's env. + """Whether a python shebang resolves OUTSIDE the running interpreter's directory. - Tokenizes the shebang (interpreter path plus any flags) and compares PATH COMPONENTS, never - substrings: ``/bin-extra/python`` is not inside ``/bin`` even though it starts with - it (sibling-directory confusion; independently surfaced in nosliwhtes' #92122 hardening - ``b96427d0`` — reimplemented here with two extensions). - - * ``env`` shebangs (``#!/usr/bin/env python3``) ALWAYS escape: ``env`` resolves through PATH, - which in the DE's cold environment is not the interactive PATH that installed the venv — the - parent-equality form could be fooled when the resolved ``env`` binary happens to sit in the same - directory tree. + Compares PATH COMPONENTS, never substrings: ``/bin-extra/python`` is not inside + ``/bin``. ``env`` shebangs ALWAYS escape — ``env`` resolves through the DE's cold PATH, + not the shell that installed the venv — except the rare ``env -S `` form, + which is judged by its absolute target. """ - tokens = shebang[2:].strip().split() + tokens = _shebang_tokens(shebang) if not tokens: - # Bare "#!python" with no path: resolves via PATH — escapes. - return True + return True # bare "#!python": resolves via PATH interp = Path(tokens[0]) if interp.name in ("env", "env.exe"): - # PATH-resolved interpreter: the DE environment's PATH decides, - # not the installing shell's — treat as escaping. A real - # ``env -S`` venv-absolute form (`env -S `), rare but valid, - # still resolves the actual interpreter from the second token. rest = [t for t in tokens[1:] if not t.startswith("-")] - if rest and Path(rest[0]).is_absolute(): - interp = Path(rest[0]) - else: + if not (rest and Path(rest[0]).is_absolute()): return True + interp = Path(rest[0]) running_dir = os.path.dirname(os.path.abspath(sys.executable)).lower() return str(interp.parent).lower() != running_dir @@ -533,18 +414,16 @@ def _run_quiet(cmd: "list[str]") -> bool: return result.returncode == 0 -# Sizes a typical hicolor ``index.theme`` actually lists. ``scalable`` is -# SVG-only — a raster PNG there is what Cinnamon's panel draws as a -# mangled low-res blob. The shipped desktop asset is 1024×1024, which is -# also not an indexed dir name, so a copy-only fallback lands in ``256x256``. +# Sizes a typical hicolor ``index.theme`` lists. ``scalable`` is SVG-only — a raster PNG there is +# what Cinnamon's panel draws as a mangled low-res blob. The shipped asset is 1024×1024 (not an +# indexed dir name), so a copy-only fallback lands in ``256x256``. _HICOLOR_INDEXED_SIZES = (16, 22, 24, 32, 36, 48, 64, 72, 96, 128, 192, 256, 512) -# Cinnamon's panel is ~24–32px. Write these so the theme loads an exact -# raster instead of downscaling a 1024px PNG at lookup time. +# Cinnamon's panel is ~24–32px: write exact rasters so the theme needn't downscale a 1024px PNG. _HICOLOR_INSTALL_SIZES = (24, 32, 48, 256) def _png_dimensions(raw: bytes) -> Optional[tuple[int, int]]: - """Return ``(width, height)`` from a PNG IHDR, or ``None`` if unreadable.""" + """``(width, height)`` from a PNG IHDR, or ``None`` if unreadable.""" if len(raw) >= 24 and raw[:8] == b"\x89PNG\r\n\x1a\n" and raw[12:16] == b"IHDR": return struct.unpack(">II", raw[16:24]) return None @@ -555,11 +434,9 @@ def _hicolor_subdir(dimensions: Optional[tuple[int, int]]) -> str: if dimensions is None: return "256x256" width, height = dimensions - if width != height or width <= 0: - return "256x256" - if width in _HICOLOR_INDEXED_SIZES: + if width in _HICOLOR_INDEXED_SIZES and width == height: return f"{width}x{width}" - if width > 256: + if width != height or width <= 0 or width > 256: return "256x256" nearest = min(_HICOLOR_INDEXED_SIZES, key=lambda size: abs(size - width)) return f"{nearest}x{nearest}" @@ -570,19 +447,15 @@ def _hicolor_icon_dest(subdir: str) -> Path: def _remove_stale_scalable_icon() -> bool: - """Drop a leftover PNG from ``scalable/`` (the pre-fix install path). - - Return True when a file was removed so the caller can refresh the icon cache. A missing file is - not an error. - """ + """Drop a leftover PNG from ``scalable/`` (the pre-fix install path); True if removed.""" stale = _hicolor_icon_dest("scalable") try: - if stale.is_file(): - stale.unlink() - return True + if not stale.is_file(): + return False + stale.unlink() + return True except OSError: return False - return False def _refresh_hicolor_cache() -> None: @@ -596,12 +469,9 @@ def _refresh_hicolor_cache() -> None: def _resized_hicolor_pngs(raw: bytes) -> Optional[dict[str, bytes]]: - """Lanczos-resize *raw* to each panel size. ``None`` when it will not decode. - - Pillow is a core dep but this module stays import-light: the import is local so the uninstaller - does not pay it. A truncated/fake PNG (tests, interrupted copy) returns None and the caller - falls back to a copy. - """ + """Lanczos-resize *raw* to each panel size; ``None`` when it will not decode (truncated/fake + PNG) so the caller falls back to a copy. Pillow is imported lazily to keep the uninstaller + import-light.""" try: from PIL import Image except ImportError: @@ -611,9 +481,8 @@ def _resized_hicolor_pngs(raw: bytes) -> Optional[dict[str, bytes]]: rgba = im.convert("RGBA") out: dict[str, bytes] = {} for size in _HICOLOR_INSTALL_SIZES: - resized = rgba.resize((size, size), Image.Resampling.LANCZOS) buf = io.BytesIO() - resized.save(buf, format="PNG") + rgba.resize((size, size), Image.Resampling.LANCZOS).save(buf, format="PNG") out[f"{size}x{size}"] = buf.getvalue() return out except (OSError, ValueError): @@ -634,12 +503,8 @@ def _write_hicolor_pngs(files: dict[str, bytes]) -> bool: def _install_icon_to_hicolor(icon: Path) -> bool: - """Install the app icon into the user's hicolor icon theme tree. - - The freedesktop icon lookup finds an installed ``apps/hermes.png`` by the unqualified name - ``hermes``, so the entry can reference the icon without an absolute checkout path. Raster PNGs - go to indexed fixed-size dirs, never ``scalable`` (SVG-only). - """ + """Install the app icon into the user's hicolor tree so ``Icon=hermes`` resolves without an + absolute checkout path. Raster PNGs go to indexed fixed-size dirs, never ``scalable``.""" try: raw = icon.read_bytes() resized = _resized_hicolor_pngs(raw) @@ -647,14 +512,11 @@ def _install_icon_to_hicolor(icon: Path) -> bool: wrote = _write_hicolor_pngs(resized) else: dest = _hicolor_icon_dest(_hicolor_subdir(_png_dimensions(raw))) - wrote = True - if dest.is_file() and dest.read_bytes() == raw: - wrote = False - else: + wrote = not (dest.is_file() and dest.read_bytes() == raw) + if wrote: dest.parent.mkdir(parents=True, exist_ok=True) shutil.copyfile(icon, dest) - removed_stale = _remove_stale_scalable_icon() - if wrote or removed_stale: + if _remove_stale_scalable_icon() or wrote: _refresh_hicolor_cache() return True except OSError: @@ -662,22 +524,19 @@ def _install_icon_to_hicolor(icon: Path) -> bool: def install_desktop_entry(project_root: Path) -> Optional[Path]: - """Write (or refresh) the Hermes desktop entry. Return its path. + """Write (or refresh) the Hermes desktop entry and return its path. - Return ``None`` on non-Linux platforms or when the write fails. This is a convenience, never a - reason to fail a launch. + ``None`` on non-Linux platforms or when the write fails — a convenience, never a reason to + fail a launch. """ if not is_supported(): return None entry_path = desktop_entry_path() icon = icon_path(project_root) - # Prefer the themed name: the icon is COPIED into the user's hicolor - # tree, so the entry outlives the checkout (moving/archiving the - # checkout would break an absolute Icon= path — the same - # durability class the Exec line was fixed for). Fall back to the - # absolute path only when the copy is impossible (read-only tree), - # and to the themed name when the checkout has no icon at all. + # Prefer the themed name: the icon is COPIED into the hicolor tree, so the entry outlives the + # checkout (an absolute Icon= path breaks when the checkout moves). Absolute path only when + # the copy is impossible (read-only tree); themed name when the checkout has no icon at all. icon_value = str(icon) if icon.is_file() else "hermes" if icon.is_file() and _install_icon_to_hicolor(icon): icon_value = "hermes" @@ -685,21 +544,15 @@ def install_desktop_entry(project_root: Path) -> Optional[Path]: try: entry_path.parent.mkdir(parents=True, exist_ok=True) - # When nothing changed, skip the rewrite. Then a launch does not - # churn the menu caches. + # Unchanged → skip the rewrite so a launch doesn't churn the menu caches. if entry_path.is_file() and entry_path.read_text(encoding="utf-8") == contents: return entry_path - # Atomic replace: an interrupted plain write can leave a zero-byte - # entry, which permanently breaks the taskbar pin (nothing later - # rewrites a file that exists at the right path). The temp+rename - # dance in utils.atomic_write_text is the codebase's shared - # implementation — ported from #80547, which closed unmerged with - # this piece unlanded. + # Atomic replace: an interrupted plain write leaves a zero-byte entry, which permanently + # breaks the taskbar pin (nothing later rewrites a file that exists at the right path). from utils import atomic_write_text atomic_write_text(entry_path, contents, create_mode=0o755) - # Some launchers (and older Plasma) offer the entry only when it - # is executable. + # Some launchers (and older Plasma) offer the entry only when it is executable. entry_path.chmod(0o755) except OSError: return None