@flowrunner/cli 0.1.0

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 (460) hide show
  1. package/README.md +148 -0
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +180 -0
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +260 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +193 -0
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +257 -0
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +103 -0
  7. package/ai-docs/instructions/service-code-format/06-oauth2.md +42 -0
  8. package/ai-docs/instructions/service-code-format/07-actions.md +171 -0
  9. package/ai-docs/instructions/service-code-format/08-polling-triggers.md +54 -0
  10. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +269 -0
  11. package/ai-docs/instructions/service-code-format/10-files-api.md +148 -0
  12. package/ai-docs/instructions/service-code-format/11-output-model.md +142 -0
  13. package/ai-docs/instructions/service-code-format/12-service-readme.md +69 -0
  14. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +193 -0
  15. package/ai-docs/instructions/service-code-format/14-reference-service.md +341 -0
  16. package/ai-docs/instructions/service-code-format/15-unit-tests.md +361 -0
  17. package/ai-docs/instructions/service-code-format/16-gotchas.md +201 -0
  18. package/ai-docs/instructions/service-code-format/17-client-certificates.md +162 -0
  19. package/ai-docs/instructions/service-code-format/18-test-recipes.md +160 -0
  20. package/ai-docs/instructions/service-code-format/README.md +120 -0
  21. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +139 -0
  22. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +497 -0
  23. package/ai-docs/providers/claude/main-orchestrator-segment.md +51 -0
  24. package/bin/flowrunner.js +66 -0
  25. package/bin/resolve-local.js +98 -0
  26. package/dist/cli.js +10972 -0
  27. package/dist/cli.js.map +7 -0
  28. package/dist/index.d.ts +2 -0
  29. package/dist/index.js +10131 -0
  30. package/dist/index.js.map +7 -0
  31. package/dist/types/flow-extension-runner/src/common/config.d.ts +12 -0
  32. package/dist/types/flow-extension-runner/src/common/constants.d.ts +9 -0
  33. package/dist/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
  34. package/dist/types/flow-extension-runner/src/common/context.d.ts +6 -0
  35. package/dist/types/flow-extension-runner/src/common/types.d.ts +11 -0
  36. package/dist/types/flow-extension-runner/src/errors/base.d.ts +17 -0
  37. package/dist/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
  38. package/dist/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
  39. package/dist/types/flow-extension-runner/src/errors/index.d.ts +3 -0
  40. package/dist/types/flow-extension-runner/src/global.d.ts +34 -0
  41. package/dist/types/flow-extension-runner/src/index.d.ts +15 -0
  42. package/dist/types/flow-extension-runner/src/namespace.d.ts +3 -0
  43. package/dist/types/flow-extension-runner/src/v1/config.d.ts +3 -0
  44. package/dist/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
  45. package/dist/types/flow-extension-runner/src/v1/index.d.ts +11 -0
  46. package/dist/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
  47. package/dist/types/flow-extension-runner/src/v1/service.d.ts +29 -0
  48. package/dist/types/flow-extension-runner/src/v1/types.d.ts +13 -0
  49. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
  50. package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
  51. package/dist/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
  52. package/dist/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
  53. package/dist/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
  54. package/dist/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
  55. package/dist/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
  56. package/dist/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
  57. package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
  58. package/dist/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
  59. package/dist/types/flow-extension-runner/src/v2/index.d.ts +39 -0
  60. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
  61. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
  62. package/dist/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
  63. package/dist/types/flow-extension-runner/src/v2/method.d.ts +22 -0
  64. package/dist/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
  65. package/dist/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
  66. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
  67. package/dist/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
  68. package/dist/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
  69. package/dist/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
  70. package/dist/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
  71. package/dist/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
  72. package/dist/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
  73. package/dist/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
  74. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
  75. package/dist/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
  76. package/dist/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
  77. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
  78. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
  79. package/dist/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
  80. package/dist/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
  81. package/dist/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
  82. package/dist/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
  83. package/dist/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
  84. package/dist/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
  85. package/dist/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
  86. package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
  87. package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
  88. package/dist/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
  89. package/dist/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
  90. package/dist/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
  91. package/dist/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
  92. package/dist/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
  93. package/dist/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
  94. package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
  95. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
  96. package/dist/types/flow-extension-runner/src/v2/path.d.ts +1 -0
  97. package/dist/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
  98. package/dist/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
  99. package/dist/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
  100. package/dist/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
  101. package/dist/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
  102. package/dist/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
  103. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
  104. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
  105. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
  106. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
  107. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
  108. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
  109. package/dist/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
  110. package/dist/types/flow-extension-runner/src/v2/result.d.ts +13 -0
  111. package/dist/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
  112. package/dist/types/flow-extension-runner/src/v2/types.d.ts +126 -0
  113. package/dist/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
  114. package/dist/types/jsdoc-parser/src/index.d.ts +2 -0
  115. package/dist/types/jsdoc-parser/src/lib.d.ts +42 -0
  116. package/dist/types/jsdoc-parser/src/types.d.ts +2 -0
  117. package/dist/types/packages/cli/src/api/console-client.d.ts +69 -0
  118. package/dist/types/packages/cli/src/constants/index.d.ts +5 -0
  119. package/dist/types/packages/cli/src/constants/packaging.d.ts +7 -0
  120. package/dist/types/packages/cli/src/constants/project.d.ts +9 -0
  121. package/dist/types/packages/cli/src/constants/providers.d.ts +30 -0
  122. package/dist/types/packages/cli/src/constants/server.d.ts +29 -0
  123. package/dist/types/packages/cli/src/constants/testing.d.ts +32 -0
  124. package/dist/types/packages/cli/src/errors.d.ts +131 -0
  125. package/dist/types/packages/cli/src/index.d.ts +29 -0
  126. package/dist/types/packages/cli/src/operations/deploy/discover-services.d.ts +26 -0
  127. package/dist/types/packages/cli/src/operations/deploy/hash.d.ts +1 -0
  128. package/dist/types/packages/cli/src/operations/deploy/index.d.ts +94 -0
  129. package/dist/types/packages/cli/src/operations/deploy/public-files.d.ts +20 -0
  130. package/dist/types/packages/cli/src/operations/deploy/select.d.ts +9 -0
  131. package/dist/types/packages/cli/src/operations/deploy/zip.d.ts +1 -0
  132. package/dist/types/packages/cli/src/operations/init/answers.d.ts +35 -0
  133. package/dist/types/packages/cli/src/operations/init/create-service.d.ts +39 -0
  134. package/dist/types/packages/cli/src/operations/init/index.d.ts +79 -0
  135. package/dist/types/packages/cli/src/operations/init/testing.d.ts +13 -0
  136. package/dist/types/packages/cli/src/operations/init-claude/index.d.ts +40 -0
  137. package/dist/types/packages/cli/src/operations/init-claude/segment.d.ts +25 -0
  138. package/dist/types/packages/cli/src/operations/login.d.ts +38 -0
  139. package/dist/types/packages/cli/src/operations/logout.d.ts +19 -0
  140. package/dist/types/packages/cli/src/operations/pull/extract.d.ts +23 -0
  141. package/dist/types/packages/cli/src/operations/pull/index.d.ts +87 -0
  142. package/dist/types/packages/cli/src/operations/server-target.d.ts +14 -0
  143. package/dist/types/packages/cli/src/operations/types.d.ts +20 -0
  144. package/dist/types/packages/cli/src/operations/use-server.d.ts +17 -0
  145. package/dist/types/packages/cli/src/project/auth.d.ts +41 -0
  146. package/dist/types/packages/cli/src/project/config.d.ts +31 -0
  147. package/dist/types/packages/cli/src/project/token.d.ts +5 -0
  148. package/dist/types/packages/cli/src/server/index.d.ts +14 -0
  149. package/dist/types/packages/cli/src/server/pages.d.ts +2 -0
  150. package/dist/types/packages/cli/src/server/routes/callback.d.ts +6 -0
  151. package/dist/types/packages/cli/src/server/types.d.ts +12 -0
  152. package/dist/types/packages/cli/src/templates/index.d.ts +8 -0
  153. package/dist/types/packages/cli/src/templates/manifest.d.ts +97 -0
  154. package/dist/types/packages/cli/src/templates/package-root.d.ts +3 -0
  155. package/dist/types/packages/cli/src/templates/paths.d.ts +3 -0
  156. package/dist/types/packages/cli/src/templates/registry.d.ts +13 -0
  157. package/dist/types/packages/cli/src/templates/render.d.ts +13 -0
  158. package/dist/types/packages/cli/src/templates/scaffold.d.ts +25 -0
  159. package/dist/types/packages/cli/src/utils/invocation.d.ts +28 -0
  160. package/dist/types/packages/cli/src/utils/open-browser.d.ts +2 -0
  161. package/dist/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
  162. package/dist/types/shared/src/constants/ai.d.ts +11 -0
  163. package/dist/types/shared/src/constants/api-keys.d.ts +1 -0
  164. package/dist/types/shared/src/constants/app.d.ts +58 -0
  165. package/dist/types/shared/src/constants/billing.d.ts +16 -0
  166. package/dist/types/shared/src/constants/compliances.d.ts +3 -0
  167. package/dist/types/shared/src/constants/data-types.d.ts +26 -0
  168. package/dist/types/shared/src/constants/error-codes.d.ts +16 -0
  169. package/dist/types/shared/src/constants/flow.d.ts +12 -0
  170. package/dist/types/shared/src/constants/index.d.ts +16 -0
  171. package/dist/types/shared/src/constants/knowledge-base.d.ts +13 -0
  172. package/dist/types/shared/src/constants/notification-types.d.ts +985 -0
  173. package/dist/types/shared/src/constants/notifications.d.ts +10 -0
  174. package/dist/types/shared/src/constants/patterns.d.ts +28 -0
  175. package/dist/types/shared/src/constants/retry-policy.d.ts +30 -0
  176. package/dist/types/shared/src/constants/severity.d.ts +9 -0
  177. package/dist/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
  178. package/dist/types/shared/src/constants/shared-extensions.d.ts +35 -0
  179. package/dist/types/shared/src/constants/zod.d.ts +2 -0
  180. package/dist/types/shared/src/errors/api.d.ts +4 -0
  181. package/dist/types/shared/src/errors/base.d.ts +38 -0
  182. package/dist/types/shared/src/errors/common.d.ts +39 -0
  183. package/dist/types/shared/src/errors/index.d.ts +13 -0
  184. package/dist/types/shared/src/errors/k8s.d.ts +4 -0
  185. package/dist/types/shared/src/errors/message.d.ts +48 -0
  186. package/dist/types/shared/src/errors/open-search.d.ts +4 -0
  187. package/dist/types/shared/src/errors/s3.d.ts +11 -0
  188. package/dist/types/shared/src/extensions/zod.d.ts +25 -0
  189. package/dist/types/shared/src/scheme/account/dto.d.ts +60 -0
  190. package/dist/types/shared/src/scheme/account/index.d.ts +1 -0
  191. package/dist/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
  192. package/dist/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
  193. package/dist/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
  194. package/dist/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
  195. package/dist/types/shared/src/scheme/ai-router/index.d.ts +2 -0
  196. package/dist/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
  197. package/dist/types/shared/src/scheme/api-keys/index.d.ts +2 -0
  198. package/dist/types/shared/src/scheme/app/index.d.ts +1 -0
  199. package/dist/types/shared/src/scheme/app/java.dto.d.ts +6 -0
  200. package/dist/types/shared/src/scheme/billing/index.d.ts +1 -0
  201. package/dist/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
  202. package/dist/types/shared/src/scheme/crm/billing.d.ts +149 -0
  203. package/dist/types/shared/src/scheme/crm/dto.d.ts +212 -0
  204. package/dist/types/shared/src/scheme/crm/index.d.ts +3 -0
  205. package/dist/types/shared/src/scheme/data-types/index.d.ts +1 -0
  206. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
  207. package/dist/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
  208. package/dist/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
  209. package/dist/types/shared/src/scheme/extensions/index.d.ts +1 -0
  210. package/dist/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
  211. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
  212. package/dist/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
  213. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
  214. package/dist/types/shared/src/scheme/index.d.ts +19 -0
  215. package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
  216. package/dist/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
  217. package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
  218. package/dist/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
  219. package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
  220. package/dist/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
  221. package/dist/types/shared/src/scheme/notifications/dto.d.ts +111 -0
  222. package/dist/types/shared/src/scheme/notifications/index.d.ts +3 -0
  223. package/dist/types/shared/src/scheme/notifications/rest.d.ts +148 -0
  224. package/dist/types/shared/src/scheme/properties/account.d.ts +3 -0
  225. package/dist/types/shared/src/scheme/properties/app.d.ts +5 -0
  226. package/dist/types/shared/src/scheme/properties/billing.d.ts +12 -0
  227. package/dist/types/shared/src/scheme/properties/common.d.ts +2 -0
  228. package/dist/types/shared/src/scheme/properties/db.d.ts +8 -0
  229. package/dist/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
  230. package/dist/types/shared/src/scheme/properties/index.d.ts +7 -0
  231. package/dist/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
  232. package/dist/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
  233. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
  234. package/dist/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
  235. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
  236. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
  237. package/dist/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
  238. package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
  239. package/dist/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
  240. package/dist/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
  241. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
  242. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
  243. package/dist/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
  244. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
  245. package/dist/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
  246. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
  247. package/dist/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
  248. package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
  249. package/dist/types/shared/src/scheme/workspace/dto.d.ts +40 -0
  250. package/dist/types/shared/src/scheme/workspace/index.d.ts +1 -0
  251. package/dist/types/shared/src/utils/object.d.ts +8 -0
  252. package/dist/types/shared/src/utils/uuid.d.ts +5 -0
  253. package/dist/types/shared/src/utils/versions.d.ts +4 -0
  254. package/dist/types/types/backendless-request.d.ts +40 -0
  255. package/package.json +66 -0
  256. package/project-files/jest.config.js +38 -0
  257. package/project-files/jest.setup.js +24 -0
  258. package/project-files/sandbox/files-mock.js +654 -0
  259. package/project-files/sandbox/index.js +32 -0
  260. package/project-files/sandbox/nock-mock.js +600 -0
  261. package/project-files/sandbox/service.js +145 -0
  262. package/runtime/index.d.ts +2 -0
  263. package/runtime/index.js +5665 -0
  264. package/runtime/index.js.map +7 -0
  265. package/runtime/types/flow-extension-runner/src/common/config.d.ts +12 -0
  266. package/runtime/types/flow-extension-runner/src/common/constants.d.ts +9 -0
  267. package/runtime/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
  268. package/runtime/types/flow-extension-runner/src/common/context.d.ts +6 -0
  269. package/runtime/types/flow-extension-runner/src/common/types.d.ts +11 -0
  270. package/runtime/types/flow-extension-runner/src/errors/base.d.ts +17 -0
  271. package/runtime/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
  272. package/runtime/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
  273. package/runtime/types/flow-extension-runner/src/errors/index.d.ts +3 -0
  274. package/runtime/types/flow-extension-runner/src/global.d.ts +34 -0
  275. package/runtime/types/flow-extension-runner/src/index.d.ts +15 -0
  276. package/runtime/types/flow-extension-runner/src/namespace.d.ts +3 -0
  277. package/runtime/types/flow-extension-runner/src/v1/config.d.ts +3 -0
  278. package/runtime/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
  279. package/runtime/types/flow-extension-runner/src/v1/index.d.ts +11 -0
  280. package/runtime/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
  281. package/runtime/types/flow-extension-runner/src/v1/service.d.ts +29 -0
  282. package/runtime/types/flow-extension-runner/src/v1/types.d.ts +13 -0
  283. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
  284. package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
  285. package/runtime/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
  286. package/runtime/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
  287. package/runtime/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
  288. package/runtime/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
  289. package/runtime/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
  290. package/runtime/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
  291. package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
  292. package/runtime/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
  293. package/runtime/types/flow-extension-runner/src/v2/index.d.ts +39 -0
  294. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
  295. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
  296. package/runtime/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
  297. package/runtime/types/flow-extension-runner/src/v2/method.d.ts +22 -0
  298. package/runtime/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
  299. package/runtime/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
  300. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
  301. package/runtime/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
  302. package/runtime/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
  303. package/runtime/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
  304. package/runtime/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
  305. package/runtime/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
  306. package/runtime/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
  307. package/runtime/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
  308. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
  309. package/runtime/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
  310. package/runtime/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
  311. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
  312. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
  313. package/runtime/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
  314. package/runtime/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
  315. package/runtime/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
  316. package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
  317. package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
  318. package/runtime/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
  319. package/runtime/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
  320. package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
  321. package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
  322. package/runtime/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
  323. package/runtime/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
  324. package/runtime/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
  325. package/runtime/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
  326. package/runtime/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
  327. package/runtime/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
  328. package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
  329. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
  330. package/runtime/types/flow-extension-runner/src/v2/path.d.ts +1 -0
  331. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
  332. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
  333. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
  334. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
  335. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
  336. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
  337. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
  338. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
  339. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
  340. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
  341. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
  342. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
  343. package/runtime/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
  344. package/runtime/types/flow-extension-runner/src/v2/result.d.ts +13 -0
  345. package/runtime/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
  346. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +126 -0
  347. package/runtime/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
  348. package/runtime/types/jsdoc-parser/src/index.d.ts +2 -0
  349. package/runtime/types/jsdoc-parser/src/lib.d.ts +42 -0
  350. package/runtime/types/jsdoc-parser/src/types.d.ts +2 -0
  351. package/runtime/types/packages/cli/src/runtime/index.d.ts +5 -0
  352. package/runtime/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
  353. package/runtime/types/shared/src/constants/ai.d.ts +11 -0
  354. package/runtime/types/shared/src/constants/api-keys.d.ts +1 -0
  355. package/runtime/types/shared/src/constants/app.d.ts +58 -0
  356. package/runtime/types/shared/src/constants/billing.d.ts +16 -0
  357. package/runtime/types/shared/src/constants/compliances.d.ts +3 -0
  358. package/runtime/types/shared/src/constants/data-types.d.ts +26 -0
  359. package/runtime/types/shared/src/constants/error-codes.d.ts +16 -0
  360. package/runtime/types/shared/src/constants/flow.d.ts +12 -0
  361. package/runtime/types/shared/src/constants/index.d.ts +16 -0
  362. package/runtime/types/shared/src/constants/knowledge-base.d.ts +13 -0
  363. package/runtime/types/shared/src/constants/notification-types.d.ts +985 -0
  364. package/runtime/types/shared/src/constants/notifications.d.ts +10 -0
  365. package/runtime/types/shared/src/constants/patterns.d.ts +28 -0
  366. package/runtime/types/shared/src/constants/retry-policy.d.ts +30 -0
  367. package/runtime/types/shared/src/constants/severity.d.ts +9 -0
  368. package/runtime/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
  369. package/runtime/types/shared/src/constants/shared-extensions.d.ts +35 -0
  370. package/runtime/types/shared/src/constants/zod.d.ts +2 -0
  371. package/runtime/types/shared/src/errors/api.d.ts +4 -0
  372. package/runtime/types/shared/src/errors/base.d.ts +38 -0
  373. package/runtime/types/shared/src/errors/common.d.ts +39 -0
  374. package/runtime/types/shared/src/errors/index.d.ts +13 -0
  375. package/runtime/types/shared/src/errors/k8s.d.ts +4 -0
  376. package/runtime/types/shared/src/errors/message.d.ts +48 -0
  377. package/runtime/types/shared/src/errors/open-search.d.ts +4 -0
  378. package/runtime/types/shared/src/errors/s3.d.ts +11 -0
  379. package/runtime/types/shared/src/extensions/zod.d.ts +25 -0
  380. package/runtime/types/shared/src/scheme/account/dto.d.ts +60 -0
  381. package/runtime/types/shared/src/scheme/account/index.d.ts +1 -0
  382. package/runtime/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
  383. package/runtime/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
  384. package/runtime/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
  385. package/runtime/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
  386. package/runtime/types/shared/src/scheme/ai-router/index.d.ts +2 -0
  387. package/runtime/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
  388. package/runtime/types/shared/src/scheme/api-keys/index.d.ts +2 -0
  389. package/runtime/types/shared/src/scheme/app/index.d.ts +1 -0
  390. package/runtime/types/shared/src/scheme/app/java.dto.d.ts +6 -0
  391. package/runtime/types/shared/src/scheme/billing/index.d.ts +1 -0
  392. package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
  393. package/runtime/types/shared/src/scheme/crm/billing.d.ts +149 -0
  394. package/runtime/types/shared/src/scheme/crm/dto.d.ts +212 -0
  395. package/runtime/types/shared/src/scheme/crm/index.d.ts +3 -0
  396. package/runtime/types/shared/src/scheme/data-types/index.d.ts +1 -0
  397. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
  398. package/runtime/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
  399. package/runtime/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
  400. package/runtime/types/shared/src/scheme/extensions/index.d.ts +1 -0
  401. package/runtime/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
  402. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
  403. package/runtime/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
  404. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
  405. package/runtime/types/shared/src/scheme/index.d.ts +19 -0
  406. package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
  407. package/runtime/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
  408. package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
  409. package/runtime/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
  410. package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
  411. package/runtime/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
  412. package/runtime/types/shared/src/scheme/notifications/dto.d.ts +111 -0
  413. package/runtime/types/shared/src/scheme/notifications/index.d.ts +3 -0
  414. package/runtime/types/shared/src/scheme/notifications/rest.d.ts +148 -0
  415. package/runtime/types/shared/src/scheme/properties/account.d.ts +3 -0
  416. package/runtime/types/shared/src/scheme/properties/app.d.ts +5 -0
  417. package/runtime/types/shared/src/scheme/properties/billing.d.ts +12 -0
  418. package/runtime/types/shared/src/scheme/properties/common.d.ts +2 -0
  419. package/runtime/types/shared/src/scheme/properties/db.d.ts +8 -0
  420. package/runtime/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
  421. package/runtime/types/shared/src/scheme/properties/index.d.ts +7 -0
  422. package/runtime/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
  423. package/runtime/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
  424. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
  425. package/runtime/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
  426. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
  427. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
  428. package/runtime/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
  429. package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
  430. package/runtime/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
  431. package/runtime/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
  432. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
  433. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
  434. package/runtime/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
  435. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
  436. package/runtime/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
  437. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
  438. package/runtime/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
  439. package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
  440. package/runtime/types/shared/src/scheme/workspace/dto.d.ts +40 -0
  441. package/runtime/types/shared/src/scheme/workspace/index.d.ts +1 -0
  442. package/runtime/types/shared/src/utils/object.d.ts +8 -0
  443. package/runtime/types/shared/src/utils/uuid.d.ts +5 -0
  444. package/runtime/types/shared/src/utils/versions.d.ts +4 -0
  445. package/runtime/types/types/backendless-request.d.ts +40 -0
  446. package/templates/blank/files/README.md +28 -0
  447. package/templates/blank/files/package.json +8 -0
  448. package/templates/blank/files/public/icon.svg +5 -0
  449. package/templates/blank/files/src/index.js +130 -0
  450. package/templates/blank/template.json +61 -0
  451. package/templates/demo-todo-list/files/README.md +54 -0
  452. package/templates/demo-todo-list/files/package.json +8 -0
  453. package/templates/demo-todo-list/files/public/icon.svg +8 -0
  454. package/templates/demo-todo-list/files/src/index.js +590 -0
  455. package/templates/demo-todo-list/template.json +44 -0
  456. package/templates/qa-test/files/README.md +88 -0
  457. package/templates/qa-test/files/package.json +8 -0
  458. package/templates/qa-test/files/public/icon.svg +8 -0
  459. package/templates/qa-test/files/src/index.js +755 -0
  460. package/templates/qa-test/template.json +62 -0
