| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161 |
- """``hermes plugins`` CLI subcommand — install, update, remove, and list plugins.
- Facade: shared primitives (errors, console/config helpers, manifest reading, discovery, enable/disable
- selection) and the dispatch table live here; each verb family lives in a ``plugins_cmd_<topic>.py``
- sibling (install, update, remove, git, capabilities, toggle, listing, catalog)."""
- from __future__ import annotations
- import functools
- import logging
- import os
- import shutil
- import sys
- import threading
- from pathlib import Path
- from typing import Any, NoReturn, Optional
- from hermes_constants import get_hermes_home, hermes_home_key
- from hermes_cli.config import cfg_get
- from hermes_cli.plugin_capabilities import _child_dict
- # Tests patch these two on the facade; the install/remove siblings read them through it.
- from hermes_cli.secret_prompt import masked_secret_prompt
- from utils import rmtree_readonly
- # Topical siblings. The facade re-exports what other modules, tests and the old updater import from
- # ``hermes_cli.plugins_cmd``; sibling bodies read those names back through the facade at call time.
- from hermes_cli.plugins_cmd_capabilities import (
- _declared_capabilities_for_key, _declared_capabilities_from_manifest, _resolve_tool_override_grant,
- _run_capability_consent, cmd_capabilities,
- )
- from hermes_cli.plugins_cmd_git import (
- _EXACT_COMMIT_RE, _canonical_source, _checkout_exact_revision, _clone_plugin_repo, _git_head_revision,
- _git_or_raise, _git_pull_plugin_dir, _git_resolve_commit, _normalize_exact_revision, _pin_annotation,
- _read_install_metadata, _run_plugin_git, _safe_git_error, _scrub_cloned_origin, _update_install_record,
- _write_install_metadata, pinned_revision,
- )
- from hermes_cli.plugins_cmd_install import (
- _check_manifest_version, _consent_python_deps, _display_after_install, _install_plugin_core,
- _install_plugin_python_deps, _prompt_plugin_env_vars, _python_dependency_summary,
- _read_manifest_for_install, cmd_install, dashboard_install_plugin,
- )
- from hermes_cli.plugins_cmd_listing import (
- _filter_plugin_entries, cmd_list, cmd_show,
- )
- from hermes_cli.plugins_cmd_remove import (
- _remove_plugin_core, cmd_remove, dashboard_remove_user_plugin,
- )
- from hermes_cli.plugins_cmd_toggle import (
- _discover_context_engines, _persist_plugin_selection, _provider_categories, _run_composite_fallback,
- cmd_toggle,
- )
- from hermes_cli.plugins_cmd_update import (
- _clear_plugin_bytecode, cmd_adopt, cmd_check_updates, cmd_trust_update_url, cmd_update,
- dashboard_update_user_plugin,
- )
- logger = logging.getLogger(__name__)
- _DEFAULT_CLONE_TIMEOUT_SECONDS = 300
- _MAX_CLONE_TIMEOUT_SECONDS = 3600
- _CLONE_TIMEOUT_HINT = "On a slow connection, raise plugins.clone_timeout_seconds in config.yaml."
- @functools.lru_cache(maxsize=1)
- def _resolve_git_executable() -> Optional[str]:
- """Resolve a git binary for subprocess use when ``PATH`` may be minimal."""
- found = shutil.which("git")
- if found:
- return found
- if os.name == "nt":
- roots = [
- os.environ.get("ProgramFiles", r"C:\Program Files"),
- os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)"),
- ]
- local = os.environ.get("LOCALAPPDATA", "")
- if local:
- roots.append(os.path.join(local, "Programs"))
- candidates = [os.path.join(r, "Git", sub, "git.exe") for r in roots for sub in ("cmd", "bin")]
- else:
- candidates = ["/usr/bin/git", "/usr/local/bin/git", "/bin/git"]
- return next((c for c in candidates if c and os.path.isfile(c)), None)
- class PluginOperationError(Exception):
- """Recoverable plugin install/update failure (CLI exits; HTTP maps to 4xx).
- ``failure_class`` names the raise site for the extension-install metric (a closed name from
- ``shared_metrics_contract.EXTENSION_PLUGIN_FAILURE_CLASSES``); untagged sites read ``other``.
- """
- failure_class = "other"
- def __init__(self, *args, failure_class: Optional[str] = None):
- super().__init__(*args)
- if failure_class is not None:
- self.failure_class = failure_class
- class PluginSourceMoved(PluginOperationError):
- """The source is no longer at the commit the install dialog reviewed. Clients answer it by reading
- the source again (``plugins.manage`` error ``data.reason == "source_moved"``), never by resending."""
- failure_class = "clone_failed"
- class PluginScanBlocked(PluginOperationError):
- """Plugin failed the security scan and was not installed."""
- failure_class = "scan_blocked"
- def __init__(self, message: str, scan_result=None):
- super().__init__(message)
- self.scan_result = scan_result
- def _console():
- """A fresh Rich console (rich is imported lazily)."""
- from rich.console import Console
- return Console()
- def _table(columns, **kwargs):
- """A Rich ``Table(**kwargs)`` with ``(header, style)`` *columns* added in order."""
- from rich.table import Table
- table = Table(**kwargs)
- for header, style in columns:
- table.add_column(header, style=style)
- return table
- def _is_tty() -> bool:
- return sys.stdin.isatty() and sys.stdout.isatty()
- def _fail(console, message: str) -> NoReturn:
- """Print *message* and exit 1."""
- console.print(message)
- sys.exit(1)
- def _ask_yes(prompt: str, reader=input) -> bool:
- """One y/N question; EOF / Ctrl-C count as "no"."""
- try:
- answer = reader(prompt).strip().lower()
- except (EOFError, KeyboardInterrupt):
- return False
- return answer in {"y", "yes"}
- def _config_value(*keys: str, default: Any) -> Any:
- """Read ``keys`` from config.yaml; *default* on a missing key or any load failure."""
- try:
- from hermes_cli.config import load_config
- return cfg_get(load_config(), *keys, default=default)
- except Exception:
- return default
- def _clone_timeout_seconds() -> int:
- """Deadline for plugin clone and pinned fetch, scoped to the active profile."""
- value = _config_value("plugins", "clone_timeout_seconds", default=_DEFAULT_CLONE_TIMEOUT_SECONDS)
- if isinstance(value, bool) or not isinstance(value, int) or value < 1:
- logger.warning("plugins.clone_timeout_seconds must be a positive integer; using %ss",
- _DEFAULT_CLONE_TIMEOUT_SECONDS)
- return _DEFAULT_CLONE_TIMEOUT_SECONDS
- if value > _MAX_CLONE_TIMEOUT_SECONDS:
- logger.warning("plugins.clone_timeout_seconds exceeds %ss; clamping", _MAX_CLONE_TIMEOUT_SECONDS)
- return _MAX_CLONE_TIMEOUT_SECONDS
- return value
- def _config_name_set(*keys: str) -> set:
- """A list-valued config key as a set (empty on any failure or non-list)."""
- value = _config_value(*keys, default=[])
- return set(value) if isinstance(value, list) else set()
- def _config_str(*keys: str, default: str) -> str:
- """A string config key; empty/missing/failed reads coerce to *default*."""
- return _config_value(*keys, default=default) or default
- def _write_config_value(section: str, key: str, value: Any) -> None:
- """Persist ``config[section][key] = value`` to config.yaml (creating the section)."""
- from hermes_cli.config import load_config, save_config
- config = load_config()
- config.setdefault(section, {})[key] = value
- save_config(config)
- def _scan_on_install_enabled() -> bool:
- """Install/update-time security scanning; on by default, off via ``plugins.scan_on_install: false``."""
- return bool(_config_value("plugins", "scan_on_install", default=True))
- def _scan_plugin_tree(plugin_dir: Path, identifier: str, *, force: bool, scan_decision_cb=None,
- reviewed_pin: bool = False):
- """Scan *plugin_dir* and enforce the install policy.
- Verdicts: safe → proceed; caution → needs confirmation (``force=True`` or a truthy
- ``scan_decision_cb(result)``); dangerous → always blocked (:class:`PluginScanBlocked`).
- *reviewed_pin* marks a tree checked out at a curated-catalog sha: that exact tree passed
- the same scanner at admission with a human reading the caution findings, so caution is
- accepted without a prompt (the Desktop has none). Dangerous still blocks — a signature
- added after review is exactly the case the backstop exists for.
- Returns the ScanResult, or None when scanning is disabled.
- """
- if not _scan_on_install_enabled():
- return None
- from tools.plugin_guard import format_scan_report, scan_plugin, should_allow_plugin_install
- result = scan_plugin(plugin_dir, source=identifier)
- allowed, reason = should_allow_plugin_install(result, force=force)
- if allowed is None and reviewed_pin:
- allowed, reason = True, "Caution verdict accepted: reviewed catalog pin"
- if allowed is None and scan_decision_cb is not None:
- try:
- if scan_decision_cb(result):
- allowed = True
- reason = "Caution verdict accepted by user"
- except Exception:
- logger.exception("plugin scan decision callback failed")
- if allowed is not True:
- raise PluginScanBlocked(
- f"Security scan blocked plugin install: {reason}\n\n"
- f"{format_scan_report(result)}\n"
- "Review the findings above. Install only plugins from sources "
- "you trust. (Scanning can be configured via "
- "plugins.scan_on_install in config.yaml.)",
- scan_result=result)
- logger.info("plugin scan passed for %s: %s", plugin_dir.name, reason)
- return result
- def _preserved_files_note(exc: PluginScanBlocked, merged: list[str]) -> str:
- """Scan-block text for a tree that also holds user files preserved from the installed copy."""
- preserved = set(merged)
- findings = exc.scan_result.findings if exc.scan_result is not None else ()
- hits = sorted({f.file for f in findings if f.file in preserved})
- if hits:
- note = ("These findings come from user files preserved from the installed copy: "
- f"{', '.join(hits)}. Move or remove them and retry the update.")
- else:
- note = "The scanned tree included user files preserved from the installed copy."
- return f"{exc}\n\n{note}"
- def _scan_merged_tree(plugin_dir: Path, identifier: str, merged: Optional[list[str]], **kwargs):
- """:func:`_scan_plugin_tree` for a candidate that may hold carried user files (*merged*).
- A block then names the findings that sit in those files, so user data does not read as a
- malicious upstream revision; the original block stays chained as the cause.
- """
- try:
- return _scan_plugin_tree(plugin_dir, identifier, **kwargs)
- except PluginScanBlocked as exc:
- if not merged:
- raise
- raise PluginScanBlocked(_preserved_files_note(exc, merged), scan_result=exc.scan_result) from exc
- def _plugins_dir() -> Path:
- """Return the user plugins directory, creating it if needed."""
- plugins = get_hermes_home() / "plugins"
- plugins.mkdir(parents=True, exist_ok=True)
- return plugins
- def _sanitize_plugin_name(name: str, plugins_dir: Path, *, allow_subdir: bool = False) -> Path:
- """Validate a plugin name and return the safe target path inside *plugins_dir*.
- Raises ``ValueError`` on traversal or a target outside the plugins directory. ``allow_subdir``
- permits forward slashes so category keys like ``web/firecrawl`` can be looked up
- (``..`` and backslashes stay rejected); install paths keep ``False`` — a clone lands top-level.
- """
- if allow_subdir and name:
- name = name.strip("/")
- if not name:
- raise ValueError("Plugin name must not be empty.")
- if name in {".", ".."}:
- raise ValueError(f"Invalid plugin name '{name}': must not reference the plugins directory itself.")
- for bad in ("\\", "..") if allow_subdir else ("/", "\\", ".."):
- if bad in name:
- raise ValueError(f"Invalid plugin name '{name}': must not contain '{bad}'.")
- target = (plugins_dir / name).resolve()
- plugins_resolved = plugins_dir.resolve()
- if target == plugins_resolved:
- raise ValueError(f"Invalid plugin name '{name}': resolves to the plugins directory itself.")
- if plugins_resolved not in target.parents:
- raise ValueError(f"Invalid plugin name '{name}': resolves outside the plugins directory.")
- return target
- _GITHUB_BROWSER_SEGMENTS = {
- "actions", "blob", "commit", "commits", "issues", "pull", "pulls", "releases", "tree", "wiki",
- }
- _URL_SCHEMES = ("https://", "http://", "git@", "ssh://", "file://")
- def _resolve_git_url(identifier: str) -> tuple[str, Optional[str]]:
- """Turn an identifier into a cloneable Git URL and optional subdirectory.
- ``http://`` and ``file://`` are accepted but trigger a security warning at install time.
- """
- if identifier.startswith(_URL_SCHEMES):
- if identifier.startswith("https://github.com/"):
- path = identifier[len("https://github.com/") :]
- path = path.split("?", 1)[0].split("#", 1)[0].strip("/")
- parts = path.split("/")
- if len(parts) >= 3 and all(parts[:2]) and parts[2] in _GITHUB_BROWSER_SEGMENTS:
- repo = parts[1].removesuffix(".git")
- subdir = None
- if parts[2] == "tree" and len(parts) >= 5:
- subdir = "/".join(p for p in parts[4:] if p).strip("/") or None
- return f"https://github.com/{parts[0]}/{repo}.git", subdir
- # Explicit ``#subdir`` fragment — unambiguous for any scheme.
- if "#" in identifier:
- git_url, _, frag = identifier.partition("#")
- return git_url, (frag.strip("/") or None)
- # Natural ``.git/`` boundary (GitHub-style URLs).
- git_url, marker, subdir = identifier.partition(".git/")
- if marker:
- return git_url + ".git", (subdir.strip("/") or None)
- return identifier, None
- # owner/repo[/subdir...] or owner/repo#subdir shorthand (the catalog spells subdirs with ``#``).
- identifier, _, fragment = identifier.partition("#")
- parts = [p for p in identifier.strip("/").split("/") if p]
- if len(parts) >= 2:
- subdir = "/".join([*parts[2:], *fragment.split("/")]).strip("/")
- return f"https://github.com/{parts[0]}/{parts[1]}.git", (subdir or None)
- raise ValueError(
- f"Invalid plugin identifier: '{identifier}'. "
- "Use a Git URL or 'owner/repo' shorthand (optionally with a subdirectory: "
- "'owner/repo/path/to/plugin').")
- def _resolve_subdir_within(clone_root: Path, subdir: str) -> Path:
- """Resolve ``subdir`` inside ``clone_root``; ``..``, absolute paths and symlinks may not
- escape the clone. Raises ``PluginOperationError`` if it escapes, is missing, or is a file."""
- clone_root = clone_root.resolve()
- candidate = (clone_root / subdir).resolve()
- if candidate != clone_root and clone_root not in candidate.parents:
- raise PluginOperationError(f"Plugin subdirectory '{subdir}' escapes the repository.",
- failure_class="invalid_source")
- if not candidate.exists():
- raise PluginOperationError(f"Plugin subdirectory '{subdir}' does not exist in the repository.",
- failure_class="invalid_source")
- if not candidate.is_dir():
- raise PluginOperationError(f"Plugin subdirectory '{subdir}' is not a directory.",
- failure_class="invalid_source")
- return candidate
- def _repo_name_from_url(url: str) -> str:
- """Repo name from a Git URL (last path component; ssh-style ``git@host:repo`` splits on ':')."""
- name = url.rstrip("/").removesuffix(".git").rsplit("/", 1)[-1]
- if ":" in name:
- name = name.rsplit(":", 1)[-1].rsplit("/", 1)[-1]
- return name
- def _native_manifest_file(plugin_dir: Path) -> Optional[Path]:
- """``plugin.yaml`` (or ``plugin.yml``) under *plugin_dir*, or None when neither exists."""
- from pm.plugin_declarations import native_manifest_file
- try:
- return native_manifest_file(plugin_dir)
- except ValueError as exc:
- raise PluginOperationError(str(exc), failure_class="manifest_invalid") from exc
- def _has_portable_manifest(plugin_dir: Path) -> bool:
- """True when ``plugin.json`` exists (or is a symlink, even dangling) under *plugin_dir*."""
- portable_file = plugin_dir / "plugin.json"
- return portable_file.exists() or portable_file.is_symlink()
- def _load_yaml_manifest(manifest_file: Path):
- """``yaml.safe_load`` of *manifest_file* (``{}`` when empty); raises on any read/parse error."""
- from pm.plugin_declarations import read_native_manifest
- return read_native_manifest(manifest_file)
- def _read_manifest(plugin_dir: Path) -> dict:
- """Read a native or portable manifest, preferring native YAML."""
- manifest_file = _native_manifest_file(plugin_dir)
- if manifest_file is None:
- if not _has_portable_manifest(plugin_dir):
- return {}
- try:
- from hermes_cli.agent_plugins import read_agent_plugin_manifest
- return read_agent_plugin_manifest(plugin_dir)[0]
- except Exception as e:
- logger.warning("Failed to read plugin.json in %s: %s", plugin_dir, e)
- return {}
- try:
- return _load_yaml_manifest(manifest_file)
- except Exception as e:
- logger.warning("Failed to read plugin.yaml in %s: %s", plugin_dir, e)
- return {}
- def _looks_like_plugin_dir(target: Path) -> bool:
- """True when *target* has a native/portable manifest or a package ``__init__.py``."""
- return (
- _native_manifest_file(target) is not None
- or (target / "plugin.json").exists()
- or (target / "__init__.py").exists())
- def _copy_example_files(plugin_dir: Path, console) -> None:
- """Copy ``*.example`` files to their real names (``config.yaml.example`` -> ``config.yaml``),
- never overwriting an existing file so reinstall keeps user config."""
- for example_file in plugin_dir.glob("*.example"):
- real_name = example_file.stem
- real_path = plugin_dir / real_name
- if real_path.exists():
- continue
- try:
- shutil.copy2(example_file, real_path)
- console.print(f"[dim] Created {real_name} from {example_file.name}[/dim]")
- except OSError as e:
- console.print(f"[yellow]Warning:[/yellow] Failed to copy {example_file.name}: {e}")
- def _missing_env_specs(manifest: dict) -> list[dict]:
- """``requires_env`` entries (plain names or ``{name, description, url, secret}`` dicts,
- normalised to dicts; nameless entries dropped) whose variable is unset in ``~/.hermes/.env``."""
- env_specs = [
- {"name": entry} if isinstance(entry, str) else entry
- for entry in manifest.get("requires_env") or []
- if isinstance(entry, str) or (isinstance(entry, dict) and entry.get("name"))
- ]
- if not env_specs:
- return []
- from hermes_cli.config import get_env_value
- return [s for s in env_specs if not get_env_value(s["name"])]
- def _clone_failure_message(git_url: str, git_error: str) -> str:
- """Plain-words clone failure: what to check (address, network, private repo), raw git text last.
- The text reaches ``_fail`` -> Rich ``console.print``: escape the git output so ``[...]`` in it is
- not parsed as markup."""
- from rich.markup import escape
- return (f"Could not download the plugin from {git_url}. Check the address (browse the catalog "
- "with `hermes plugins search`), check your internet connection, or, if the repository "
- "is private, sign in first with `gh auth login` (or set GITHUB_TOKEN in your .env).\n"
- f"Details: {escape(git_error.strip())}")
- def _require_installed_plugin(name: str, plugins_dir: Path, console) -> Path:
- """The plugin path if it exists; else exit 1 (invalid name, or a listing of installed plugins)."""
- try:
- target = _sanitize_plugin_name(name, plugins_dir, allow_subdir=True)
- except ValueError as e:
- _fail(console, f"[red]Error:[/red] {e}")
- if not target.exists():
- target = _resolved_user_plugin_dir(name)
- if target is None:
- _fail(console, _unknown_plugin_message(name, downloaded_only=True))
- return target
- def _unknown_plugin_message(name: str, *, downloaded_only: bool = False) -> str:
- """``No plugin named ...`` with the exact-name rule and the two commands that resolve it."""
- scope = (" This command only works on downloaded plugins; bundled ones can only be enabled or disabled."
- if downloaded_only else " Bundled plugins can only be enabled or disabled.")
- from hermes_cli.left_core_migration import moved_plugin_hint
- if moved := moved_plugin_hint(name):
- return f"[red]No plugin named '{name}'.[/red] {moved}"
- return (f"[red]No plugin named '{name}'.[/red] Run `hermes plugins list` to see the exact names "
- f"(nested plugins use their full key, e.g. web/firecrawl).{scope} "
- "To add one: `hermes plugins install <owner/repo>`.")
- # ``plugins.disabled`` is an explicit deny-list that wins over the ``plugins.enabled`` allow-list.
- _get_disabled_set = functools.partial(_config_name_set, "plugins", "disabled")
- _get_enabled_set = functools.partial(_config_name_set, "plugins", "enabled")
- def _save_enabled_set(enabled: set) -> None:
- """Frozen old-updater import: never resurrect a raw plugin-selection write."""
- from hermes_cli._old_updater import stop_for_relaunch
- stop_for_relaunch()
- def _plugin_selection_version() -> str:
- from hermes_cli.runtime_state import _digest
- return _digest(get_hermes_home() / "config.yaml") or "missing"
- def _admit_and_save_plugin_sets(
- enabled: set, disabled: set, *, extra_dirs=(), console=None, action: str = "enable", expected_config=None,
- plugin: Optional[str] = None, settled=(),
- ) -> None:
- """ONE admission authority for proposed enabled/disabled sets (C13):
- the candidate union is resolved against the ACTIVE environment and
- the config commits inside the same worker-owned PM transaction — a refusal or a config-write failure
- publishes nothing: previous config bytes AND previous environment
- stay exactly in place. Raises :class:`AdmissionRefused` (UI callers
- catch and surface it — admission never auto-disables to fit); a resolver
- conflict raises its :class:`DependencyConflict` subclass naming *plugin*."""
- from rich.markup import escape
- from hermes_cli.plugins_admission import AdmissionRefused, DependencyConflict, admit_plugin_set_change
- try:
- admit_plugin_set_change(
- enabled, disabled, active_plugins_dir=_plugins_dir(), extra_dirs=extra_dirs, expected_config=expected_config,
- plugin=plugin, settled=settled,
- )
- except DependencyConflict as exc:
- # `hermes pm install` cannot fix a conflict, so the retry hint below would mislead here.
- if console is not None:
- console.print(f"[red]✗[/red] {escape(str(exc))}")
- console.print("[dim]config.yaml and the active environment are unchanged.[/dim]")
- raise
- except AdmissionRefused as exc:
- if console is not None:
- console.print(f"[red]✗[/red] {action} refused: {exc}")
- console.print(
- "[dim]config.yaml and the active environment are unchanged. "
- "Run `hermes pm install` to resolve dependencies, then retry.[/dim]"
- )
- raise
- _BASIC_AUTH_PLUGIN_KEYS = frozenset({"basic", "dashboard_auth/basic"})
- def ensure_basic_auth_plugin_enabled_in_config(cfg: dict) -> bool:
- """Drop the bundled basic dashboard-auth plugin from ``plugins.disabled`` in *cfg*.
- ``hermes setup`` / ``hermes plugins disable basic`` can park it there while
- ``dashboard.basic_auth`` is configured, and password auth then silently fails.
- Returns True when modified.
- """
- plugins_cfg = cfg.get("plugins")
- disabled = plugins_cfg.get("disabled") if isinstance(plugins_cfg, dict) else None
- if not isinstance(disabled, list) or not (set(disabled) & _BASIC_AUTH_PLUGIN_KEYS):
- return False
- plugins_cfg["disabled"] = sorted(set(disabled) - _BASIC_AUTH_PLUGIN_KEYS)
- return True
- def _discard_key_and_leaf(names: set, key: str) -> None:
- """Drop *key* and its bare leaf (``web/exa`` -> ``exa``) from *names*, so a
- stale legacy bare-name entry can't keep vetoing the canonical key."""
- names.discard(key)
- names.discard(key.split("/")[-1])
- def _plugin_aliases(key: str, entries: Optional[list] = None) -> set:
- """Every spelling a config list may hold for *key*: the key, its bare leaf and the manifest name.
- The loader matches BOTH the canonical key (``web/firecrawl``) and the manifest name
- (``web-firecrawl``), so a stale entry under any form vetoes an enable ("explicit disable wins").
- Pass *entries* to reuse one :func:`_discover_all_plugins` scan across several keys."""
- from hermes_cli.left_core_migration import legacy_plugin_keys
- names = {key, key.split("/")[-1], *legacy_plugin_keys(key)}
- names.update(e[0] for e in (_discover_all_plugins() if entries is None else entries) if e[5] == key)
- return names
- def _activate_key(key: str, *, enable: bool, console=None) -> bool:
- """Transactionally persist canonical *key*, purging aliases from the opposing list.
- False when the lists already say so (nothing written). PM owns the selection and dependency
- publication together, so every CLI/dashboard activation surface goes through the same admission
- transaction instead of writing ``config.yaml`` directly."""
- enabled, disabled = _get_enabled_set(), _get_disabled_set()
- aliases = _plugin_aliases(key)
- target, other = (enabled, disabled) if enable else (disabled, enabled)
- # A plugin an update disabled is retried by later updates; disabling it yourself stops that.
- if key in target and not (aliases & other) and not (not enable and _disabled_by_update(key, aliases)):
- return False
- _set_plugin_enabled(key, enable=enable, aliases=aliases, console=console)
- return True
- def _disabled_by_update(key: str, aliases) -> bool:
- """Whether an update disabled this plugin and will retry it (``pm.plugin_eviction`` records it)."""
- from pm.plugins_state import RECORD
- from pm.plugins_state import read_home_selection
- record = ((read_home_selection(get_hermes_home()) or {}).get("plugins") or {}).get(RECORD)
- return isinstance(record, dict) and bool({key, *aliases} & set(record))
- def _forget_plugin_config(aliases: set) -> dict[str, Any]:
- """Drop every trace of a removed plugin (its :func:`_plugin_aliases`, taken BEFORE the tree went)
- from config.yaml: allow/deny-list entries, ``plugins.entries.<id>`` grants and a ``memory.provider``
- selection naming it. A later reinstall under the same name must start from the "Enable now?"
- decision, not inherit a stale enable or grant (#54336); a dangling ``memory.provider`` would make
- the next agent init re-clone the plugin from the catalog, silently undoing the uninstall.
- Returns ``{"cleared_memory_provider": True}`` when the selection was reset."""
- from hermes_cli.config import load_config, save_config
- config = load_config()
- changed = False
- result: dict[str, Any] = {}
- plugins_cfg = config.get("plugins")
- if isinstance(plugins_cfg, dict):
- for list_key in ("enabled", "disabled"):
- names = plugins_cfg.get(list_key)
- if isinstance(names, list) and aliases & set(names):
- plugins_cfg[list_key] = sorted(set(names) - aliases)
- changed = True
- entries = plugins_cfg.get("entries")
- if isinstance(entries, dict) and aliases & set(entries):
- for alias in aliases & set(entries):
- del entries[alias]
- changed = True
- memory_cfg = config.get("memory")
- if isinstance(memory_cfg, dict) and str(memory_cfg.get("provider") or "").strip() in aliases:
- memory_cfg["provider"] = ""
- changed, result = True, {"cleared_memory_provider": True}
- if changed:
- save_config(config)
- return result
- # One lock per Hermes home. The Desktop install card enables several plugins at once, each on its own
- # thread; without it every thread read the same config version and all but the first commit were
- # refused as stale. The version check in PM stays: it still catches an edit from another process.
- _SELECTION_LOCKS: dict[str, threading.Lock] = {}
- _SELECTION_LOCKS_GUARD = threading.Lock()
- def _selection_lock() -> threading.Lock:
- with _SELECTION_LOCKS_GUARD:
- return _SELECTION_LOCKS.setdefault(hermes_home_key(), threading.Lock())
- def _set_plugin_enabled(name: str, *, enable: bool, aliases=(), console=None) -> None:
- """Submit the command's delta with the version of the selection it read."""
- from pm.plugins_state import read_home_selection
- with _selection_lock():
- expected_config = _plugin_selection_version()
- config = read_home_selection(get_hermes_home()) or {}
- plugins = config.get("plugins") or {}
- enabled = set(plugins.get("enabled") or ())
- disabled = set(plugins.get("disabled") or ())
- _apply_activation(enabled, disabled, name, aliases, enable=enable)
- _admit_and_save_plugin_sets(enabled, disabled, console=console,
- action=f"{'Enable' if enable else 'Disable'} '{name}'",
- expected_config=expected_config, plugin=name if enable else None,
- settled=(name, *aliases))
- def _apply_activation(enabled: set, disabled: set, key: str, aliases, *, enable: bool) -> None:
- """Add canonical *key* to the target list and purge it, its bare leaf and *aliases* from the other."""
- removed = disabled if enable else enabled
- _discard_key_and_leaf(removed, key)
- removed.difference_update(aliases)
- (enabled if enable else disabled).add(key)
- def _resolve_plugin_key(name: str) -> Optional[str]:
- """Canonical registry key for a manifest name / directory name / path key, or ``None``.
- The single normalization point so enable/disable write the key ``PluginManager`` gates on."""
- resolved = _resolve_plugin_key_and_source(name)
- return resolved[0] if resolved else None
- def _catalog_installed_dir(name: str) -> Optional[Path]:
- """Install dir whose installer-owned record names catalog entry *name* (``hermes-memory-wiki`` is
- installed as ``plugins/memory-wiki``), else None (also when two dirs claim it). Read through
- :func:`catalog_install_record` (``.install-metadata.json``), never the tree, so a URL-installed
- repo cannot claim a catalog entry's name."""
- from hermes_cli.plugins_cmd_catalog import catalog_install_record
- try:
- keys = list(_read_install_metadata())
- except PluginOperationError:
- return None
- hits = [target for key in keys if (target := _plugins_dir() / key).is_dir()
- and (record := catalog_install_record(target)) and record["catalog_name"] == name]
- return hits[0] if len(hits) == 1 else None
- def _find_plugin_entry(name: str) -> Optional[tuple]:
- """THE plugin name resolver for every verb (enable/disable/show/capabilities/remove/update, the
- dashboard and the Desktop hub): the discovered ``(name, version, description, source, dir_path, key)``
- entry for a canonical key or manifest name; else a bare leaf (``exa`` ->
- ``web/exa``) only when unique; else the catalog name the plugin was installed under.
- Never guesses between two candidates."""
- entries = _discover_all_plugins()
- from hermes_cli.left_core_migration import legacy_plugin_alias
- target = legacy_plugin_alias(name) or name # ``observability/langfuse`` -> its catalog plugin
- exact = next((entry for entry in entries if target in (entry[0], entry[5])), None)
- if exact is not None:
- return exact
- leaf_matches = [entry for entry in entries if name == entry[5].split("/")[-1]]
- if leaf_matches:
- return leaf_matches[0] if len(leaf_matches) == 1 else None
- target = _catalog_installed_dir(name)
- return next((entry for entry in entries if target is not None and entry[4] and Path(str(entry[4])) == target),
- None)
- def _resolve_plugin_key_and_source(name: str) -> Optional[tuple]:
- """Resolve *name* to ``(canonical_key, source)`` or ``None`` through :func:`_find_plugin_entry`."""
- entry = _find_plugin_entry(name)
- return (entry[5], entry[3]) if entry else None
- def cmd_enable(name: str, allow_tool_override: Optional[bool] = None) -> None:
- """Add a plugin to the enabled allow-list (and remove it from disabled).
- Non-bundled plugins request consent for declared capabilities. The legacy
- ``allow_tool_override`` grant changes only with an explicit True/False flag;
- None leaves it unchanged. Bundled plugins are trusted.
- """
- from hermes_cli.relay_plugin_cutover import LEGACY_RELAY_PLUGIN_KEYS, RELAY_PLUGINS_CONFIG_ENV
- console = _console()
- def _refuse_legacy_relay(plugin: str) -> None:
- if plugin in LEGACY_RELAY_PLUGIN_KEYS:
- _fail(console, (
- f"[red]Plugin '{plugin}' was removed.[/red] Relay lifecycle is owned "
- "by Hermes core; configure a standard user or system Relay plugins.toml, or use "
- f"{RELAY_PLUGINS_CONFIG_ENV} for an explicit user-file override."))
- _refuse_legacy_relay(name)
- resolved = _resolve_plugin_key_and_source(name)
- if resolved is None:
- _fail(console, _unknown_plugin_message(name))
- key, source = resolved
- _refuse_legacy_relay(key)
- if source != "bundled":
- # Activating recalled code is the same act as installing it (`plugins/AGENTS.md`: kill list).
- from hermes_cli import plugins_cmd_catalog as catalog
- try:
- catalog.refuse_if_installed_removed(key, _user_installed_plugin_dir(key.rsplit("/", 1)[-1]))
- except PluginOperationError as exc:
- _fail(console, f"[red]Error:[/red] {exc}")
- changed = _activate_key(key, enable=True, console=console)
- if changed:
- from hermes_cli.plugins_activation import report_activation
- console.print(f"[green]✓[/green] Plugin [bold]{key}[/bold] enabled.") # the hint says when it applies
- report_activation(console, key)
- else:
- console.print(f"[dim]Plugin '{key}' is already enabled.[/dim]")
- if source != "bundled":
- _enable_consent(console, key, allow_tool_override)
- if changed: # after consent: register() sees the grants; same saved-list edit as the Desktop toggle
- _toggle_plugin_toolset(key, enable=True)
- def _enable_consent(console, key: str, allow_tool_override: Optional[bool]) -> None:
- """Capability consent and the legacy tool-override grant for a non-bundled plugin's enable."""
- # When the manifest declares capabilities the consent screen is the canonical grant path
- # (it covers tools.override too); the legacy prompt then only runs on an explicit flag.
- # See #64228.
- declared_caps = _declared_capabilities_for_key(key)
- if declared_caps:
- _run_capability_consent(console, key, declared_caps, context="enable")
- # Enabling a plugin is not a request for undeclared privileges. Keep existing
- # grants unchanged unless the operator explicitly grants or revokes one.
- if allow_tool_override is not None:
- _resolve_tool_override_grant(console, key, allow_tool_override)
- def cmd_disable(name: str) -> None:
- """Remove a plugin from the enabled allow-list (and add to disabled)."""
- console = _console()
- key = _resolve_plugin_key(name)
- if key is None:
- _fail(console, _unknown_plugin_message(name))
- toolset_key = _saved_list_toolset_key(key) # resolve while the plugin still loads
- if not _activate_key(key, enable=False, console=console):
- console.print(f"[dim]Plugin '{key}' is already disabled.[/dim]")
- return
- _toggle_plugin_toolset(key, enable=False, toolset_key=toolset_key)
- from hermes_cli.plugins_activation import gateway_reload_hint, reload_running_gateway
- console.print(f"[yellow]⊘[/yellow] Plugin [bold]{key}[/bold] disabled.")
- console.print(f"[dim]{gateway_reload_hint(reload_running_gateway(), key)}[/dim]")
- def _read_manifest_info(d: Path, prefix: str):
- """Read a native or portable manifest and return display metadata."""
- manifest_file = _native_manifest_file(d)
- if manifest_file is None:
- if not _has_portable_manifest(d):
- return None
- try:
- from hermes_cli.agent_plugins import read_agent_plugin_manifest
- manifest = read_agent_plugin_manifest(d)[0]
- name = manifest["name"]
- except Exception:
- return None
- else:
- # Unreadable YAML (or no yaml module) degrades to the directory name, silently.
- try:
- manifest = _load_yaml_manifest(manifest_file)
- except Exception:
- manifest = {}
- if not isinstance(manifest, dict):
- manifest = {}
- name = manifest.get("name", d.name)
- key = f"{prefix}/{d.name}" if prefix else name
- return name, manifest.get("version", ""), manifest.get("description", ""), key
- def _is_portable_plugin_dir(dir_path) -> bool:
- """True for an Agent Plugins v1 package (``plugin.json`` only; native ``plugin.yaml`` wins)."""
- try:
- d = Path(dir_path)
- return d.is_dir() and _native_manifest_file(d) is None and _has_portable_manifest(d)
- except OSError:
- return False
- # Manifest kinds active-by-default when bundled (backends auto-load, platforms register lazily,
- # model providers go through providers/ discovery). Standalone/exclusive kinds stay opt-in.
- _BUNDLED_DEFAULT_ON_KINDS = frozenset({"backend", "platform", "model-provider"})
- def _default_on(dir_path, source: str) -> bool:
- """True when a plugin is active without a ``plugins.enabled`` entry (portable ``plugin.json``
- packages have no kind, so never). Bundled default-on kinds always; a user model provider only
- where providers/ discovery loads it (``providers._scan_home_layer``): a
- ``plugins/model-providers/<name>/`` child whose kind is model-provider, or a flat
- ``plugins/<name>/`` child declaring exactly ``kind: model-provider``. Discovery imports any other
- ``model-providers/`` child too, but nothing calls its ``register(ctx)``, so it is not on.
- Entry-point rows store ``module:attr`` in the path slot. That string is not a directory;
- opening it as one is WinError 123 on Windows and aborts the whole plugin list.
- """
- path = Path(dir_path)
- if not path.is_dir():
- return False
- if source != "bundled":
- from providers import _declares_model_provider_kind
- root = _plugins_dir()
- if path.name.startswith(("_", ".")) or path.parent not in (root, root / "model-providers"):
- return False
- if path.parent == root:
- return _declares_model_provider_kind(path)
- manifest_file = _native_manifest_file(path)
- if manifest_file is None:
- return False
- try:
- kind = str(_load_yaml_manifest(manifest_file).get("kind", "standalone")).strip().lower()
- except Exception:
- return False
- return kind == "model-provider" or (source == "bundled" and kind in _BUNDLED_DEFAULT_ON_KINDS)
- def _scan_level(base: Path, source: str, skip_names: set, prefix: str, depth: int, seen: dict) -> None:
- """Recursive directory scan matching PluginManager._scan_directory_level."""
- if not base.is_dir():
- return
- try:
- children = sorted(base.iterdir())
- except OSError as exc:
- logger.warning("Skipping unreadable plugin directory %s: %s", base, exc)
- return
- for d in children:
- try:
- if not d.is_dir() or (depth == 0 and skip_names and d.name in skip_names):
- continue
- info = _read_manifest_info(d, prefix)
- except (OSError, PluginOperationError) as exc:
- # The PM declaration reader wraps unreadable manifests for install callers;
- # listing still skips them rather than hiding every other plugin.
- logger.warning("Skipping unreadable plugin directory %s: %s", d, exc)
- continue
- if info is None:
- if depth == 0:
- _scan_level(d, source, set(), f"{prefix}/{d.name}" if prefix else d.name, 1, seen)
- continue
- name, version, description, key = info
- if key in seen and source == "bundled":
- continue
- src_label = "git" if source == "user" and (d / ".git").exists() else source
- seen[key] = (name, version, description, src_label, d, key)
- def _discover_all_plugins() -> list:
- """``(name, version, description, source, dir_path, key)`` for every plugin the loader sees,
- in ``PluginManager.discover_and_load`` order: bundled, user, then entry points — which never
- displace a directory plugin of the same key (see ``PluginManager._discover_and_load_inner``)."""
- seen: dict = {}
- # memory/, context_engine/, computer_use/, model-providers/ and config_backends/ load through dedicated
- # paths, not the PluginManager opt-in surface, so listing them as toggleable plugins would mislead.
- from hermes_cli.plugins import discover_entrypoint_manifests, get_bundled_plugins_dir
- for base, source, skip in (
- (get_bundled_plugins_dir(), "bundled", {"memory", "context_engine", "computer_use", "model-providers", "config_backends"}),
- (_plugins_dir(), "user", set()),
- ):
- _scan_level(base, source, skip, "", 0, seen)
- # Entry-point plugins are installed as Python packages, so they have no plugin directory.
- for m in discover_entrypoint_manifests():
- seen.setdefault(m.name, (m.name, m.version, m.description, "entrypoint", m.path, m.name))
- return list(seen.values())
- def _category_active_names() -> set:
- """Provider names switched on through ``<category>.provider`` config rather than
- ``plugins.enabled`` (the live memory provider), so status never calls them "not enabled"."""
- return {n for n in (_get_current_memory_provider(),) if n}
- def _plugin_status(name: str, enabled: set, disabled: set, key: str = "", *, source: str = "",
- dir_path=None, active: frozenset | set = frozenset()) -> str:
- """User-facing activation state for a plugin name or key. Mirrors ``gate_manifest``: an explicit
- disable wins, then the allow-list, then the activations that need no list entry — bundled
- backends/platforms and model providers from any source (*source* + *dir_path*) and category-selected providers
- (*active*, see :func:`_category_active_names`)."""
- names = {name, key}
- if names & disabled:
- return "disabled"
- if names & enabled or names & active:
- return "enabled"
- if dir_path is not None and _default_on(dir_path, source):
- return "enabled"
- return "not enabled"
- # ── Provider category config accessors ──────────────────────────────────────────────────────
- # memory.provider ("" = built-in) and context.engine config accessors.
- _get_current_memory_provider = functools.partial(_config_str, "memory", "provider", default="")
- _get_current_context_engine = functools.partial(_config_str, "context", "engine", default="compressor")
- _save_memory_provider = functools.partial(_write_config_value, "memory", "provider")
- _save_context_engine = functools.partial(_write_config_value, "context", "engine")
- def _get_plugin_toolset_key(name: str) -> Optional[str]:
- """Toolset key a plugin registers its tools under, or None: from the live registry (plugin
- already loaded), else from ``provides_tools`` in plugin.yaml looked up in the registry."""
- try:
- from tools.registry import registry
- except Exception:
- return None
- def _first_toolset(tool_names) -> Optional[str]:
- return next((e.toolset for t in tool_names if (e := registry.get_entry(t)) and e.toolset), None)
- def _from_loaded_plugin() -> Optional[str]:
- from hermes_cli.plugins import discover_plugins, get_plugin_manager
- discover_plugins() # idempotent — ensures plugins are loaded
- for _key, loaded in get_plugin_manager()._plugins.items():
- if loaded.manifest.name == name or _key == name:
- return _first_toolset(loaded.tools_registered)
- return None
- def _from_manifest_on_disk() -> Optional[str]:
- from hermes_cli.plugins import get_bundled_plugins_dir
- return next((
- toolset for base in (get_bundled_plugins_dir(), _plugins_dir())
- if base.is_dir() and (base / name).is_dir()
- and (toolset := _first_toolset(_read_manifest(base / name).get("provides_tools") or []))
- ), None)
- for lookup in (_from_loaded_plugin, _from_manifest_on_disk):
- try:
- if toolset := lookup():
- return toolset
- except Exception:
- continue
- return None
- def _saved_list_toolset_key(name: str) -> Optional[str]:
- """The plugin's toolset key, or None without loading any plugin when no platform has a SAVED
- ``platform_toolsets`` list (the only lists :func:`_toggle_plugin_toolset` edits)."""
- from hermes_cli.config import load_config
- from hermes_cli.toolset_validation import parse_platform_toolsets_value
- saved = load_config().get("platform_toolsets")
- if not isinstance(saved, dict) or all(parse_platform_toolsets_value(v) is None for v in saved.values()):
- return None
- return _get_plugin_toolset_key(name)
- def _toggle_plugin_toolset(name: str, *, enable: bool, toolset_key: Optional[str] = None) -> None:
- """Add/remove a plugin's toolset in every SAVED ``platform_toolsets`` list (no-op when the plugin
- provides no tools). Platforms with no saved list are left alone: a plugin toolset is already on
- there by default, and seeding ``[<plugin_ts>]`` would replace the core composite and strip every
- built-in tool. The key resolves only while the plugin is loaded, so enable calls this after the
- plugin loads and disable resolves *toolset_key* before the disable is written."""
- toolset_key = toolset_key or _saved_list_toolset_key(name)
- if not toolset_key:
- return
- from hermes_cli.config import load_config, save_config
- from hermes_cli.toolset_validation import parse_platform_toolsets_value
- config = load_config()
- platform_toolsets = _child_dict(config, "platform_toolsets")
- changed = False
- for platform, raw in list(platform_toolsets.items()):
- # A list-literal string (older `hermes config set`) is the user's real selection; toggling
- # it re-saves the entry as a proper list so the string never persists.
- ts_list = parse_platform_toolsets_value(raw)
- if ts_list is not None and enable != (toolset_key in ts_list):
- (ts_list.append if enable else ts_list.remove)(toolset_key)
- platform_toolsets[platform] = ts_list
- changed = True
- if changed:
- save_config(config)
- def dashboard_set_agent_plugin_enabled(name: str, *, enabled: bool) -> dict[str, Any]:
- """Enable or disable a plugin in ``config.yaml`` (runtime allow/deny lists). *name* may be the
- canonical key, the manifest name or a unique bare leaf; the canonical key is what gets written
- (the loader never matches a bare leaf, and a stale key in ``disabled`` outranks a manifest-name
- entry in ``enabled`` — so writing the raw identifier reported success while the plugin stayed off)."""
- key = _resolve_plugin_key(name)
- if key is None:
- return {"ok": False, "error": f"Plugin '{name}' is not installed or bundled."}
- from hermes_cli.plugins_admission import AdmissionRefused
- toolset_key = None if enabled else _saved_list_toolset_key(key)
- try:
- changed = _activate_key(key, enable=enabled)
- except AdmissionRefused as exc:
- return {
- "ok": False,
- "error": str(exc),
- "name": key,
- "unchanged": True,
- "restart_required": False,
- }
- if changed and enabled:
- # Load it now, here and in the running gateway; ``activation`` tells the UI what is live vs
- # deferred, and ``restart_required`` only survives when no gateway answered (#87770).
- from hermes_cli.plugins_activation import activate_plugin_now
- result = {"ok": True, "name": key, "unchanged": False, **activate_plugin_now(key)}
- # Only now is the plugin loaded here, so its toolset key resolves: a backend that scanned
- # while the plugin was off held a placeholder and the toolset was never re-added.
- _toggle_plugin_toolset(key, enable=True)
- return result
- if changed:
- _toggle_plugin_toolset(key, enable=False, toolset_key=toolset_key)
- # Disable is config-only: there is no un-wire primitive, so a running gateway keeps the plugin's
- # handlers until restart and every UI says so — #71595/#54941.
- return {"ok": True, "name": key, "unchanged": not changed, "restart_required": changed}
- def _user_installed_plugin_dir(name: str) -> Optional[Path]:
- """Resolved path under ``~/.hermes/plugins/<name>`` if it exists, else the user install
- :func:`_find_plugin_entry` resolves *name* to (its manifest or catalog name)."""
- try:
- target = _sanitize_plugin_name(name, _plugins_dir(), allow_subdir=True)
- except ValueError:
- return None
- return target if target.is_dir() else _resolved_user_plugin_dir(name)
- def _resolved_user_plugin_dir(name: str) -> Optional[Path]:
- """Dir of the user install :func:`_find_plugin_entry` resolves *name* to (manifest or catalog name)."""
- entry = _find_plugin_entry(name)
- found = Path(str(entry[4])) if entry and entry[3] in ("user", "git") and entry[4] else None
- return found if found is not None and found.is_dir() else None
- def cmd_plugin_doctor(target: str = ".", *, ci: bool = False) -> None:
- """Validate one plugin through runtime discovery and registration."""
- from hermes_cli.plugin_dev import doctor_plugin
- report = doctor_plugin(target)
- _console().print(report.format_text())
- if ci and not report.ok:
- raise SystemExit(1)
- def _tri_state_flag(args, yes_attr: str, no_attr: str) -> Optional[bool]:
- """Map an argparse ``--x`` / ``--no-x`` pair to True / False / None (neither given)."""
- return True if getattr(args, yes_attr, False) else (False if getattr(args, no_attr, False) else None)
- def _catalog():
- from hermes_cli import plugins_cmd_catalog
- return plugins_cmd_catalog
- def _action_update(args):
- if args.name:
- if getattr(args, "yes", False):
- _fail(_console(), "[red]Error:[/red] --yes only applies to `hermes plugins update` with no name.")
- cmd_update(args.name, force=getattr(args, "force", False))
- return
- if getattr(args, "force", False):
- _fail(_console(), "[red]Error:[/red] --force applies to one named plugin: `hermes plugins update <name> --force`.")
- from hermes_cli.plugins_cmd_update_all import cmd_update_all
- cmd_update_all(yes=getattr(args, "yes", False))
- def _action_auto_update(args):
- from hermes_cli.plugins_auto_update import auto_update_state, set_auto_update
- console = _console()
- state = getattr(args, "state", None)
- try:
- current = auto_update_state() if state is None else set_auto_update(state == "on")
- except PluginOperationError as exc:
- _fail(console, f"[red]Error:[/red] {exc}")
- word = "[green]on[/green]" if current["auto_apply"] else "[dim]off[/dim]"
- cadence = (f"checked every {current['check_hours']:g}h by the gateway" if current["check_hours"] > 0
- else "the gateway's check is off: plugins.auto_update_check_hours is 0")
- console.print(f"Plugin auto-update: {word} ({cadence}; updates load in new sessions)")
- def _action_pack(args):
- from hermes_cli.plugin_packs import pack_command
- pack_command(args)
- # Tri-state flags: neither --x nor --no-x given == None == interactive prompt.
- _PLUGIN_ACTIONS = {
- "install": lambda args: cmd_install(
- args.identifier,
- force=getattr(args, "force", False),
- enable=_tri_state_flag(args, "enable", "no_enable"),
- ref=getattr(args, "ref", None),
- allow_removed=getattr(args, "allow_removed", False),
- no_deps=getattr(args, "no_deps", False),
- yes_deps=getattr(args, "yes_deps", False)),
- "search": lambda args: _catalog().cmd_search(
- getattr(args, "term", "") or "", json_output=getattr(args, "json", False)),
- "browse": lambda args: _catalog().cmd_search(""),
- "validate": lambda args: _catalog().cmd_validate(
- args.path, as_json=getattr(args, "json", False), install_deps=getattr(args, "install_deps", False)),
- "update": _action_update,
- "auto-update": _action_auto_update,
- "autoupdate": _action_auto_update,
- "adopt": lambda args: cmd_adopt(args.name),
- "trust-update-url": lambda args: cmd_trust_update_url(args.name),
- "check-updates": lambda args: cmd_check_updates(args),
- "check": lambda args: cmd_check_updates(args),
- "remove": lambda args: cmd_remove(args.name),
- "rm": lambda args: cmd_remove(args.name),
- "uninstall": lambda args: cmd_remove(args.name),
- "enable": lambda args: cmd_enable(
- args.name,
- allow_tool_override=_tri_state_flag(args, "allow_tool_override", "no_allow_tool_override")),
- "disable": lambda args: cmd_disable(args.name),
- "capabilities": lambda args: cmd_capabilities(getattr(args, "name", None)),
- "list": lambda args: cmd_list(args),
- "ls": lambda args: cmd_list(args),
- "doctor": lambda args: cmd_plugin_doctor(args.target, ci=getattr(args, "ci", False)),
- "pack": _action_pack,
- "show": lambda args: cmd_show(args.name),
- "info": lambda args: _catalog().cmd_info(args.name),
- None: lambda args: cmd_toggle(),
- }
- def plugins_command(args) -> None:
- """Dispatch hermes plugins subcommands."""
- action = getattr(args, "plugins_action", None)
- handler = _PLUGIN_ACTIONS.get(action)
- if handler is None:
- _fail(_console(), f"[red]Unknown plugins action: {action}[/red]")
- handler(args)
|