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,120 @@
1
+ """Locate and read the bundled plugin tree at runtime.
2
+
3
+ The bundle lives at ``robotframework_plugins/_assets/`` inside the installed
4
+ wheel. We use ``importlib.resources.files`` (3.9+, stable in 3.12) so
5
+ the same code path works under:
6
+
7
+ * normal pip / pipx wheel installs
8
+ * PEP 660 editable installs
9
+ * zipapp / PyInstaller frozen builds
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ from contextlib import contextmanager
16
+ from importlib.resources import as_file, files
17
+ from pathlib import Path
18
+ from typing import Any, Iterator
19
+
20
+ # Resource root inside the installed package. The build hook copies each
21
+ # bundled plugin to ``_assets/plugins/<name>/`` and writes
22
+ # ``_assets/catalog.json`` at wheel time.
23
+ _ASSETS_RESOURCE_NAME = "_assets"
24
+ #: The plugin an adapter plans when no other is named (tests, old callers):
25
+ #: ``rf-core`` ships the hooks and the subagents every install needs.
26
+ DEFAULT_PLUGIN = "rf-core"
27
+
28
+
29
+ def bundle_root_traversable():
30
+ """Return the whole bundle (catalogue plus plugins) as an importlib Traversable."""
31
+ return files("robotframework_plugins").joinpath(_ASSETS_RESOURCE_NAME)
32
+
33
+
34
+ def asset_root_traversable(plugin: str = DEFAULT_PLUGIN):
35
+ """Return one bundled plugin tree as an importlib Traversable."""
36
+ return bundle_root_traversable().joinpath("plugins", plugin)
37
+
38
+
39
+ @contextmanager
40
+ def asset_root_path(plugin: str = DEFAULT_PLUGIN) -> Iterator[Path]:
41
+ """Yield one bundled plugin tree as a real ``Path``.
42
+
43
+ ``importlib.resources.as_file`` extracts the resource into a
44
+ temporary directory if it lives inside a zip / wheel; for normal
45
+ on-disk installs (the common case) it returns the path directly.
46
+ """
47
+ with as_file(asset_root_traversable(plugin)) as p:
48
+ yield Path(p)
49
+
50
+
51
+ def asset_files(*subpath_parts: str, plugin: str = DEFAULT_PLUGIN) -> Iterator[Path]:
52
+ """Yield every file under ``_assets/plugins/<plugin>/<subpath>`` as a Path.
53
+
54
+ Recurses into subdirectories. Useful for adapters that want to
55
+ walk a category like ``skills/`` or ``agents/``.
56
+ """
57
+ with asset_root_path(plugin) as root:
58
+ target = root.joinpath(*subpath_parts)
59
+ if not target.exists():
60
+ return
61
+ if target.is_file():
62
+ yield target
63
+ return
64
+ for child in sorted(target.rglob("*")):
65
+ if child.is_file():
66
+ yield child
67
+
68
+
69
+ def bundled_catalog() -> list[dict[str, Any]]:
70
+ """The bundled plugins: name, version, tier, status, summary, libraries, ...
71
+
72
+ Empty when the bundle has no catalogue (a broken build).
73
+ """
74
+ try:
75
+ text = bundle_root_traversable().joinpath("catalog.json").read_text(encoding="utf-8")
76
+ except (FileNotFoundError, OSError):
77
+ return []
78
+ return list(json.loads(text).get("plugins", []))
79
+
80
+
81
+ def is_bundle(entry: dict[str, Any]) -> bool:
82
+ """A catalogue entry with no content of its own (``rf-agentskills`` since 4.0.0)."""
83
+ return bool(entry.get("bundle"))
84
+
85
+
86
+ def expand_bundles(names: list[str], catalog: list[dict[str, Any]]) -> list[str]:
87
+ """``names`` with every bundle replaced by the plugins it bundles.
88
+
89
+ File mode copies content per plugin: installing the bundle means
90
+ installing the plugins it ships a copy of. Order is kept; duplicates are dropped."""
91
+ by_name = {p["name"]: p for p in catalog}
92
+ out: list[str] = []
93
+
94
+ def add(name: str, seen: frozenset[str]) -> None:
95
+ entry = by_name.get(name, {})
96
+ if is_bundle(entry) and name not in seen:
97
+ for dep in entry.get("bundled", []):
98
+ add(dep, seen | {name})
99
+ elif name not in out:
100
+ out.append(name)
101
+
102
+ for name in names:
103
+ add(name, frozenset())
104
+ return out
105
+
106
+
107
+ def content_plugins() -> tuple[str, ...]:
108
+ """Every active plugin with content in the bundled catalogue (what a plan
109
+ covers when the caller names none); ``(DEFAULT_PLUGIN,)`` without a catalogue."""
110
+ names = [p["name"] for p in bundled_catalog() if p.get("status") == "active" and not is_bundle(p)]
111
+ if DEFAULT_PLUGIN in names: # rf-core first: the others depend on it
112
+ names.remove(DEFAULT_PLUGIN)
113
+ names.insert(0, DEFAULT_PLUGIN)
114
+ return tuple(names) or (DEFAULT_PLUGIN,)
115
+
116
+
117
+ def relative_to_assets(path: Path, plugin: str = DEFAULT_PLUGIN) -> Path:
118
+ """Compute ``path`` relative to the plugin's asset root, raising if outside."""
119
+ with asset_root_path(plugin) as root:
120
+ return path.resolve().relative_to(root.resolve())
@@ -0,0 +1,123 @@
1
+ """Build catalogue entries from plugin folders.
2
+
3
+ Shared by the wheel's build hook (``hatch_build.py`` loads this file by path,
4
+ because the package isn't importable at build time) and by ``bundle.fetch()``,
5
+ which builds the catalogue of a downloaded repository snapshot. Both must
6
+ produce the same entries, so the rules live here once.
7
+
8
+ Only the standard library and PyYAML (a package dependency) are used.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ import yaml
18
+
19
+ #: Version of the catalogue's shape (``catalog.json`` ``format``). Bumped only
20
+ #: on a breaking change to the documented entry fields; see the README's
21
+ #: "Python API" section.
22
+ CATALOG_FORMAT = 1
23
+ #: Statuses that are bundled; ``removed`` plugins stay out.
24
+ BUNDLED_STATUSES = ("active", "deprecated")
25
+ #: A plugin's own top-level folders that are for this repository's CI, not for
26
+ #: users. Skills ship example ``tests/`` folders too, so only the plugin root.
27
+ PLUGIN_ONLY_DIRS = frozenset({"tests", "evals"})
28
+ _REQUIRED_MANIFEST = ("tier", "status", "summary")
29
+
30
+
31
+ class CatalogError(ValueError):
32
+ """A plugin folder whose manifest can't be turned into a catalogue entry."""
33
+
34
+
35
+ def has_content(plugin_dir: Path) -> bool:
36
+ """Ships a skill, a subagent or a hook."""
37
+ return (any((s / "SKILL.md").is_file() for s in (plugin_dir / "skills").glob("*"))
38
+ or any((plugin_dir / "agents").glob("*.md"))
39
+ or (plugin_dir / "hooks" / "hooks.json").is_file())
40
+
41
+
42
+ def _manifest(plugin_dir: Path) -> dict[str, Any]:
43
+ path = plugin_dir / "catalog.yaml"
44
+ if not path.is_file():
45
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml missing; run scripts/build-catalog.py --check")
46
+ try:
47
+ m = yaml.safe_load(path.read_text(encoding="utf-8"))
48
+ except yaml.YAMLError as exc:
49
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml is not valid YAML ({exc})") from exc
50
+ if not isinstance(m, dict):
51
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml is not a mapping")
52
+ missing = [k for k in _REQUIRED_MANIFEST if not m.get(k)]
53
+ if missing:
54
+ raise CatalogError(f"{plugin_dir.name}: catalog.yaml lacks {', '.join(missing)}")
55
+ return m
56
+
57
+
58
+ def _plugin_json(plugin_dir: Path) -> dict[str, Any]:
59
+ path = plugin_dir / ".claude-plugin" / "plugin.json"
60
+ if not path.is_file():
61
+ raise CatalogError(f"{plugin_dir.name}: .claude-plugin/plugin.json missing")
62
+ try:
63
+ pj = json.loads(path.read_text(encoding="utf-8"))
64
+ except json.JSONDecodeError as exc:
65
+ raise CatalogError(f"{plugin_dir.name}: plugin.json is not valid JSON ({exc})") from exc
66
+ if not isinstance(pj, dict) or not pj.get("version"):
67
+ raise CatalogError(f"{plugin_dir.name}: plugin.json lacks version")
68
+ return pj
69
+
70
+
71
+ def catalog_entries(plugins_dir: Path) -> list[dict[str, Any]]:
72
+ """One entry per bundled plugin under ``plugins_dir``, from its catalog.yaml and plugin.json."""
73
+ entries = []
74
+ for d in sorted(p for p in plugins_dir.iterdir() if p.is_dir()):
75
+ m = _manifest(d)
76
+ if m["status"] not in BUNDLED_STATUSES:
77
+ continue
78
+ pj = _plugin_json(d)
79
+ deps = [x if isinstance(x, str) else x["name"] for x in pj.get("dependencies", [])]
80
+ entry = {
81
+ "name": d.name,
82
+ "version": pj.get("version"),
83
+ "tier": m["tier"],
84
+ "status": m["status"],
85
+ "summary": m["summary"],
86
+ "libraries": m.get("libraries", []),
87
+ "robotframework": str(m.get("robotframework", "")),
88
+ "dependencies": deps,
89
+ # A bundle ships a copy of other plugins (catalog.yaml ``bundle``) and
90
+ # no content of its own; file mode installs those plugins instead.
91
+ "bundle": bool(m.get("bundle")) and not has_content(d),
92
+ "bundled": list(m.get("bundle", [])),
93
+ }
94
+ for key in ("replacement", "deprecated_since"):
95
+ if key in m:
96
+ entry[key] = str(m[key])
97
+ entries.append(entry)
98
+ return entries
99
+
100
+
101
+ def catalog_document(entries: list[dict[str, Any]]) -> str:
102
+ """The ``catalog.json`` text for ``entries``."""
103
+ return json.dumps({"format": CATALOG_FORMAT, "plugins": entries}, indent=2, ensure_ascii=False) + "\n"
104
+
105
+
106
+ #: The plugin listed first by ``skills_dirs()``: the others depend on it.
107
+ CORE_PLUGIN = "rf-core"
108
+
109
+
110
+ def skill_dirs(entries: list[dict[str, Any]], root: Path) -> dict[str, Path]:
111
+ """``{name: <root>/plugins/<name>/skills}`` for every active plugin in ``entries``
112
+ that isn't a bundle and has at least one ``*/SKILL.md``; ``rf-core`` first,
113
+ then catalogue order."""
114
+ names = [e["name"] for e in entries if e.get("status") == "active" and not e.get("bundle")]
115
+ if CORE_PLUGIN in names:
116
+ names.remove(CORE_PLUGIN)
117
+ names.insert(0, CORE_PLUGIN)
118
+ out: dict[str, Path] = {}
119
+ for name in names:
120
+ skills = root / "plugins" / name / "skills"
121
+ if any(skills.glob("*/SKILL.md")):
122
+ out[name] = skills.resolve()
123
+ return out
@@ -0,0 +1,320 @@
1
+ """Snapshots of the plugins at a ref of the repository (``bundle.fetch()``).
2
+
3
+ The only code in the package that uses the network, and only when
4
+ ``fetch()`` is called. The installer's commands never import it.
5
+
6
+ 1. Resolve the ref to a commit SHA (a full SHA is taken as is).
7
+ 2. Reuse ``<cache>/<sha>/`` when a finished snapshot in the running
8
+ catalogue format is there.
9
+ 3. Download the commit's archive from GitHub or the configured source, with a
10
+ timeout and size caps. A token goes only to the source's own host.
11
+ 4. Check every archive entry, and extract ``plugins/`` by hand: only regular
12
+ files and directories, no absolute paths, no ``..``.
13
+ 5. Build the catalogue with the wheel's rules (``_catalog``), then move the
14
+ finished folder into the cache in one step, replacing a stale one.
15
+
16
+ Nothing from the snapshot is imported or run.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import copy
22
+ import datetime as _dt
23
+ import http.client
24
+ import json
25
+ import os
26
+ import re
27
+ import shutil
28
+ import tarfile
29
+ import tempfile
30
+ import urllib.error
31
+ import urllib.parse
32
+ import urllib.request
33
+ import uuid
34
+ from dataclasses import dataclass
35
+ from pathlib import Path, PurePosixPath
36
+ from typing import Any
37
+
38
+ from . import __version__, _catalog
39
+
40
+ REPOSITORY = "MarketSquare/robotframework-plugins"
41
+ #: Base URLs of the default source; tests point them at a local server.
42
+ GITHUB_API = "https://api.github.com"
43
+ CODELOAD = "https://codeload.github.com"
44
+ #: Environment settings for a mirror and a token (README, "fetch() and the network").
45
+ SOURCE_ENV = "ROBOTFRAMEWORK_PLUGINS_SOURCE"
46
+ TOKEN_ENV = "ROBOTFRAMEWORK_PLUGINS_TOKEN"
47
+ _LOOPBACK = ("localhost", "127.0.0.1", "::1")
48
+ #: Caps on the compressed download and on what it may expand to.
49
+ MAX_ARCHIVE_BYTES = 64 * 1024 * 1024
50
+ MAX_EXTRACTED_BYTES = 512 * 1024 * 1024
51
+ _SHA = re.compile(r"[0-9a-f]{40}")
52
+ _DONE = "snapshot.json"
53
+
54
+
55
+ class FetchError(RuntimeError):
56
+ """A snapshot couldn't be fetched or failed its checks; the cache is unchanged."""
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class Snapshot:
61
+ """The plugins at one commit of the repository, extracted in the cache."""
62
+
63
+ ref: str
64
+ commit: str
65
+ path: Path
66
+ #: Catalogue format the snapshot was built with; None for snapshots from before 2026.11.0.
67
+ catalog_format: int | None = None
68
+
69
+ def catalog(self) -> list[dict[str, Any]]:
70
+ """The snapshot's plugins (active and deprecated), as ``bundle.catalog()``."""
71
+ doc = json.loads((self.path / "catalog.json").read_text(encoding="utf-8"))
72
+ return copy.deepcopy(list(doc.get("plugins", [])))
73
+
74
+ def skills_dirs(self) -> dict[str, Path]:
75
+ """``{plugin: skills folder}`` of the snapshot, as ``bundle.skills_dirs()``."""
76
+ return _catalog.skill_dirs(self.catalog(), self.path)
77
+
78
+
79
+ def default_cache_dir() -> Path:
80
+ if os.name == "nt":
81
+ base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
82
+ else:
83
+ base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
84
+ return base / "robotframework-plugins" / "snapshots"
85
+
86
+
87
+ @dataclass(frozen=True)
88
+ class _Source:
89
+ """Where requests go: the default github.com, or a GitHub-compatible API."""
90
+
91
+ api: str
92
+ token: str | None
93
+ default: bool
94
+
95
+ @property
96
+ def where(self) -> str:
97
+ """`` at <host>`` for a configured source, for error messages; never the token."""
98
+ if self.default:
99
+ return ""
100
+ parts = urllib.parse.urlsplit(self.api) # hostname and port only: netloc may hold user:password
101
+ return f" at {parts.hostname}" + (f":{parts.port}" if parts.port else "")
102
+
103
+
104
+ def _source(source: str | None, token: str | None) -> _Source:
105
+ configured = (source if source is not None else os.environ.get(SOURCE_ENV, "")).strip().rstrip("/")
106
+ default = not configured
107
+ api = GITHUB_API if default else configured
108
+ if token is None:
109
+ # GITHUB_TOKEN is a GitHub credential: never send it to a mirror.
110
+ token = os.environ.get(TOKEN_ENV) or (os.environ.get("GITHUB_TOKEN") if default else None)
111
+ token = (token or "").strip() or None
112
+ parts = urllib.parse.urlsplit(api)
113
+ if parts.scheme not in ("http", "https") or not parts.hostname:
114
+ raise FetchError(f"source {api!r} is not an http(s) URL")
115
+ if token and parts.scheme == "http" and parts.hostname not in _LOOPBACK:
116
+ raise FetchError(f"refusing to send a token over plain HTTP to {parts.hostname}; use an https source")
117
+ return _Source(api=api, token=token, default=default)
118
+
119
+
120
+ def fetch(ref: str = "stable", *, source: str | None = None, token: str | None = None,
121
+ cache_dir: str | os.PathLike[str] | None = None, timeout: float = 30.0) -> Snapshot:
122
+ """Snapshot of the plugins at ``ref`` (branch, tag or full commit SHA) of the repository.
123
+
124
+ ``source`` is the base URL of a GitHub-compatible API (GitHub Enterprise,
125
+ an artifact manager's GitHub remote); default ``ROBOTFRAMEWORK_PLUGINS_SOURCE``,
126
+ then github.com. ``token`` is sent as a bearer token to that source only;
127
+ default ``ROBOTFRAMEWORK_PLUGINS_TOKEN``, then ``GITHUB_TOKEN`` for github.com.
128
+ ``token=""`` sends none. Raises :class:`FetchError` on any failure.
129
+ """
130
+ ref = str(ref).strip()
131
+ if not ref:
132
+ raise FetchError("ref is empty")
133
+ src = _source(source, token)
134
+ cache = Path(cache_dir) if cache_dir is not None else default_cache_dir()
135
+ sha = ref.lower() if _SHA.fullmatch(ref.lower()) else None
136
+ if sha is None:
137
+ sha = _resolve(ref, timeout, src)
138
+ hit = _cached(cache, sha, ref)
139
+ if hit is not None:
140
+ return hit
141
+ return _build(ref, sha, cache, timeout, src)
142
+
143
+
144
+ def _cached(cache: Path, sha: str, ref: str) -> Snapshot | None:
145
+ """A finished snapshot of ``sha`` in the running catalogue format, else None."""
146
+ folder = cache / sha
147
+ if not ((folder / _DONE).is_file() and (folder / "catalog.json").is_file()):
148
+ return None
149
+ try:
150
+ recorded = json.loads((folder / _DONE).read_text(encoding="utf-8")).get("catalog_format")
151
+ except (OSError, ValueError, AttributeError):
152
+ return None
153
+ if recorded != _catalog.CATALOG_FORMAT:
154
+ return None
155
+ return Snapshot(ref=ref, commit=sha, path=folder.resolve(), catalog_format=recorded)
156
+
157
+
158
+ def _request(url: str, accept: str, token: str | None = None) -> urllib.request.Request:
159
+ req = urllib.request.Request(url, headers={"Accept": accept, "User-Agent": f"robotframework-plugins/{__version__}"})
160
+ if token:
161
+ # Unredirected: urllib doesn't copy it to the host a redirect points to.
162
+ req.add_unredirected_header("Authorization", f"Bearer {token}")
163
+ return req
164
+
165
+
166
+ def _resolve(ref: str, timeout: float, src: _Source) -> str:
167
+ url = f"{src.api}/repos/{REPOSITORY}/commits/{urllib.parse.quote(ref, safe='/')}"
168
+ try:
169
+ with urllib.request.urlopen(_request(url, "application/vnd.github.sha", src.token), timeout=timeout) as resp:
170
+ body = resp.read(200).decode("ascii", "replace").strip()
171
+ except urllib.error.HTTPError as exc:
172
+ if exc.code in (404, 422):
173
+ hint = ("; it is created by the first plugin release, until then use 'latest' or a tag"
174
+ if ref == "stable" else "")
175
+ raise FetchError(f"ref {ref!r} not found in {REPOSITORY}{src.where}{hint}") from exc
176
+ raise FetchError(f"resolving ref {ref!r}{src.where} failed: HTTP {exc.code}") from exc
177
+ except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
178
+ raise FetchError(f"resolving ref {ref!r}{src.where} failed: {_reason(exc)}") from exc
179
+ if not _SHA.fullmatch(body):
180
+ raise FetchError(f"resolving ref {ref!r} returned no commit SHA")
181
+ return body
182
+
183
+
184
+ def _reason(exc: BaseException) -> str:
185
+ reason = getattr(exc, "reason", None) or exc
186
+ return f"{type(reason).__name__}: {reason}"
187
+
188
+
189
+ def _build(ref: str, sha: str, cache: Path, timeout: float, src: _Source) -> Snapshot:
190
+ try:
191
+ cache.mkdir(parents=True, exist_ok=True)
192
+ work = Path(tempfile.mkdtemp(prefix=f".tmp-{sha[:12]}-", dir=cache))
193
+ except OSError as exc:
194
+ raise FetchError(f"cache folder {cache} is not writable: {exc}") from exc
195
+ try:
196
+ archive = work / "archive.tar.gz"
197
+ _download(sha, archive, timeout, src)
198
+ snap = work / "snapshot"
199
+ _extract_plugins(archive, snap)
200
+ try:
201
+ entries = _catalog.catalog_entries(snap / "plugins")
202
+ except _catalog.CatalogError as exc:
203
+ raise FetchError(f"snapshot {sha[:12]}: {exc}") from exc
204
+ (snap / "catalog.json").write_text(_catalog.catalog_document(entries), encoding="utf-8")
205
+ (snap / _DONE).write_text(json.dumps({
206
+ "repository": REPOSITORY, "ref": ref, "commit": sha,
207
+ "fetched_at": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"), # noqa: UP017 (3.10)
208
+ "catalog_format": _catalog.CATALOG_FORMAT,
209
+ "built_by": f"robotframework-plugins {__version__}",
210
+ }, indent=2) + "\n", encoding="utf-8")
211
+ target = cache / sha
212
+ try:
213
+ _install(snap, target, cache, sha)
214
+ except OSError as exc:
215
+ # Another process finished the same snapshot first: use its folder.
216
+ hit = _cached(cache, sha, ref)
217
+ if hit is None:
218
+ raise FetchError(f"storing snapshot {sha[:12]} in {cache} failed: {exc}") from exc
219
+ return hit
220
+ return Snapshot(ref=ref, commit=sha, path=target.resolve(), catalog_format=_catalog.CATALOG_FORMAT)
221
+ finally:
222
+ shutil.rmtree(work, ignore_errors=True)
223
+
224
+
225
+ def _install(snap: Path, target: Path, cache: Path, sha: str) -> None:
226
+ """Move the finished ``snap`` to ``target``; a stale snapshot there goes only once the move worked."""
227
+ if _cached(cache, sha, "") is not None:
228
+ raise OSError("a current snapshot appeared meanwhile")
229
+ stale = None
230
+ if target.exists():
231
+ stale = cache / f".stale-{sha[:12]}-{uuid.uuid4().hex[:8]}"
232
+ os.replace(target, stale)
233
+ try:
234
+ os.replace(snap, target)
235
+ except OSError:
236
+ if stale is not None and not target.exists():
237
+ os.replace(stale, target)
238
+ stale = None
239
+ raise
240
+ finally:
241
+ if stale is not None:
242
+ shutil.rmtree(stale, ignore_errors=True)
243
+
244
+
245
+ def _download(sha: str, dest: Path, timeout: float, src: _Source) -> None:
246
+ # github.com: the public archive host needs no API quota and no token.
247
+ if src.default:
248
+ req = _request(f"{CODELOAD}/{REPOSITORY}/tar.gz/{sha}", "application/octet-stream")
249
+ else:
250
+ req = _request(f"{src.api}/repos/{REPOSITORY}/tarball/{sha}", "application/octet-stream", src.token)
251
+ size = 0
252
+ try:
253
+ with urllib.request.urlopen(req, timeout=timeout) as resp, \
254
+ dest.open("wb") as out:
255
+ while chunk := resp.read(1024 * 1024):
256
+ size += len(chunk)
257
+ if size > MAX_ARCHIVE_BYTES:
258
+ raise FetchError(f"archive of {sha[:12]} is larger than {MAX_ARCHIVE_BYTES // 2**20} MB")
259
+ out.write(chunk)
260
+ except urllib.error.HTTPError as exc:
261
+ raise FetchError(f"downloading {sha[:12]}{src.where} failed: HTTP {exc.code}") from exc
262
+ except (urllib.error.URLError, OSError, http.client.HTTPException) as exc:
263
+ raise FetchError(f"downloading {sha[:12]}{src.where} failed: {_reason(exc)}") from exc
264
+
265
+
266
+ def _safe_parts(name: str) -> tuple[str, ...]:
267
+ path = PurePosixPath(name.replace("\\", "/"))
268
+ parts = tuple(p for p in path.parts if p not in ("", "."))
269
+ if path.is_absolute() or ".." in parts or (parts and ":" in parts[0]):
270
+ raise FetchError(f"archive entry {name!r} leaves the snapshot folder")
271
+ return parts
272
+
273
+
274
+ def _extract_plugins(archive: Path, dest: Path) -> None:
275
+ """Check every entry, then write ``<top>/plugins/**`` (minus plugin tests/evals) to ``dest/plugins``."""
276
+ try:
277
+ with tarfile.open(archive, "r:gz") as tf:
278
+ members = tf.getmembers()
279
+ _check_members(members)
280
+ written = _write_plugins(tf, members, dest)
281
+ except (tarfile.TarError, EOFError) as exc:
282
+ raise FetchError(f"archive is not a readable gzip tarball: {exc}") from exc
283
+ except OSError as exc:
284
+ raise FetchError(f"extracting the archive failed: {exc}") from exc
285
+ if not written or not (dest / "plugins").is_dir():
286
+ raise FetchError("archive has no plugins/ folder")
287
+
288
+
289
+ def _check_members(members: list[tarfile.TarInfo]) -> None:
290
+ total = 0
291
+ for m in members:
292
+ _safe_parts(m.name)
293
+ if not (m.isfile() or m.isdir()):
294
+ raise FetchError(f"archive entry {m.name!r} is a link or a special file")
295
+ total += m.size if m.isfile() else 0
296
+ if total > MAX_EXTRACTED_BYTES:
297
+ raise FetchError(f"archive expands to more than {MAX_EXTRACTED_BYTES // 2**20} MB")
298
+
299
+
300
+ def _write_plugins(tf: tarfile.TarFile, members: list[tarfile.TarInfo], dest: Path) -> int:
301
+ written = 0
302
+ for m in members:
303
+ parts = _safe_parts(m.name)
304
+ # <top>/plugins/<plugin>/...; a plugin's own tests/ and evals/ stay out.
305
+ if len(parts) < 3 or parts[1] != "plugins":
306
+ continue
307
+ if len(parts) > 3 and parts[3] in _catalog.PLUGIN_ONLY_DIRS:
308
+ continue
309
+ target = dest.joinpath("plugins", *parts[2:])
310
+ if m.isdir():
311
+ target.mkdir(parents=True, exist_ok=True)
312
+ continue
313
+ src = tf.extractfile(m)
314
+ if src is None:
315
+ raise FetchError(f"archive entry {m.name!r} can't be read")
316
+ target.parent.mkdir(parents=True, exist_ok=True)
317
+ with src, target.open("wb") as out:
318
+ shutil.copyfileobj(src, out)
319
+ written += 1
320
+ return written
@@ -0,0 +1,53 @@
1
+ """Per-agent adapters.
2
+
3
+ Each adapter is a class that implements :class:`._base.Adapter` and is
4
+ registered in :data:`ALL_ADAPTERS`. The CLI dispatches by ``--agent
5
+ <name>`` to the matching entry.
6
+
7
+ Adding a new adapter: drop a new module under ``adapters/``, expose a
8
+ class implementing the protocol, append to ``ALL_ADAPTERS``.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from . import (
14
+ claude_code,
15
+ claude_desktop,
16
+ codex,
17
+ copilot,
18
+ cursor,
19
+ goose,
20
+ opencode,
21
+ )
22
+ from ._base import Adapter, InstallOptions, InstallTarget
23
+
24
+ ALL_ADAPTERS: tuple[type[Adapter], ...] = (
25
+ claude_code.ClaudeCodeAdapter,
26
+ copilot.CopilotAdapter,
27
+ codex.CodexAdapter,
28
+ cursor.CursorAdapter,
29
+ goose.GooseAdapter,
30
+ opencode.OpenCodeAdapter,
31
+ claude_desktop.ClaudeDesktopAdapter,
32
+ )
33
+
34
+
35
+ def by_name(name: str) -> type[Adapter] | None:
36
+ for cls in ALL_ADAPTERS:
37
+ if cls.name == name:
38
+ return cls
39
+ return None
40
+
41
+
42
+ def all_names() -> tuple[str, ...]:
43
+ return tuple(cls.name for cls in ALL_ADAPTERS)
44
+
45
+
46
+ __all__ = (
47
+ "Adapter",
48
+ "InstallOptions",
49
+ "InstallTarget",
50
+ "ALL_ADAPTERS",
51
+ "by_name",
52
+ "all_names",
53
+ )