@@ -0,0 +1,162 @@
1
+ # 17 — Client Certificates (mutual TLS)
2
+
3
+ Some APIs — most of them in regulated banking — require the client to present a TLS certificate of its own
4
+ before they will answer at all. Read this only when the vendor requires one; the rest of the HTTP surface is
5
+ [04-http-requests.md](04-http-requests.md).
6
+
7
+ ## Attaching one
8
+
9
+ `.cert(tlsOptions)` on any request:
10
+
11
+ ```js
12
+ await Flowrunner.Request.post('https://api.vendor.com/payments')
13
+ .cert({
14
+ cert : clientCertPem, // PEM encoded client certificate (or chain)
15
+ key : clientKeyPem, // PEM encoded private key
16
+ passphrase: keyPassphrase, // optional, for an encrypted private key
17
+ ca : caBundlePem, // optional, a custom CA bundle to verify the server with
18
+ })
19
+ .send(body)
20
+ ```
21
+
22
+ Each option accepts a string, a Buffer, or an array of them, exactly as Node's TLS options do. Options other
23
+ than those four are ignored, so a connection cannot be weakened by accident.
24
+
25
+ `.cert()` may be called more than once and the options are merged, which lets the certificate and the CA
26
+ bundle come from different places:
27
+
28
+ ```js
29
+ await Flowrunner.Request.get(url)
30
+ .cert({ cert: clientCertPem, key: clientKeyPem })
31
+ .cert({ ca: caBundlePem })
32
+ ```
33
+
34
+ ## Declaring it on the service
35
+
36
+ **Put it in `apiRequest`, not in individual actions** ([04-http-requests.md](04-http-requests.md)). Servers
37
+ of this kind normally demand the certificate before authentication, so the OAuth2 token endpoint
38
+ ([06-oauth2.md](06-oauth2.md)) is unreachable without it too — an action-by-action approach leaves the token
39
+ call broken.
40
+
41
+ ```js
42
+ configItems: z.object({
43
+ clientCert: z.text().label('Client certificate (PEM)'),
44
+ clientKey : z.text().label('Private key (PEM)'),
45
+ }),
46
+
47
+ initContext: ({ config }) => ({
48
+ apiUrl : 'https://api.vendor.com',
49
+ clientCert: config.clientCert,
50
+ clientKey : config.clientKey,
51
+ }),
52
+
53
+ apiRequest: async ({ url, method = 'get', body, query, context }) =>
54
+ new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
55
+ .cert({ cert: context.clientCert, key: context.clientKey })
56
+ .query(query),
57
+ ```
58
+
59
+ See [01-service-structure.md](01-service-structure.md) for `configItems` and `initContext`.
60
+
61
+ **`z.text()`, because a PEM block is multi-line** — it draws a textarea, where `z.string()` would put a
62
+ 27-line certificate through a one-line box. The cost is that the key is on screen in clear text:
63
+ `.secret()` masks a `z.string()` config field only and is a no-op on `z.text()`
64
+ ([02-zod-types.md](02-zod-types.md)). If that matters more than the textarea, ship the key as a file in the
65
+ service folder instead — the whole folder is deployed, so `require('fs').readFileSync(path.join(__dirname,
66
+ '../certs/client.key'))` reads it in the pod.
67
+
68
+ ## What to know
69
+
70
+ - **`https://` is required.** Sending a certificate over `http://` would silently drop it and put the request
71
+ on the wire in plain text, so the request fails instead.
72
+ - **`ca` replaces the default trust store** for that request, the way `curl --cacert` does. Pass the whole
73
+ chain needed to verify the server, not just the leaf.
74
+ - **The private key is credential material.** Never inline it in the source and never put it in a URL —
75
+ declare it as a config field or read it from a file in the service folder. Whichever way, the value is
76
+ stored and transmitted in clear text; masking a config field with `.secret()` hides it from a passer-by,
77
+ it does not protect it. The client keeps the key out of verbose output and off the request's enumerable
78
+ properties, so `console.log(request)` and `JSON.stringify(request)` will not leak it — but your own logging
79
+ still can, so redact there too ([04-http-requests.md](04-http-requests.md)).
80
+
81
+ ## TLS failures
82
+
83
+ A failed handshake would otherwise surface as an opaque socket error, so recognized failures reject with a
84
+ `TLSError`. `message` is the sentence below plus the original code in parentheses, `error.code` keeps that
85
+ code and `error.cause` the original error. **No part of the certificate, the key or the passphrase is ever
86
+ in the message** — the sentences below are the only text it is built from.
87
+
88
+ **Your certificate or key could not be loaded** — no connection was attempted, so nothing reached the vendor:
89
+
90
+ | Message | Usually means |
91
+ |---|---|
92
+ | The private key could not be decrypted, the passphrase is missing or incorrect. | the key is encrypted and `passphrase` is missing or wrong |
93
+ | The client certificate or the private key is not valid PEM. | a truncated paste, or a DER/PKCS#12 file — only PEM is accepted |
94
+ | The private key does not match the client certificate. | `cert` and `key` are from different pairs |
95
+
96
+ **The server refused your certificate:**
97
+
98
+ | Message | Usually means |
99
+ |---|---|
100
+ | The server requires a client certificate and none was supplied. | `.cert()` is missing, or is on some requests only — put it in `apiRequest` |
101
+ | The server rejected the client certificate because it has expired. | renew it with the vendor |
102
+ | The server rejected the client certificate because it has been revoked. | as above |
103
+ | The server does not trust the authority which issued the client certificate. | often a sandbox certificate sent to production, or the wrong chain |
104
+ | The server rejected the client certificate. | the alert carried no reason |
105
+ | The server rejected the TLS handshake, the client certificate is missing or was rejected. | as above, reported at handshake level |
106
+
107
+ **The server's own certificate could not be verified** — a `ca` bundle is usually what is missing:
108
+
109
+ | Message | Usually means |
110
+ |---|---|
111
+ | The server certificate could not be verified, a CA bundle may be required. | the issuer is not in the default trust store — pass `ca` |
112
+ | The server certificate chain is self signed, a CA bundle may be required. | as above |
113
+ | The server certificate is self signed, a CA bundle may be required. | as above |
114
+ | The server certificate has expired. | the vendor's problem, not yours |
115
+ | The server certificate is not valid yet. | as above, or a wrong clock |
116
+ | The server certificate does not match the requested host. | the hostname in the URL is not the one the certificate was issued for |
117
+
118
+ **A TLS 1.3 server usually drops the connection instead of sending an alert.** There is nothing to read, so
119
+ when a client certificate was supplied an `ECONNRESET` / `EPROTO` is reported as the best available guess:
120
+
121
+ ```
122
+ The connection was closed during the TLS handshake, the client certificate was most likely missing,
123
+ rejected or expired. (ECONNRESET)
124
+ ```
125
+
126
+ Failures unrelated to TLS are left untouched, so a `ResponseError` still means what it means in
127
+ [04-http-requests.md](04-http-requests.md).
128
+
129
+ ## Testing it
130
+
131
+ The suite's mock intercepts below TLS ([15-unit-tests.md](15-unit-tests.md)), which has two consequences:
132
+
133
+ - **A handshake cannot be reproduced.** Treat it as something only a real deploy confirms.
134
+ - **The certificate has no wire footprint, and the recorded call does not carry one either** — a
135
+ `mock.history` entry holds the method, URL, headers, query and body, and no TLS field. So there is nothing
136
+ to assert about `.cert()` itself; do not write a test that tries.
137
+
138
+ **What is worth covering is your own error handling**, by making the mock fail the way TLS fails. Three
139
+ forms, matching the three ways a reason is recognized:
140
+
141
+ ```js
142
+ // 1. the TLS 1.3 connection drop — needs `cert` or `key` on the request, or it stays a plain ECONNRESET
143
+ mock.onGet(url).replyWithNetworkError('ECONNRESET')
144
+
145
+ // 2. a reason matched on the OpenSSL code. `replyWithNetworkError` only sets `error.code` for `E…` codes,
146
+ // so anything else has to carry the code itself
147
+ mock.onGet(url).replyWithError(Object.assign(new Error('cert expired'), { code: 'CERT_HAS_EXPIRED' }))
148
+
149
+ // 3. a reason matched on the message — the handshake alerts and every local-material failure
150
+ mock.onGet(url).replyWithError(new Error('sslv3 alert certificate required'))
151
+ mock.onGet(url).replyWithError(new Error('error:06065064:digital envelope routines::bad decrypt'))
152
+ ```
153
+
154
+ Each rejects with the `TLSError` from the tables above, so a suite can assert that a retry, a log line or a
155
+ surfaced message behaves the way it should.
156
+
157
+ **The `https://` guard needs no mock at all** — the request is rejected before anything is sent:
158
+
159
+ ```js
160
+ await expect(Flowrunner.Request.get('http://api.vendor.com/x').cert({ cert, key }))
161
+ .rejects.toThrow('A client certificate can only be used with an https:// URL.')
162
+ ```
@@ -0,0 +1,160 @@
1
+ # 18 — Test Recipes
2
+
3
+ Per-kind testing recipes, split out of [15-unit-tests.md](15-unit-tests.md) so a suite only loads what its
4
+ service has. **Read 15 first** — the harness, `runServiceMethod`, the HTTP mock, the history record and the
5
+ suite skeleton are all there, and everything below assumes them.
6
+
7
+ Load only the sections that apply: a service with no triggers does not need *Triggers*, and one that never
8
+ touches a file does not need *Files API*.
9
+
10
+ ## Dictionaries
11
+
12
+ `{ search?, cursor?, criteria? }` in, `{ items: [{ label, value, note? }], cursor }` out
13
+ ([05-dictionaries.md](05-dictionaries.md)). Cover the mapping, a case-insensitive search, an absent
14
+ `search` listing everything, and empty data answering `{ items: [], cursor: null }`.
15
+
16
+ **A dictionary is invoked through a single `payload` param** — the runner synthesizes it, you never declare
17
+ it ([05-dictionaries.md](05-dictionaries.md)). So `methodData` wraps the whole `{ search, cursor, criteria }`
18
+ envelope in `payload`, and the per-`describe` shortcut is where that wrapper belongs, so no individual test
19
+ repeats it:
20
+
21
+ ```js
22
+ // One shortcut per describe, naming the method once — the method name IS the dictionary id.
23
+ function runItemsDictionaryMethod(payload) {
24
+ return runMethod({ methodName: 'getItemsDictionary', methodData: { payload } })
25
+ }
26
+ ```
27
+
28
+ `payload` itself has to be there. `methodData: { payload: null }` is a malformed **call**, not an empty
29
+ search, and throws `MissingMethodParamError` — so "no search" means an absent or null `search` **inside** the
30
+ payload, which is `runItemsDictionaryMethod({})`.
31
+
32
+ Then the failure branch, and read [05-dictionaries.md](05-dictionaries.md) before deciding what to assert —
33
+ the two cases that look alike are not the same:
34
+
35
+ - **A search that matched nothing** is `{ items: [], cursor: null }`. That is the documented behaviour of a
36
+ *resolve* dictionary and the right thing to pin.
37
+ - **A request that failed** — a rejected key, a dropped connection — is not "there are none". A dictionary
38
+ that answers `{ items: [] }` there hands the flow author an empty dropdown and no way to tell why, and if
39
+ the service does that behind a bare `catch`, pinning it as correct is how it stays.
40
+
41
+ ```js
42
+ it('answers an unmatched search with an empty list', async () => {
43
+ httpMock.onGet(`${ BASE }/items`).reply({ items: [] })
44
+
45
+ await expect(runItemsDictionaryMethod({ search: 'nothing' })).resolves.toEqual({ items: [], cursor: null })
46
+ })
47
+
48
+ it('does not answer a rejected key with an empty list', async () => {
49
+ httpMock.onGet(`${ BASE }/items`).replyWithError({ message: 'Invalid API key' }, 401)
50
+
51
+ await expect(runItemsDictionaryMethod({})).rejects.toThrow()
52
+ })
53
+ ```
54
+
55
+ If the second one fails because the service swallows the error, that is a finding to report — not a test to
56
+ rewrite into agreement with the service.
57
+
58
+ ## Triggers
59
+
60
+ Only the SYSTEM methods are runnable, because only they are what the platform calls
61
+ ([08-polling-triggers.md](08-polling-triggers.md), [09-realtime-triggers.md](09-realtime-triggers.md)). A
62
+ trigger's own handler is reached *through* one of them, and the mapping in between is the part most likely
63
+ to be wrong — calling the handler directly skips exactly that.
64
+
65
+ **Group by trigger, never by SYSTEM method.** The groups are `onMessage`, `onChannelPost`,
66
+ `onChatJoinRequest` — the things a flow author picks from a list. Declare the SYSTEM shortcuts once at the
67
+ top of `RealTime Triggers`, then call them inside each trigger's own `describe`. A
68
+ `describe('handleTriggerResolveEvents')` collecting every trigger's shaping tests is wrong: it reads as a
69
+ statement about the runtime rather than about the service, and it scatters one trigger's behaviour across
70
+ several groups.
71
+
72
+ Their payload goes one level down, under `invocation`:
73
+
74
+ ```js
75
+ describe('RealTime Triggers', () => {
76
+ function runHandleTriggerResolveEventsMethod(invocation) {
77
+ return runMethod({ methodName: 'handleTriggerResolveEvents', methodData: { invocation } })
78
+ }
79
+
80
+ function runHandleTriggerUpsertWebhookMethod(invocation) {
81
+ return runMethod({ methodName: 'handleTriggerUpsertWebhook', methodData: { invocation } })
82
+ }
83
+
84
+ describe('onMention', () => {
85
+ it('shapes one event per mention in the delivery', async () => {
86
+ const result = await runHandleTriggerResolveEventsMethod({
87
+ body: { team_id: 'T1', event: { type: 'message', text: 'hey', user: 'U9' } },
88
+ })
89
+
90
+ // The WHOLE emission — one delivery often produces events for other triggers too.
91
+ expect(result).toEqual({ eventScopeId: 'T1', events: [{ name: 'onMention', data: { … } }] })
92
+ })
93
+
94
+ it('registers one webhook covering this trigger', async () => {
95
+ // the registration path belongs here too — not in a group named after the SYSTEM method
96
+ const result = await runHandleTriggerUpsertWebhookMethod({ callbackUrl: 'https://cb/x', triggers: [] })
97
+
98
+ expect(result).toEqual({ webhookData: { id: 'hook_1' } })
99
+ })
100
+ })
101
+ })
102
+ ```
103
+
104
+ Polling is about state — the first poll seeds and emits nothing, later polls emit only what is new:
105
+
106
+ ```js
107
+ const result = await runHandleTriggerPollingForEventMethod({
108
+ eventName: 'onMessageFromQuery', triggerData: { query: 'x' }, state: { messages: [{ ts: '1.1' }] },
109
+ })
110
+
111
+ expect(result).toEqual({ events: [{ ts: '3.3' }], state: { messages: [{ ts: '1.1' }, { ts: '3.3' }] } })
112
+ ```
113
+
114
+ Webhook lifecycle (`handleTriggerUpsertWebhook` / `DeleteWebhook`) is asserted like any action — the whole
115
+ history entry for the registration call, the whole returned `webhookData` — and it lives inside a trigger's
116
+ `describe` like everything else. One registration serves every trigger, so exercise it under the trigger
117
+ whose delivery the rest of that group covers rather than repeating it under all of them.
118
+
119
+ > **The live trigger set is out of reach.** `triggers` is resolved from persisted flow instances, which a
120
+ > test has none of, so whatever array a subscribe-path invocation carries is discarded silently. Do not
121
+ > build a test on it — see *What the harness cannot reach* in
122
+ > [13-runtime-contracts.md](13-runtime-contracts.md).
123
+
124
+ ## Files API
125
+
126
+ Hand a backend to `runServiceMethod({ createFiles })` — the same seam the platform fills in production
127
+ ([10-files-api.md](10-files-api.md)). Storage is real, so the test asserts **what ended up saved** rather
128
+ than what a stub was asked for.
129
+
130
+ ```js
131
+ beforeAll(() => { httpMock = createNockMock(); filesAPI = createFilesSandbox() })
132
+ afterEach(() => { httpMock.reset(); filesAPI.reset() })
133
+ afterAll(() => { httpMock.dispose(); filesAPI.dispose() })
134
+
135
+ function runMethod({ methodName, methodData, data }) {
136
+ return runServiceMethod({ serviceId, serviceEntryPointPath, configs,
137
+ createFiles: filesAPI.inMemory, ...data, methodName, methodData })
138
+ }
139
+ ```
140
+
141
+ ```js
142
+ filesAPI.stored() // [{ key, scope, filename, contents, size, ttl, generateUrl, … }]
143
+ filesAPI.urlFor('flow/test-flow-id/a.pdf') // the URL the service hands back to the flow
144
+ filesAPI.keys() · contents(scope, name) · read(scope, name)
145
+ filesAPI.calls() // [{ method, scope, filename, size, options }] — options as the service BUILT them
146
+ filesAPI.seed('FLOW', 'a.pdf', 'BYTES') // storage an earlier run left behind
147
+ filesAPI.failNext(body, 507) // one-shot failure
148
+ ```
149
+
150
+ Use `inMemory`: a saved file's URL is an output the flow reads, not something a third party fetches, so
151
+ local storage behind a `file://` URL is the whole requirement. The clock is frozen, so `createdAt` and
152
+ `urlExpiresAt` are byte-stable and a whole-object compare on a result works at all. `calls()` is where an
153
+ inverted option spread shows — `options` is the object the service built, so `options.filename` is whichever
154
+ name actually won.
155
+
156
+ With the client injected **nothing goes over the wire**, which is itself worth asserting: `httpMock.history`
157
+ then holds the vendor's calls and nothing else, so a whole-array compare on it proves the upload never
158
+ reached the platform's file service.
159
+
160
+ The full contract, limits included, is in the docstring at the top of `sandbox/files-mock.js`.
@@ -0,0 +1,120 @@
1
+ # FlowRunner Extension Development
2
+
3
+ This is the reference for building a FlowRunner service extension. It describes the one supported way to
4
+ declare a service — use it both for new services and for changes to existing ones.
5
+
6
+ > **This tree is self-contained.** It ships as an npm module, so every link must be relative and must stay
7
+ > inside this folder. Never link out to the FlowRunner console repo — if a fact from there matters, state the
8
+ > fact here rather than pointing at it.
9
+
10
+ > **This reference is complete, and it is the only source.** Everything needed to build a service — the
11
+ > declaration surface, the runtime behaviour it depends on, and the naming and layout rules — is written
12
+ > down here. So: **never read the `flowrunner-cli` source, its bundled runtime, its type definitions or its
13
+ > templates**, and never infer a rule from a neighbouring service or from what an API "probably" does.
14
+ >
15
+ > If you cannot find something here, that is a defect in this reference, not an invitation to go and look.
16
+ > Stop, state what is missing, and proceed on the documented behaviour — flagging plainly that you did.
17
+ > Guessing produces a service that looks right and is wrong in a way nobody sees until it is deployed.
18
+
19
+ > **These are authoring docs — how to *write* a service.** Runtime behaviour appears here only where it
20
+ > changes what you should write: the validation guarantees in [07-actions.md](07-actions.md), the trigger
21
+ > lifecycles in [08](08-polling-triggers.md)/[09](09-realtime-triggers.md), the service model in
22
+ > [11-output-model.md](11-output-model.md), and the runtime contracts in
23
+ > [13-runtime-contracts.md](13-runtime-contracts.md).
24
+
25
+ A service is a single JavaScript module in `services/{id}/src/index.js` that builds an extension with the
26
+ global `Flowrunner.createExtension(...)` factory. Everything is declared through factory props and zod
27
+ schemas (`Flowrunner.z`). Declaring a service produces the platform's service model
28
+ (`SharedExtensionServiceInfo` + `methodsMap` + config descriptions), and the `handleTrigger*` SYSTEM methods
29
+ are the runtime seam the platform drives.
30
+
31
+ ## Working on an existing service
32
+
33
+ Read its `src/index.js` first and follow what is already there — its `id` values, categories, labels and
34
+ param names are live contract, not style choices.
35
+
36
+ ## Identity & naming
37
+
38
+ - **Identity:** every registered item (action / trigger / dictionary) is keyed by **`id`** (not `name`).
39
+ `id` is persisted and drives execution — once a service is deployed, an `id` can never change, and an
40
+ existing service's `id`s are authoritative even when they read oddly. `name` is the service display label
41
+ only; per-item human text is `label`.
42
+ - **Uniqueness:** ids must be unique across *all* item kinds — see
43
+ [01-service-structure.md](01-service-structure.md).
44
+ - **Naming:** a dictionary `id` starts with `get` and ends with `Dictionary` (`getTablesDictionary`), and
45
+ the const holding the ref carries the same name; reused param schemas end `Param` (`appIdParam`).
46
+
47
+ ## Reading order
48
+
49
+ **Decide the feature set first, then load in one batch.** Every document you load stays in context for the
50
+ rest of the task and is re-read on every subsequent turn, so loading all eighteen to build a three-action
51
+ service is the single most expensive mistake available here. Loading one you turn out to need *late* is
52
+ worse still — it costs a rewrite. So: settle what the service will contain, then read the core plus the
53
+ conditional groups that apply, together.
54
+
55
+ ### Core — read for every service
56
+
57
+ | # | Document | Covers |
58
+ |---|----------|--------|
59
+ | 1 | [01-service-structure.md](01-service-structure.md) | `Flowrunner.createExtension(props)`: id/name/logo/colors, `usesFileStorage`, `configItems`, `initContext`, `apiRequest`, `helpers`; folder layout |
60
+ | 2 | [02-zod-types.md](02-zod-types.md) | zod types & plugins — widget derived from type; `.label`/`.describe`/`.example`/`.optional`/`.default`/`.shared`/`.dictionary`/`.map` |
61
+ | 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — and `dynamicParams` (runtime-generated fields) |
62
+ | 4 | [04-http-requests.md](04-http-requests.md) | the shared `apiRequest` helper, and the `Flowrunner.Request` client under it — sending model, methods, query, headers, bodies, multipart, responses, `ResponseError` |
63
+ | 5 | [05-dictionaries.md](05-dictionaries.md) | `ext.dictionary(props)` — dynamic param options; `label` (→ `operationName`, always set it), `criteria` → auto `dependsOn`, optional `result` sample |
64
+ | 6 | [07-actions.md](07-actions.md) | `ext.addAction(props)`, the shared `execute` context bag, and input validation |
65
+ | 7 | [16-gotchas.md](16-gotchas.md) | Cross-cutting traps that fail *silently* — empty-string params, lookup tables keyed by user input, dictionary error handling. Deliberately short |
66
+ | 8 | [14-reference-service.md](14-reference-service.md) | A complete verified service exercising the whole surface — **read this instead of the CLI templates** |
67
+
68
+ Dictionaries are core because nearly every service has at least one id-like parameter, and a flow author
69
+ picking a value from a list is the difference between a usable service and one that requires them to go
70
+ and look an id up by hand. Assume you need [05](05-dictionaries.md) until you have established that no
71
+ parameter can be backed — and note that "the API has no endpoint that lists these" does **not** settle it;
72
+ see *Browse versus resolve* in that document.
73
+
74
+ ### Conditional — read the group that applies
75
+
76
+ Add whole groups, decided from the feature set, before you start writing.
77
+
78
+ **OAuth2** — [06-oauth2.md](06-oauth2.md)
79
+ Read it when the API authenticates with OAuth2. **Skip it entirely for API-key, bearer-token or
80
+ URL-embedded-token auth** — those need only `configItems` + `initContext` from [01](01-service-structure.md).
81
+
82
+ **Triggers** — [08-polling-triggers.md](08-polling-triggers.md) · [09-realtime-triggers.md](09-realtime-triggers.md)
83
+ Skip both when the service is actions-only. Otherwise read the one that matches how the API delivers
84
+ changes: 08 for polling, 09 for webhooks. Read both only while you are deciding between them — and note
85
+ that some APIs make the two mutually exclusive, in which case the decision comes first and the loser is
86
+ dead weight.
87
+
88
+ **Files** — [10-files-api.md](10-files-api.md)
89
+ Read it when any parameter takes a file or an action returns one. It also states which file scopes a method
90
+ can use depending on whether it runs inside a flow execution, so read it before declaring `usesFileStorage`.
91
+ Letting the flow author choose how a file is stored, listed, fetched or deleted is a platform param group,
92
+ not something you declare — one per Files call. See *Platform param schemas* in
93
+ [03-parameters.md](03-parameters.md).
94
+
95
+ **Client certificates** — [17-client-certificates.md](17-client-certificates.md)
96
+ Read it when the API requires mutual TLS. `.cert()` belongs in `apiRequest`, and the certificate is needed
97
+ for the OAuth2 token call too, so decide this before writing the auth layer.
98
+
99
+ **Verifying the build** — [13-runtime-contracts.md](13-runtime-contracts.md) · [11-output-model.md](11-output-model.md)
100
+ Read 13 at the build-check step, or earlier if a runtime fact is unclear (where `.default()` is applied,
101
+ which SYSTEM-method contracts are exercisable locally). Read
102
+ [11](11-output-model.md) only when you need to know how a declaration surfaces to the platform — it is a
103
+ debugging aid, not something you need in order to write a service correctly.
104
+
105
+ **Service README** — [12-service-readme.md](12-service-readme.md)
106
+ Read it at the step where you write the service `README.md`, not up front.
107
+
108
+ **Unit tests** — [15-unit-tests.md](15-unit-tests.md) · [18-test-recipes.md](18-test-recipes.md)
109
+ Read 15 when you write or fix a suite; add [18](18-test-recipes.md) for the kinds the service actually
110
+ registers — dictionaries, triggers, files — and skip it entirely for an actions-only service. `flowrunner init` copies a unit-test harness into the project —
111
+ `sandbox/` at the root, one suite per service in `services/{id}/tests/` — which runs a service exactly as
112
+ the platform does with HTTP intercepted at the socket. It is a separate document because writing a service
113
+ and testing one are separate jobs; do not read it while writing a service.
114
+
115
+ That is also separate from **checking that a service builds**, which needs no suite at all and is part of
116
+ writing one: `require('flowrunner-cli/runtime')` exports `buildServiceDefinition`, `getServiceConfigs`,
117
+ `runServiceMethod`, `detectVersion`, `resetRegistry` and `parseJsDocToServiceJson`, and importing it installs
118
+ the `Flowrunner` global (`Request`, `z`, `crypto`, `createExtension`, `getExtension`, `ServerCode`).
119
+ Signatures, a copy-paste snippet, and the boundary between a throwaway check and a suite are in
120
+ [13-runtime-contracts.md](13-runtime-contracts.md).
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: flowrunner-service-code-engineer
3
+ description: "Use this agent to create, review, fix or extend a FlowRunner custom extension service in this project — anything that touches a service's src/index.js. This includes new services from scratch, adding actions or triggers, wiring dictionaries to parameters, declaring params with zod, implementing OAuth2, and debugging an existing service. Examples — <example>Context: User wants a new service. user: \"I need a Linear service that can create issues and list teams\" assistant: \"I'll use the flowrunner-service-code-engineer agent to build the service against the shipped authoring reference.\"</example> <example>Context: A parameter should be a dropdown. user: \"The projectId field on my Asana service should be a dropdown\" assistant: \"Let me use the flowrunner-service-code-engineer agent to add a dictionary and wire it to that param.\"</example> <example>Context: An action misbehaves. user: \"My Stripe refund action returns the wrong shape\" assistant: \"I'll use the flowrunner-service-code-engineer agent to review the action and its result declaration.\"</example>"
4
+ color: red
5
+ ---
6
+
7
+ You are an expert FlowRunner extension engineer. You create, review, fix and extend custom extension
8
+ services in this project. A service is one JavaScript module — `services/{id}/src/index.js` — that calls
9
+ `Flowrunner.createExtension(props)` and registers items on the returned `ext`. Everything is declared through
10
+ factory props and zod schemas (`Flowrunner.z`).
11
+
12
+ ## Load the documentation first — always
13
+
14
+ The canonical authoring reference ships inside the installed CLI, versioned with it:
15
+
16
+ `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/`
17
+
18
+ If that directory does not exist, stop and ask the developer to install or update `flowrunner-cli` — do not
19
+ proceed from memory.
20
+
21
+ **Read `README.md` there before anything else, then the documents it routes you to.** It carries the
22
+ identity-and-naming rules and a reading-order split into a *core* set and a *conditional* set — that split
23
+ is the routing authority, so follow it rather than guessing from filenames.
24
+
25
+ **Load once, deliberately.** Decide the feature set first — auth style, whether there are triggers and of
26
+ which kind, whether any parameter takes a file or wants a dropdown — then read the core plus exactly the
27
+ conditional documents that decision implies, in a single batch. Do not read all eighteen by default: every
28
+ document stays in context and is re-read on each subsequent turn, so an unneeded one is paid for many times
29
+ over. Reading a needed one late is worse, which is why the feature-set decision comes first.
30
+
31
+ For a service you are building from scratch, `14-reference-service.md` is a complete verified example; read
32
+ it once instead of reconstructing the shape from snippets.
33
+
34
+ Do not work from memory, and do not infer a rule from a neighbouring service. **Where anything in this file
35
+ conflicts with those documents, the documents win** — this file describes *how to work*, they define *what
36
+ is correct*.
37
+
38
+ **The reference is complete, and it is the only source.** Those documents are the one thing you read out
39
+ of `node_modules/` — never the rest of the `flowrunner-cli` package: not its source, not its bundled
40
+ runtime, not its type definitions, not its `templates/`. And never reason from what the runtime "probably"
41
+ does. If something you need is not documented, that is a defect in the reference: say so in your report,
42
+ proceed on what *is* documented, and mark plainly which part you could not confirm. A supposition that
43
+ happens to be wrong produces a service that looks correct and fails only once deployed.
44
+
45
+
46
+ ## Creating a service
47
+
48
+ 1. **Establish the target API's real behaviour from its official documentation before writing code** — the
49
+ auth methods it supports, where credentials go (a URL-embedded secret must be redacted in logs), each
50
+ listing endpoint's pagination contract, whether ids are numbers or strings, which response fields are
51
+ optional, the error body shape, and any mutually exclusive modes such as webhook versus polling. Every
52
+ design decision should trace to documented behaviour rather than an assumption.
53
+ 2. **Default scope is the complete service, in one pass.** The API's commonly-used action surface; a
54
+ dictionary on every id-like parameter that has any viable data source; triggers wherever the API supports
55
+ webhooks or polling. A plain parameter with no dictionary, or a missing trigger, is acceptable only as a
56
+ documented API limitation — never as an omission because it was harder. Narrow this only when the
57
+ developer narrows it explicitly.
58
+ **On dictionaries specifically: "the API has no endpoint that lists these" does not justify free text.**
59
+ A dictionary's `execute` receives `search`, so a parameter is still backable whenever the API can look
60
+ one entity up by id, handle or URL — see *Browse versus resolve* in `05-dictionaries.md`. Every id-like
61
+ parameter a flow author has to type by hand is a defect unless the API can neither list nor resolve it,
62
+ and that verdict belongs in the service `README.md`.
63
+ 3. Read the core documents plus exactly the conditional ones your feature set implies, in one batch.
64
+ 4. Scaffold the layout, then write `src/index.js` against the documents — put every HTTP call through the
65
+ shared `apiRequest` prop so unwrapping, error normalisation and secret redaction happen in one place.
66
+ 5. Derive per-handler types where they belong: `configItems`, `initContext` and `helpers` are what every
67
+ handler's context bag is inferred from. Widen `initContext`'s return rather than casting at a call site.
68
+ 6. **Verify the service builds before you call it done** — `buildServiceDefinition` over the entry point,
69
+ per `13-runtime-contracts.md`. Confirm the model is the one you intended, then delete the scratch script.
70
+ Exercising a handler against a stubbed API is worthwhile and belongs in the suite the test engineer
71
+ writes; iterating scratch scripts to discover runtime internals is not — see the hard rule below. Keep
72
+ this step to a small number of runs.
73
+ 7. Write the service's `README.md` — it ships with the service, not after it.
74
+ 8. **End your report with a handover** — see below. A suite is written next, by an agent that cannot see your
75
+ context.
76
+
77
+ ## Handing over to the test engineer
78
+
79
+ Your final report is the only thing the next agent inherits, and re-deriving your intent from the source is
80
+ the most expensive part of writing a suite. End it with a handover covering, compactly:
81
+
82
+ - **Every registered item** — action / dictionary / trigger `id`s with their param names, grouped by kind.
83
+ State it from the built model, not from memory of what you wrote.
84
+ - **What each one calls**: endpoint and verb, and any param that is transformed rather than passed through.
85
+ - **The error envelope** and how you normalise it, including anything you deliberately let through.
86
+ - **Deliberate omissions and their reason** — an endpoint you left out, a param with no dictionary because
87
+ the API can neither list nor resolve it. Without the reason these read as oversights and get re-litigated.
88
+ - **The paths you are least sure of.** Name them plainly. A path you guessed at is the one most worth a test,
89
+ and saying so is what gets it covered rather than confirmed.
90
+
91
+ Write it as a map for someone whose job is to *disagree* with you — not as an argument that the service is
92
+ correct. Do not write it to a file: a manifest on disk goes stale the moment the service changes, and the
93
+ test engineer can always rebuild the authoritative list itself.
94
+
95
+ ## Reviewing or fixing a service
96
+
97
+ 1. **Read the service's `src/index.js` in full first, and follow what is already there.** Its `id` values,
98
+ categories, labels and param names are live contract, not style choices.
99
+ 2. Read the documents covering the areas the service touches.
100
+ 3. Fix defects and every deviation from the documented rules.
101
+ 4. Re-verify that it still builds, and update its `README.md` if the action or trigger surface changed.
102
+
103
+ ## Hard rules
104
+
105
+ - **An `id` is frozen once deployed** — it is the persisted execution key, and ids must be unique across all
106
+ item kinds. The reference states the full rule; treat every existing `id` as untouchable.
107
+ - All changes stay inside the one `services/{id}/` folder; service logic lives only in `src/index.js`.
108
+ - **Never read `node_modules/` as project source.** The authoring reference under
109
+ `node_modules/flowrunner-cli/ai-docs/` is the only exception; everything else in that package is off
110
+ limits, including the CLI's bundled runtime, its type definitions and its `templates/`. If a runtime fact
111
+ seems undocumented it belongs in `13-runtime-contracts.md`: report the gap rather than going to look.
112
+ - **Do not reverse-engineer an undocumented runtime contract by probing it.** Calling a SYSTEM method with
113
+ empty or deliberately malformed input to read its validation errors back is the same offence as reading
114
+ the bundle, in a more expensive form: it burns a turn per attempt and it tells you about the runtime's
115
+ input validator rather than about what your handler receives in production. `13-runtime-contracts.md`
116
+ states which contracts are exercisable locally and which the harness cannot reach. If what you need is
117
+ not there, say so in your report and proceed on the documented behaviour — do not guess, and never present
118
+ an inference drawn from error messages as a verified finding.
119
+ - **Never hedge against an unclear contract.** When you cannot tell how a runtime API behaves, do not write
120
+ code that tries to work either way — feature-detecting a method, tolerating two shapes, `?.` over a call
121
+ you are unsure exists. That hedge looks careful, type-checks, and silently picks the wrong branch; it has
122
+ already shipped a service whose file upload sent an empty request. Instead: re-read the reference, and if
123
+ the answer genuinely is not there, **write the single branch the documentation implies and report the gap**
124
+ — naming the fact you could not confirm — so it reaches `13-runtime-contracts.md` or `16-gotchas.md`. Do
125
+ not investigate the runtime to settle it yourself; the reference is the contract, and a hole in it is for
126
+ the developer to close, not for you to paper over.
127
+ - **You do not write tests — none, of any kind, unless you were explicitly asked to.** Not a suite, not a
128
+ single `it()`, not a "temporary" or "throwaway" test file you intend to delete. `flowrunner-service-test-engineer`
129
+ owns `services/{id}/tests/`, and an engineer who owns both ends up fixing the service to make the test
130
+ pass. Writing tests unasked also spends a large share of the budget on work nobody requested — a suite is
131
+ routinely bigger than the service it covers.
132
+
133
+ When the service is done, **ask whether it should be covered with unit tests** and stop there. Do not
134
+ start.
135
+
136
+ This does **not** cover the build check in step 6: `buildServiceDefinition` over the entry point is not a
137
+ test, it is expected every time, and it leaves nothing behind.
138
+ - **A service's `README.md` is part of the service.** Whenever its actions or triggers change, update the
139
+ README in the same pass. List each item's `label`, never its `id`.