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,400 @@
1
+ """Adapter protocol shared by every per-agent installer.
2
+
3
+ An adapter is a small class with three responsibilities:
4
+
5
+ 1. ``detect()`` — best-effort check for whether the target agent is
6
+ installed on this machine. Used by ``robotframework-plugins targets`` and to
7
+ gate ``install --all``.
8
+ 2. ``plan(opts)`` — produce a :class:`InstallPlan` describing every
9
+ file to write and every config-merge to perform. **No I/O** here so
10
+ that ``--dry-run`` can render the plan without side effects and
11
+ tests can assert on the plan structure.
12
+ 3. ``post_install(opts)`` — return a list of human-readable warnings or
13
+ next-step instructions printed after a successful install (e.g.
14
+ "enable preview flags X, Y").
15
+
16
+ The CLI's ``install`` flow is:
17
+
18
+ plan = adapter.plan(opts)
19
+ if --dry-run: render(plan); return
20
+ execute(plan) # writes files, performs merges
21
+ manifest.upsert(...) # records what we wrote
22
+ print(adapter.post_install(opts)) # nudges to user
23
+
24
+ Tests in ``tests/installer/test_adapter_*.py`` assert on plan structure
25
+ without ever touching real user homes.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import os
31
+ from dataclasses import dataclass, field
32
+ from pathlib import Path
33
+ from typing import Any, Callable, Iterable, Protocol
34
+
35
+ from .._assets import DEFAULT_PLUGIN, content_plugins
36
+
37
+
38
+ # ---------------------------------------------------------------------------
39
+ # Public types
40
+ # ---------------------------------------------------------------------------
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class InstallOptions:
45
+ """User-supplied flags passed to every adapter for one install run."""
46
+
47
+ scope: str = "project" # "project" (default) | "user"
48
+ project_dir: Path | None = None # project scope target; defaults to CWD
49
+ prefix: Path | None = None # override the install root (for tests / sandboxing)
50
+ what: frozenset[str] = field(
51
+ default_factory=lambda: frozenset({"skills", "agents", "hooks"})
52
+ )
53
+ dry_run: bool = False
54
+ force: bool = False # overwrite even when destination is user-modified
55
+ mode: str = "files" # "files" (copy the bundle) | "plugin" (point at the marketplace)
56
+ ref: str | None = None # plugin mode: pin the marketplace to this git ref / tag
57
+ # The bundled plugins this run installs, and the one an adapter's
58
+ # ``plan`` is planning right now (the CLI plans each in turn).
59
+ plugins: tuple[str, ...] = field(default_factory=content_plugins)
60
+ plugin: str = DEFAULT_PLUGIN
61
+ # True when ``--plugins`` named the plugins. Otherwise an upgrade keeps
62
+ # what the target already has (see ``upgrade_plugins``).
63
+ plugins_explicit: bool = False
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class InstallTarget:
68
+ """One file that should be written to ``dst`` (post-transform).
69
+
70
+ ``payload`` is the bytes that go to disk. ``transform_name`` is a
71
+ string label (e.g. ``"skill_md_to_cursor_mdc"``) recorded in the
72
+ manifest for traceability — uninstall doesn't *use* it, but it
73
+ makes ``robotframework-plugins list --verbose`` informative.
74
+
75
+ Marking ``executable=True`` makes the dispatcher chmod +x after
76
+ write (no-op on Windows; harmless).
77
+ """
78
+
79
+ dst: Path
80
+ payload: bytes
81
+ transform_name: str | None = None
82
+ executable: bool = False
83
+ plugin: str | None = None # bundled plugin the file comes from (set by the CLI)
84
+
85
+
86
+ @dataclass(frozen=True)
87
+ class ConfigMergeOp:
88
+ """A merge into a pre-existing config file.
89
+
90
+ ``apply`` is a callable that performs the merge and returns the
91
+ list of keys it added at the location identified by ``key_path``.
92
+ The dispatcher records the result in the manifest's
93
+ ``config_merges`` so ``uninstall`` can later remove only those
94
+ keys, traversing into ``key_path`` first.
95
+
96
+ ``kind`` tags the file format so uninstall can dispatch to the
97
+ right remover (``json_top``, ``json_nested``, ``toml_table``,
98
+ ``yaml_block``). ``key_path`` is the parent traversal: ``()`` for
99
+ top-level merges, e.g. ``("mcpServers",)`` for nested merges into
100
+ ``mcpServers`` inside a ``.mcp.json`` file.
101
+
102
+ ``revert`` is the in-process reverse — adapters expose it for
103
+ transactional rollback in case ``apply`` later fails. Out-of-
104
+ process uninstall (``robotframework-plugins uninstall``) reconstructs
105
+ deletion from ``kind`` + ``key_path`` + recorded ``added_keys``
106
+ rather than calling this callback (it lives in the install
107
+ process only).
108
+ """
109
+
110
+ path: Path
111
+ description: str # human readable, shown in --dry-run output
112
+ apply: Callable[[], list[str]]
113
+ revert: Callable[[], None] # called by uninstall in same process
114
+ kind: str = "json_top"
115
+ key_path: tuple[str, ...] = ()
116
+ # For kind="json_hooks": the install-dir ownership marker so that
117
+ # out-of-process uninstall can remove only rf-agentskills-owned hook
118
+ # matcher-groups (see transforms.remove_owned_hook_entries).
119
+ marker: str | None = None
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class InstallPlan:
124
+ """Everything one adapter wants to do for a single install."""
125
+
126
+ targets: tuple[InstallTarget, ...] = ()
127
+ merges: tuple[ConfigMergeOp, ...] = ()
128
+ notes: tuple[str, ...] = () # "matched feature shipped but disabled" etc.
129
+
130
+
131
+ # ---------------------------------------------------------------------------
132
+ # Protocol — adapters implement this informally; we declare it for type checkers
133
+ # ---------------------------------------------------------------------------
134
+
135
+
136
+ class Adapter(Protocol):
137
+ """The contract every per-agent adapter satisfies.
138
+
139
+ Implemented as a Protocol rather than an ABC so adapters can be
140
+ plain classes; the CLI uses :class:`AdapterBase` for shared
141
+ helpers but adapters needn't subclass it.
142
+ """
143
+
144
+ name: str # short id, e.g. "claude-code", used by --agent
145
+ pretty: str # display name, e.g. "Claude Code"
146
+
147
+ def detect(self) -> bool: ...
148
+
149
+ def plan(self, opts: InstallOptions) -> InstallPlan: ...
150
+
151
+ def post_install(self, opts: InstallOptions) -> list[str]: ...
152
+
153
+
154
+ # ---------------------------------------------------------------------------
155
+ # Helpers shared by concrete adapters
156
+ # ---------------------------------------------------------------------------
157
+
158
+
159
+ class AdapterBase:
160
+ """Convenience base — adapters can subclass for shared helpers.
161
+
162
+ Not required (the protocol is structural) but eliminates a lot of
163
+ boilerplate in each adapter for things like "where is the install
164
+ root, with --prefix and --scope folded in".
165
+ """
166
+
167
+ name: str = "?"
168
+ pretty: str = "?"
169
+
170
+ # Whether the agent substitutes ${CLAUDE_SKILL_DIR} in SKILL.md content
171
+ # itself (Claude Code does). When False, installed skill text files get
172
+ # the absolute installed skill dir written in (transforms.substitute_skill_dir).
173
+ expands_skill_dir: bool = False
174
+
175
+ # Default user-config root if --prefix is not set. Overridden per
176
+ # adapter (e.g. ~/.claude or ~/.codex).
177
+ user_root_subpath: tuple[str, ...] = ()
178
+ project_root_subpath: tuple[str, ...] = (".claude",)
179
+
180
+ def install_root(self, opts: InstallOptions) -> Path:
181
+ """The base directory we write into for this install."""
182
+ if opts.prefix is not None:
183
+ return opts.prefix
184
+ if opts.scope == "project":
185
+ # project scope defaults to the current directory
186
+ project = opts.project_dir if opts.project_dir is not None else Path.cwd()
187
+ return project.joinpath(*self.project_root_subpath)
188
+ return Path.home().joinpath(*self.user_root_subpath)
189
+
190
+ @staticmethod
191
+ def filtered(items: Iterable[Any], what: frozenset[str], category: str) -> list[Any]:
192
+ """Filter helper for ``--what`` selectivity."""
193
+ return list(items) if category in what else []
194
+
195
+ def plugin_plan(self, opts: InstallOptions) -> InstallPlan | None:
196
+ """Plan for ``--mode plugin``; ``None`` means "no marketplace, copy files"."""
197
+ return None
198
+
199
+ def plugin_commands(self, opts: InstallOptions) -> list[list[str]]:
200
+ """Per-user commands plugin mode prints (and runs with ``--yes``)."""
201
+ return []
202
+
203
+ def render_skill_dir(self, payload: bytes, src: Path, skill_dir_dst: Path) -> bytes:
204
+ """Apply ``${CLAUDE_SKILL_DIR}`` substitution for non-expanding agents."""
205
+ from .. import transforms as _x # local import: transforms has no adapter deps
206
+
207
+ if self.expands_skill_dir or not _x.is_substitution_candidate(src):
208
+ return payload
209
+ return _x.substitute_skill_dir_bytes(
210
+ payload, _x.to_native_path_string(skill_dir_dst.resolve())
211
+ )
212
+
213
+
214
+ # ---------------------------------------------------------------------------
215
+ # Plugin mode (marketplace-distribution): point an agent at the marketplace
216
+ # ---------------------------------------------------------------------------
217
+
218
+ MARKETPLACE_NAME = "robotframework-plugins"
219
+ MARKETPLACE_REPO = "MarketSquare/robotframework-plugins"
220
+ #: The marketplace this one replaces; its settings entries are migrated on reinstall.
221
+ OLD_MARKETPLACE_NAME = "robotframework-agentskills"
222
+ OLD_MARKETPLACE_REPO = "manykarim/robotframework-agentskills"
223
+ PLUGIN_NAME = "rf-agentskills"
224
+ PLUGIN_ID = f"{PLUGIN_NAME}@{MARKETPLACE_NAME}"
225
+
226
+
227
+ def plugin_id(plugin: str) -> str:
228
+ """Install id of a bundled plugin in the marketplace: ``<plugin>@robotframework-plugins``."""
229
+ return f"{plugin}@{MARKETPLACE_NAME}"
230
+
231
+
232
+ def support_dir_name(plugin: str) -> str:
233
+ """Folder that holds a plugin's scripts, hooks and skill scripts in file mode."""
234
+ return f"{plugin}-files"
235
+
236
+
237
+ #: Support folders of earlier layouts: before the plugin split, rf-agentskills
238
+ #: held every hook script in ``rf-agentskills-files``.
239
+ LEGACY_SUPPORT_DIRS = ("rf-agentskills-files",)
240
+
241
+
242
+ def legacy_markers(plugin_root_abs: str) -> tuple[str, ...]:
243
+ """Hook ownership markers of the legacy support folders next to ``plugin_root_abs``."""
244
+ parent = plugin_root_abs.replace("\\", "/").rsplit("/", 1)[0]
245
+ return tuple(f"{parent}/{d}" for d in LEGACY_SUPPORT_DIRS if not plugin_root_abs.endswith(d))
246
+
247
+
248
+ #: Test hook: a local checkout to use as the marketplace instead of GitHub.
249
+ MARKETPLACE_DIR_ENV = "RF_AGENTSKILLS_MARKETPLACE_DIR"
250
+
251
+
252
+ def marketplace_source(ref: str | None) -> dict[str, Any]:
253
+ """``extraKnownMarketplaces`` source: GitHub (optionally pinned) or a local dir."""
254
+ local = os.environ.get(MARKETPLACE_DIR_ENV)
255
+ if local:
256
+ return {"source": "directory", "path": str(Path(local).resolve())}
257
+ source: dict[str, Any] = {"source": "github", "repo": MARKETPLACE_REPO}
258
+ if ref:
259
+ source["ref"] = ref
260
+ return source
261
+
262
+
263
+ def _old_marketplace_entry(settings_path: Path) -> dict[str, Any] | None:
264
+ """The ``robotframework-agentskills`` marketplace entry in ``settings_path``, if any.
265
+
266
+ Only an entry whose source is the old GitHub repository counts, so a
267
+ user's own marketplace that happens to share the name is left alone.
268
+ """
269
+ import json
270
+
271
+ try:
272
+ data = json.loads(settings_path.read_text(encoding="utf-8"))
273
+ except (OSError, ValueError):
274
+ return None
275
+ if not isinstance(data, dict) or not isinstance(data.get("extraKnownMarketplaces"), dict):
276
+ return None
277
+ entry = data["extraKnownMarketplaces"].get(OLD_MARKETPLACE_NAME)
278
+ if not isinstance(entry, dict):
279
+ return None
280
+ source = entry.get("source")
281
+ if not isinstance(source, dict) or source.get("repo") != OLD_MARKETPLACE_REPO:
282
+ return None
283
+ return entry
284
+
285
+
286
+ def old_marketplace_note(settings_path: Path) -> str | None:
287
+ """A note naming the migration, when ``settings_path`` holds the old entry."""
288
+ if _old_marketplace_entry(settings_path) is None:
289
+ return None
290
+ return (
291
+ f"{settings_path}: replaced the {OLD_MARKETPLACE_NAME} marketplace "
292
+ f"({OLD_MARKETPLACE_REPO}) with {MARKETPLACE_NAME} ({MARKETPLACE_REPO})."
293
+ )
294
+
295
+
296
+ def enabled_marketplace_plugins(settings_path: Path) -> list[str]:
297
+ """Plugins ``settings_path`` already enables from this marketplace; the old
298
+ ``rf-agentskills@robotframework-agentskills`` entry counts as the bundle."""
299
+ import json
300
+
301
+ try:
302
+ data = json.loads(settings_path.read_text(encoding="utf-8"))
303
+ except (OSError, ValueError):
304
+ return []
305
+ enabled = data.get("enabledPlugins") if isinstance(data, dict) else None
306
+ if not isinstance(enabled, dict):
307
+ return []
308
+ names: list[str] = []
309
+ for key, on in enabled.items():
310
+ name, _, market = str(key).partition("@")
311
+ if on and (market == MARKETPLACE_NAME or (market == OLD_MARKETPLACE_NAME and name == PLUGIN_NAME)):
312
+ if name not in names:
313
+ names.append(name)
314
+ return names
315
+
316
+
317
+ def upgrade_plugins(settings_path: Path, opts: InstallOptions) -> tuple[str, ...]:
318
+ """The plugins to enable in ``settings_path``: ``--plugins`` when given;
319
+ otherwise what the file already enables (an upgrade, so nothing the user
320
+ had disappears), else ``opts.plugins``."""
321
+ if opts.plugins_explicit:
322
+ return opts.plugins
323
+ return tuple(enabled_marketplace_plugins(settings_path)) or opts.plugins
324
+
325
+
326
+ def marketplace_settings_merges(
327
+ settings_path: Path, ref: str | None, plugins: Iterable[str] = (PLUGIN_NAME,)
328
+ ) -> list[ConfigMergeOp]:
329
+ """Merge ``extraKnownMarketplaces`` + ``enabledPlugins`` into a settings JSON.
330
+
331
+ The shape Claude Code, Copilot CLI and VS Code read from ``.claude/settings.json``
332
+ (Copilot also from ``.github/copilot/settings.json``). Each key is its own
333
+ ``json_nested`` merge, so uninstall removes exactly the entries we added.
334
+
335
+ When the file still holds the old ``robotframework-agentskills`` entries,
336
+ they are removed first, and the old entry's ``ref`` pin is kept unless
337
+ ``ref`` is given. The removal adds no keys, so uninstall has nothing of
338
+ it to undo.
339
+ """
340
+ from .. import transforms as _x
341
+
342
+ migrations: list[ConfigMergeOp] = []
343
+ old = _old_marketplace_entry(settings_path)
344
+ if old is not None:
345
+ if ref is None:
346
+ ref = old["source"].get("ref")
347
+
348
+ def drop_old() -> list[str]:
349
+ _x.remove_json_keys_at_path(settings_path, ["extraKnownMarketplaces"], [OLD_MARKETPLACE_NAME])
350
+ _x.remove_json_keys_at_path(
351
+ settings_path, ["enabledPlugins"], [f"{PLUGIN_NAME}@{OLD_MARKETPLACE_NAME}"])
352
+ return []
353
+
354
+ migrations.append(ConfigMergeOp(
355
+ path=settings_path,
356
+ description=f"replace marketplace {OLD_MARKETPLACE_NAME} in {settings_path}",
357
+ apply=drop_old,
358
+ revert=lambda: None,
359
+ kind="json_nested",
360
+ key_path=("extraKnownMarketplaces",),
361
+ ))
362
+
363
+ def op(key: str, values: dict[str, Any], what: str) -> ConfigMergeOp:
364
+ return ConfigMergeOp(
365
+ path=settings_path,
366
+ description=f"add {what} to {settings_path}",
367
+ apply=lambda: _x.merge_json_at_path(settings_path, [key], values),
368
+ revert=lambda: _x.remove_json_keys_at_path(settings_path, [key], list(values)),
369
+ kind="json_nested",
370
+ key_path=(key,),
371
+ )
372
+
373
+ return [
374
+ *migrations,
375
+ op("extraKnownMarketplaces", {MARKETPLACE_NAME: {"source": marketplace_source(ref)}},
376
+ f"marketplace {MARKETPLACE_NAME}"),
377
+ op("enabledPlugins", {plugin_id(p): True for p in plugins},
378
+ "enabled plugin(s) " + ", ".join(plugin_id(p) for p in plugins)),
379
+ ]
380
+
381
+
382
+ def needs_support_dir(src_root: Path) -> bool:
383
+ """A plugin needs a ``<plugin>-files`` folder only for hook scripts, hooks
384
+ or skill scripts; the technology plugins have none (split-rf-agentskills D7)."""
385
+ return ((src_root / "scripts").is_dir() or (src_root / "hooks" / "hooks.json").is_file()
386
+ or bool(skill_script_files(src_root)))
387
+
388
+
389
+ def skill_script_files(src_root: Path) -> list[Path]:
390
+ """Every file under ``skills/<skill>/scripts/`` of the bundled plugin tree.
391
+
392
+ Adapters that install hooks stage these under
393
+ ``rf-agentskills-files/skills/<skill>/scripts/`` too: the Stop hook runs
394
+ ``../skills/rf-results/scripts/rf_results.py`` relative to the hook
395
+ scripts, independent of where the agent's skills are installed.
396
+ """
397
+ return [
398
+ f for f in sorted(src_root.glob("skills/*/scripts/**/*"))
399
+ if f.is_file() and "__pycache__" not in f.parts
400
+ ]