robotframework-plugins 2026.11.0__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 (199) 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 +113 -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/async-jobs.md +42 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/loose-assertions.md +20 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +120 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/loose-assertions.md +18 -0
  31. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  32. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  33. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  34. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  35. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +13 -0
  36. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  37. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -0
  38. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  39. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  40. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  41. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +445 -0
  42. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +128 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  50. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  51. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +517 -0
  52. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  108. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  109. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  110. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +119 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +123 -0
  115. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  116. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  117. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +10 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +268 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  128. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  129. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  130. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  143. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  144. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  145. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  146. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  147. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  148. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  149. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +134 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/selector-drift.md +29 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  172. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  173. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  174. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  175. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  176. robotframework_plugins/_assets.py +120 -0
  177. robotframework_plugins/_catalog.py +123 -0
  178. robotframework_plugins/_snapshot.py +320 -0
  179. robotframework_plugins/adapters/__init__.py +53 -0
  180. robotframework_plugins/adapters/_base.py +400 -0
  181. robotframework_plugins/adapters/claude_code.py +312 -0
  182. robotframework_plugins/adapters/claude_desktop.py +129 -0
  183. robotframework_plugins/adapters/codex.py +276 -0
  184. robotframework_plugins/adapters/copilot.py +87 -0
  185. robotframework_plugins/adapters/cursor.py +295 -0
  186. robotframework_plugins/adapters/goose.py +240 -0
  187. robotframework_plugins/adapters/opencode.py +170 -0
  188. robotframework_plugins/bundle.py +85 -0
  189. robotframework_plugins/cli.py +1311 -0
  190. robotframework_plugins/detect.py +121 -0
  191. robotframework_plugins/manifest.py +338 -0
  192. robotframework_plugins/py.typed +0 -0
  193. robotframework_plugins/skillzip.py +39 -0
  194. robotframework_plugins/transforms.py +725 -0
  195. robotframework_plugins-2026.11.0.dist-info/METADATA +198 -0
  196. robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
  197. robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
  198. robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
  199. robotframework_plugins-2026.11.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,725 @@
