@classytic/arc 2.45.1 → 2.46.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 (321) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  3. package/dist/{EventTransport-4b0noGwa.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-4pABQnGn.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-BBaN_Ne-.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-kiZzy5bX.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-BLnbDA6g.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
  9. package/dist/audit/index.d.mts +2 -10
  10. package/dist/audit/index.mjs +8 -12
  11. package/dist/auth/audit.d.mts +0 -2
  12. package/dist/auth/audit.mjs +2 -3
  13. package/dist/auth/index.d.mts +9 -17
  14. package/dist/auth/index.mjs +26 -29
  15. package/dist/auth/redis-session.d.mts +2 -4
  16. package/dist/auth/redis-session.mjs +2 -3
  17. package/dist/{authorizationDecision-CVlaTjAX.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DSy7KkeX.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-B4IhILv9.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
  21. package/dist/cache/index.d.mts +4 -10
  22. package/dist/cache/index.mjs +5 -6
  23. package/dist/{caching-DqakP2vY.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-XoiVrWZ2.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +9 -18
  26. package/dist/cleanup/index.mjs +12 -20
  27. package/dist/cli/commands/describe.d.mts +1 -3
  28. package/dist/cli/commands/describe.mjs +4 -5
  29. package/dist/cli/commands/docs.d.mts +1 -3
  30. package/dist/cli/commands/docs.mjs +4 -5
  31. package/dist/cli/commands/doctor.d.mts +1 -3
  32. package/dist/cli/commands/doctor.mjs +2 -3
  33. package/dist/cli/commands/generate.d.mts +1 -1
  34. package/dist/cli/commands/generate.mjs +2 -2
  35. package/dist/cli/commands/init.d.mts +1 -1
  36. package/dist/cli/commands/init.mjs +2 -2
  37. package/dist/cli/commands/introspect.d.mts +1 -3
  38. package/dist/cli/commands/introspect.mjs +3 -4
  39. package/dist/cli/index.d.mts +2 -2
  40. package/dist/cli/index.mjs +3 -3
  41. package/dist/{constants-CtWkmWn3.mjs → constants-CHZMUwBW.mjs} +2 -3
  42. package/dist/context/index.d.mts +0 -8
  43. package/dist/context/index.mjs +6 -7
  44. package/dist/core/index.d.mts +3 -3
  45. package/dist/core/index.mjs +8 -8
  46. package/dist/{core-Cro2v5a7.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-k-gwiPv6.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-BqWqhAPG.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-Dw7L72Hz.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-pxbd7BBK.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-DwgEjLCO.mjs → defineResource-CGmdmGwh.mjs} +78 -29
  53. package/dist/discovery/index.d.mts +1 -3
  54. package/dist/discovery/index.mjs +2 -3
  55. package/dist/docs/index.d.mts +8 -8
  56. package/dist/docs/index.mjs +4 -5
  57. package/dist/{elevation-B9wF2Z1F.mjs → elevation-CzhqAyVN.mjs} +9 -10
  58. package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  59. package/dist/encryption/index.d.mts +1 -7
  60. package/dist/encryption/index.mjs +8 -13
  61. package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
  62. package/dist/{errorHandler-Dr2nG0Ui.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-BtHzrSA6.mjs → errors-BY8vzlP4.mjs} +2 -3
  64. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-Dvs7OBw8.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-BVoCTG5c.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
  68. package/dist/events/index.d.mts +4 -16
  69. package/dist/events/index.mjs +8 -9
  70. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  71. package/dist/events/transports/redis-stream-entry.mjs +5 -6
  72. package/dist/events/transports/redis.d.mts +2 -4
  73. package/dist/events/transports/redis.mjs +3 -4
  74. package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
  75. package/dist/factory/index.d.mts +4 -14
  76. package/dist/factory/index.mjs +12 -18
  77. package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
  78. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  79. package/dist/{fields-C1e_7Fwi.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-xaiEKtz8.mjs → filter-merge-BAWi019Q.mjs} +2 -3
  81. package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
  82. package/dist/{generate-DJiJMaXN.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Dr-wt6Tr.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-DkkWbJtQ.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-BLYn_Hds.mjs → health-Dp-3EC9o.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/idempotency/index.d.mts +3 -9
  89. package/dist/idempotency/index.mjs +10 -13
  90. package/dist/idempotency/redis.d.mts +1 -1
  91. package/dist/idempotency/redis.mjs +3 -4
  92. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  93. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  94. package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
  95. package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
  96. package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
  97. package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
  98. package/dist/index.d.mts +7 -9
  99. package/dist/index.mjs +12 -13
  100. package/dist/{init-CW3kJqNW.mjs → init-BOaNkLYb.mjs} +18 -35
  101. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  102. package/dist/integrations/event-gateway.d.mts +3 -5
  103. package/dist/integrations/event-gateway.mjs +3 -4
  104. package/dist/integrations/index.d.mts +3 -3
  105. package/dist/integrations/index.mjs +1 -1
  106. package/dist/integrations/jobs/index.d.mts +1 -1
  107. package/dist/integrations/jobs/index.mjs +7 -11
  108. package/dist/integrations/mcp/index.d.mts +7 -39
  109. package/dist/integrations/mcp/index.mjs +8 -14
  110. package/dist/integrations/mcp/testing.d.mts +3 -5
  111. package/dist/integrations/mcp/testing.mjs +3 -4
  112. package/dist/integrations/streamline.d.mts +1 -3
  113. package/dist/integrations/streamline.mjs +4 -5
  114. package/dist/integrations/webhooks.d.mts +2 -4
  115. package/dist/integrations/webhooks.mjs +4 -5
  116. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  117. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  118. package/dist/integrations/websocket-redis.d.mts +2 -4
  119. package/dist/integrations/websocket-redis.mjs +2 -3
  120. package/dist/integrations/websocket.d.mts +2 -2
  121. package/dist/integrations/websocket.mjs +13 -24
  122. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  123. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  124. package/dist/{jsonBody-DPU8yYwA.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-Dgn6OYhl.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-BtKj6P1P.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-Bmq6TnB7.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
  128. package/dist/logger/index.d.mts +1 -3
  129. package/dist/logger/index.mjs +2 -2
  130. package/dist/{logger-qQNLlOAU.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-DDfe8jAP.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-C0Blueoh.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-DYka72iN.mjs → metrics-CZDQWVjS.mjs} +4 -5
  134. package/dist/middleware/index.d.mts +1 -5
  135. package/dist/middleware/index.mjs +4 -5
  136. package/dist/migrations/index.d.mts +0 -2
  137. package/dist/migrations/index.mjs +3 -4
  138. package/dist/{module-BszSyWbd.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-RHvIkNmc.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-BrFPc3Ny.mjs → openapi-Co7hl073.mjs} +18 -28
  143. package/dist/outbox-admin/index.d.mts +2 -4
  144. package/dist/outbox-admin/index.mjs +6 -7
  145. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
  146. package/dist/{outbox-module-DF4Bu_Qa.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
  147. package/dist/permissions/index.d.mts +4 -4
  148. package/dist/permissions/index.mjs +7 -7
  149. package/dist/{permissions-DN1CWH56.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-B8uq865o.mjs → pipe-Czpw9U2n.mjs} +3 -4
  151. package/dist/pipeline/index.d.mts +1 -9
  152. package/dist/pipeline/index.mjs +5 -8
  153. package/dist/{plan-DUGfynNg.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-ByU3h-bR.mjs → plugin-DTWt_8C3.mjs} +130 -62
  155. package/dist/plugins/index.d.mts +8 -16
  156. package/dist/plugins/index.mjs +22 -26
  157. package/dist/plugins/response-cache.d.mts +2 -4
  158. package/dist/plugins/response-cache.mjs +10 -10
  159. package/dist/plugins/tracing-entry.d.mts +1 -1
  160. package/dist/plugins/tracing-entry.mjs +3 -4
  161. package/dist/{pluralize-Cdya8zYt.mjs → pluralize-msB9X3yw.mjs} +2 -3
  162. package/dist/presets/filesUpload.d.mts +4 -6
  163. package/dist/presets/filesUpload.mjs +6 -7
  164. package/dist/presets/index.d.mts +3 -19
  165. package/dist/presets/index.mjs +2 -2
  166. package/dist/presets/multiTenant.d.mts +1 -1
  167. package/dist/presets/multiTenant.mjs +7 -7
  168. package/dist/presets/search.d.mts +3 -5
  169. package/dist/presets/search.mjs +3 -4
  170. package/dist/{presets-CCOlKTZw.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-BGty6ie4.mjs → projection-ClBqtsIw.mjs} +3 -4
  172. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  173. package/dist/{queryCachePlugin-B7itTkWu.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-DBWO59H9.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-_59Rlje8.mjs → realtime-Ber8uJN2.mjs} +17 -19
  177. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  178. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  179. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  180. package/dist/registry/index.d.mts +2 -12
  181. package/dist/registry/index.mjs +3 -3
  182. package/dist/{registry-uG4wr541.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CiU3ZynH.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-Dr2pnXZg.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DBKIdmDi.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-DxOaghWD.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BBdj5yRq.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-DpVPUeXF.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-BNTqM1Eh.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-D_3eUO6V.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-CVS7c1nv.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-BQbg7loK.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-CUI3hPQR.mjs → schemaIR-CEScKT2v.mjs} +3 -4
  196. package/dist/schemas/index.d.mts +0 -2
  197. package/dist/schemas/index.mjs +2 -3
  198. package/dist/scim/index.d.mts +0 -12
  199. package/dist/scim/index.mjs +10 -18
  200. package/dist/scope/index.d.mts +2 -6
  201. package/dist/scope/index.mjs +5 -5
  202. package/dist/{scope-DFXngazv.mjs → scope-B-Sm9m_E.mjs} +5 -6
  203. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  204. package/dist/{shutdown-BCXCwghd.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-5jOzYQ_L.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-BilBz766.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-BG_uJL6J.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-CzLZdVa1.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-DgUvMWlv.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-EWnIZ-U8.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-CVMvO5DH.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-DIH-GX4g.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
  214. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  215. package/dist/testing/cleanupStoreContract.mjs +2 -3
  216. package/dist/testing/index.d.mts +6 -32
  217. package/dist/testing/index.mjs +24 -37
  218. package/dist/testing/outboxStoreContract.d.mts +1 -3
  219. package/dist/testing/outboxStoreContract.mjs +3 -4
  220. package/dist/testing/requiredPorts.d.mts +2 -4
  221. package/dist/testing/requiredPorts.mjs +3 -4
  222. package/dist/testing/storageContract.d.mts +2 -4
  223. package/dist/testing/storageContract.mjs +2 -3
  224. package/dist/{timing-q9NITK04.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-NHmhDIOF.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CPYR9RCg.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
  228. package/dist/types/index.d.mts +4 -4
  229. package/dist/types/index.mjs +1 -1
  230. package/dist/types/storage.d.mts +1 -1
  231. package/dist/types/storage.mjs +1 -1
  232. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  233. package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
  234. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  235. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  236. package/dist/{types-BI4sbUJ3.mjs → types-CuGjhn83.mjs} +5 -6
  237. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  238. package/dist/usage/index.d.mts +2 -10
  239. package/dist/usage/index.mjs +8 -12
  240. package/dist/{userHelpers-oBTU3a_k.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
  241. package/dist/utils/index.d.mts +5 -39
  242. package/dist/utils/index.mjs +12 -12
  243. package/dist/{utils-BmE8zRrh.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-Dby08LhR.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-P6JMNcJr.mjs → versioning-Dk2-19La.mjs} +4 -5
  246. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  247. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  248. package/dist/{workScope-BcMLKa3G.mjs → workScope-DoBsoVo4.mjs} +3 -4
  249. package/llms.txt +37 -30
  250. package/package.json +9 -8
  251. package/skills/arc/SKILL.md +65 -844
  252. package/skills/arc/references/agent-auth.md +82 -193
  253. package/skills/arc/references/api-reference.md +41 -245
  254. package/skills/arc/references/auth-api-keys.md +99 -0
  255. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  256. package/skills/arc/references/auth-better-auth.md +78 -0
  257. package/skills/arc/references/auth-permissions.md +100 -0
  258. package/skills/arc/references/auth-strategies.md +122 -0
  259. package/skills/arc/references/boot.md +80 -0
  260. package/skills/arc/references/enterprise-auth.md +65 -81
  261. package/skills/arc/references/events-outbox.md +90 -0
  262. package/skills/arc/references/events.md +75 -440
  263. package/skills/arc/references/integrations-jobs.md +74 -0
  264. package/skills/arc/references/integrations-realtime.md +84 -0
  265. package/skills/arc/references/integrations-webhooks.md +71 -0
  266. package/skills/arc/references/integrations-workflows.md +47 -0
  267. package/skills/arc/references/mcp-auth.md +83 -0
  268. package/skills/arc/references/mcp-custom-tools.md +125 -0
  269. package/skills/arc/references/mcp-setup.md +115 -0
  270. package/skills/arc/references/mcp-testing.md +63 -0
  271. package/skills/arc/references/multi-tenancy.md +56 -230
  272. package/skills/arc/references/permissions-scope.md +81 -0
  273. package/skills/arc/references/production-api.md +119 -0
  274. package/skills/arc/references/production-audit.md +101 -0
  275. package/skills/arc/references/production-boot.md +91 -0
  276. package/skills/arc/references/production-caching.md +63 -0
  277. package/skills/arc/references/production-distributed.md +75 -0
  278. package/skills/arc/references/production-idempotency.md +83 -0
  279. package/skills/arc/references/production-observability.md +83 -0
  280. package/skills/arc/references/production-realtime.md +70 -0
  281. package/skills/arc/references/production-reliability.md +100 -0
  282. package/skills/arc/references/production-shutdown.md +43 -0
  283. package/skills/arc/references/querying.md +76 -0
  284. package/skills/arc/references/resources.md +97 -0
  285. package/skills/arc/references/schedules.md +79 -0
  286. package/skills/arc/references/scim.md +61 -208
  287. package/skills/arc/references/tenancy-scope-install.md +82 -0
  288. package/skills/arc/references/testing.md +101 -144
  289. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  290. package/skills/arc/references/validation.md +91 -0
  291. package/skills/arc/references/writes-hooks-errors.md +80 -0
  292. package/skills/arc-code-review/SKILL.md +67 -114
  293. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  294. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  295. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  296. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  297. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  298. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  299. package/skills/arc-code-review/references/scaffolding.md +61 -198
  300. package/skills/arc-code-review/references/severity.md +49 -102
  301. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  302. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  303. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  304. package/skills/arc-code-review/references/smells-platform.md +89 -0
  305. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  306. package/skills/arc-module-publishing/SKILL.md +82 -208
  307. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  308. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  309. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  310. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  311. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  312. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  313. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  314. package/skills/arc/references/auth.md +0 -729
  315. package/skills/arc/references/integrations.md +0 -452
  316. package/skills/arc/references/mcp.md +0 -691
  317. package/skills/arc/references/production.md +0 -835
  318. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  319. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  320. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  321. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -0,0 +1,84 @@
1
+ # WebSocket and event gateway
2
+
3
+ Peer: `@fastify/websocket`. Needs a persistent runtime (not serverless).
4
+
5
+ ## websocketPlugin
6
+
7
+ ```typescript
8
+ import fastifyWebsocket from '@fastify/websocket';
9
+ import { websocketPlugin } from '@classytic/arc/integrations/websocket';
10
+
11
+ await app.register(fastifyWebsocket);
12
+ await app.register(websocketPlugin, {
13
+ path: '/ws',
14
+ auth: true, // default; fails at boot if no fastify.authenticate and no authenticate()
15
+ resources: ['product', 'order'], // auto-broadcast <resource>.created|updated|deleted to the room of that name
16
+ roomPolicy: (client, room) => ['product', 'order'].includes(room), // default allow all
17
+ authenticate: async (request) => ({ userId, organizationId }), // returns AuthResult | null
18
+ heartbeatInterval: 30000, // 0 disables
19
+ reauthInterval: 300000, // 0 disables; expired token closes with 4003
20
+ maxClientsPerRoom: 10000,
21
+ maxMessageBytes: 16384,
22
+ maxSubscriptionsPerClient: 100,
23
+ maxOutboundBytes: 5 * 1024 * 1024,
24
+ exposeStats: 'authenticated', // false (default) | true | 'authenticated'; route {path}/stats
25
+ onConnect, onDisconnect, onMessage,
26
+ });
27
+ ```
28
+
29
+ Org-scoped events (`meta.organizationId`) reach only clients of that org.
30
+
31
+ ## Client protocol
32
+
33
+ | Direction | Message |
34
+ |---|---|
35
+ | server to client on connect | `{ type: 'connected', clientId, pushRef, resources }` |
36
+ | client to server | `{ type: 'subscribe', resource }` (or `channel`), `{ type: 'unsubscribe', resource }` |
37
+ | server reply | `{ type: 'subscribed', channel }`, `{ type: 'unsubscribed', channel }`, `{ type: 'error', error }` |
38
+ | CRUD push | `{ type: 'product.created', data, meta }` |
39
+ | room broadcast | `{ type: 'broadcast', channel, data }` |
40
+ | direct send | `{ type: 'direct', data }` |
41
+
42
+ Heartbeat uses RFC 6455 ping frames. `?pushRef=` on the upgrade URL resumes a session.
43
+
44
+ ## Server API
45
+
46
+ ```typescript
47
+ app.ws.broadcast('product', { productId: '1' });
48
+ app.ws.broadcastToOrg('org-1', 'product', {});
49
+ app.ws.send({ userId }, data); // or { pushRef }; critical, ordered
50
+ app.ws.sendRealtime({ userId }, data, 'coalesce-key'); // droppable, coalesced
51
+ app.ws.getStats();
52
+ app.ws.rooms; // RoomManager
53
+ ```
54
+
55
+ ## Resume and scale-out
56
+
57
+ | Need | Option |
58
+ |---|---|
59
+ | Replay after reconnect | `messageEnvelope: 'seq'` (wraps critical sends as `{ seq, t, msg }`; client sends `{ type: 'resume', lastSeq }`), `deadQueueSize` (128), `pushRefTtlMs` (60000), `pushRefMaxEntries` (10000) |
60
+ | Multi-instance broadcast | `adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })` from `@classytic/arc/integrations/websocket-redis` |
61
+ | Resume across nodes | `pushRefStore: new RedisPushRefStore(redis, { keyPrefix, graceMs })` from `@classytic/arc/integrations/websocket-pushref-redis` |
62
+
63
+ The default `LocalWebSocketAdapter` is single-instance. Also exported: `RoomManager`, `GeoRoom`, `PushRefRegistry`, `MemoryPushRefStore`.
64
+
65
+ ## eventGatewayPlugin (SSE plus WebSocket)
66
+
67
+ One config for both transports with shared auth, tenant scoping and room policy.
68
+
69
+ ```typescript
70
+ import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
71
+
72
+ await app.register(eventGatewayPlugin, {
73
+ auth: true, // default; boot fails without fastify.authenticate or authenticate()
74
+ roomPolicy: (client, room) => ['product', 'order'].includes(room),
75
+ maxMessageBytes: 8192,
76
+ maxSubscriptionsPerClient: 50,
77
+ sse: { path: '/api/events', patterns: ['order.*'], heartbeat: 30000, filter: (event, request) => true }, // false disables
78
+ ws: { path: '/ws', resources: ['product', 'order'], exposeStats: 'authenticated' }, // false disables
79
+ });
80
+ ```
81
+
82
+ - `orgScoped` is forwarded to SSE only when set; SSE defaults to tenant-scoped. Set `false` only for a cross-tenant ops stream.
83
+ - Registers `@fastify/websocket` itself; throws with install instructions if missing (or pass `ws: false`).
84
+ - Prefer it over registering SSE and WebSocket separately.
@@ -0,0 +1,71 @@
1
+ # Webhooks (outbound, signed)
2
+
3
+ ```typescript
4
+ import { webhookPlugin, verifyWebhook, verifySignature, defaultWebhookUrlPolicy } from '@classytic/arc/integrations/webhooks';
5
+ ```
6
+
7
+ Auto-delivers bus events to registered endpoints. Needs the events plugin (registered by `createApp`).
8
+
9
+ ```typescript
10
+ await app.register(webhookPlugin, {
11
+ store, // WebhookStore { name, getAll, save, remove }; default in-memory
12
+ timeout: 10000,
13
+ concurrency: 5, // parallel deliveries per event
14
+ maxLogEntries: 1000,
15
+ retry: { attempts: 3, backoffMs: 1000 }, // best-effort in-process; network, timeout, 429, 5xx only
16
+ validateUrl: defaultWebhookUrlPolicy, // https only, blocks private, loopback, metadata hosts
17
+ // durable: { store: outboxStore }, // guaranteed delivery, exclusive with retry
18
+ });
19
+
20
+ await app.webhooks.register({ id: 'wh-1', url: 'https://c.example/hook', events: ['order.*'], secret });
21
+ await app.events.publish('order.created', { orderId: '1' }); // signed POST to matches
22
+ ```
23
+
24
+ `app.webhooks`: `register`, `unregister`, `list()` (secrets withheld), `getSecret(id)`, `deliveryLog(limit?)` (`{ subscriptionId, eventType, success, status?, error?, timestamp, attempts? }`).
25
+
26
+ - Patterns: exact, `order.*`, `*`.
27
+ - `validateUrl` runs on register, on every persisted subscription at init, and at delivery with `redirect: 'manual'` (a 3xx counts as failed). It checks the URL literal only; do DNS-rebinding defence at the egress boundary.
28
+
29
+ ## Wire contract (v1)
30
+
31
+ Headers: `x-arc-webhook-signature: v1=<hex>`, `x-arc-webhook-timestamp` (epoch ms), `x-arc-webhook-delivery` (event `meta.id`, stable across retries). Body: `{ type, payload, meta }`. Signed string: `v1.<timestamp>.<deliveryId>.<body>` (HMAC-SHA256), so replay is bounded and dedupe uses an authenticated id. `signWebhook(body, secret, { timestamp, deliveryId })` produces it.
32
+
33
+ ## Verify (receiver)
34
+
35
+ ```typescript
36
+ app.post('/hooks/arc', { config: { rawBody: true } }, async (req, reply) => {
37
+ const r = verifyWebhook({
38
+ body: req.rawBody as string, // exact bytes, never the parsed body
39
+ secret,
40
+ signature: req.headers['x-arc-webhook-signature'] as string,
41
+ timestamp: req.headers['x-arc-webhook-timestamp'] as string,
42
+ deliveryId: req.headers['x-arc-webhook-delivery'] as string,
43
+ toleranceMs: 300000, // default
44
+ });
45
+ if (!r.valid) return reply.status(401).send({ error: r.reason }); // missing_headers | bad_timestamp | expired | bad_signature
46
+ // dedupe on r.deliveryId, then handle
47
+ });
48
+ ```
49
+
50
+ Third-party senders: `verifySignature(rawBody, secret, header, { prefix: 'sha256=', algorithm: 'sha256' })` returns boolean (`prefix: ''` for bare hex). Both throw `TypeError` when the body is not a string or Buffer (re-serialised JSON breaks the HMAC).
51
+
52
+ ## Durable delivery
53
+
54
+ Each (event x subscription) becomes one outbox row (`<event id>:wh:<subscription id>` as dedupe key); a relay performs the signed POST, retries and dead-letters.
55
+
56
+ ```typescript
57
+ import { createDurableWebhookModule, webhookDeliveryFailurePolicy } from '@classytic/arc/integrations/webhooks';
58
+ import { repositoryAsOutboxStore } from '@classytic/arc/events';
59
+
60
+ const store = repositoryAsOutboxStore(deliveryRepo);
61
+ await createApp({
62
+ modules: [createDurableWebhookModule({ store, delivery: { maxAttempts: 8, baseMs: 5000, maxMs: 900000 } })],
63
+ plugins: async (f) => { await f.register(webhookPlugin, { durable: { store } }); },
64
+ });
65
+ ```
66
+
67
+ - Module name defaults to `'webhook-delivery'`. It accepts the `createOutboxModule` options plus `fetch`, `timeout`, `validateUrl`, `resolveHeaders(sub, event)`, `delivery`, `failurePolicy`.
68
+ - `resolveHeaders` cannot override `content-type` or the `x-arc-webhook-*` headers.
69
+ - Non-transient failures (4xx, 3xx, URL policy rejection, malformed row) dead-letter at once; transient ones (network, timeout, 429, 5xx) retry with backoff.
70
+ - The delivering process must also register `webhookPlugin` with the shared subscription store (checked at boot). `role: 'api'` only enqueues, `role: 'relay'` delivers.
71
+ - Row type constant: `WEBHOOK_DELIVERY_EVENT`; errors: `WebhookDeliveryError` (`status`, `transient`); lower level `createWebhookDeliveryTransport`.
@@ -0,0 +1,47 @@
1
+ # Streamline workflows
2
+
3
+ ```typescript
4
+ import { streamlinePlugin } from '@classytic/arc/integrations/streamline';
5
+ ```
6
+
7
+ Peer: `@classytic/streamline`. Workflows come from `createWorkflow` there.
8
+
9
+ ```typescript
10
+ await app.register(streamlinePlugin, {
11
+ workflows: [orderWorkflow],
12
+ prefix: '/api/workflows', // default '/workflows'
13
+ auth: true, // default
14
+ bridgeEvents: true, // default: workflow.<id>.started|resumed|cancelled
15
+ bridgeBusEvents: false, // true: every engine event as workflow.<id>.<eventName>
16
+ enableStreaming: false, // true: SSE run stream
17
+ enableHookEndpoint: false, // true: POST <prefix>/hooks/:token
18
+ tenantResolver: (req) => req.user?.organizationId, // from auth, never the body
19
+ bypassTenantResolver: (req) => false,
20
+ permissions: { start: (req) => true, cancel: (req) => true }, // also resume, list, get, execute, pause, rewind
21
+ idempotency: { required: ['start'], workflows: ['order'] }, // needs idempotencyPlugin
22
+ });
23
+ ```
24
+
25
+ `execute` falls back to the `start` permission; `pause` and `rewind` fall back to `cancel`.
26
+
27
+ ## Routes (per workflow `<prefix>/<id>`)
28
+
29
+ | Route | Purpose |
30
+ |---|---|
31
+ | `GET <prefix>` | List workflows |
32
+ | `POST <prefix>/<id>/start` | Start a run |
33
+ | `GET <prefix>/<id>/runs`, `GET .../runs/:runId` | List, get runs |
34
+ | `POST .../runs/:runId/resume` | Resume a waiting run (`{ payload }`) |
35
+ | `POST .../runs/:runId/cancel`, `/execute`, `/pause`, `/rewind` | Run control (`pause`, `rewind`, `wait` depend on the engine) |
36
+ | `DELETE .../runs/:runId` | Cancel then delete, when the repository supports it |
37
+ | `GET .../runs/:runId/wait` | Poll until terminal, when the engine supports it |
38
+ | `GET .../runs/:runId/stream` | SSE with `enableStreaming`; closes on terminal state |
39
+ | `POST <prefix>/hooks/:token` | Resume via hook with `enableHookEndpoint`; workflow must pass `{ hookToken: hook.token }` to `ctx.wait` |
40
+
41
+ ## Events and decorators
42
+
43
+ - Bridge payload: `{ runId, workflowId, status }` for started and resumed, `{ runId, workflowId }` for cancelled.
44
+ - Constants: `STREAMLINE_BUS_EVENTS`, `STREAMLINE_STREAM_EVENTS`, `STREAMLINE_TERMINAL_EVENTS`, `STREAMLINE_FAILURE_CODES`, `TERMINAL_RUN_STATUSES`, `isStreamTerminal(eventOrStatus, compensates, kind)`.
45
+ - Decorators: `app.workflows` (Map), `app.getWorkflow(id)`.
46
+ - A failed run with compensation keeps streaming its rollback; without it, `failed` is terminal.
47
+ - If `fastify.authenticate` is missing, auth middleware is skipped. A permission left unset allows.
@@ -0,0 +1,83 @@
1
+ # MCP: authentication modes
2
+
3
+ `auth` on `mcpPlugin` is one of: `false`, a Better Auth instance (OAuth 2.1), or an `McpAuthResolver`. A resolver returns `McpAuthResult` to allow or `null` to reject (401).
4
+
5
+ ## 1. No auth (dev, stdio)
6
+
7
+ ```typescript
8
+ await app.register(mcpPlugin, { resources, auth: false });
9
+ ```
10
+
11
+ `ctx.user` is null and scope kind is `public`; guards like `!!ctx.user` still block. DNS rebinding protection defaults on.
12
+
13
+ ## 2. Better Auth OAuth 2.1 (production SaaS)
14
+
15
+ ```typescript
16
+ // auth config
17
+ import { mcp } from 'better-auth/plugins/mcp';
18
+ betterAuth({ plugins: [mcp({ loginPage: '/login' })] });
19
+
20
+ // app
21
+ await app.register(mcpPlugin, { resources, auth: getAuth() });
22
+ ```
23
+
24
+ Arc registers `GET /.well-known/oauth-authorization-server` and `GET /.well-known/oauth-protected-resource` (forwarded to Better Auth). Each request resolves identity with `auth.api.getMcpSession({ headers })` (`userId`, `activeOrganizationId`).
25
+
26
+ ## 3. Better Auth API key (machine clients)
27
+
28
+ ```typescript
29
+ import { createMcpAuthFromBetterAuthApiKey } from '@classytic/arc/mcp';
30
+
31
+ await app.register(mcpPlugin, {
32
+ resources,
33
+ auth: createMcpAuthFromBetterAuthApiKey(getAuth(), {
34
+ orgFromMetadata: true, // true (default) | false | (metadata, key) => string | undefined
35
+ metadataOrgField: 'tenantId', // default 'organizationId'
36
+ permissionScope: 'mcp', // key.permissions[scope] becomes scopes; false disables
37
+ }),
38
+ });
39
+ ```
40
+
41
+ - Requires the `apiKey()` plugin (`auth.api.verifyApiKey`), else throws at creation.
42
+ - Header order: `Authorization: Bearer <key>`, then `x-api-key`.
43
+ - User binding falls back `userId` then `referenceId`; a key with neither is a service principal (`clientId = key.id`).
44
+ - Disabled, expired or failing keys return null (fail closed).
45
+
46
+ ## 4. Custom resolver
47
+
48
+ ```typescript
49
+ auth: async (headers) => {
50
+ const token = headers['authorization']?.replace('Bearer ', '');
51
+ if (!token) return null;
52
+ const p = await verifyJwt(token);
53
+ return p ? { userId: p.sub, organizationId: p.org, roles: p.roles, orgRoles: p.orgRoles } : null;
54
+ },
55
+ ```
56
+
57
+ `McpAuthResult` fields:
58
+
59
+ | Field | Use |
60
+ |---|---|
61
+ | `userId` | Human id; optional for machine principals |
62
+ | `organizationId` | Tenant scope |
63
+ | `roles`, `orgRoles` | Read by `requireRole()` and permission checks |
64
+ | `clientId` | Present: scope kind `service`, `ctx.user` is null |
65
+ | `scopes` | OAuth scopes carried on the service scope |
66
+ | `teamId` | Carried on `member` scope |
67
+ | `context` | `Record<string, string>` custom scope dimensions (`branchId`, ...). Resources gated with `requireScopeContext()` deny until supplied |
68
+
69
+ ```typescript
70
+ // Service principal
71
+ auth: async (h) => h['x-service-key'] === process.env.SVC_KEY
72
+ ? { clientId: 'ingestion', organizationId: 'org-123', scopes: ['write:events'] }
73
+ : null,
74
+ ```
75
+
76
+ ## Tenancy
77
+
78
+ `organizationId` becomes the request scope (`member`, or `service` with `clientId`); the controller adds the tenant filter to every query, same as REST. Resources with `tenantField: false` are visible to all authenticated callers.
79
+
80
+ ## Gotchas
81
+
82
+ - Resolver results are cached `authCacheTtlMs` (5 s) keyed by a hash of `authorization`/`x-api-key`; revocation lags by that window.
83
+ - `auth: false` exposes every generated tool anonymously; combine with `expose` and permissions.
@@ -0,0 +1,125 @@
1
+ # MCP: custom tools, guards, AI SDK bridge
2
+
3
+ ```typescript
4
+ import { z } from 'zod';
5
+ import { createMcpServer, defineTool, definePrompt } from '@classytic/arc/mcp';
6
+ ```
7
+
8
+ ## defineTool and definePrompt
9
+
10
+ `input` is a flat Zod shape (`{ field: z.string() }`), not `z.object(...)`. The SDK wraps it in a stripping object.
11
+
12
+ ```typescript
13
+ export const notifyTool = defineTool('send_notification', {
14
+ description: 'Send a notification',
15
+ input: { channel: z.enum(['email', 'telegram']), recipient: z.string(), message: z.string() },
16
+ annotations: { openWorldHint: true },
17
+ handler: async ({ channel, recipient, message }, ctx) => {
18
+ const result = await notifications.send(channel, recipient, message);
19
+ return { content: [{ type: 'text', text: JSON.stringify(result) }] };
20
+ },
21
+ });
22
+
23
+ export const planPrompt = definePrompt('content_calendar', {
24
+ description: 'Plan a content calendar',
25
+ args: { platforms: z.string(), theme: z.string().optional() },
26
+ handler: ({ platforms }) => ({
27
+ messages: [{ role: 'user', content: { type: 'text', text: `Plan content for ${platforms}` } }],
28
+ }),
29
+ });
30
+
31
+ // With the plugin
32
+ await app.register(mcpPlugin, { resources, extraTools: [notifyTool], extraPrompts: [planPrompt] });
33
+
34
+ // Standalone server
35
+ const server = await createMcpServer({ name: 'tools', version: '1.0.0', tools: [notifyTool], prompts: [planPrompt] });
36
+ ```
37
+
38
+ - `ToolContext`: `{ session, log(level, msg), extra }`. `session` is the `McpAuthResult` or `null` (no auth).
39
+ - Handler returns `CallToolResult`: `{ content: [{ type: 'text', text }], isError? }`. `toCallToolResult`, `toCallToolSuccess`, `toCallToolError`, `permissionDeniedResult` build it.
40
+ - `defineTool<MySession>(...)` widens `ctx.session` to a host type extending `McpAuthResult`.
41
+ - Custom tools bypass resource permissions: guard them explicitly.
42
+
43
+ ## Guards
44
+
45
+ ```typescript
46
+ import { guard, requireAuth, requireOrg, requireRole, requireOrgId, customGuard } from '@classytic/arc/mcp';
47
+
48
+ defineTool('purge', {
49
+ description: 'Purge records',
50
+ handler: guard(requireAuth, requireOrg, requireRole('admin', 'editor'), async (input, ctx) => {
51
+ return { content: [{ type: 'text', text: 'done' }] };
52
+ }),
53
+ });
54
+
55
+ const businessHours = customGuard(() => new Date().getHours() >= 9, 'Business hours only');
56
+ ```
57
+
58
+ | Guard | Rejects when |
59
+ |---|---|
60
+ | `requireAuth` | no session or anonymous |
61
+ | `requireOrg` | no `organizationId` |
62
+ | `requireRole(...roles)` | none of the roles in `session.roles` (OR) |
63
+ | `requireOrgId(id)` | session org differs |
64
+ | `customGuard(fn, msg)` | predicate false |
65
+
66
+ Inline: `isAuthenticated(ctx)`, `hasOrg(ctx)`, `isOrg(ctx, id)`, `getUserId(ctx)`, `getOrgId(ctx)`, `denied(msg)` (returns an `isError` result). `requireRole` needs the auth resolver to return `roles`.
67
+
68
+ ## fieldRulesToZod
69
+
70
+ Build flat shapes from `schemaOptions.fieldRules`:
71
+
72
+ ```typescript
73
+ import { fieldRulesToZod } from '@classytic/arc/mcp';
74
+
75
+ const shape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
76
+ mode: 'create', // 'create' | 'update' | 'list'
77
+ hiddenFields: ['internalScore'],
78
+ readonlyFields: ['slug'],
79
+ });
80
+ ```
81
+
82
+ ## Compose controller calls
83
+
84
+ `invokeController(controller, op, input, options)` runs a controller method with the full pipeline (permissions, hooks, events) outside HTTP; `mcpHandlerAdapter(fn)` wraps a handler so thrown `ArcError`s become canonical error results.
85
+
86
+ ```typescript
87
+ import { defineTool, mcpHandlerAdapter, invokeController } from '@classytic/arc/mcp';
88
+
89
+ defineTool('archive_post', {
90
+ description: 'Archive a post',
91
+ input: { id: z.string() },
92
+ handler: mcpHandlerAdapter(async (input, ctx) =>
93
+ invokeController(postController, 'update', { id: input.id, archived: true },
94
+ { session: ctx.session, resourceName: 'post' })),
95
+ });
96
+ ```
97
+
98
+ ## AI SDK bridge
99
+
100
+ Expose one AI SDK `tool()` builder over MCP. The bridge rejects unauthenticated callers, runs the optional `guard`, maps `{ error }` results and thrown errors to `isError`, and calls `buildTool(ctx)` per request.
101
+
102
+ ```typescript
103
+ import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
104
+ import { tool } from 'ai';
105
+
106
+ export const triggerJob: McpBridge = {
107
+ name: 'trigger_job',
108
+ description: 'Start a job.',
109
+ inputSchema: { phase: z.enum(['investigate', 'fix']) },
110
+ annotations: { destructiveHint: true },
111
+ buildTool: (ctx) => tool({
112
+ description: 'Start a job.',
113
+ inputSchema: z.object({ phase: z.enum(['investigate', 'fix']) }),
114
+ execute: async ({ phase }) => ({ jobId: `${getUserId(ctx)}-${phase}` }),
115
+ }),
116
+ guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
117
+ };
118
+
119
+ await app.register(mcpPlugin, {
120
+ resources,
121
+ extraTools: buildMcpToolsFromBridges([triggerJob], { exclude: readOnly ? ['trigger_job'] : [] }),
122
+ });
123
+ ```
124
+
125
+ `buildMcpToolsFromBridges` also takes `{ include: [...] }`. `bridgeToMcp(bridge)` converts one.
@@ -0,0 +1,115 @@
1
+ # MCP: plugin setup and generated tools
2
+
3
+ Peer deps: `@modelcontextprotocol/server` (>=2), `zod`. Tests also use `@modelcontextprotocol/client`.
4
+
5
+ ```typescript
6
+ import { mcpPlugin } from '@classytic/arc/mcp';
7
+ import { createApp, loadResources } from '@classytic/arc/factory';
8
+
9
+ const resources = await loadResources('./src/resources');
10
+ const app = await createApp({
11
+ resources,
12
+ plugins: async (f) => {
13
+ await f.register(mcpPlugin, { resources, auth: false, expose: ['product', 'order'] });
14
+ },
15
+ });
16
+ ```
17
+
18
+ ## Generated tools (per resource)
19
+
20
+ | Source | Tool name | Annotations |
21
+ |---|---|---|
22
+ | `list` | `list_{plural}` | `readOnlyHint` |
23
+ | `get` | `get_{name}` | `readOnlyHint` |
24
+ | `create` | `create_{name}` | `destructiveHint: false` |
25
+ | `update`, `delete` | `update_{name}`, `delete_{name}` | `destructiveHint`, `idempotentHint` |
26
+ | `actions` | `{action}_{name}` (input: `id` + action schema) | `destructiveHint` |
27
+ | custom routes (function or string handler) | `{operation or slug}_{name}` | GET: `readOnlyHint`, else `openWorldHint` |
28
+
29
+ - A CRUD op becomes a tool only when `permissions.<op>` is declared and the op is not in `disabledRoutes`.
30
+ - Tools run the same controller pipeline as REST: auth, tenant scope, permission policy, hooks, field masking, events.
31
+ - `list_*` accepts `page`, `limit`, `cursor` (keyset; `page` ignored when set), `sort`, `search`, `select`, `populate`, filters. `get_*` accepts `id`, `select`. `limit` max follows the resource `queryParser.maxLimit`.
32
+ - Mutating tools accept `_idempotencyKey` when an idempotency store is wired (register `idempotencyPlugin` before `mcpPlugin`). `idempotency.required` on a resource without a store throws at boot.
33
+ - Route/action tools: `mcp: false` hides, `mcp: { description, annotations }` customizes. `defineResource({ mcp: false })` removes the whole resource.
34
+
35
+ ## McpPluginOptions
36
+
37
+ | Option | Default | Notes |
38
+ |---|---|---|
39
+ | `resources` | required | |
40
+ | `auth` | `false` | `false`, Better Auth instance, or `McpAuthResolver` (see mcp-auth.md) |
41
+ | `expose` | none | Default-deny allowlist of resource names. Preferred |
42
+ | `exclude` | none | Default-allow blocklist. Mutually exclusive with `expose` (throws) |
43
+ | `prefix` | `/mcp` | Endpoint path |
44
+ | `serverName`, `serverVersion` | `arc-mcp`, `1.0.0` | |
45
+ | `instructions` | none | LLM guidance |
46
+ | `toolNamePrefix` | none | `'crm'` gives `crm_list_products` |
47
+ | `overrides` | none | Per-resource `McpResourceConfig` |
48
+ | `extraTools`, `extraPrompts` | none | Hand-written tools/prompts |
49
+ | `stateful`, `sessionTtlMs`, `maxSessions` | `false`, 1800000, 1000 | Session mode |
50
+ | `authCacheTtlMs` | 5000 | Stateless auth-result cache; `0` disables |
51
+ | `dnsRebindingProtection` | on if `auth: false` | See below |
52
+
53
+ ## Per-resource overrides
54
+
55
+ ```typescript
56
+ await app.register(mcpPlugin, {
57
+ resources,
58
+ expose: ['job'],
59
+ overrides: {
60
+ job: {
61
+ operations: ['list', 'get'],
62
+ toolNamePrefix: 'db', // db_list_jobs
63
+ names: { get: 'get_job_by_id' },
64
+ hideFields: ['internalScore'],
65
+ descriptions: {
66
+ list: 'Browse jobs',
67
+ get: ({ defaultDescription }) => `${defaultDescription} Prefer isActive: true.`,
68
+ },
69
+ },
70
+ },
71
+ });
72
+ ```
73
+
74
+ ## Permissions
75
+
76
+ Resource `permissions` apply unchanged. A permission returning `allow({ policy })` scopes `list_*` by that policy; `deny('msg')` returns a tool error; boolean results work.
77
+
78
+ ```typescript
79
+ import { allow, deny } from '@classytic/arc/permissions';
80
+ permissions: {
81
+ list: (ctx) => ctx.user ? allow({ policy: { orgId: ctx.user.orgId } }) : deny('Auth required'),
82
+ delete: () => deny('Read-only'),
83
+ }
84
+ ```
85
+
86
+ ## DNS rebinding protection
87
+
88
+ Validates `Host`/`Origin`. Default on when `auth: false` (localhost set), off when auth is configured.
89
+
90
+ ```typescript
91
+ mcpPlugin({ resources, auth, dnsRebindingProtection: {} }); // localhost + auth
92
+ mcpPlugin({ resources, dnsRebindingProtection: { allowedHosts: ['mcp.example.com'] } });
93
+ mcpPlugin({ resources, auth: false, dnsRebindingProtection: false }); // public
94
+ ```
95
+
96
+ Absent `Origin` passes; present-but-unlisted is refused. `${prefix}/health` is exempt.
97
+
98
+ ## Endpoints and modes
99
+
100
+ | Mode | Behavior |
101
+ |---|---|
102
+ | Stateless (default) | `POST /mcp` fresh server per request; `GET` returns 405; `DELETE` no-op. Use for scaling/serverless |
103
+ | `stateful: true` | `POST` reuses `Mcp-Session-Id`; `GET` is SSE; `DELETE` ends session. TTL cache, LRU eviction at `maxSessions` |
104
+
105
+ - `GET /mcp/health` returns `{ status, mode }`; with valid auth (or `auth: false`) it also returns `tools`, `resources`, `toolNames`, `sessions`.
106
+ - Resources `arc://schemas` and `arc://schemas/{name}` expose resource schemas to agents.
107
+ - Multiple endpoints: register `mcpPlugin` repeatedly with different `resources` and `prefix`.
108
+
109
+ ## Tool-name collisions
110
+
111
+ `createMcpServer` resolves duplicates before the SDK sees them. A preset tool vs a user tool: the preset is renamed (`softdelete_restore_post`). Any other duplicate throws `ArcError` code `arc.mcp.tool_name_collision` naming both `source` labels. `resolveToolCollisions(tools)` is exported for tests.
112
+
113
+ ## Scaffold
114
+
115
+ `arc generate resource order --mcp` or `arc generate mcp analytics` creates `<name>.mcp.ts`; pass its tools via `extraTools`.
@@ -0,0 +1,63 @@
1
+ # MCP: testing
2
+
3
+ `@classytic/arc/mcp/testing` serves the real Streamable HTTP transport on an ephemeral loopback port (needs `@modelcontextprotocol/client`). Always `await client.close()`.
4
+
5
+ ## createTestMcpClient
6
+
7
+ Builds tools from resources and connects a client; no Fastify app needed.
8
+
9
+ ```typescript
10
+ import { createTestMcpClient } from '@classytic/arc/mcp/testing';
11
+
12
+ const client = await createTestMcpClient({
13
+ pluginOptions: { resources: [productResource], extraTools: [notifyTool] },
14
+ auth: { userId: 'u1', organizationId: 'org-1', roles: ['admin'] },
15
+ });
16
+
17
+ const tools = await client.listTools();
18
+ expect(tools.map((t) => t.name)).toContain('list_products');
19
+
20
+ const res = await client.callTool('list_products', { limit: 5 });
21
+ expect(res.isError).toBeFalsy();
22
+ await client.close();
23
+ ```
24
+
25
+ | Option | Notes |
26
+ |---|---|
27
+ | `pluginOptions` | `resources`, `overrides`, `expose`, `exclude`, `toolNamePrefix`, `extraTools`, `extraPrompts`, `instructions` |
28
+ | `auth` | `McpAuthResult` for the session; `null` or omitted runs anonymous |
29
+ | `serverName` | default `test-mcp` |
30
+
31
+ `callTool` returns `{ content: [{ type, text }], isError? }`; parse `content[0].text` as JSON.
32
+
33
+ ## connectMcpTestClient
34
+
35
+ For a server you built with `createMcpServer`:
36
+
37
+ ```typescript
38
+ import { connectMcpTestClient } from '@classytic/arc/mcp/testing';
39
+
40
+ const server = await createMcpServer({ name: 't', tools: [notifyTool] });
41
+ const { client, close } = await connectMcpTestClient(server);
42
+ const result = await client.callTool({ name: 'send_notification', arguments: { /* ... */ } });
43
+ await close();
44
+ ```
45
+
46
+ `client` is the SDK `Client` (`listTools`, `callTool`, `listPrompts`).
47
+
48
+ ## What to assert
49
+
50
+ - Tool list per `expose`/`exclude`/`operations` and the generated names.
51
+ - Anonymous session is denied where permissions require a user.
52
+ - Tenant isolation: two orgs, each sees only its rows.
53
+ - Custom tools reject without a role (`isError: true`).
54
+
55
+ ## Manual check with Claude CLI
56
+
57
+ ```bash
58
+ claude mcp add --transport http my-api http://localhost:3000/mcp
59
+ echo "List all products" | claude -p --allowedTools "mcp__my-api__*"
60
+ claude mcp remove my-api
61
+ ```
62
+
63
+ Check `GET /mcp/health` first to confirm the server is up.