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,517 @@
1
+ #!/usr/bin/env node
2
+ // validate_robot.mjs — Per-file static validation for Robot Framework
3
+ // .robot / .resource files.
4
+ //
5
+ // Runs from the PostToolUse hook after Write or Edit. Tiers:
6
+ //
7
+ // Tier 0 (errors): `robotcode --format json analyze code <file>` from the
8
+ // project root, so robot.toml, profiles, python-path and the installed
9
+ // libraries apply. Error-severity diagnostics are classified by code:
10
+ // - KeywordNotFound / VariableNotFound -> unresolved name: advisory on
11
+ // edit (the agent may be about to write it in another file); the file
12
+ // is recorded as pending and blocks at Stop if still unresolved.
13
+ // - any other error (ModelError, argument DataError, failed import, …)
14
+ // -> blocking error. The hook exits 2 and writes the diagnostic to
15
+ // stderr (Claude Code and Codex feed it back to the agent) and also
16
+ // prints {"decision":"block","reason":…} on stdout, the only channel
17
+ // Copilot CLI passes to its model.
18
+ // Warnings, infos and hints are dropped; each list shows at most 5
19
+ // diagnostics. With RF_AGENTSKILLS_STOP_RECHECK=1 (set by
20
+ // report_pending_errors.mjs) unresolved names block too and the advisory
21
+ // tiers are skipped. No robotcode, a timeout (20 s) or unparsable output =
22
+ // silence: a tool failure is never a finding.
23
+ //
24
+ // Tier 1 (deprecations, one Robocop pass classified by rule ID):
25
+ // `robocop check --no-cache` with the project's configured rule set and a
26
+ // pipe-separated issue format. Error findings are left to tier 0:
27
+ // - DEPR03/04/07/08/09/10/11 -> hard deprecation (advisory warning)
28
+ // - any other DEPR rule (DEPR05/06 …) -> modernization hint (advisory)
29
+ // - everything else (style rules) -> dropped
30
+ // Deprecations ONLY WARN: no DEPR finding ever causes exit 2. Findings on
31
+ // lines the edit touched are listed individually (hard first, each with the
32
+ // modern replacement), capped at 10 lines / 2,000 characters and not
33
+ // repeated within one session; other deprecations are counted per rule.
34
+ // RF_AGENTSKILLS_DEPRECATION_CHECK=off turns the deprecation output off;
35
+ // any other value (including a legacy `block`) means `warn`.
36
+ // No parsable line from a failing Robocop run = tool failure = silence.
37
+ //
38
+ // Tier 2 (opt-in, RF_AGENTSKILLS_FORMAT_CHECK=1, formatting drift):
39
+ // `robocop format --check --diff`. Informational additionalContext only.
40
+ // Off by default: a formatting diff leads the agent to reformat and
41
+ // re-check a file that is otherwise correct.
42
+ //
43
+ // Tier 3 (opt-in, RF_AGENTSKILLS_FILE_DRYRUN=1): `robotcode robot --dryrun`
44
+ // on the edited suite (.robot only, not __init__.robot) from the project
45
+ // root, so robot.toml and its profiles apply. Advisory context only.
46
+ //
47
+ // Advisory output (tiers 0-3) is written only when no exit-2 diagnostic is.
48
+ // A file with blocking errors or unresolved names is also recorded per session
49
+ // (_pending_errors.mjs) and cleared by its next clean run; report_pending_errors.mjs
50
+ // re-checks the recorded files at Stop. Every spawned process has a timeout
51
+ // (robotcode 20 s, Robocop 10 s, dry run 20 s, probes 5 s); a timeout skips
52
+ // that tier silently. `--no-cache` keeps Robocop from leaving a .robocop_cache/
53
+ // directory; robotcode keeps its normal .robotcode_cache/ (the warm cache makes
54
+ // the check take about a second).
55
+ //
56
+ // Input: the PostToolUse event JSON on stdin (legacy `TOOL_INPUT` env var as a
57
+ // fallback), in any agent's shape — see _hook_input.mjs (Claude Code, Copilot
58
+ // CLI, Cursor, VS Code, Codex). Non-edit tools exit silently; a patch that
59
+ // touches several .robot/.resource files is validated file by file. Tools: see
60
+ // _python_env.mjs (VIRTUAL_ENV -> <cwd>/.venv -> python_runtime.json -> PATH);
61
+ // robotcode, Robocop and Robot Framework are each optional — a missing tool
62
+ // makes its tier a silent no-op.
63
+ import { existsSync, readFileSync, writeFileSync } from "node:fs";
64
+ import { spawn, spawnSync } from "node:child_process";
65
+ import { createHash } from "node:crypto";
66
+ import { tmpdir } from "node:os";
67
+ import { basename, dirname, join, relative, isAbsolute } from "node:path";
68
+ import { fileURLToPath } from "node:url";
69
+ import { readHookInput } from "./_hook_input.mjs";
70
+ import { recordResult } from "./_pending_errors.mjs";
71
+ import { findInterpreterWith, findRobotcode, projectRoot, spawnOptions } from "./_python_env.mjs";
72
+
73
+ // Child processes still running; killed when the hook exits early.
74
+ const running = new Set();
75
+ const ANALYZE_TIMEOUT_MS = 20000;
76
+ const ROBOCOP_TIMEOUT_MS = 10000;
77
+ const DRYRUN_TIMEOUT_MS = 20000;
78
+ const MAX_LISTED = 10;
79
+ const MAX_DIAGNOSTICS = 5;
80
+ const MAX_CHARS = 2000;
81
+ // Diagnostics that may resolve once the agent writes the next file.
82
+ const UNRESOLVED_CODES = new Set(["KeywordNotFound", "VariableNotFound"]);
83
+ const STOP_RECHECK = /^(1|true|yes|on)$/i.test((process.env.RF_AGENTSKILLS_STOP_RECHECK ?? "").trim());
84
+
85
+ // Hard deprecations: listed first, with the modern replacement.
86
+ const HARD_DEPRECATIONS = {
87
+ DEPR03: "`WITH NAME` → use `AS`",
88
+ DEPR04: "singular section header → use the plural header (`*** Test Cases ***`, `*** Keywords ***`)",
89
+ DEPR07: "`Force Tags`/`Default Tags` → use `Test Tags` (and `[Tags] -tag`)",
90
+ DEPR08: "`Run Keyword If`/`Unless` → use `IF`/`ELSE`/`END`",
91
+ DEPR09: "`Exit For Loop`/`Continue For Loop` → use `BREAK`/`CONTINUE`",
92
+ DEPR10: "`Return From Keyword (If)` → use `RETURN` (inside `IF`)",
93
+ DEPR11: "`[Return]` → use `RETURN`",
94
+ };
95
+ // Modernization hints (RF 7 `VAR`); Robocop already gates them by RF version.
96
+ const HINTS = {
97
+ DEPR05: "`Set Test/Suite/Global Variable` → `VAR ${name} value scope=TEST|SUITE|GLOBAL` (RF 7+)",
98
+ DEPR06: "`Create List`/`Create Dictionary` → `VAR @{list}` / `VAR &{dict}` (RF 7+)",
99
+ };
100
+
101
+ const ISSUE_RE = /^([IWE])\|([A-Z]+\d+)\|(.+):(\d+):(\d+)\|(.*)$/;
102
+
103
+ function isTruthy(v) {
104
+ return /^(1|true|yes|on)$/i.test((v ?? "").toString().trim());
105
+ }
106
+
107
+ const input = readHookInput();
108
+ const event = input.event;
109
+ const robotFiles = input.isEdit
110
+ ? input.files.filter((f) => /\.(robot|resource)$/i.test(f) && existsSync(f))
111
+ : [];
112
+ if (!robotFiles.length) process.exit(0);
113
+ if (robotFiles.length > 1) validateEach(robotFiles);
114
+ const filePath = robotFiles[0];
115
+
116
+ /** Report real errors: stderr + exit 2, plus the decision JSON for Copilot. */
117
+ function reportErrors(text) {
118
+ const reason =
119
+ "The edit was applied, but Robot Framework validation found errors. Fix them:\n" + text.trim();
120
+ process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
121
+ process.stderr.write(text.endsWith("\n") ? text : text + "\n");
122
+ for (const child of running) child.kill("SIGKILL");
123
+ process.exit(2);
124
+ }
125
+
126
+ // One edit (an apply_patch) touched several files: validate each in a child run
127
+ // of this script, then report the merged result in the same exit-code contract.
128
+ function validateEach(files) {
129
+ const self = fileURLToPath(import.meta.url);
130
+ const errors = [];
131
+ const contexts = [];
132
+ for (const f of files) {
133
+ const child = { ...event, tool_name: "Write", tool_input: { file_path: f } };
134
+ delete child.tool_response;
135
+ delete child.tool_result;
136
+ const r = spawnSync(
137
+ process.execPath,
138
+ [self],
139
+ spawnOptions(ANALYZE_TIMEOUT_MS + ROBOCOP_TIMEOUT_MS * 2 + DRYRUN_TIMEOUT_MS, {
140
+ input: JSON.stringify(child), encoding: "utf-8", env: { ...process.env, TOOL_INPUT: "" },
141
+ }),
142
+ );
143
+ if (r.status === 2) errors.push((r.stderr ?? "").trim());
144
+ try {
145
+ const ctx = JSON.parse(r.stdout || "null")?.hookSpecificOutput?.additionalContext;
146
+ if (ctx) contexts.push(ctx);
147
+ } catch {
148
+ // no advisory output
149
+ }
150
+ }
151
+ if (errors.length) reportErrors(errors.join("\n"));
152
+ if (contexts.length) {
153
+ const payload = { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: contexts.join("\n\n") } };
154
+ process.stdout.write(JSON.stringify(payload) + "\n");
155
+ }
156
+ process.exit(0);
157
+ }
158
+
159
+ const cwd = projectRoot(event);
160
+ let fileLines = [];
161
+ try {
162
+ fileLines = readFileSync(filePath, "utf-8").split(/\r?\n/);
163
+ } catch {
164
+ process.exit(0);
165
+ }
166
+
167
+ // ── Touched lines (design D4) ───────────────────────────────────────────────
168
+ // Returns a Set of 1-based line numbers, or null for "all lines touched".
169
+ function touchedLines() {
170
+ const response = event?.tool_response;
171
+ const patch = response && Array.isArray(response.structuredPatch) ? response.structuredPatch : null;
172
+ // 1. structuredPatch: '+' lines of each hunk (Edit, Write update).
173
+ if (patch && patch.length) {
174
+ const set = new Set();
175
+ for (const hunk of patch) {
176
+ let line = Number(hunk?.newStart);
177
+ if (!Number.isInteger(line) || !Array.isArray(hunk?.lines)) return null;
178
+ for (const l of hunk.lines) {
179
+ const s = String(l);
180
+ if (s.startsWith("+")) {
181
+ set.add(line);
182
+ line += 1;
183
+ } else if (s.startsWith("-")) {
184
+ // removed line: no new-file line
185
+ } else if (s.startsWith("\\")) {
186
+ // ""
187
+ } else {
188
+ line += 1;
189
+ }
190
+ }
191
+ }
192
+ return set;
193
+ }
194
+ const toolName = (event?.tool_name ?? "").toString();
195
+ const newString = event?.tool_input?.new_string;
196
+ // 2. Edit without a patch: the spans where new_string occurs now.
197
+ if (/^(Edit|MultiEdit)$/.test(toolName) && typeof newString === "string" && newString.trim()) {
198
+ const text = fileLines.join("\n");
199
+ const set = new Set();
200
+ let from = 0;
201
+ for (;;) {
202
+ const idx = text.indexOf(newString, from);
203
+ if (idx < 0) break;
204
+ const start = text.slice(0, idx).split("\n").length;
205
+ const span = newString.split("\n").length;
206
+ for (let i = 0; i < span; i++) set.add(start + i);
207
+ from = idx + Math.max(newString.length, 1);
208
+ }
209
+ return set.size ? set : null;
210
+ }
211
+ // 3. Write (create, or no patch) and anything else: the whole file.
212
+ return null;
213
+ }
214
+
215
+ // ── Per-session dedupe marker (design D5) ───────────────────────────────────
216
+ const sessionId = (event?.session_id ?? "").toString();
217
+ const markerPath = sessionId
218
+ ? join(tmpdir(), `rf-agentskills-depr-${sessionId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`)
219
+ : "";
220
+
221
+ function loadSeen() {
222
+ if (!markerPath) return new Set();
223
+ try {
224
+ const data = JSON.parse(readFileSync(markerPath, "utf-8"));
225
+ return new Set(Array.isArray(data) ? data.map(String) : []);
226
+ } catch {
227
+ return new Set();
228
+ }
229
+ }
230
+
231
+ function saveSeen(seen) {
232
+ if (!markerPath) return;
233
+ try {
234
+ writeFileSync(markerPath, JSON.stringify([...seen].slice(-2000)));
235
+ } catch {
236
+ // Read-only temp dir etc. — only the dedupe is lost.
237
+ }
238
+ }
239
+
240
+ function findingKey(f) {
241
+ const text = (fileLines[f.line - 1] ?? "").trim();
242
+ return createHash("sha1").update(`${filePath}\0${f.rule}\0${text}`).digest("hex");
243
+ }
244
+
245
+ // The robotcode and Robocop runs are independent, so they run in parallel; the
246
+ // hook then takes about as long as the slowest of them.
247
+ function spawnAsync(cmd, args, defaultTimeoutMs, runDir = cwd) {
248
+ const opts = spawnOptions(defaultTimeoutMs);
249
+ return new Promise((resolve) => {
250
+ let child;
251
+ try {
252
+ child = spawn(cmd, args, { cwd: runDir, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
253
+ } catch (error) {
254
+ resolve({ error, status: null, stdout: "" });
255
+ return;
256
+ }
257
+ running.add(child);
258
+ let stdout = "";
259
+ let done = false;
260
+ const finish = (res) => {
261
+ if (done) return;
262
+ done = true;
263
+ clearTimeout(timer);
264
+ running.delete(child);
265
+ resolve(res);
266
+ };
267
+ const timer = setTimeout(() => {
268
+ child.kill(opts.killSignal);
269
+ finish({ error: new Error("timeout"), status: null, stdout });
270
+ }, opts.timeout);
271
+ child.stdout.setEncoding("utf-8");
272
+ child.stdout.on("data", (chunk) => {
273
+ if (stdout.length < opts.maxBuffer) stdout += chunk;
274
+ });
275
+ child.stderr.resume();
276
+ child.on("error", (error) => finish({ error, status: null, stdout }));
277
+ child.on("close", (status) => finish({ error: null, status, stdout }));
278
+ });
279
+ }
280
+
281
+ function exitNow(code) {
282
+ for (const child of running) child.kill("SIGKILL");
283
+ process.exit(code);
284
+ }
285
+
286
+ // ── Tier 0: robotcode analyze code ──────────────────────────────────────────
287
+ // Returns {blocking, unresolved} (lists of {line, col, code, message}) or null
288
+ // when robotcode is missing, timed out or printed nothing parsable.
289
+ function startAnalyze() {
290
+ const rc = findRobotcode(cwd);
291
+ if (!rc) return Promise.resolve(null);
292
+ // robotcode only analyzes files under the root it finds from its working
293
+ // directory; a file outside the event's project is analyzed from its folder.
294
+ const rel = relative(cwd, filePath);
295
+ const runDir = rel && !rel.startsWith("..") && !isAbsolute(rel) ? cwd : dirname(filePath);
296
+ return spawnAsync(rc.exe, ["--format", "json", "--no-color", "analyze", "code", filePath], ANALYZE_TIMEOUT_MS, runDir);
297
+ }
298
+
299
+ function parseAnalyze(r) {
300
+ if (!r || r.error || r.status === null) return null;
301
+ let data;
302
+ try {
303
+ data = JSON.parse(r.stdout || "");
304
+ } catch {
305
+ return null;
306
+ }
307
+ const byFile = data && typeof data.diagnostics === "object" && data.diagnostics ? data.diagnostics : null;
308
+ if (!byFile) return null;
309
+ if (data.summary && data.summary.files === 0) return null; // nothing analyzed: no result
310
+ const blocking = [];
311
+ const unresolved = [];
312
+ for (const list of Object.values(byFile)) {
313
+ for (const d of Array.isArray(list) ? list : []) {
314
+ if (d?.severity !== 1) continue; // LSP severity 1 = error
315
+ const item = {
316
+ line: Number(d.range?.start?.line ?? 0) + 1,
317
+ col: Number(d.range?.start?.character ?? 0) + 1,
318
+ code: String(d.code ?? "Error"),
319
+ message: String(d.message ?? "").trim(),
320
+ };
321
+ (UNRESOLVED_CODES.has(item.code) ? unresolved : blocking).push(item);
322
+ }
323
+ }
324
+ const order = (a, b) => a.line - b.line || a.col - b.col;
325
+ return { blocking: blocking.sort(order), unresolved: unresolved.sort(order) };
326
+ }
327
+
328
+ function diagnosticLines(items) {
329
+ const lines = items
330
+ .slice(0, MAX_DIAGNOSTICS)
331
+ .map((d) => `${filePath}:${d.line}:${d.col}: [ERROR] ${d.code}: ${d.message}`);
332
+ if (items.length > MAX_DIAGNOSTICS) lines.push(`… ${items.length - MAX_DIAGNOSTICS} more omitted.`);
333
+ return lines.join("\n");
334
+ }
335
+
336
+ // ── Tier 1: one Robocop pass ────────────────────────────────────────────────
337
+ function startRobocop(py) {
338
+ return spawnAsync(
339
+ py,
340
+ [
341
+ "-m", "robocop", "check", "--no-cache",
342
+ "-c", "print_issues.output_format=simple",
343
+ "--issue-format", "{severity}|{rule_id}|{source}:{line}:{col}|{desc}",
344
+ filePath,
345
+ ],
346
+ ROBOCOP_TIMEOUT_MS,
347
+ );
348
+ }
349
+
350
+ function parseRobocop(r) {
351
+ if (!r || r.error || r.status === null) return null; // timeout, overflow, crash
352
+ const findings = [];
353
+ for (const line of (r.stdout ?? "").split(/\r?\n/)) {
354
+ const m = ISSUE_RE.exec(line.trim());
355
+ if (m) {
356
+ findings.push({
357
+ severity: m[1], rule: m[2], line: Number(m[4]), col: Number(m[5]), desc: m[6], raw: line.trim(),
358
+ });
359
+ }
360
+ }
361
+ // A failing run that printed nothing parsable is a tool failure, not a finding.
362
+ if (!findings.length && r.status !== 0) return null;
363
+ return findings;
364
+ }
365
+
366
+ function deprecationText(deprFindings) {
367
+ const touched = touchedLines();
368
+ const seen = loadSeen();
369
+ const listed = [];
370
+ const counted = {};
371
+ for (const f of deprFindings) {
372
+ const isTouched = touched === null || touched.has(f.line);
373
+ if (isTouched && !seen.has(findingKey(f))) listed.push(f);
374
+ else counted[f.rule] = (counted[f.rule] ?? 0) + 1;
375
+ }
376
+ const rank = (f) => (f.rule in HARD_DEPRECATIONS ? 0 : 1);
377
+ listed.sort((a, b) => rank(a) - rank(b) || a.line - b.line || a.col - b.col);
378
+ if (!listed.length && !Object.keys(counted).length) return "";
379
+
380
+ const name = basename(filePath);
381
+ const header =
382
+ `Deprecated Robot Framework syntax in ${filePath} (advisory, not blocking; ` +
383
+ "modern forms: rf-language skill, references/migration.md):";
384
+ const lines = [header];
385
+ let used = header.length;
386
+ let shown = 0;
387
+ const emitted = [];
388
+ for (const f of listed) {
389
+ const hard = f.rule in HARD_DEPRECATIONS;
390
+ const replacement = HARD_DEPRECATIONS[f.rule] ?? HINTS[f.rule] ?? f.desc;
391
+ const line = ` ${hard ? "WARN" : "HINT"} ${f.rule} ${name}:${f.line} — ${replacement}`;
392
+ if (shown >= MAX_LISTED || used + line.length + 1 > MAX_CHARS - 260) break;
393
+ lines.push(line);
394
+ used += line.length + 1;
395
+ emitted.push(f);
396
+ shown += 1;
397
+ }
398
+ const omitted = listed.length - shown;
399
+ if (omitted > 0) lines.push(` … ${omitted} more deprecation finding(s) omitted.`);
400
+ const counts = Object.entries(counted).sort(([a], [b]) => a.localeCompare(b));
401
+ if (counts.length) {
402
+ lines.push(
403
+ " Also in this file (lines not changed by this edit, or already reported this session): " +
404
+ counts.map(([rule, n]) => `${rule} ×${n}`).join(", ") + ".",
405
+ );
406
+ }
407
+ lines.push(
408
+ " Silence with RF_AGENTSKILLS_DEPRECATION_CHECK=off or by ignoring the rule in the Robocop config.",
409
+ );
410
+ for (const f of emitted) seen.add(findingKey(f));
411
+ saveSeen(seen);
412
+ let text = lines.join("\n");
413
+ if (text.length > MAX_CHARS) text = text.slice(0, MAX_CHARS - 1) + "…";
414
+ return text;
415
+ }
416
+
417
+ // ── Tier 3 (opt-in): per-file dry run ───────────────────────────────────────
418
+ // `robotcode robot --dryrun` from the project root, so robot.toml and its
419
+ // profiles (python-path, variables) apply as in the other tiers.
420
+ function dryRunText() {
421
+ if (!isTruthy(process.env.RF_AGENTSKILLS_FILE_DRYRUN)) return "";
422
+ if (!/\.robot$/i.test(filePath) || /^__init__\.robot$/i.test(basename(filePath))) return "";
423
+ const rc = findRobotcode(cwd);
424
+ if (!rc) return "";
425
+ const rel = relative(cwd, filePath);
426
+ const runDir = rel && !rel.startsWith("..") && !isAbsolute(rel) ? cwd : dirname(filePath);
427
+ const r = spawnSync(
428
+ rc.exe,
429
+ ["--no-color", "robot", "--dryrun", "--output", "NONE", "--report", "NONE", "--log", "NONE",
430
+ "--console", "dotted", filePath],
431
+ // UTF-8 output: robotcode crashes on non-ASCII text under a Windows code page.
432
+ spawnOptions(DRYRUN_TIMEOUT_MS, { encoding: "utf-8", cwd: runDir, env: { ...process.env, PYTHONIOENCODING: "utf-8" } }),
433
+ );
434
+ if (r.error || r.status === null) return "";
435
+ const out = `${r.stdout ?? ""}\n${r.stderr ?? ""}`.split(/\r?\n/);
436
+ const items = [];
437
+ for (let i = 0; i < out.length; i++) {
438
+ const l = out[i];
439
+ if (l.includes("[ ERROR ]") && !/contains no tests/i.test(l)) items.push(l.trim());
440
+ else if (l.startsWith("FAIL: ")) {
441
+ const msg = [];
442
+ for (let j = i + 1; j < out.length && !/^[-=]{10,}/.test(out[j]); j++) {
443
+ if (out[j].trim()) msg.push(out[j].trim());
444
+ }
445
+ items.push(`${l.slice(6).trim()}: ${msg.join(" ")}`);
446
+ }
447
+ }
448
+ if (!items.length) return "";
449
+ const shown = items.slice(0, MAX_LISTED).map((s) => ` ${s.length > 300 ? s.slice(0, 299) + "…" : s}`);
450
+ if (items.length > MAX_LISTED) shown.push(` … ${items.length - MAX_LISTED} more omitted.`);
451
+ let text = `robotcode robot --dryrun of ${filePath} (advisory; a keyword you write next may still be missing):\n` +
452
+ shown.join("\n");
453
+ if (text.length > MAX_CHARS) text = text.slice(0, MAX_CHARS - 1) + "…";
454
+ return text;
455
+ }
456
+
457
+ // ── Main ────────────────────────────────────────────────────────────────────
458
+ const advisory = [];
459
+ const robocopPy = STOP_RECHECK ? null : findInterpreterWith("robocop", cwd);
460
+ const analyzeRun = startAnalyze();
461
+ const robocopRun = robocopPy ? startRobocop(robocopPy) : Promise.resolve(null);
462
+ const formatRun = robocopPy && isTruthy(process.env.RF_AGENTSKILLS_FORMAT_CHECK)
463
+ ? spawnAsync(robocopPy, ["-m", "robocop", "format", "--no-cache", "--check", "--diff", "--no-overwrite", filePath],
464
+ ROBOCOP_TIMEOUT_MS)
465
+ : Promise.resolve(null);
466
+ const analysis = parseAnalyze(await analyzeRun);
467
+ if (analysis) {
468
+ const { blocking, unresolved } = analysis;
469
+ // Remember the result for the Stop-time re-check (report_pending_errors.mjs).
470
+ recordResult(sessionId, filePath, blocking.length + unresolved.length > 0);
471
+ const blockingNow = STOP_RECHECK ? [...blocking, ...unresolved] : blocking;
472
+ if (blockingNow.length) {
473
+ reportErrors(`Robot Framework validation found errors in ${filePath}:\n` + diagnosticLines(blockingNow));
474
+ }
475
+ if (unresolved.length) {
476
+ advisory.push(
477
+ `robotcode cannot resolve these names in ${filePath} yet (advisory; define or import them before you ` +
478
+ "finish, the check blocks at the end of the turn otherwise):\n" + diagnosticLines(unresolved),
479
+ );
480
+ }
481
+ }
482
+ if (STOP_RECHECK) exitNow(0);
483
+
484
+ if (robocopPy) {
485
+ const findings = parseRobocop(await robocopRun);
486
+ if (findings) {
487
+ const mode = (process.env.RF_AGENTSKILLS_DEPRECATION_CHECK ?? "").trim().toLowerCase();
488
+ if (mode !== "off") {
489
+ const text = deprecationText(findings.filter((f) => f.rule.startsWith("DEPR")));
490
+ if (text) advisory.push(text);
491
+ }
492
+
493
+ // ── Tier 2 (opt-in): formatting drift (informational only) ──
494
+ const fmt = await formatRun;
495
+ if (fmt && !fmt.error && fmt.status !== 0 && fmt.status !== null && (fmt.stdout ?? "").trim()) {
496
+ let diff = fmt.stdout.trim();
497
+ if (diff.length > MAX_CHARS) diff = diff.slice(0, MAX_CHARS - 1) + "…";
498
+ advisory.push(
499
+ `Robocop suggests formatting changes for ${filePath} (run \`robocop format\` to apply):\n` + diff,
500
+ );
501
+ }
502
+ }
503
+ }
504
+
505
+ const dry = dryRunText();
506
+ if (dry) advisory.push(dry);
507
+
508
+ if (advisory.length) {
509
+ const payload = {
510
+ hookSpecificOutput: {
511
+ hookEventName: "PostToolUse",
512
+ additionalContext: advisory.join("\n\n"),
513
+ },
514
+ };
515
+ process.stdout.write(JSON.stringify(payload) + "\n");
516
+ }
517
+ process.exit(0);
@@ -0,0 +1,103 @@
1
+ #!/usr/bin/env node
2
+ // validate_robot_project.mjs — Opt-in, end-of-task project-wide validation
3
+ // for Robot Framework suites. Runs from the Stop hook.
4
+ //
5
+ // This tier performs CROSS-FILE / semantic checks that only make sense
6
+ // once the whole project is on disk — running them per-save would
7
+ // false-alarm constantly (a keyword you just wrote looks "unused" until
8
+ // something calls it). One tool, one run:
9
+ //
10
+ // `robotcode --format json analyze code --collect-unused` from the project
11
+ // root. It reads robot.toml (paths, python-path, variables) and reports
12
+ // - every error-severity diagnostic (unresolved keywords and variables,
13
+ // failed imports, argument errors, model errors), and
14
+ // - unused keywords and variables (KeywordNotUsed / VariableNotUsed).
15
+ // The JSON is parsed; robotcode's bitmask exit code is not used.
16
+ //
17
+ // OPT-IN: the entire tier is gated behind the RF_AGENTSKILLS_PROJECT_VALIDATION
18
+ // env var (truthy = 1/true/yes/on). It is OFF by default because the analysis
19
+ // loads the project's libraries (to read their keywords) and scales with
20
+ // project size. When enabled and findings exist, the hook exits 2 with the
21
+ // diagnostic on stderr so the agent gets one more turn to fix before the turn
22
+ // ends.
23
+ //
24
+ // Graceful degradation: silent no-op (exit 0) when the flag is unset, robotcode
25
+ // isn't installed, the run times out (120 s) or its output is unparsable.
26
+ import { readFileSync } from "node:fs";
27
+ import { spawnSync } from "node:child_process";
28
+ import { findRobotcode, projectRoot as projectRootOf, spawnOptions } from "./_python_env.mjs";
29
+
30
+ // Project-wide checks scale with project size: bounded, but more generous than
31
+ // the per-file check. A timeout skips the check silently.
32
+ const PROJECT_TIMEOUT_MS = 120000;
33
+ const MAX_LISTED = 20;
34
+ const UNUSED_CODES = new Set(["KeywordNotUsed", "VariableNotUsed"]);
35
+
36
+ // ── Gate: opt-in only ───────────────────────────────────────────────────────
37
+ function isTruthy(v) {
38
+ return /^(1|true|yes|on)$/i.test((v ?? "").toString().trim());
39
+ }
40
+ if (!isTruthy(process.env.RF_AGENTSKILLS_PROJECT_VALIDATION)) process.exit(0);
41
+
42
+ // Read the Stop event once (stdin can only be consumed once). Break the
43
+ // Stop-hook loop: when firing as a continuation of a previous Stop block
44
+ // (`stop_hook_active`), exit 2 here would re-block on the same persistent
45
+ // finding forever — so no-op in that state.
46
+ let stopEvent = null;
47
+ try {
48
+ stopEvent = JSON.parse(readFileSync(0, "utf-8"));
49
+ } catch {
50
+ // No / unparsable stdin — proceed with process cwd.
51
+ }
52
+ if (stopEvent?.stop_hook_active) process.exit(0);
53
+
54
+ // Resolve the project root from the (already-parsed) Stop event JSON (cwd),
55
+ // falling back to the process cwd.
56
+ const projectRoot = projectRootOf(stopEvent);
57
+
58
+ const findings = [];
59
+
60
+ const rc = findRobotcode(projectRoot);
61
+ if (rc) {
62
+ const r = spawnSync(
63
+ rc.exe,
64
+ ["--format", "json", "--no-color", "analyze", "code", "--collect-unused"],
65
+ spawnOptions(PROJECT_TIMEOUT_MS, { encoding: "utf-8", cwd: projectRoot }),
66
+ );
67
+ let data = null;
68
+ if (!r.error && r.status !== null) {
69
+ try {
70
+ data = JSON.parse(r.stdout || "");
71
+ } catch {
72
+ data = null; // unparsable: tool failure, not a finding
73
+ }
74
+ }
75
+ const errors = [];
76
+ const unused = [];
77
+ for (const [file, list] of Object.entries(data?.diagnostics ?? {})) {
78
+ for (const d of Array.isArray(list) ? list : []) {
79
+ const code = String(d?.code ?? "");
80
+ const line = `${file}:${Number(d?.range?.start?.line ?? 0) + 1}:${Number(d?.range?.start?.character ?? 0) + 1}: ` +
81
+ `${code}: ${String(d?.message ?? "").trim()}`;
82
+ if (UNUSED_CODES.has(code)) unused.push(line);
83
+ else if (d?.severity === 1) errors.push(line);
84
+ }
85
+ }
86
+ const listed = (items) =>
87
+ items.slice(0, MAX_LISTED).join("\n ") +
88
+ (items.length > MAX_LISTED ? `\n … ${items.length - MAX_LISTED} more omitted.` : "");
89
+ if (errors.length) findings.push("Errors (robotcode analyze code):\n " + listed(errors));
90
+ if (unused.length) findings.push("Unused keywords and variables:\n " + listed(unused));
91
+ }
92
+
93
+ // ── Report ──────────────────────────────────────────────────────────────────
94
+ if (findings.length) {
95
+ process.stderr.write(
96
+ "Robot Framework project validation found issues:\n\n" +
97
+ findings.join("\n\n") +
98
+ "\n",
99
+ );
100
+ process.exit(2);
101
+ }
102
+
103
+ process.exit(0);