1
+ """Pure transforms used by the per-agent adapters.
2
+
3
+ Each function takes input bytes / text / dicts and returns the
4
+ transformed form. No I/O — adapters call these to produce the bytes
5
+ they then write to disk.
6
+
7
+ Tested in tests/installer/test_transforms.py.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import re
14
+ import sys
15
+ from dataclasses import dataclass
16
+ from pathlib import Path, PureWindowsPath
17
+ from typing import Any, Iterable
18
+
19
+ if sys.version_info >= (3, 11):
20
+ import tomllib
21
+ else: # pragma: no cover - 3.10 fallback
22
+ import tomli as tomllib
23
+
24
+ import tomli_w
25
+ import yaml
26
+
27
+
28
+ PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}"
29
+ RF_FILE_PATTERN = re.compile(r"\.(robot|resource)\b", re.IGNORECASE)
30
+
31
+
32
+ # ---------------------------------------------------------------------------
33
+ # ${CLAUDE_PLUGIN_ROOT} substitution
34
+ # ---------------------------------------------------------------------------
35
+
36
+
37
+ def substitute_plugin_root(text: str, plugin_root_abs: str) -> str:
38
+ """Replace every ``${CLAUDE_PLUGIN_ROOT}`` with the absolute install dir.
39
+
40
+ Mirrors what the rf-skill-eval harness already does at runtime —
41
+ here we do it once at install time so the resulting files are
42
+ self-contained and don't depend on the env var being set.
43
+ """
44
+ return text.replace(PLUGIN_ROOT_TOKEN, plugin_root_abs)
45
+
46
+
47
+ def substitute_plugin_root_bytes(data: bytes, plugin_root_abs: str) -> bytes:
48
+ """Bytes variant for files that may not be valid UTF-8."""
49
+ return data.replace(PLUGIN_ROOT_TOKEN.encode("utf-8"),
50
+ plugin_root_abs.encode("utf-8"))
51
+
52
+
53
+ # ---------------------------------------------------------------------------
54
+ # ${CLAUDE_SKILL_DIR} substitution (agents that do not expand it)
55
+ # ---------------------------------------------------------------------------
56
+
57
+ SKILL_DIR_TOKEN = "${CLAUDE_SKILL_DIR}"
58
+ # A relative bundled-script command (root/VS Code form): `python scripts/x.py`
59
+ # or `uv run --script scripts/x.py`.
60
+ _RELATIVE_SCRIPT_CMD = re.compile(r"(python3?|--script) scripts/([A-Za-z0-9_]+\.py)")
61
+
62
+
63
+ def substitute_skill_dir(text: str, abs_skill_dir: str) -> str:
64
+ """Render skill script paths as absolute paths of the installed skill.
65
+
66
+ Claude Code substitutes ``${CLAUDE_SKILL_DIR}`` in SKILL.md content;
67
+ other agents (Codex, Cursor, Copilot, Goose, OpenCode) do not. For them
68
+ the installer replaces the token with ``abs_skill_dir`` and also turns a
69
+ relative ``python scripts/<name>.py`` command into
70
+ ``python "<abs_skill_dir>/scripts/<name>.py"``, so the documented command
71
+ works from any working directory.
72
+ """
73
+ text = text.replace(SKILL_DIR_TOKEN, abs_skill_dir)
74
+ return _RELATIVE_SCRIPT_CMD.sub(
75
+ lambda m: f'{m.group(1)} "{abs_skill_dir}/scripts/{m.group(2)}"', text
76
+ )
77
+
78
+
79
+ def substitute_skill_dir_bytes(data: bytes, abs_skill_dir: str) -> bytes:
80
+ """Bytes variant; non-UTF-8 payloads pass through unchanged."""
81
+ try:
82
+ text = data.decode("utf-8")
83
+ except UnicodeDecodeError:
84
+ return data
85
+ return substitute_skill_dir(text, abs_skill_dir).encode("utf-8")
86
+
87
+
88
+ def is_substitution_candidate(path: Path) -> bool:
89
+ """Whether to attempt substitution on a file based on its suffix."""
90
+ return path.suffix.lower() in {
91
+ ".md", ".sh", ".py", ".txt", ".json", ".ps1", ".mjs", ".cjs", ".js",
92
+ }
93
+
94
+
95
+ def node_available() -> bool:
96
+ """Whether the host has a ``node`` binary on PATH.
97
+
98
+ Hook commands shipped by rf-agentskills invoke
99
+ ``node "<path>/<name>.mjs"`` (per the cross-platform Node-hooks
100
+ recommendation at https://claudefa.st/blog/tools/hooks/cross-platform-hooks).
101
+ If Node isn't installed, the hooks merge would write a settings.json
102
+ that references unrunnable commands; adapters use this probe to
103
+ gracefully skip the merge instead and report the gap via post_install.
104
+ """
105
+ import shutil
106
+ return shutil.which("node") is not None
107
+
108
+
109
+ def python_runtime_config_bytes() -> bytes:
110
+ """Pin the install-time Python interpreter for hook scripts to find.
111
+
112
+ Hook scripts that need to call into Robot Framework (``validate_robot.mjs``,
113
+ ``check_rf_environment.mjs``) read this JSON from
114
+ ``<plugin_dst>/scripts/python_runtime.json``. The recorded
115
+ ``interpreter`` is whatever ``sys.executable`` was when
116
+ ``robotframework-plugins install`` ran — i.e. the venv / pipx env / system
117
+ Python that actually has ``robotframework`` available.
118
+
119
+ Without this pinning, a hook running on Windows would probe ``python``
120
+ on PATH (often a different Python than the one rf-agentskills was
121
+ installed into, especially under pipx / uv tool install) and falsely
122
+ report robotframework as not installed.
123
+
124
+ The ``fallbacks`` list is consumed when the recorded interpreter is
125
+ no longer reachable (user moved their venv, etc.).
126
+ """
127
+ config = {
128
+ "interpreter": sys.executable,
129
+ "fallbacks": ["python3", "python"],
130
+ "captured_by": "rf-agentskills",
131
+ }
132
+ return json.dumps(config, indent=2).encode("utf-8")
133
+
134
+
135
+ # ---------------------------------------------------------------------------
136
+ # Markdown frontmatter parsing (used for SKILL.md and subagent .md files)
137
+ # ---------------------------------------------------------------------------
138
+
139
+
140
+ @dataclass(frozen=True)
141
+ class FrontmatterDoc:
142
+ """A markdown doc split into YAML-ish frontmatter and body."""
143
+ frontmatter: dict[str, Any]
144
+ body: str
145
+
146
+
147
+ _FRONTMATTER_RE = re.compile(
148
+ r"\A---\s*\n(?P<fm>.*?)\n---\s*\n?(?P<body>.*)\Z",
149
+ re.DOTALL,
150
+ )
151
+
152
+
153
+ def parse_frontmatter(text: str) -> FrontmatterDoc:
154
+ """Parse YAML frontmatter at the head of a markdown doc.
155
+
156
+ Returns an empty dict for ``frontmatter`` when no frontmatter block
157
+ is present, leaving ``body`` as the original text.
158
+ """
159
+ m = _FRONTMATTER_RE.match(text)
160
+ if not m:
161
+ return FrontmatterDoc(frontmatter={}, body=text)
162
+ fm_text = m.group("fm")
163
+ body = m.group("body")
164
+ try:
165
+ fm = yaml.safe_load(fm_text) or {}
166
+ if not isinstance(fm, dict):
167
+ fm = {}
168
+ except yaml.YAMLError:
169
+ fm = {}
170
+ return FrontmatterDoc(frontmatter=fm, body=body)
171
+
172
+
173
+ def render_frontmatter(fm: dict[str, Any], body: str) -> str:
174
+ """Inverse of parse_frontmatter — emit ``---\\n...\\n---\\n<body>``."""
175
+ if not fm:
176
+ return body
177
+ fm_text = yaml.safe_dump(fm, sort_keys=False, allow_unicode=True).rstrip()
178
+ return f"---\n{fm_text}\n---\n{body}"
179
+
180
+
181
+ # ---------------------------------------------------------------------------
182
+ # SKILL.md → Cursor MDC
183
+ # ---------------------------------------------------------------------------
184
+
185
+
186
+ def skill_md_to_cursor_mdc(skill_text: str, *, default_globs: Iterable[str] | None = None) -> str:
187
+ """Convert a Claude/Codex SKILL.md into a Cursor 1.7+ rules MDC file.
188
+
189
+ Cursor's MDC format is markdown with a ``description``, ``globs``,
190
+ and ``alwaysApply`` frontmatter. We map:
191
+
192
+ - ``name`` → kept as informational comment in the body
193
+ - ``description`` → ``description`` (verbatim)
194
+ - SKILL body → MDC body verbatim
195
+
196
+ ``default_globs`` defaults to Robot Framework file patterns so the
197
+ rule fires when the user opens a ``.robot`` or ``.resource`` file.
198
+ """
199
+ doc = parse_frontmatter(skill_text)
200
+ name = doc.frontmatter.get("name", "")
201
+ description = doc.frontmatter.get("description", "")
202
+ globs = list(default_globs or ["**/*.robot", "**/*.resource"])
203
+
204
+ new_fm = {
205
+ "description": str(description) if description else f"rf-agentskills/{name}",
206
+ "globs": globs,
207
+ "alwaysApply": False,
208
+ }
209
+ body = doc.body
210
+ if name:
211
+ body = f"<!-- rf-agentskills source: {name} -->\n{body}"
212
+ return render_frontmatter(new_fm, body)
213
+
214
+
215
+ # ---------------------------------------------------------------------------
216
+ # Subagent .md → Codex agent.toml
217
+ # ---------------------------------------------------------------------------
218
+
219
+
220
+ def subagent_md_to_codex_toml(agent_text: str) -> str:
221
+ """Convert a Claude Code subagent .md into Codex's agent.toml shape.
222
+
223
+ Codex's agent format requires three keys: ``name``, ``description``,
224
+ ``developer_instructions``. The Claude .md frontmatter has the first
225
+ two; we put the markdown body into ``developer_instructions``.
226
+
227
+ Optional Claude fields (``tools``, ``model``) are mapped to Codex's
228
+ ``mcp_servers`` / ``model`` where shapes match.
229
+ """
230
+ doc = parse_frontmatter(agent_text)
231
+ name = doc.frontmatter.get("name", "")
232
+ description = doc.frontmatter.get("description", "")
233
+ body = doc.body.lstrip("\n")
234
+
235
+ payload: dict[str, Any] = {
236
+ "name": str(name),
237
+ "description": str(description),
238
+ "developer_instructions": body,
239
+ }
240
+ if "model" in doc.frontmatter:
241
+ payload["model"] = str(doc.frontmatter["model"])
242
+
243
+ return tomli_w.dumps(payload)
244
+
245
+
246
+ # ---------------------------------------------------------------------------
247
+ # SKILL.md → OpenCode slash command
248
+ # ---------------------------------------------------------------------------
249
+
250
+
251
+ def skill_md_to_opencode_command(skill_text: str) -> str:
252
+ """Convert SKILL.md to an OpenCode slash-command markdown file.
253
+
254
+ OpenCode's command format wants ``description`` (and optional
255
+ ``agent``, ``model``) in frontmatter, then markdown body.
256
+ """
257
+ doc = parse_frontmatter(skill_text)
258
+ new_fm = {
259
+ "description": str(doc.frontmatter.get("description", "")),
260
+ }
261
+ return render_frontmatter(new_fm, doc.body)
262
+
263
+
264
+ # ---------------------------------------------------------------------------
265
+ # Hooks rewrites
266
+ # ---------------------------------------------------------------------------
267
+
268
+
269
+ def rewrite_hooks_for_cursor(hooks: dict[str, Any]) -> dict[str, Any]:
270
+ """Translate Claude Code hook events to Cursor 1.7+ event names.
271
+
272
+ Both schemas share the matcher-as-regex idea; the differences:
273
+
274
+ - Cursor uses lowercase event names (``preToolUse`` not ``PreToolUse``)
275
+ - Cursor uses namespaced tool matchers: ``Shell``, ``Read``, ``Write``,
276
+ ``MCP:<name>``, ``Edit`` (note: same name for built-in tools, but
277
+ ``mcp__rf-mcp__.*`` becomes ``MCP:rf-mcp``).
278
+ """
279
+ name_map = {
280
+ "PreToolUse": "preToolUse",
281
+ "PostToolUse": "postToolUse",
282
+ "UserPromptSubmit": "beforeSubmitPrompt",
283
+ "SessionStart": "sessionStart",
284
+ "SessionEnd": "sessionEnd",
285
+ "Stop": "stop",
286
+ "PreCompact": "preCompact",
287
+ "SubagentStart": "subagentStart",
288
+ "SubagentStop": "subagentStop",
289
+ }
290
+ out: dict[str, Any] = {}
291
+ for k, v in hooks.items():
292
+ new_key = name_map.get(k, k)
293
+ out[new_key] = _rewrite_hook_entries(v)
294
+ return out
295
+
296
+
297
+ _MCP_PATTERN_RE = re.compile(r"^mcp__(?P<server>[A-Za-z0-9_-]+)__")
298
+
299
+
300
+ def _rewrite_hook_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
301
+ """Per-entry rewrite: namespace MCP matchers, leave others alone."""
302
+ out: list[dict[str, Any]] = []
303
+ for entry in entries:
304
+ new_entry = dict(entry)
305
+ matcher = entry.get("matcher", "")
306
+ if matcher:
307
+ new_entry["matcher"] = _namespace_matcher(matcher)
308
+ out.append(new_entry)
309
+ return out
310
+
311
+
312
+ def _namespace_matcher(matcher: str) -> str:
313
+ """Convert ``mcp__rf-mcp__execute_step`` → ``MCP:rf-mcp:execute_step``."""
314
+ m = _MCP_PATTERN_RE.match(matcher)
315
+ if not m:
316
+ return matcher
317
+ server = m.group("server")
318
+ rest = matcher[m.end():]
319
+ if rest in ("", ".*"):
320
+ return f"MCP:{server}"
321
+ return f"MCP:{server}:{rest}"
322
+
323
+
324
+ # ---------------------------------------------------------------------------
325
+ # JSON / TOML / YAML config merges
326
+ # ---------------------------------------------------------------------------
327
+
328
+
329
+ def merge_json_file(path: Path, key: str, value: Any) -> list[str]:
330
+ """Set ``key`` in the JSON object at ``path`` to ``value``.
331
+
332
+ Creates the file (with ``{key: value}``) if it doesn't exist. Adds
333
+ or replaces the top-level key without disturbing siblings. Returns
334
+ the list of top-level keys that were newly added (used for
335
+ manifest tracking — uninstall removes only those).
336
+ """
337
+ if path.is_file():
338
+ try:
339
+ data = json.loads(path.read_text(encoding="utf-8"))
340
+ if not isinstance(data, dict):
341
+ data = {}
342
+ except (OSError, json.JSONDecodeError):
343
+ data = {}
344
+ else:
345
+ data = {}
346
+ pre_keys = set(data.keys())
347
+ data[key] = value
348
+ path.parent.mkdir(parents=True, exist_ok=True)
349
+ path.write_text(json.dumps(data, indent=2), encoding="utf-8")
350
+ return [k for k in data if k not in pre_keys]
351
+
352
+
353
+ def remove_json_keys(path: Path, keys: list[str]) -> None:
354
+ """Delete each top-level ``keys[i]`` from the JSON at ``path``.
355
+
356
+ No-op if file is missing or unparseable. Writes back only the
357
+ remaining keys (preserving order).
358
+ """
359
+ remove_json_keys_at_path(path, key_path=[], keys=keys)
360
+
361
+
362
+ def remove_json_keys_at_path(path: Path, key_path: list[str], keys: list[str]) -> None:
363
+ """Delete ``keys`` from the JSON object found at ``key_path`` in ``path``.
364
+
365
+ Used by uninstall for nested merges (e.g. ``mcpServers`` in
366
+ ``~/.mcp.json``). After deletion, if the parent object becomes
367
+ empty *and* it was nested, pop it from its grandparent too. If the
368
+ file ends up empty (``{}``), remove it.
369
+ """
370
+ if not path.is_file():
371
+ return
372
+ try:
373
+ data = json.loads(path.read_text(encoding="utf-8"))
374
+ except (OSError, json.JSONDecodeError):
375
+ return
376
+ if not isinstance(data, dict):
377
+ return
378
+ parent = data
379
+ for k in key_path:
380
+ nxt = parent.get(k)
381
+ if not isinstance(nxt, dict):
382
+ return # path doesn't exist; nothing to do
383
+ parent = nxt
384
+ for k in keys:
385
+ parent.pop(k, None)
386
+ # Walk back up: drop any now-empty intermediate dicts.
387
+ if not parent and key_path:
388
+ cursor = data
389
+ for k in key_path[:-1]:
390
+ cursor = cursor[k]
391
+ cursor.pop(key_path[-1], None)
392
+ if data:
393
+ path.write_text(json.dumps(data, indent=2), encoding="utf-8")
394
+ else:
395
+ try:
396
+ path.unlink()
397
+ except OSError:
398
+ pass
399
+
400
+
401
+ def merge_json_at_path(
402
+ path: Path, key_path: list[str], values: dict[str, Any]
403
+ ) -> list[str]:
404
+ """Add ``values`` to the dict at ``key_path`` inside the JSON file.
405
+
406
+ Like :func:`merge_json_file` but writes nested. Returns the keys
407
+ newly added at the leaf — the manifest records them so uninstall
408
+ knows what to drop. Creates intermediate dicts as needed.
409
+ """
410
+ if path.is_file():
411
+ try:
412
+ data = json.loads(path.read_text(encoding="utf-8"))
413
+ if not isinstance(data, dict):
414
+ data = {}
415
+ except (OSError, json.JSONDecodeError):
416
+ data = {}
417
+ else:
418
+ data = {}
419
+
420
+ cursor: dict[str, Any] = data
421
+ for k in key_path:
422
+ nxt = cursor.get(k)
423
+ if not isinstance(nxt, dict):
424
+ nxt = {}
425
+ cursor[k] = nxt
426
+ cursor = nxt
427
+
428
+ pre = set(cursor.keys())
429
+ cursor.update(values)
430
+ added = [k for k in values if k not in pre]
431
+
432
+ path.parent.mkdir(parents=True, exist_ok=True)
433
+ path.write_text(json.dumps(data, indent=2), encoding="utf-8")
434
+ return added
435
+
436
+
437
+ def _load_json_object(path: Path) -> dict[str, Any]:
438
+ """Read ``path`` as a JSON object, returning ``{}`` on any problem."""
439
+ if path.is_file():
440
+ try:
441
+ data = json.loads(path.read_text(encoding="utf-8"))
442
+ if not isinstance(data, dict):
443
+ return {}
444
+ return data
445
+ except (OSError, json.JSONDecodeError):
446
+ return {}
447
+ return {}
448
+
449
+
450
+ def _hook_group_owned(group: Any, marker: str) -> bool:
451
+ """True if a hook matcher-group was installed by rf-agentskills.
452
+
453
+ Ownership is identified by the install-dir ``marker`` appearing in any
454
+ of the group's hook commands (every rf-agentskills hook command
455
+ references its ``rf-agentskills-files`` install dir). This avoids
456
+ polluting the hook schema with a sentinel field and reuses the exact
457
+ path already recorded in the manifest.
458
+ """
459
+ if not isinstance(group, dict):
460
+ return False
461
+ for h in group.get("hooks", []) or []:
462
+ if isinstance(h, dict) and marker and marker in str(h.get("command", "")):
463
+ return True
464
+ return False
465
+
466
+
467
+ def merge_hooks_block(
468
+ path: Path,
469
+ events_value: dict[str, Any],
470
+ *,
471
+ marker: str,
472
+ top_key: str = "hooks",
473
+ legacy_markers: tuple[str, ...] = (),
474
+ ) -> list[str]:
475
+ """Granularly merge rf-agentskills hook entries into ``path``.
476
+
477
+ Claude Code ``settings.json`` (and Cursor ``hooks.json``) store hooks
478
+ as ``{top_key: {<Event>: [ {matcher, hooks:[...]} , ... ]}}``. Unlike a
479
+ whole-key replace, this:
480
+
481
+ * appends rf-agentskills' matcher-groups to each event **without
482
+ touching** groups owned by the user or other tools, and
483
+ * is **idempotent / update-safe**: any previously rf-agentskills-owned
484
+ group (identified by ``marker``) is dropped first, then the current
485
+ groups are appended — so a re-install never duplicates or strands
486
+ stale entries.
487
+
488
+ ``legacy_markers`` are install dirs of earlier layouts (``rf-agentskills-files``
489
+ before the plugin split): their groups are dropped from every event, so an
490
+ upgrade leaves no hook pointing at scripts that are gone.
491
+
492
+ Returns the list of event names rf-agentskills contributed to (recorded
493
+ in the manifest so uninstall knows which events to clean).
494
+ """
495
+ data = _load_json_object(path)
496
+ block = data.get(top_key)
497
+ if not isinstance(block, dict):
498
+ block = {}
499
+ for event in list(block):
500
+ groups = block[event]
501
+ if not isinstance(groups, list):
502
+ continue
503
+ kept = [g for g in groups if not any(_hook_group_owned(g, m) for m in legacy_markers)]
504
+ if kept:
505
+ block[event] = kept
506
+ else:
507
+ block.pop(event)
508
+
509
+ touched: list[str] = []
510
+ for event, groups in events_value.items():
511
+ existing = block.get(event)
512
+ if not isinstance(existing, list):
513
+ existing = []
514
+ kept = [g for g in existing if not _hook_group_owned(g, marker)]
515
+ kept.extend(groups)
516
+ block[event] = kept
517
+ touched.append(event)
518
+
519
+ data[top_key] = block
520
+ path.parent.mkdir(parents=True, exist_ok=True)
521
+ path.write_text(json.dumps(data, indent=2), encoding="utf-8")
522
+ return touched
523
+
524
+
525
+ def remove_owned_hook_entries(
526
+ path: Path,
527
+ *,
528
+ marker: str,
529
+ events: list[str],
530
+ top_key: str = "hooks",
531
+ ) -> None:
532
+ """Inverse of :func:`merge_hooks_block` — remove only our hook groups.
533
+
534
+ For each recorded event, drops only matcher-groups owned by ``marker``;
535
+ foreign and user-authored groups are preserved. Prunes an event list
536
+ that becomes empty, prunes ``top_key`` if it becomes empty, and deletes
537
+ the file only if the whole document becomes ``{}`` (so a shared file
538
+ with other top-level keys or foreign hooks is retained).
539
+ """
540
+ if not path.is_file():
541
+ return
542
+ data = _load_json_object(path)
543
+ block = data.get(top_key)
544
+ if not isinstance(block, dict):
545
+ return
546
+ for event in events:
547
+ groups = block.get(event)
548
+ if not isinstance(groups, list):
549
+ continue
550
+ kept = [g for g in groups if not _hook_group_owned(g, marker)]
551
+ if kept:
552
+ block[event] = kept
553
+ else:
554
+ block.pop(event, None)
555
+ if not block:
556
+ data.pop(top_key, None)
557
+ if data:
558
+ path.write_text(json.dumps(data, indent=2), encoding="utf-8")
559
+ else:
560
+ try:
561
+ path.unlink()
562
+ except OSError:
563
+ pass
564
+
565
+
566
+ def merge_toml_table(path: Path, table_path: list[str], value: Any) -> list[str]:
567
+ """Set ``[a.b.c]`` to ``value`` in the TOML at ``path`` (round-trip).
568
+
569
+ Returns the list of newly-added top-level keys for manifest
570
+ tracking. Uses tomli-w which preserves nothing — for richer
571
+ round-trip with comments we'd need tomlkit; the cost in deps isn't
572
+ worth it for our lean install footprint.
573
+ """
574
+ if path.is_file():
575
+ try:
576
+ data = tomllib.loads(path.read_text(encoding="utf-8"))
577
+ except (OSError, tomllib.TOMLDecodeError):
578
+ data = {}
579
+ else:
580
+ data = {}
581
+ if not isinstance(data, dict):
582
+ data = {}
583
+ pre_top_keys = set(data.keys())
584
+ cursor: dict[str, Any] = data
585
+ for k in table_path[:-1]:
586
+ nxt = cursor.get(k)
587
+ if not isinstance(nxt, dict):
588
+ nxt = {}
589
+ cursor[k] = nxt
590
+ cursor = nxt
591
+ cursor[table_path[-1]] = value
592
+ path.parent.mkdir(parents=True, exist_ok=True)
593
+ path.write_text(tomli_w.dumps(data), encoding="utf-8")
594
+ return [k for k in data if k not in pre_top_keys]
595
+
596
+
597
+ def remove_toml_table(path: Path, table_path: list[str]) -> None:
598
+ """Inverse of merge_toml_table — drop the nested table.
599
+
600
+ Walks back up the path and removes any intermediate dicts that
601
+ become empty (``[mcp_servers.rf-tools]`` removal also drops the
602
+ empty ``[mcp_servers]`` parent so the file doesn't accumulate
603
+ useless headers). Removes the file entirely if the document ends
604
+ up empty.
605
+ """
606
+ if not path.is_file():
607
+ return
608
+ try:
609
+ data = tomllib.loads(path.read_text(encoding="utf-8"))
610
+ except (OSError, tomllib.TOMLDecodeError):
611
+ return
612
+
613
+ # Walk to the leaf's parent, recording the chain so we can prune.
614
+ chain: list[dict[str, Any]] = [data]
615
+ for k in table_path[:-1]:
616
+ nxt = chain[-1].get(k)
617
+ if not isinstance(nxt, dict):
618
+ return
619
+ chain.append(nxt)
620
+ chain[-1].pop(table_path[-1], None)
621
+
622
+ # Walk back up: drop any now-empty intermediate dicts.
623
+ for i in range(len(chain) - 1, 0, -1):
624
+ if chain[i]:
625
+ break
626
+ chain[i - 1].pop(table_path[i - 1], None)
627
+
628
+ if data:
629
+ path.write_text(tomli_w.dumps(data), encoding="utf-8")
630
+ else:
631
+ try:
632
+ path.unlink()
633
+ except OSError:
634
+ pass
635
+
636
+
637
+ def merge_yaml_block(path: Path, key: str, value: Any) -> list[str]:
638
+ """Set ``key`` in the YAML mapping at ``path`` to ``value``.
639
+
640
+ Used for Goose's ``~/.config/goose/config.yaml`` extensions block.
641
+ Round-trips comments only at the limit of pyyaml's ``safe_dump``
642
+ (it doesn't preserve comments — fine for our use).
643
+ """
644
+ if path.is_file():
645
+ try:
646
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
647
+ if not isinstance(data, dict):
648
+ data = {}
649
+ except yaml.YAMLError:
650
+ data = {}
651
+ else:
652
+ data = {}
653
+ pre_keys = set(data.keys())
654
+ if isinstance(data.get(key), dict) and isinstance(value, dict):
655
+ data[key] = {**data[key], **value}
656
+ else:
657
+ data[key] = value
658
+ path.parent.mkdir(parents=True, exist_ok=True)
659
+ path.write_text(
660
+ yaml.safe_dump(data, sort_keys=False, allow_unicode=True),
661
+ encoding="utf-8",
662
+ )
663
+ return [k for k in data if k not in pre_keys]
664
+
665
+
666
+ def remove_yaml_keys(path: Path, keys: list[str], parent_key: str | None = None) -> None:
667
+ """Drop ``keys`` either at top-level or under a given ``parent_key``."""
668
+ if not path.is_file():
669
+ return
670
+ try:
671
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
672
+ except yaml.YAMLError:
673
+ return
674
+ target = data.get(parent_key) if parent_key else data
675
+ if not isinstance(target, dict):
676
+ return
677
+ for k in keys:
678
+ target.pop(k, None)
679
+ if not target and parent_key:
680
+ data.pop(parent_key, None)
681
+ if data:
682
+ path.write_text(
683
+ yaml.safe_dump(data, sort_keys=False, allow_unicode=True),
684
+ encoding="utf-8",
685
+ )
686
+ else:
687
+ try:
688
+ path.unlink()
689
+ except OSError:
690
+ pass
691
+
692
+
693
+ # ---------------------------------------------------------------------------
694
+ # Path utilities
695
+ # ---------------------------------------------------------------------------
696
+
697
+
698
+ def to_native_path_string(path: Path) -> str:
699
+ """Return ``path`` as a string safe to embed in substituted text.
700
+
701
+ On POSIX this is just ``str(path)``. On Windows the path is rendered
702
+ with **forward slashes** rather than backslashes — e.g.
703
+ ``C:/Users/x/.claude/rf-agentskills-files`` not
704
+ ``C:\\Users\\x\\.claude\\rf-agentskills-files``.
705
+
706
+ Why forward slashes on Windows:
707
+
708
+ * Every consumer of substituted ``${CLAUDE_PLUGIN_ROOT}`` values
709
+ runs the result through a JSON / TOML / YAML parser at some
710
+ point (Claude Code's ``settings.json`` hooks block, ``.mcp.json``,
711
+ Codex's ``config.toml``, Cursor's ``mcp.json``, OpenCode's
712
+ ``opencode.json``, Claude Desktop's ``claude_desktop_config.json``).
713
+ Backslashes in those formats need escaping (``\\\\``), and bare
714
+ Windows paths inserted via substitution produce ``Invalid \\escape``
715
+ decode errors. Forward slashes don't need escaping in any of
716
+ those formats.
717
+ * Every supported Windows tool (Claude Code, Codex CLI, PowerShell,
718
+ Python ``pathlib``, Node ``child_process``) accepts forward-slash
719
+ paths.
720
+
721
+ Regression history: docs/archive/issues/win-powershell-install-fix-proposal.md.
722
+ """
723
+ if sys.platform == "win32":
724
+ return PureWindowsPath(path).as_posix()
725
+ return str(path)