| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188 |
- """Install a desktop plugin from Git onto the host that serves the Webapp.
- Native Desktop clones one in Electron (``apps/desktop/electron/desktop-plugin-install.ts``,
- ``installDesktopPluginFromGit``). A browser-hosted tab has no disk of its own, so until now the install
- dialog could only *read* a repository through the gateway (``plugins_cmd_inspect``) and then had
- nothing to install with: a desktop-only package answered "nothing to install here", and the desktop
- half of a mixed one was reported skipped. This is the missing half of the trip — the same inspection,
- held to the commit it read, the same folder name and package-marker rules as Electron, published
- atomically into the app-level root that ``/api/desktop-plugins`` serves.
- The install is a clone, a staged copy and a rename: no code is imported or run here. The plugin loads
- the way any other installed plugin does, on the next scan of ``desktop-plugins/``.
- """
- from __future__ import annotations
- import re
- import tempfile
- from pathlib import Path
- from typing import Any, Optional
- from hermes_cli import desktop_plugin_halves as halves
- from hermes_constants import get_default_hermes_root
- from utils import rmtree_readonly
- DESKTOP_PLUGINS_DIR = "desktop-plugins"
- _COMMIT = re.compile(r"[0-9a-f]{40}")
- #: Windows device names: a folder called one of these (whatever its extension) opens the device instead.
- _WINDOWS_DEVICE = re.compile(r"(?:CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|CLOCK\$|COM[0-9¹²³]|LPT[0-9¹²³])", re.IGNORECASE)
- def desktop_plugins_root() -> Path:
- """The app-level root ``desktop-plugins/``, created on demand and resolved, exactly as Electron's
- ``desktopPluginsRoot`` and the Webapp's read routes resolve it: one folder whichever profile the
- caller names."""
- root = get_default_hermes_root() / DESKTOP_PLUGINS_DIR
- root.mkdir(parents=True, exist_ok=True)
- return root.resolve()
- def _pc():
- """The facade, read at call time: tests patch ``plugins_cmd.<name>`` and sibling calls must see it."""
- from hermes_cli import plugins_cmd
- return plugins_cmd
- def _failure(error: str) -> dict[str, Any]:
- return {"ok": False, "error": error}
- def _checked_name(name: Optional[str]) -> str:
- """*name* when it can be one folder under the root, else raise: the name comes from a repository
- (a subdirectory's last segment, a manifest's ``name``) and must never reach a path unresolved. A
- leading dot is refused too — the root's staging folders use that prefix. So are the names Windows
- reads as something else: a colon makes ``C:..`` a drive-relative path, a device name opens the
- device, and a trailing dot is dropped."""
- candidate = (name or "").strip()
- if (not candidate or candidate.startswith(".") or candidate.endswith(".")
- or any(char in candidate for char in "/\\:\0") or any(ord(char) < 32 for char in candidate)
- or len(candidate) > 128 or _WINDOWS_DEVICE.fullmatch(candidate.split(".", 1)[0].rstrip(" "))):
- raise _pc().PluginOperationError(
- f"'{name}' is not a desktop plugin folder name: it must be a plain folder name, not a path."
- )
- return candidate
- def _resolve_source(identifier: str, catalog_name: Optional[str]) -> tuple[str, Optional[str], Optional[str]]:
- """``(git_url, subdir, catalog_sha)`` through the installer's own resolution and kill list, with the
- catalog's reviewed pin when *catalog_name* is given (its repository replaces *identifier*).
- Every scheme the CLI installs from is accepted (``git@``/``ssh://`` for private plugins, ``file://``,
- ``http://``): the Webapp opens only for the signed-in owner of this host, whose keys and disk these are."""
- pc = _pc()
- revision = None
- if catalog_name:
- from hermes_cli import plugins_cmd_catalog as catalog
- entry = catalog.get_live_catalog_entry(catalog_name)
- if entry is None:
- raise pc.PluginOperationError(f"'{catalog_name}' is not in the Hermes plugin catalog.")
- identifier, revision = entry.install_identifier, entry.sha or None
- try:
- git_url, subdir = pc._resolve_git_url(identifier)
- except ValueError as exc:
- raise pc.PluginOperationError(str(exc)) from exc
- from hermes_cli.plugins_cmd_catalog import raise_if_removed
- raise_if_removed(identifier, git_url, *((catalog_name,) if catalog_name else ()))
- return git_url, subdir, revision
- def install_desktop_plugin(identifier: str, *, ref: Optional[str], catalog_name: Optional[str] = None,
- force: bool = False) -> dict[str, Any]:
- """Clone a repository's desktop half into ``desktop-plugins/<name>`` on this host.
- *ref* is the commit the install dialog showed (``inspect``'s ``sha``): the clone is checked out at
- exactly that commit, so a repository that moved after review is refused rather than installed. The
- halves are read from that same checkout. Returns ``{ok, plugin_name, path, sha, paired_with_agent,
- warnings}``, or ``ok: False`` with ``error``. A package carrying both halves lands under its *agent*
- name with the package marker Electron writes, so the Plugins page pairs the two rows; a desktop-only
- repository keeps its Git-derived folder name and carries no marker.
- """
- from hermes_cli.plugins_cmd_inspect import _desktop_folder_name, detect_components
- pc = _pc()
- sha = (ref or "").strip().lower()
- try:
- if not _COMMIT.fullmatch(sha):
- raise pc.PluginOperationError("Installing a desktop plugin needs the commit the install dialog reviewed.")
- git_url, subdir, catalog_sha = _resolve_source(identifier, catalog_name)
- root = desktop_plugins_root()
- with tempfile.TemporaryDirectory(prefix="hermes-plugin-install-") as tmp:
- clone = Path(tmp) / "plugin"
- # A catalog entry is fetched at its own pin, as the agent installer fetches it: an
- # annotated-tag pin names the tag object, and only its peeled commit is what the dialog read.
- head = pc._clone_plugin_repo(clone, git_url, catalog_sha or sha, subdir)
- if head != sha:
- raise pc.PluginSourceMoved(
- "The catalog's reviewed commit changed since the dialog read it; inspect it again.")
- # Nothing reads a plugin's Git metadata, and Git's read-only object files would make the
- # published folder one that Windows cannot delete.
- rmtree_readonly(clone / ".git")
- plugin_root = pc._resolve_subdir_within(clone, subdir) if subdir else clone
- fallback = subdir.rstrip("/").rsplit("/", 1)[-1] if subdir else pc._repo_name_from_url(git_url)
- found = detect_components(plugin_root, fallback)
- if not found["desktop"]:
- return _failure("This package ships no desktop plugin to install here.")
- package_name = _checked_name(found["agent_name"]) if found["agent"] else None
- folder = package_name or _checked_name(_desktop_folder_name(git_url, subdir))
- source_dir = _desktop_tree(plugin_root)
- target = root / folder
- # A package's half keeps the marker Electron writes (the Plugins page pairs it to the agent
- # row); a standalone plugin carries none.
- marker = {"package": package_name, "repo": git_url, "source": str(target),
- "sourceMtimeMs": halves.mtime_ms((source_dir / "plugin.js").stat())} if package_name else None
- # The exists check and the publish must not interleave with a reconcile pass.
- with halves.ROOT_WRITER:
- if (halves._is_link(target) or target.exists()) and not force:
- return _failure(f"Desktop plugin '{folder}' already exists. Enable force reinstall to replace it.")
- halves.publish_desktop_tree(source_dir, target, marker)
- except pc.PluginOperationError as exc:
- return {**_failure(str(exc)), **({"source_moved": True} if isinstance(exc, pc.PluginSourceMoved) else {})}
- except OSError as exc:
- return _failure(f"Could not install the desktop plugin: {exc}")
- return {"ok": True, "plugin_name": folder, "path": str(target), "sha": sha,
- "paired_with_agent": bool(package_name), "warnings": []}
- def _desktop_tree(plugin_root: Path) -> Path:
- """The folder that is the desktop plugin (:func:`halves.desktop_source`, the rule the host's
- reconcile applies to an installed package too). It must be a plain tree inside the clone."""
- source = halves.desktop_source(plugin_root) or plugin_root / "desktop"
- refused = halves.check_desktop_tree(source, plugin_root)
- if refused:
- raise _pc().PluginOperationError(refused)
- return source
- def remove_desktop_plugin(name: str, *, force: bool = False) -> dict[str, Any]:
- """Delete one installed desktop plugin folder from this host.
- A folder carrying the package marker is the desktop half of an installed agent plugin: removing it
- alone would leave the Plugins page pairing a row with nothing behind it, and the next reconcile
- would copy it straight back, so it is refused unless *force* says the caller means it.
- """
- try:
- folder = _checked_name(name)
- except _pc().PluginOperationError as exc:
- return _failure(str(exc))
- target = desktop_plugins_root() / folder
- if halves._is_link(target):
- return _failure(
- f"'{folder}' is linked from somewhere else on this host; remove that link where it lives."
- )
- if not target.is_dir():
- return _failure(f"No desktop plugin named '{folder}' is installed.")
- with halves.ROOT_WRITER:
- marker = halves.read_package_marker(target)
- if marker and not force:
- return _failure(
- f"'{folder}' is the desktop half of an agent plugin — uninstall that plugin instead."
- )
- try:
- rmtree_readonly(target)
- except OSError as exc:
- return _failure(f"Could not remove the desktop plugin: {exc}")
- return {"ok": True, "plugin_name": folder, "path": str(target), "unpaired_from": (marker or {}).get("package")}
|