Teknium
0a5164cebe
hermes_cli/plugin_compat.py is now the single source of truth for the compat window:
COMPAT_REMOVAL_DATE = 2026-09-14; scan_plugin() statically finds `from F import n`, `import F` + `F.n`,
alias forms and string targets against compat_manifest.json; compat_report() aggregates over the user's
ENABLED external (non-bundled) plugins; disable_reason() decides the loader's skip.
Surfaces (all read from that one report):
* CLI: yellow block under the banner naming plugins + date + `hermes plugins compat` (red + DISABLED after)
* `hermes plugins compat [--json] [path]`: file:line, old -> new per hit; exit 1 while anything remains;
`path` lets a plugin author scan their own checkout
* `hermes doctor`: "Plugin import paths (removed Sep 14, 2026)" section next to the xAI retirement check
* `hermes update`: post-update notice alongside the FTS/curator notices
* Desktop: compat_report() writes HERMES_HOME/.plugin-compat-report.json (deleted when clean); Electron
shows ONE warning dialog per distinct report after the backend is up and persists the dismissal in
userData/plugin-compat-dismissed.json. A new affected plugin, or the date passing, is a new report.
From the date, PluginManager skips a hitting external plugin before importing it, with the reason in
LoadedPlugin.error ("uses N import path(s) removed on 2026-09-14; run `hermes plugins compat` ...") — the
same path a plugin with a broken register() takes, so nothing else is affected. Escape hatch:
plugins.allow_deprecated_imports: true (config_defaults), which only helps until the compat commit is
actually reverted.
Docs: COMPAT_MANIFEST.md (removal date, what-happens table, author instructions), plugin dev guide section.
Tests: tests/test_plugin_compat_notice.py (scanner forms, report scope, date gate + escape hatch, summary
text, report file lifecycle, loader skip via a real PluginManager), electron/plugin-compat-notice.test.ts
(show once, re-show on a different set or on the date passing, malformed file ignored).
Live A/B on this box with a demo plugin on old paths: before the date it loads and the banner/doctor/report
name it; with today=2026-09-14 it is skipped with the reason and the banner turns red; with the escape
hatch it loads again.
146 lines
7.6 KiB
Python
146 lines
7.6 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 a Git URL, owner/repo, or index name")
|
|
plugins_install.add_argument(
|
|
"identifier",
|
|
help="Git URL, owner/repo shorthand (e.g. anpicasso/hermes-plugin-chrome-profiles), "
|
|
"or a bare plugin name resolved through the community index "
|
|
"(see `hermes plugins search`)")
|
|
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")
|
|
_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 community plugin index")
|
|
plugins_search.add_argument(
|
|
"term", nargs="?", default="",
|
|
help="Search term matched fuzzily against name, description, and tags "
|
|
"(omit to browse the full index)")
|
|
add_json_flag(plugins_search, "Print machine-readable JSON")
|
|
plugins_search.add_argument(
|
|
"--capability", metavar="CAP",
|
|
help="Filter by declared capability (e.g. tools, platform, commands)")
|
|
plugins_search.add_argument(
|
|
"--refresh", action="store_true", help="Bypass the local cache and re-fetch the index")
|
|
|
|
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)
|