refactor(cli-misc): linux_desktop_entry.py — hoist nested helpers, flatten wrapper probe, compact WHY comments
This commit is contained in:
+183
-330
@@ -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 ``<python> -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
|
||||
# `<python> 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
|
||||
# `<python> 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 (``<checkout>-old``, ``<checkout>.bak``), so the root must end at a quote /
|
||||
whitespace / EOL or continue INTO the tree (``<root>/``). 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 `<checkout>-old` or `<checkout>.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
|
||||
# <root>/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 ``<checkout>/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.
|
||||
"""
|
||||
"""``<checkout>`` 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: ``<venv>/bin-extra/python`` is not inside ``<venv>/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: ``<venv>/bin-extra/python`` is not inside
|
||||
``<venv>/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 <abs-interpreter>`` 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 <abs>`), 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
|
||||
|
||||
Reference in New Issue
Block a user