plugins.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. """``hermes plugins`` subcommand parser."""
  2. from __future__ import annotations
  3. from typing import Callable
  4. from hermes_cli.subcommands._shared import add_json_flag
  5. def build_plugins_parser(subparsers, *, cmd_plugins: Callable) -> None:
  6. """Attach the ``plugins`` subcommand to ``subparsers``."""
  7. plugins_parser = subparsers.add_parser(
  8. "plugins", help="Manage and validate plugins",
  9. description="Install, update, remove, list, or validate native Hermes plugins "
  10. "and portable Agent Plugins v1 packages. Portable packages install disabled.")
  11. plugins_subparsers = plugins_parser.add_subparsers(dest="plugins_action")
  12. plugins_install = plugins_subparsers.add_parser(
  13. "install", help="Install a plugin from the curated catalog, a Git URL, or owner/repo")
  14. plugins_install.add_argument(
  15. "identifier",
  16. help="Bare plugin catalog entry name (see `hermes plugins search`), Git URL, or owner/repo "
  17. "shorthand (e.g. anpicasso/hermes-plugin-chrome-profiles)")
  18. plugins_install.add_argument(
  19. "--force", "-f", action="store_true",
  20. help="Reinstall over an existing plugin (from the same source, your untracked files are kept)")
  21. plugins_install.add_argument(
  22. "--ref", metavar="COMMIT_SHA",
  23. help="Install exactly one immutable 40-character Git commit SHA")
  24. plugins_install.add_argument(
  25. "--allow-removed", action="store_true",
  26. help="DANGEROUS: bypass the catalog removed-plugin blocklist check")
  27. _install_deps_group = plugins_install.add_mutually_exclusive_group()
  28. _install_deps_group.add_argument(
  29. "--no-deps", action="store_true",
  30. help="Download without dependency consent and leave disabled; cannot replace an active plugin")
  31. _install_deps_group.add_argument(
  32. "--yes-deps", action="store_true",
  33. help="Answer the Python dependency consent question yourself, so non-interactive installs "
  34. "(SSH automation, CI, Docker entrypoints) finish in one run instead of being refused")
  35. _install_enable_group = plugins_install.add_mutually_exclusive_group()
  36. _install_enable_group.add_argument(
  37. "--enable", action="store_true",
  38. help="Auto-enable the plugin after install (skip confirmation prompt)")
  39. _install_enable_group.add_argument(
  40. "--no-enable", action="store_true",
  41. help="Install disabled (skip confirmation prompt); enable later with `hermes plugins enable <name>`",
  42. )
  43. plugins_search = plugins_subparsers.add_parser(
  44. "search", help="Search the curated Hermes plugin catalog")
  45. plugins_search.add_argument(
  46. "term", nargs="?", default="",
  47. help="Query matched against entry names, descriptions and declared tools (omit to list the whole catalog)")
  48. add_json_flag(plugins_search, "Print machine-readable JSON")
  49. plugins_subparsers.add_parser("browse", help="List every curated plugin catalog entry")
  50. plugins_validate = plugins_subparsers.add_parser(
  51. "validate", help="Validate a plugin directory for catalog admission (CI gate)")
  52. plugins_validate.add_argument("path", help="Path to the plugin directory")
  53. plugins_validate.add_argument(
  54. "--install-deps", action="store_true",
  55. help="Install the plugin's declared Python dependencies (pyproject/python_dependencies) into this "
  56. "venv before the capability probe, exactly as `plugins install` would — the catalog CI gate")
  57. add_json_flag(plugins_validate, "Print machine-readable JSON (for CI)")
  58. plugins_update = plugins_subparsers.add_parser(
  59. "update", help="Update an installed plugin, or with no name every plugin that has an update")
  60. plugins_update.add_argument(
  61. "name", nargs="?", help="Plugin name to update (default: list every plugin with an update and offer them all)")
  62. plugins_update.add_argument(
  63. "--yes", "-y", action="store_true",
  64. help="With no name: update everything listed without the confirmation question (required without a terminal)")
  65. plugins_update.add_argument(
  66. "--force", "-f", action="store_true",
  67. help="Apply the update even when the security scan returns a caution verdict (a dangerous verdict "
  68. "still blocks). Without it, a terminal asks first")
  69. plugins_auto = plugins_subparsers.add_parser(
  70. "auto-update", aliases=["autoupdate"],
  71. help="Show or set unattended plugin updates (plugins.auto_apply)",
  72. description=(
  73. "With auto-update on, the gateway's update check (every plugins.auto_update_check_hours) "
  74. "applies the catalog and tracked Git updates `hermes plugins update` would apply, through the "
  75. "same security scan. Updated code loads in new sessions; a widened catalog pin or new "
  76. "capabilities are never accepted unattended. Off by default."))
  77. plugins_auto.add_argument("state", nargs="?", choices=["on", "off"], help="Omit to show the current setting")
  78. plugins_adopt = plugins_subparsers.add_parser(
  79. "adopt",
  80. help="Adopt a self-cloned plugin dir into provenance tracking",
  81. description=(
  82. "For plugin dirs you cloned yourself (no install record): read "
  83. "the git origin URL, write the provenance row, and become a "
  84. "tracked git install (check-updates + update)."
  85. ),
  86. )
  87. plugins_adopt.add_argument("name", help="Self-cloned plugin directory name")
  88. plugins_trust = plugins_subparsers.add_parser(
  89. "trust-update-url",
  90. help="Confirm a changed plugin update_url into the saved tag",
  91. description=(
  92. "The ONLY path that moves a saved update_url tag. When a "
  93. "plugin's manifest changed its update_url (needs-fixing "
  94. "mismatch), running this trusts the new url after review. "
  95. "Never triggered automatically."
  96. ),
  97. )
  98. plugins_trust.add_argument("name", help="Plugin name")
  99. plugins_check = plugins_subparsers.add_parser(
  100. "check-updates",
  101. aliases=["check"],
  102. help="Check whether installed plugins have updates (read-only)",
  103. description=(
  104. "Standard, read-only update check for every installed plugin: "
  105. "saved-tag update_url feeds (with mismatch protection), git "
  106. "ls-remote for git installs, and a stateless PyPI probe for "
  107. "pip entry-point plugins. NEVER mutates anything — apply with "
  108. "`hermes plugins update <name>`."
  109. ),
  110. )
  111. plugins_check.add_argument(
  112. "--json",
  113. action="store_true",
  114. help="Print machine-readable JSON (the receipt-section shape)",
  115. )
  116. plugins_remove = plugins_subparsers.add_parser(
  117. "remove", aliases=["rm", "uninstall"], help="Remove an installed plugin")
  118. plugins_remove.add_argument("name", help="Plugin directory name to remove")
  119. plugins_list = plugins_subparsers.add_parser(
  120. "list", aliases=["ls"], help="List installed plugins")
  121. plugins_list.add_argument("--enabled", action="store_true", help="Show only enabled plugins")
  122. plugins_list.add_argument(
  123. "--user", action="store_true",
  124. help="Show only user-installed plugins (including git plugins)")
  125. plugins_list.add_argument("--no-bundled", action="store_true", help="Hide bundled plugins")
  126. plugins_list.add_argument(
  127. "--plain", action="store_true",
  128. help="Print compact plain-text output instead of a Rich table")
  129. add_json_flag(plugins_list, "Print machine-readable JSON")
  130. plugins_enable = plugins_subparsers.add_parser("enable", help="Enable a disabled plugin")
  131. plugins_enable.add_argument("name", help="Plugin name to enable")
  132. _enable_override_group = plugins_enable.add_mutually_exclusive_group()
  133. _enable_override_group.add_argument(
  134. "--allow-tool-override", action="store_true",
  135. help="Grant this plugin permission to replace built-in tools "
  136. "(e.g. shell_exec, write_file). Skips the confirmation prompt.")
  137. _enable_override_group.add_argument(
  138. "--no-allow-tool-override", action="store_true",
  139. help="Enable without granting built-in tool override (skip prompt).")
  140. plugins_disable = plugins_subparsers.add_parser(
  141. "disable", help="Disable a plugin without removing it")
  142. plugins_disable.add_argument("name", help="Plugin name to disable")
  143. plugins_capabilities = plugins_subparsers.add_parser(
  144. "capabilities", help="Show declared vs granted capabilities per plugin",
  145. description="Show each plugin's declared capabilities (from plugin.yaml) "
  146. "against what the user has granted. Capabilities are a consent "
  147. "and audit layer over host API surfaces — NOT a sandbox.")
  148. plugins_capabilities.add_argument(
  149. "name", nargs="?", default=None,
  150. help="Plugin id to inspect (omit to list all plugins with capabilities)")
  151. plugins_doctor = plugins_subparsers.add_parser(
  152. "doctor", help="Validate a plugin with the real runtime contracts")
  153. plugins_doctor.add_argument(
  154. "target", nargs="?", default=".",
  155. help="Plugin path or installed plugin id (default: current directory)")
  156. plugins_doctor.add_argument(
  157. "--ci", action="store_true", help="Exit non-zero when validation reports an error")
  158. plugins_pack = plugins_subparsers.add_parser(
  159. "pack", help="Declarative, shareable plugin sets (hermes-pack.yaml)",
  160. description="Install, export, or inspect plugin packs — a single YAML file "
  161. "pinning a set of plugins to exact commit SHAs, with optional "
  162. "non-secret config seeds. Installing a pack fans out to ordinary "
  163. "pinned installs; capability consent stays per-plugin.")
  164. pack_subparsers = plugins_pack.add_subparsers(dest="pack_action")
  165. pack_install = pack_subparsers.add_parser(
  166. "install", help="Review and install a pack from a file path or https URL")
  167. pack_install.add_argument("source", help="Path to a hermes-pack.yaml file, or an https:// URL")
  168. pack_install.add_argument(
  169. "--force", "-f", action="store_true", help="Reinstall plugins that already exist")
  170. pack_export = pack_subparsers.add_parser(
  171. "export", help="Emit a pack YAML for the current install on stdout")
  172. pack_export.add_argument(
  173. "--enabled-only", action="store_true",
  174. help="Only include plugins currently in plugins.enabled")
  175. pack_export.add_argument(
  176. "--name", default="my-hermes-pack", help="Pack name to embed in the exported YAML")
  177. pack_show = pack_subparsers.add_parser(
  178. "show", help="Dry-run: parse and display a pack without installing")
  179. pack_show.add_argument("source", help="Path to a hermes-pack.yaml file, or an https:// URL")
  180. plugins_show = plugins_subparsers.add_parser(
  181. "show", aliases=["info"], help="Show details for a single plugin (including emits/listens)")
  182. plugins_show.add_argument("name", help="Plugin name or key to show")
  183. plugins_parser.set_defaults(func=cmd_plugins)