41b4555ed9
- hermes_cli/plugins_cmd_catalog.py: new sibling owning resolution, the
.hermes-catalog.json provenance sidecar, search/info/validate, re-pin on
update, and the dashboard/TUI payload builders. plugins_cmd.py only
gains the hooks (cmd_install catalog branch, cmd_update / dashboard
update re-pin, dashboard_install_plugin catalog_name + kill list,
dispatch entries); the community index (plugin_index.py) is gone.
- hermes_cli/plugin_catalog.py: catalog_dir parameter replaces the
test-only HERMES_PLUGIN_CATALOG_DIR env var; live refresh reads ONE
published document (/docs/api/plugin-catalog.json, 6h cache, in-tree
fallback) instead of the unauthenticated GitHub contents API (60 req/h,
1 request per entry); in-tree and live removals are unioned so a stale
cache can never un-block.
- Catalog route lives in web_routers/dashboard_ui.py (the facade is off
limits); _plugin_runtime_status shared from web_server_dashboard.py;
hub rows carry removed_reason. TUI plugins.manage gains catalog_name
install, catalog row fields and an update action.
- plugin_validate: the probe context honours ctx.get_config defaults
(real plugins do int(ctx.get_config("timeout", 180)) in register()).
- Installed-state merge matches through the sidecar's catalog_name
first — catalog names rarely equal manifest names.
- extract-plugins.py emits plugin-catalog.json; deploy-site triggers on
plugin-catalog/** so entry merges republish it.
149 lines
7.9 KiB
Python
149 lines
7.9 KiB
Python
"""``hermes plugins`` subcommand parser."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Callable
|
|
|
|
from hermes_cli.subcommands._shared import add_json_flag
|
|
|
|
|
|
def build_plugins_parser(subparsers, *, cmd_plugins: Callable) -> None:
|
|
"""Attach the ``plugins`` subcommand to ``subparsers``."""
|
|
plugins_parser = subparsers.add_parser(
|
|
"plugins", help="Manage and validate plugins",
|
|
description="Install, update, remove, list, or validate native Hermes plugins "
|
|
"and portable Agent Plugins v1 packages. Portable packages install disabled.")
|
|
plugins_subparsers = plugins_parser.add_subparsers(dest="plugins_action")
|
|
|
|
plugins_install = plugins_subparsers.add_parser(
|
|
"install", help="Install a plugin from the curated catalog, a Git URL, or owner/repo")
|
|
plugins_install.add_argument(
|
|
"identifier",
|
|
help="Bare plugin catalog entry name (see `hermes plugins search`), Git URL, or owner/repo "
|
|
"shorthand (e.g. anpicasso/hermes-plugin-chrome-profiles)")
|
|
plugins_install.add_argument(
|
|
"--force", "-f", action="store_true", help="Remove existing plugin and reinstall")
|
|
plugins_install.add_argument(
|
|
"--ref", metavar="COMMIT_SHA",
|
|
help="Install exactly one immutable 40-character Git commit SHA")
|
|
plugins_install.add_argument(
|
|
"--allow-removed", action="store_true",
|
|
help="DANGEROUS: bypass the catalog removed-plugin blocklist check")
|
|
_install_enable_group = plugins_install.add_mutually_exclusive_group()
|
|
_install_enable_group.add_argument(
|
|
"--enable", action="store_true",
|
|
help="Auto-enable the plugin after install (skip confirmation prompt)")
|
|
_install_enable_group.add_argument(
|
|
"--no-enable", action="store_true",
|
|
help="Install disabled (skip confirmation prompt); enable later with `hermes plugins enable <name>`",
|
|
)
|
|
|
|
plugins_search = plugins_subparsers.add_parser(
|
|
"search", help="Search the curated Hermes plugin catalog")
|
|
plugins_search.add_argument(
|
|
"term", nargs="?", default="",
|
|
help="Query matched against entry names, descriptions and declared tools (omit to list the whole catalog)")
|
|
add_json_flag(plugins_search, "Print machine-readable JSON")
|
|
|
|
plugins_subparsers.add_parser("browse", help="List every curated plugin catalog entry")
|
|
|
|
plugins_validate = plugins_subparsers.add_parser(
|
|
"validate", help="Validate a plugin directory for catalog admission (CI gate)")
|
|
plugins_validate.add_argument("path", help="Path to the plugin directory")
|
|
add_json_flag(plugins_validate, "Print machine-readable JSON (for CI)")
|
|
|
|
plugins_update = plugins_subparsers.add_parser(
|
|
"update", help="Pull latest changes for an installed plugin")
|
|
plugins_update.add_argument("name", help="Plugin name to update")
|
|
|
|
plugins_remove = plugins_subparsers.add_parser(
|
|
"remove", aliases=["rm", "uninstall"], help="Remove an installed plugin")
|
|
plugins_remove.add_argument("name", help="Plugin directory name to remove")
|
|
|
|
plugins_list = plugins_subparsers.add_parser(
|
|
"list", aliases=["ls"], help="List installed plugins")
|
|
plugins_list.add_argument("--enabled", action="store_true", help="Show only enabled plugins")
|
|
plugins_list.add_argument(
|
|
"--user", action="store_true",
|
|
help="Show only user-installed plugins (including git plugins)")
|
|
plugins_list.add_argument("--no-bundled", action="store_true", help="Hide bundled plugins")
|
|
plugins_list.add_argument(
|
|
"--plain", action="store_true",
|
|
help="Print compact plain-text output instead of a Rich table")
|
|
add_json_flag(plugins_list, "Print machine-readable JSON")
|
|
|
|
plugins_enable = plugins_subparsers.add_parser("enable", help="Enable a disabled plugin")
|
|
plugins_enable.add_argument("name", help="Plugin name to enable")
|
|
_enable_override_group = plugins_enable.add_mutually_exclusive_group()
|
|
_enable_override_group.add_argument(
|
|
"--allow-tool-override", action="store_true",
|
|
help="Grant this plugin permission to replace built-in tools "
|
|
"(e.g. shell_exec, write_file). Skips the confirmation prompt.")
|
|
_enable_override_group.add_argument(
|
|
"--no-allow-tool-override", action="store_true",
|
|
help="Enable without granting built-in tool override (skip prompt).")
|
|
|
|
plugins_disable = plugins_subparsers.add_parser(
|
|
"disable", help="Disable a plugin without removing it")
|
|
plugins_disable.add_argument("name", help="Plugin name to disable")
|
|
|
|
plugins_capabilities = plugins_subparsers.add_parser(
|
|
"capabilities", help="Show declared vs granted capabilities per plugin",
|
|
description="Show each plugin's declared capabilities (from plugin.yaml) "
|
|
"against what the user has granted. Capabilities are a consent "
|
|
"and audit layer over host API surfaces — NOT a sandbox.")
|
|
plugins_capabilities.add_argument(
|
|
"name", nargs="?", default=None,
|
|
help="Plugin id to inspect (omit to list all plugins with capabilities)")
|
|
|
|
plugins_doctor = plugins_subparsers.add_parser(
|
|
"doctor", help="Validate a plugin with the real runtime contracts")
|
|
plugins_doctor.add_argument(
|
|
"target", nargs="?", default=".",
|
|
help="Plugin path or installed plugin id (default: current directory)")
|
|
plugins_doctor.add_argument(
|
|
"--ci", action="store_true", help="Exit non-zero when validation reports an error")
|
|
|
|
plugins_compat = plugins_subparsers.add_parser(
|
|
"compat",
|
|
help="Show installed plugins that import paths removed by the Sep 2026 decomposition",
|
|
description="Statically scans every enabled external plugin for imports of pre-decomposition "
|
|
"module paths (see COMPAT_MANIFEST.md) and prints file:line, old path -> new path. "
|
|
"Exits 1 when any plugin is affected. Plugins still affected on the removal date are "
|
|
"not loaded (override: plugins.allow_deprecated_imports: true).")
|
|
plugins_compat.add_argument("--json", action="store_true", help="Machine-readable output")
|
|
plugins_compat.add_argument(
|
|
"path", nargs="?", help="Scan one plugin directory instead of the installed set (for plugin authors)")
|
|
|
|
plugins_pack = plugins_subparsers.add_parser(
|
|
"pack", help="Declarative, shareable plugin sets (hermes-pack.yaml)",
|
|
description="Install, export, or inspect plugin packs — a single YAML file "
|
|
"pinning a set of plugins to exact commit SHAs, with optional "
|
|
"non-secret config seeds. Installing a pack fans out to ordinary "
|
|
"pinned installs; capability consent stays per-plugin.")
|
|
pack_subparsers = plugins_pack.add_subparsers(dest="pack_action")
|
|
|
|
pack_install = pack_subparsers.add_parser(
|
|
"install", help="Review and install a pack from a file path or https URL")
|
|
pack_install.add_argument("source", help="Path to a hermes-pack.yaml file, or an https:// URL")
|
|
pack_install.add_argument(
|
|
"--force", "-f", action="store_true", help="Reinstall plugins that already exist")
|
|
|
|
pack_export = pack_subparsers.add_parser(
|
|
"export", help="Emit a pack YAML for the current install on stdout")
|
|
pack_export.add_argument(
|
|
"--enabled-only", action="store_true",
|
|
help="Only include plugins currently in plugins.enabled")
|
|
pack_export.add_argument(
|
|
"--name", default="my-hermes-pack", help="Pack name to embed in the exported YAML")
|
|
|
|
pack_show = pack_subparsers.add_parser(
|
|
"show", help="Dry-run: parse and display a pack without installing")
|
|
pack_show.add_argument("source", help="Path to a hermes-pack.yaml file, or an https:// URL")
|
|
|
|
plugins_show = plugins_subparsers.add_parser(
|
|
"show", aliases=["info"], help="Show details for a single plugin (including emits/listens)")
|
|
plugins_show.add_argument("name", help="Plugin name or key to show")
|
|
|
|
plugins_parser.set_defaults(func=cmd_plugins)
|