robotframework-plugins 2026.11.0.dev1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +110 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +119 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  31. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  32. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +11 -0
  33. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  34. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +104 -0
  35. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  36. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  37. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  38. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +435 -0
  39. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  40. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  41. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  42. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +108 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +509 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  50. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  51. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  52. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  108. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +103 -0
  109. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  110. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +107 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  115. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  116. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +9 -0
  117. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +266 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  128. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  129. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  130. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  143. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  144. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  145. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  146. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  147. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +132 -0
  148. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  149. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  172. robotframework_plugins/_assets.py +120 -0
  173. robotframework_plugins/_catalog.py +123 -0
  174. robotframework_plugins/_snapshot.py +230 -0
  175. robotframework_plugins/adapters/__init__.py +53 -0
  176. robotframework_plugins/adapters/_base.py +400 -0
  177. robotframework_plugins/adapters/claude_code.py +312 -0
  178. robotframework_plugins/adapters/claude_desktop.py +129 -0
  179. robotframework_plugins/adapters/codex.py +276 -0
  180. robotframework_plugins/adapters/copilot.py +87 -0
  181. robotframework_plugins/adapters/cursor.py +295 -0
  182. robotframework_plugins/adapters/goose.py +240 -0
  183. robotframework_plugins/adapters/opencode.py +170 -0
  184. robotframework_plugins/bundle.py +85 -0
  185. robotframework_plugins/cli.py +1311 -0
  186. robotframework_plugins/detect.py +121 -0
  187. robotframework_plugins/manifest.py +338 -0
  188. robotframework_plugins/py.typed +0 -0
  189. robotframework_plugins/skillzip.py +39 -0
  190. robotframework_plugins/transforms.py +725 -0
  191. robotframework_plugins-2026.11.0.dev1.dist-info/METADATA +178 -0
  192. robotframework_plugins-2026.11.0.dev1.dist-info/RECORD +195 -0
  193. robotframework_plugins-2026.11.0.dev1.dist-info/WHEEL +4 -0
  194. robotframework_plugins-2026.11.0.dev1.dist-info/entry_points.txt +2 -0
  195. robotframework_plugins-2026.11.0.dev1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,276 @@
1
+ """Adapter for OpenAI Codex CLI.
2
+
3
+ Per the proposal (docs/installer/proposal.md, Phase 2) — adjusted
4
+ 2026-05-07 against developers.openai.com/codex/skills, which lists
5
+ ``$HOME/.agents/skills`` as the canonical USER-scope path (the
6
+ cross-vendor "agentskills.io" convention also honoured by Cursor 2.4+
7
+ and Goose v1.25+ Summon). Codex *also* reads ``~/.codex/skills`` (where
8
+ its bundled `.system` skills live) but the public spec is ``.agents``:
9
+
10
+ * skills → ``~/.agents/skills/<name>/`` (USER) or
11
+ ``<project>/.agents/skills/<name>/`` (PROJECT).
12
+ SKILL.md format identical to Claude Code; verbatim copy
13
+ modulo ``${CLAUDE_PLUGIN_ROOT}`` substitution.
14
+ * subagents → ``~/.codex/agents/<name>.toml``, the generated
15
+ ``variants/codex/agents/`` files (scripts/build-agent-variants.py).
16
+ * hooks → ``~/.codex/hooks.json``. Codex hooks are **experimental**
17
+ and gated by ``[features] codex_hooks = true`` in
18
+ ``config.toml``. We do *not* flip that flag automatically;
19
+ ``post_install`` tells the user how.
20
+
21
+ Plus a co-located copy of the plugin's ``scripts/`` (hook scripts) and
22
+ the skills' scripts under ``<root>/<plugin>-files/`` — same staging
23
+ strategy as the Claude Code adapter — so ``${CLAUDE_PLUGIN_ROOT}``
24
+ references in hook commands resolve to a stable, post-substitution path.
25
+
26
+ Substitution happens *at install time*, per the proposal's
27
+ decision-point #2: the ``${CLAUDE_PLUGIN_ROOT}`` token is rewritten to
28
+ the absolute path of the staged copy, so the resulting files are
29
+ self-contained and don't require the env var to be set at runtime.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import shutil
35
+ from dataclasses import dataclass
36
+ from pathlib import Path
37
+ from typing import Iterable
38
+
39
+ from .. import _assets
40
+ from .. import transforms as _x
41
+ from ._base import (
42
+ needs_support_dir,
43
+ MARKETPLACE_REPO,
44
+ plugin_id,
45
+ AdapterBase,
46
+ InstallOptions,
47
+ InstallPlan,
48
+ InstallTarget,
49
+ skill_script_files,
50
+ support_dir_name,
51
+ )
52
+
53
+
54
+ CONFIG_TOML_FILENAME = "config.toml"
55
+ HOOKS_JSON_FILENAME = "hooks.json"
56
+
57
+
58
+ @dataclass
59
+ class CodexAdapter(AdapterBase):
60
+ name: str = "codex"
61
+ pretty: str = "OpenAI Codex CLI"
62
+ user_root_subpath: tuple[str, ...] = (".codex",)
63
+ project_root_subpath: tuple[str, ...] = (".codex",)
64
+
65
+ # ------------------------------------------------------------------
66
+ # detect
67
+ # ------------------------------------------------------------------
68
+
69
+ def detect(self) -> bool:
70
+ """True if the ``codex`` CLI is on PATH or ``~/.codex`` exists."""
71
+ if shutil.which("codex") is not None:
72
+ return True
73
+ return (Path.home() / ".codex").is_dir()
74
+
75
+ # ------------------------------------------------------------------
76
+ # plan
77
+ # ------------------------------------------------------------------
78
+
79
+ def _skills_root(self, opts: InstallOptions) -> Path:
80
+ """Codex docs canonical user-scope skills path is ``$HOME/.agents/skills``
81
+ (cross-vendor universal). With ``--prefix`` we keep the layout
82
+ consistent with Goose's adapter: ``<prefix>/agents/skills/``.
83
+ """
84
+ if opts.prefix is not None:
85
+ return opts.prefix / "agents" / "skills"
86
+ if opts.scope == "project":
87
+ project = opts.project_dir if opts.project_dir is not None else Path.cwd()
88
+ return project / ".agents" / "skills"
89
+ return Path.home() / ".agents" / "skills"
90
+
91
+ def plan(self, opts: InstallOptions) -> InstallPlan:
92
+ root = self.install_root(opts)
93
+ plugin_dst = root / support_dir_name(opts.plugin)
94
+ plugin_root_abs = _x.to_native_path_string(plugin_dst.resolve())
95
+
96
+ # Codex hooks invoke `node "<…>.mjs"`. If Node isn't on PATH at
97
+ # install time, skip writing hooks.json entirely and surface a
98
+ # post_install note (the file would be inert anyway).
99
+ register_hooks = "hooks" in opts.what and _x.node_available()
100
+
101
+ with _assets.asset_root_path(opts.plugin) as src_root:
102
+ targets = list(self._collect_targets(
103
+ src_root=src_root,
104
+ root=root,
105
+ skills_root=self._skills_root(opts),
106
+ plugin_dst=plugin_dst,
107
+ plugin_root_abs=plugin_root_abs,
108
+ what=opts.what,
109
+ register_hooks=register_hooks,
110
+ ))
111
+
112
+ notes: list[str] = []
113
+ if "hooks" in opts.what:
114
+ if register_hooks:
115
+ notes.append(
116
+ "Codex hooks are experimental — enable them by adding "
117
+ "`[features]\\ncodex_hooks = true` to ~/.codex/config.toml "
118
+ "(installer does not flip this flag for you)."
119
+ )
120
+ else:
121
+ notes.append(
122
+ "Node.js was not found on PATH; Codex hooks.json was NOT "
123
+ "written. Install Node.js then re-run `rf-agentskills "
124
+ "install --agent codex` to enable hooks."
125
+ )
126
+ return InstallPlan(targets=tuple(targets), notes=tuple(notes))
127
+
128
+ def plugin_plan(self, opts: InstallOptions) -> InstallPlan | None:
129
+ """Codex reads no committed marketplace: install the subagents (plugins
130
+ cannot ship them) and hand over the per-user plugin commands."""
131
+ root = self.install_root(opts)
132
+ targets = []
133
+ for plugin in opts.plugins:
134
+ with _assets.asset_root_path(plugin) as src_root:
135
+ targets += [
136
+ InstallTarget(dst=root / "agents" / f.name, payload=f.read_bytes(),
137
+ transform_name="codex_agent_variant", plugin=plugin)
138
+ for f in sorted((src_root / "variants" / "codex" / "agents").glob("*.toml"))
139
+ ]
140
+ commands = "\n".join(" " + " ".join(c) for c in self.plugin_commands(opts))
141
+ return InstallPlan(targets=tuple(targets), notes=(
142
+ "Codex: every user runs once (or pass --yes to run them now):\n" + commands,
143
+ "Then trust the plugin's hooks once with /hooks in Codex.",
144
+ ))
145
+
146
+ def plugin_commands(self, opts: InstallOptions) -> list[list[str]]:
147
+ add = ["codex", "plugin", "marketplace", "add", MARKETPLACE_REPO]
148
+ if opts.ref:
149
+ add += ["--ref", opts.ref]
150
+ return [add, *(["codex", "plugin", "add", plugin_id(p)] for p in opts.plugins)]
151
+
152
+ def _collect_targets(
153
+ self,
154
+ *,
155
+ src_root: Path,
156
+ root: Path,
157
+ skills_root: Path,
158
+ plugin_dst: Path,
159
+ plugin_root_abs: str,
160
+ what: frozenset[str],
161
+ register_hooks: bool = True,
162
+ ) -> Iterable[InstallTarget]:
163
+ # 1. Skills — ``$HOME/.agents/skills/<name>/`` per Codex docs
164
+ # (developers.openai.com/codex/skills, USER scope row).
165
+ # SKILL.md format is identical to Claude Code's so we copy
166
+ # the whole tree (SKILL.md + references/ + assets/ + scripts/)
167
+ # verbatim, with ${CLAUDE_PLUGIN_ROOT} substituted at install
168
+ # time.
169
+ if "skills" in what:
170
+ skill_src = src_root / "skills"
171
+ if skill_src.is_dir():
172
+ for f in sorted(skill_src.rglob("*")):
173
+ if not f.is_file():
174
+ continue
175
+ rel = f.relative_to(skill_src)
176
+ yield InstallTarget(
177
+ dst=skills_root / rel,
178
+ payload=self.render_skill_dir(
179
+ self._read_with_substitution(f, plugin_root_abs),
180
+ f, skills_root / rel.parts[0],
181
+ ),
182
+ transform_name="plugin_root_substitution",
183
+ )
184
+
185
+ # 2. Subagents — <root>/agents/<name>.toml: the committed Codex variants
186
+ # (scripts/build-agent-variants.py), so marketplace and installer
187
+ # users get byte-identical files.
188
+ if "agents" in what:
189
+ variants_src = src_root / "variants" / "codex" / "agents"
190
+ if variants_src.is_dir():
191
+ for f in sorted(variants_src.glob("*.toml")):
192
+ yield InstallTarget(
193
+ dst=root / "agents" / f.name,
194
+ payload=f.read_bytes(),
195
+ transform_name="codex_agent_variant",
196
+ )
197
+
198
+ # 3. Hooks — <root>/hooks.json. Verbatim copy of the plugin's
199
+ # hooks.json; the actual activation happens via
200
+ # [features] codex_hooks = true in config.toml, which we
201
+ # deliberately do NOT toggle (see post_install). Skipped when
202
+ # Node isn't on PATH (the hook command shells out to node).
203
+ if register_hooks:
204
+ hooks_src = src_root / "hooks" / "hooks.json"
205
+ if hooks_src.is_file():
206
+ yield InstallTarget(
207
+ dst=root / HOOKS_JSON_FILENAME,
208
+ payload=self._read_with_substitution(hooks_src, plugin_root_abs),
209
+ transform_name="plugin_root_substitution",
210
+ )
211
+
212
+ # 4. Plugin-co-located files: scripts/, hooks/. These live under
213
+ # <root>/<plugin>-files/ so the substituted
214
+ # ${CLAUDE_PLUGIN_ROOT} paths in skills / agents / hooks resolve.
215
+ if {"hooks", "skills", "agents"} & what and needs_support_dir(src_root):
216
+ for category in ("scripts", "hooks"):
217
+ cat_src = src_root / category
218
+ if not cat_src.is_dir():
219
+ continue
220
+ for f in sorted(cat_src.rglob("*")):
221
+ if not f.is_file():
222
+ continue
223
+ rel = f.relative_to(src_root)
224
+ yield InstallTarget(
225
+ dst=plugin_dst / rel,
226
+ payload=self._read_with_substitution(f, plugin_root_abs),
227
+ transform_name="plugin_root_substitution",
228
+ executable=f.suffix in (".sh", ".ps1") or f.name.endswith(".bash"),
229
+ )
230
+ # Per-skill scripts for the hooks (<plugin_dst>/skills/<skill>/scripts/;
231
+ # the Stop hook runs skills/rf-results/scripts/rf_results.py).
232
+ for f in skill_script_files(src_root):
233
+ rel = f.relative_to(src_root)
234
+ yield InstallTarget(
235
+ dst=plugin_dst / rel,
236
+ payload=f.read_bytes(),
237
+ transform_name="skill_script_for_hooks",
238
+ )
239
+ # Pin the install-time Python interpreter (see claude_code.py).
240
+ yield InstallTarget(
241
+ dst=plugin_dst / "scripts" / "python_runtime.json",
242
+ payload=_x.python_runtime_config_bytes(),
243
+ transform_name="python_runtime_pin",
244
+ )
245
+
246
+ # ------------------------------------------------------------------
247
+ # post_install
248
+ # ------------------------------------------------------------------
249
+
250
+ def post_install(self, opts: InstallOptions) -> list[str]:
251
+ notes = [
252
+ "Codex will pick up skills and agents on next session start "
253
+ "(it walks ~/.codex/skills/ and ~/.codex/agents/ at launch).",
254
+ ]
255
+ if "hooks" in opts.what:
256
+ notes.append(
257
+ "Codex hooks are EXPERIMENTAL. To enable them, add this to "
258
+ "~/.codex/config.toml (we did not flip it for you):\n"
259
+ " [features]\n codex_hooks = true"
260
+ )
261
+ return notes
262
+
263
+ # ------------------------------------------------------------------
264
+ # internals
265
+ # ------------------------------------------------------------------
266
+
267
+ @staticmethod
268
+ def _read_with_substitution(src: Path, plugin_root_abs: str) -> bytes:
269
+ """Read ``src`` and substitute ``${CLAUDE_PLUGIN_ROOT}``.
270
+
271
+ Files we don't recognise as text (binaries) are passed through.
272
+ """
273
+ data = src.read_bytes()
274
+ if _x.is_substitution_candidate(src):
275
+ return _x.substitute_plugin_root_bytes(data, plugin_root_abs)
276
+ return data
@@ -0,0 +1,87 @@
1
+ """Adapter for GitHub Copilot in VS Code (≥ 1.108).
2
+
3
+ Copilot's customization model (changelog 2025-12-18) reads Claude
4
+ Code's filesystem layout natively — `.claude/skills/`, `.claude/agents/`,
5
+ `.claude/settings.json` are all honored without transformation. The
6
+ Copilot adapter therefore reuses the Claude Code adapter's plan
7
+ verbatim, with one adjustment:
8
+
9
+ * **Hook field-name shim** — VS Code passes camelCase JSON to hook
10
+ scripts (``filePath`` not ``file_path``). The hook scripts in
11
+ ``plugins/rf-agentskills/`` already accept both via the jq fallbacks
12
+ we added in the conditional UserPromptSubmit/Stop scripts. No
13
+ transform needed at install time.
14
+
15
+ Notes the user must act on (returned by ``post_install``):
16
+
17
+ * Enable preview flags in VS Code: ``chat.agent.plugins.enabled``,
18
+ ``chat.skills.enabled``, ``chat.hooks.enabled``.
19
+ * Hook matcher value is silently ignored by VS Code; our hook scripts
20
+ filter on file extension internally so this is a no-op for us.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import shutil
26
+ from dataclasses import dataclass
27
+ from pathlib import Path
28
+
29
+ from ._base import InstallOptions, InstallPlan, marketplace_settings_merges, old_marketplace_note, upgrade_plugins
30
+ from .claude_code import ClaudeCodeAdapter
31
+
32
+
33
+ @dataclass
34
+ class CopilotAdapter(ClaudeCodeAdapter):
35
+ name: str = "copilot"
36
+ pretty: str = "GitHub Copilot (VS Code)"
37
+ # VS Code does not document ${CLAUDE_SKILL_DIR} substitution.
38
+ expands_skill_dir: bool = False
39
+
40
+ def detect(self) -> bool:
41
+ # VS Code on PATH OR a known per-OS Code config dir exists.
42
+ if shutil.which("code") is not None:
43
+ return True
44
+ candidates = [
45
+ Path.home() / ".config" / "Code", # Linux
46
+ Path.home() / "Library" / "Application Support" / "Code", # macOS
47
+ Path.home() / "AppData" / "Roaming" / "Code", # Windows
48
+ ]
49
+ return any(c.is_dir() for c in candidates)
50
+
51
+ def post_install(self, opts: InstallOptions) -> list[str]:
52
+ notes = list(super().post_install(opts))
53
+ notes.append(
54
+ "VS Code Copilot 1.108+ reads `.claude/` paths natively. "
55
+ "If you don't see skills/agents/hooks, enable the preview flag "
56
+ "`chat.useAgentSkills` in VS Code settings (and `chat.hooks.enabled` "
57
+ "if you want hooks active)."
58
+ )
59
+ return notes
60
+
61
+ def plugin_plan(self, opts: InstallOptions) -> InstallPlan | None:
62
+ """Claude Code's settings entries plus Copilot's own settings file
63
+ (``.github/copilot/settings.json`` in a project, ``~/.copilot/settings.json``
64
+ for the user); Copilot CLI reads either."""
65
+ base = super().plugin_plan(opts)
66
+ assert base is not None
67
+ if opts.prefix is not None:
68
+ copilot_settings = opts.prefix / ".github" / "copilot" / "settings.json"
69
+ elif opts.scope == "project":
70
+ project = opts.project_dir if opts.project_dir is not None else Path.cwd()
71
+ copilot_settings = project / ".github" / "copilot" / "settings.json"
72
+ else:
73
+ copilot_settings = Path.home() / ".copilot" / "settings.json"
74
+ notes = (
75
+ *base.notes,
76
+ f"{copilot_settings} carries the same entries for Copilot CLI.",
77
+ "VS Code: enable `chat.plugins.enabled` and `chat.useHooks`; add "
78
+ '"MarketSquare/robotframework-plugins" to `chat.plugins.marketplaces` '
79
+ "(user settings) to install it outside this workspace.",
80
+ )
81
+ migrated = old_marketplace_note(copilot_settings)
82
+ if migrated:
83
+ notes = (*notes, migrated)
84
+ return InstallPlan(
85
+ merges=(*base.merges, *marketplace_settings_merges(copilot_settings, opts.ref, upgrade_plugins(copilot_settings, opts))),
86
+ notes=notes,
87
+ )
@@ -0,0 +1,295 @@
1
+ """Adapter for Cursor (≥ 2.4).
2
+
3
+ Cursor 2.4+ added native SKILL.md support (changelog "Subagents,
4
+ Skills, and Image Generation" at cursor.com/changelog/2-4). Skills are
5
+ auto-discovered from any of:
6
+
7
+ * ``<project>/.cursor/skills/<name>/`` (project)
8
+ * ``~/.cursor/skills/<name>/`` (user)
9
+ * Plus cross-vendor: ``.claude/skills/``, ``.codex/skills/``,
10
+ ``.agents/skills/`` — all read by Cursor automatically.
11
+
12
+ We pick the agent-native path (``~/.cursor/skills/<name>/``) so users
13
+ who installed Cursor without any other agent still get the bundle.
14
+
15
+ * skills → ``<root>/skills/<name>/SKILL.md`` (+ subtree). Verbatim
16
+ copy modulo ``${CLAUDE_PLUGIN_ROOT}`` substitution. Same
17
+ format Cursor 2.4 documents at cursor.com/docs/skills.
18
+ * subagents → ``<root>/agents/<name>.md``. Cursor 2.4 also added
19
+ native subagent support — same .md frontmatter shape as
20
+ Claude Code, so verbatim copy works.
21
+ * hooks → ``<root>/hooks.json`` via
22
+ :func:`transforms.rewrite_hooks_for_cursor` (lowercases
23
+ event names and namespaces ``mcp__rf-mcp__*`` matchers
24
+ to ``MCP:rf-mcp``). The result is wrapped under a
25
+ top-level ``"hooks"`` key — Cursor's expected shape.
26
+
27
+ Plugin-co-located hook scripts are staged under
28
+ ``<root>/<plugin>-files/`` (same trick the Claude Code adapter
29
+ uses) so the post-substitution ``${CLAUDE_PLUGIN_ROOT}`` references in
30
+ SKILL bodies and hook commands resolve to absolute paths.
31
+
32
+ User-scope install root is ``~/.cursor/``; project scope uses
33
+ ``<project>/.cursor/``. ``--prefix`` overrides both.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import json
39
+ import shutil
40
+ from dataclasses import dataclass
41
+ from pathlib import Path
42
+ from typing import Iterable
43
+
44
+ from .. import _assets
45
+ from .. import transforms as _x
46
+ from ._base import (
47
+ needs_support_dir,
48
+ legacy_markers,
49
+ MARKETPLACE_REPO,
50
+ plugin_id,
51
+ AdapterBase,
52
+ ConfigMergeOp,
53
+ InstallOptions,
54
+ InstallPlan,
55
+ InstallTarget,
56
+ skill_script_files,
57
+ support_dir_name,
58
+ )
59
+
60
+
61
+
62
+
63
+ @dataclass
64
+ class CursorAdapter(AdapterBase):
65
+ name: str = "cursor"
66
+ pretty: str = "Cursor"
67
+ user_root_subpath: tuple[str, ...] = (".cursor",)
68
+ project_root_subpath: tuple[str, ...] = (".cursor",)
69
+
70
+ # ------------------------------------------------------------------
71
+ # detect
72
+ # ------------------------------------------------------------------
73
+
74
+ def detect(self) -> bool:
75
+ """True if either the Cursor CLI is on PATH or ``~/.cursor`` exists."""
76
+ if shutil.which("cursor") is not None:
77
+ return True
78
+ return (Path.home() / ".cursor").is_dir()
79
+
80
+ # ------------------------------------------------------------------
81
+ # plan
82
+ # ------------------------------------------------------------------
83
+
84
+ def plan(self, opts: InstallOptions) -> InstallPlan:
85
+ root = self.install_root(opts)
86
+ plugin_dst = root / support_dir_name(opts.plugin)
87
+ plugin_root_abs = _x.to_native_path_string(plugin_dst.resolve())
88
+
89
+ # Cursor's hooks.json embeds the same `node "<…>.mjs"` commands
90
+ # as Claude Code's — see ``transforms.rewrite_hooks_for_cursor``
91
+ # which only adjusts the matcher namespacing, not the command
92
+ # shape. If Node isn't on PATH, skip hooks with a note.
93
+ register_hooks = "hooks" in opts.what and _x.node_available()
94
+
95
+ with _assets.asset_root_path(opts.plugin) as src_root:
96
+ targets = list(self._collect_targets(
97
+ src_root=src_root,
98
+ root=root,
99
+ plugin_dst=plugin_dst,
100
+ plugin_root_abs=plugin_root_abs,
101
+ what=opts.what,
102
+ ))
103
+ merges = list(self._collect_merges(
104
+ src_root=src_root,
105
+ root=root,
106
+ plugin_root_abs=plugin_root_abs,
107
+ what=opts.what,
108
+ register_hooks=register_hooks,
109
+ ))
110
+
111
+ notes: list[str] = []
112
+ if "hooks" in opts.what and not register_hooks:
113
+ notes.append(
114
+ "Node.js was not found on PATH; Cursor hooks were NOT registered. "
115
+ "Install Node.js then re-run with `--agent cursor` to enable them."
116
+ )
117
+ return InstallPlan(targets=tuple(targets), merges=tuple(merges), notes=tuple(notes))
118
+
119
+ def plugin_plan(self, opts: InstallOptions) -> InstallPlan | None:
120
+ """Cursor keeps marketplaces on the Cursor account: print the steps."""
121
+ return InstallPlan(notes=(
122
+ f"Cursor: add the marketplace https://github.com/{MARKETPLACE_REPO} "
123
+ "(Customize -> Plugins, or `cursor-agent plugin marketplace add "
124
+ f"https://github.com/{MARKETPLACE_REPO}`), then install "
125
+ + ", ".join(plugin_id(p) for p in opts.plugins) + " and "
126
+ "choose project or user scope.",
127
+ "Cursor also imports the plugin when it is installed in Claude Code and "
128
+ "enabled in .claude/settings.json (Settings -> Third-Party Imports).",
129
+ ))
130
+
131
+ def _collect_targets(
132
+ self,
133
+ *,
134
+ src_root: Path,
135
+ root: Path,
136
+ plugin_dst: Path,
137
+ plugin_root_abs: str,
138
+ what: frozenset[str],
139
+ ) -> Iterable[InstallTarget]:
140
+ # 1. Skills → <root>/skills/<name>/ (Cursor 2.4+ reads SKILL.md
141
+ # natively per cursor.com/docs/skills). Verbatim copy of the
142
+ # full skill tree so references/, assets/, scripts/ come
143
+ # along too.
144
+ if "skills" in what:
145
+ skills_src = src_root / "skills"
146
+ if skills_src.is_dir():
147
+ for f in sorted(skills_src.rglob("*")):
148
+ if not f.is_file():
149
+ continue
150
+ rel = f.relative_to(skills_src)
151
+ yield InstallTarget(
152
+ dst=root / "skills" / rel,
153
+ payload=self.render_skill_dir(
154
+ self._read_with_substitution(f, plugin_root_abs),
155
+ f, root / "skills" / rel.parts[0],
156
+ ),
157
+ transform_name="plugin_root_substitution",
158
+ )
159
+
160
+ # 2. Subagents → <root>/agents/<name>.md (Cursor 2.4 added
161
+ # native subagent support; same .md format as Claude Code).
162
+ if "agents" in what:
163
+ agents_src = src_root / "agents"
164
+ if agents_src.is_dir():
165
+ for agent_md in sorted(agents_src.glob("*.md")):
166
+ yield InstallTarget(
167
+ dst=root / "agents" / agent_md.name,
168
+ payload=self._read_with_substitution(agent_md, plugin_root_abs),
169
+ transform_name="plugin_root_substitution",
170
+ )
171
+
172
+ # 3. Plugin-co-located files: scripts/, hooks/.
173
+ # Same pattern as Claude Code — staged under
174
+ # <root>/<plugin>-files/ so substituted paths resolve.
175
+ if {"hooks", "skills"} & what and needs_support_dir(src_root):
176
+ for category in ("scripts", "hooks"):
177
+ cat_src = src_root / category
178
+ if not cat_src.is_dir():
179
+ continue
180
+ for f in sorted(cat_src.rglob("*")):
181
+ if not f.is_file():
182
+ continue
183
+ rel = f.relative_to(src_root)
184
+ yield InstallTarget(
185
+ dst=plugin_dst / rel,
186
+ payload=self._read_with_substitution(f, plugin_root_abs),
187
+ transform_name="plugin_root_substitution",
188
+ executable=f.suffix in (".sh", ".ps1") or f.name.endswith(".bash"),
189
+ )
190
+ # Per-skill scripts for the hooks (<plugin_dst>/skills/<skill>/scripts/;
191
+ # the Stop hook runs skills/rf-results/scripts/rf_results.py).
192
+ for f in skill_script_files(src_root):
193
+ rel = f.relative_to(src_root)
194
+ yield InstallTarget(
195
+ dst=plugin_dst / rel,
196
+ payload=f.read_bytes(),
197
+ transform_name="skill_script_for_hooks",
198
+ )
199
+ # Pin the install-time Python interpreter so hook .mjs scripts
200
+ # target the env that has robotframework. See claude_code.py
201
+ # for the rationale.
202
+ yield InstallTarget(
203
+ dst=plugin_dst / "scripts" / "python_runtime.json",
204
+ payload=_x.python_runtime_config_bytes(),
205
+ transform_name="python_runtime_pin",
206
+ )
207
+
208
+ def _collect_merges(
209
+ self,
210
+ *,
211
+ src_root: Path,
212
+ root: Path,
213
+ plugin_root_abs: str,
214
+ what: frozenset[str],
215
+ register_hooks: bool = True,
216
+ ) -> Iterable[ConfigMergeOp]:
217
+ # 4. Hooks → <root>/hooks.json with cursor-namespaced events.
218
+ # Skipped when Node isn't on PATH at install time.
219
+ if register_hooks:
220
+ hooks_json_src = src_root / "hooks" / "hooks.json"
221
+ if hooks_json_src.is_file():
222
+ yield self._hooks_merge_op(
223
+ hooks_json_src=hooks_json_src,
224
+ hooks_path=root / "hooks.json",
225
+ plugin_root_abs=plugin_root_abs,
226
+ )
227
+
228
+ # ------------------------------------------------------------------
229
+ # post_install
230
+ # ------------------------------------------------------------------
231
+
232
+ def post_install(self, opts: InstallOptions) -> list[str]:
233
+ notes = [
234
+ "Cursor will pick up rules in .cursor/rules/ on next session.",
235
+ "Subagents are folded into rules as _subagent-<name>.mdc.",
236
+ ]
237
+ if "hooks" in opts.what:
238
+ notes.append(
239
+ "Hooks installed to .cursor/hooks.json with cursor-namespaced "
240
+ "events (postToolUse, etc.) and matchers (MCP:rf-mcp)."
241
+ )
242
+ return notes
243
+
244
+ # ------------------------------------------------------------------
245
+ # internals
246
+ # ------------------------------------------------------------------
247
+
248
+ @staticmethod
249
+ def _read_with_substitution(src: Path, plugin_root_abs: str) -> bytes:
250
+ """Read ``src`` and substitute ``${CLAUDE_PLUGIN_ROOT}``."""
251
+ data = src.read_bytes()
252
+ if _x.is_substitution_candidate(src):
253
+ return _x.substitute_plugin_root_bytes(data, plugin_root_abs)
254
+ return data
255
+
256
+
257
+ def _hooks_merge_op(
258
+ self,
259
+ *,
260
+ hooks_json_src: Path,
261
+ hooks_path: Path,
262
+ plugin_root_abs: str,
263
+ ) -> ConfigMergeOp:
264
+ raw = _x.substitute_plugin_root(
265
+ hooks_json_src.read_text(encoding="utf-8"),
266
+ plugin_root_abs,
267
+ )
268
+ hooks_obj = json.loads(raw)
269
+ # Plugin's hooks.json wraps under "hooks"; unwrap to get the
270
+ # event-keyed dict, rewrite for cursor, then wrap back.
271
+ events = hooks_obj.get("hooks", hooks_obj)
272
+ cursor_events = _x.rewrite_hooks_for_cursor(events)
273
+
274
+ # Ownership marker: rf-agentskills hook commands reference this
275
+ # install dir. Granular merge preserves any user/other-tool hooks
276
+ # already present in hooks.json.
277
+ marker = plugin_root_abs
278
+
279
+ def apply() -> list[str]:
280
+ return _x.merge_hooks_block(hooks_path, cursor_events, marker=marker, legacy_markers=legacy_markers(plugin_root_abs))
281
+
282
+ def revert() -> None:
283
+ _x.remove_owned_hook_entries(
284
+ hooks_path, marker=marker, events=list(cursor_events)
285
+ )
286
+
287
+ return ConfigMergeOp(
288
+ path=hooks_path,
289
+ description=f"merge hooks block into {hooks_path}",
290
+ apply=apply,
291
+ revert=revert,
292
+ kind="json_hooks",
293
+ key_path=("hooks",),
294
+ marker=marker,
295
+ )