@classytic/arc 2.45.2 → 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-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.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-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.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-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +4 -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-D_aiew34.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-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.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-BJTsSnke.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-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-grZkIA8N.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-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.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-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-CDc7YMwX.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-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.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-jC3rMPzb.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-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-BkHHTu_B.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-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-Ckp2zRy-.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-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-DAPxjYHX.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-B4FAkx3A.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-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-CQv7PsAK.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-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-DXTjVg_Q.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-C3VJKRGp.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-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-CgfSLOSM.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-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-CbWtVbqK.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-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-REV2y7Wd.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-Bevxy_ST.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-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-dYvWrgNa.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-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CEl10KPy.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-D9NWjpYc.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-BHig1kHq.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-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-DBGHjPh7.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-DPPfM4m6.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
@@ -1,141 +1,94 @@
1
1
  ---
2
2
  name: arc-code-review
3
- description: |
4
- Audit a client codebase that has @classytic/arc installed for gaps in arc-convention adoption.
5
- Surfaces hand-rolled CRUD/auth/query/cache code that should be one defineResource() call,
6
- Mongoose models that should use @classytic/mongokit, manual JSON Schema that should be fieldRules,
7
- bypassed RequestScope, missing presets, and other patterns that defeat arc's "less code, more
8
- maintainability" promise. Produces a prioritized migration report with before/after recipes.
9
- Use when reviewing/auditing a downstream project that depends on @classytic/arc, when the
10
- user asks for an "arc audit", "arc gap analysis", "arc migration plan", "why isn't arc helping
11
- us", or when refactoring a Fastify/Express service to arc conventions.
12
- Triggers: arc audit, arc review, arc gap, arc migration, arc convention check, arc compliance,
13
- classytic audit, defineResource refactor, mongoose to mongokit, hand-rolled crud to arc,
14
- arc adoption, arc lint, arc smell, arc anti-pattern.
3
+ description: Audit a client codebase that uses @classytic/arc for hand-rolled code arc already provides (CRUD routes, permission checks, scope reads, manual zod parsing, cron gates, cache, mongoose repos) and report prioritized replace-X-with-Y fixes. Use for an arc audit, gap analysis, or refactoring a Fastify service to arc. Triggers: arc audit, arc review, arc smell, arc adoption.
15
4
  license: MIT
16
5
  metadata:
17
6
  author: Classytic
7
+ minVersion: "2.46.0"
18
8
  tags:
19
9
  - arc
20
10
  - code-review
21
11
  - audit
22
- - migration
23
12
  - refactor
24
- - fastify
25
- - mongoose
26
- - mongokit
27
- - convention-check
28
- progressive_disclosure:
29
- entry_point:
30
- summary: "Audit a client codebase using @classytic/arc for unrealized convention gains. Detect hand-rolled CRUD/auth/query/cache, Mongoose-without-mongokit, bypassed scope, and emit a prioritized migration report."
31
- when_to_use: "Reviewing or migrating a project that has arc installed but hasn't adopted defineResource()/presets/permissions/scope/mongokit. Use whenever the user asks 'why isn't arc helping us' or wants a gap analysis."
32
- quick_start: "1. Confirm arc/mongokit versions 2. Run detection sweep (references/anti-patterns.md) 3. Score each finding (references/severity.md) 4. Emit report using template below"
33
- context_limit: 900
34
13
  ---
35
14
 
36
15
  # arc-code-review
37
16
 
38
- Audit skill for client projects that depend on `@classytic/arc`. Detects places where the team is writing code arc would have generated, then emits a prioritized migration plan with concrete before/after diffs.
17
+ Audit a project that depends on `@classytic/arc`: find code arc generates or enforces, score it, emit a report with a concrete fix per finding. For work on arc itself, use the arc skill.
39
18
 
40
- ## When to use
19
+ ## Do not hand-roll
41
20
 
42
- Invoke when:
43
- - The user asks for an "arc audit", "arc gap analysis", "arc migration plan", or "why isn't arc helping us".
44
- - A repo `dependsOn @classytic/arc` (or `@classytic/mongokit`) and the conversation is about refactoring, code-review, or onboarding.
45
- - The user mentions hand-rolled CRUD, manual JSON Schema, raw `req.user` access, manual `Model.find()` in route handlers, or hand-written OpenAPI alongside arc.
46
- - Migrating a Fastify/Express service to arc conventions.
47
-
48
- **Do NOT use** for arc framework development itself — that's the `arc` skill in `skills/arc/`. This skill audits *consumers* of arc.
49
-
50
- ## Mental model — what arc replaces
51
-
52
- One `defineResource()` call **replaces all of these** in a typical Fastify service:
53
-
54
- | Hand-rolled today | Arc capability that subsumes it | Reference |
21
+ | Smell in client code | Arc API | Import |
55
22
  |---|---|---|
56
- | 5 × `fastify.get/post/patch/delete` per resource | CRUD auto-generation | [arc-cheatsheet.md](references/arc-cheatsheet.md) |
57
- | `if (req.user.role !== 'admin')` inside handler | `permissions: { create: requireRoles(['admin']) }` | [anti-patterns.md §4](references/anti-patterns.md) |
58
- | Manual `req.query.filter` parsing, `$or`/`$and` building | `ArcQueryParser` / mongokit `QueryParser` | [anti-patterns.md §1](references/anti-patterns.md) |
59
- | Hand-written `schema: { body, response }` per route | `schemaOptions.fieldRules` | [anti-patterns.md §2](references/anti-patterns.md) |
60
- | `schema.set('toJSON', { transform })` to strip `password`/`__v` | `fieldRules: { password: { hidden: true } }` | [anti-patterns.md §5](references/anti-patterns.md) |
61
- | Hand-maintained `openapi.yaml` / `swagger.json` | `arc docs ./openapi.json` | [anti-patterns.md §6](references/anti-patterns.md) |
62
- | `eventBus.emit('product.created', ...)` in handler | `events: { created: {} }` (auto-emitted) | [anti-patterns.md §7](references/anti-patterns.md) |
63
- | `cache.del('products-*')` after mutation | `cache: { tags: ['catalog'] }` (auto-invalidated) | [anti-patterns.md §8](references/anti-patterns.md) |
64
- | `req.user._id`, `req.user.orgId` direct access | `getUserId(scope)`, `getOrgId(scope)` from `@classytic/arc/scope` | [anti-patterns.md §9](references/anti-patterns.md) |
65
- | `import mongoose from 'mongoose'` in route/service files | Adapter-only via `createMongooseAdapter` | [anti-patterns.md §10](references/anti-patterns.md) |
66
- | Soft-delete: `/deleted` route + `deletedAt` field + restore handler | `presets: ['softDelete']` | [anti-patterns.md §14](references/anti-patterns.md) |
67
- | `class UserRepository { async create() { Model.create() } }` | `new Repository(Model)` (mongokit) | [mongokit-migration.md](references/mongokit-migration.md) |
68
- | Per-schema `schema.pre('save', ...)` for timestamps/validation | `timestampPlugin()`, `validationChainPlugin()` | [mongokit-migration.md](references/mongokit-migration.md) |
69
- | Hand-written `name === 'admin'` MCP tool handlers | `mcpPlugin({ resources })` (auto-generated) | [anti-patterns.md §15](references/anti-patterns.md) |
70
-
71
- ## Audit workflow
72
-
73
- 1. **Confirm arc is actually installed.** Read root `package.json`. Note `@classytic/arc`, `@classytic/mongokit`, `@classytic/repo-core`, `@classytic/sqlitekit` versions. If arc is absent, this skill doesn't apply — recommend `npx @classytic/arc init` instead.
74
- 2. **Locate the entry point.** Search for `createApp(` or `defineResource(` to see what arc surface is already in use. Note `auth`, `runtime`, `arcPlugins`, `presets` config.
75
- 3. **Inventory resources.** For each `defineResource()` call: list `name`, `permissions`, `presets`, `cache`, `schemaOptions`, custom `routes`/`actions`. Compare to what's used.
76
- 4. **Run the detection sweep.** Walk every section of [anti-patterns.md](references/anti-patterns.md). For each pattern, run the listed grep against `src/` (excluding `node_modules`, `dist`, `test*`). Record file:line of each hit.
77
- 5. **Score findings.** Apply [severity.md](references/severity.md) rubric (critical / high / medium / low). Critical = security gap or duplicated arc behavior that drifts. Low = cosmetic.
78
- 6. **Cross-check mongokit adoption.** If `mongoose` is a direct dep but `@classytic/mongokit` is not, every model is a candidate for migration. Use [mongokit-migration.md](references/mongokit-migration.md).
79
- 7. **Check arc CLI scaffolding hygiene.** Look for `.arcrc`, `arc generate resource` output structure (`{name}.model.ts`, `{name}.repository.ts`, `{name}.resource.ts`). Mismatch = team is hand-creating files. See [scaffolding.md](references/scaffolding.md).
80
- 8. **Emit the report** using the template below.
81
-
82
- ## Reporting template
23
+ | 5 `fastify.get/post/patch/delete` per entity | `defineResource` | `@classytic/arc` |
24
+ | Role or owner checks inside handlers | `requireRoles`, `requireOwnership`, `anyOf`, `allOf` in `permissions` | `@classytic/arc/permissions` |
25
+ | `req.user._id`, `req.user.orgId` | `getUserId`, `getOrgId`, `requireOrgId`, `requireUserId` | `@classytic/arc/scope` |
26
+ | `.parse()` in every handler, hand-written JSON Schema | zod v4 once: `routeInput`, `crudInput`, `parsed`, `defineAction({ schema, parse: true })`, `noPayloadSchema` | `@classytic/arc/core` |
27
+ | `{ body: X }` as an action schema | the action `schema` IS the body schema | `@classytic/arc/core` |
28
+ | `toJSON` transform stripping secrets | `schemaOptions.fieldRules` with `hidden`, `fields.visibleTo` | `@classytic/arc`, `@classytic/arc/permissions` |
29
+ | Manual `req.query` filter and page parsing | built-in parser, `ArcQueryParser` | `@classytic/arc/utils` |
30
+ | `setNotFoundHandler` returning custom JSON | default 404 `arc.not_found`; `errorHandler: { notFound }` | `createApp` option |
31
+ | `emit('x.created')` after each write | automatic CRUD events, `eventPlugin`, `defineEvent` | `@classytic/arc/events` |
32
+ | `cache.del('list')` after writes | `cache: { staleTime, tags }`, `arcPlugins.queryCache` | `defineResource` option |
33
+ | `setInterval`, node-cron, marker rows for once-a-day | `schedulesPlugin` with `daily: { hour, minute?, zone, ledger }`, `DailyLedger`, `createMemoryDailyLedger` | `@classytic/arc/plugins` |
34
+ | Hand-wired BullMQ queue | `jobsPlugin`, `defineJob` | `@classytic/arc/integrations/jobs` |
35
+ | `Idempotency-Key` table | `idempotencyPlugin` | `@classytic/arc/idempotency` |
36
+ | Audit rows written in handlers | `auditPlugin`, `audit: true` | `@classytic/arc/audit` |
37
+ | `Model.aggregate([...])` in a route | `aggregations`, `defineAggregation` | `@classytic/arc` |
38
+ | Soft delete, slug, tree, bulk, tenant glue | `presets: [...]` | `@classytic/arc/presets` |
39
+ | Hand-written MCP tools | `mcpPlugin` | `@classytic/arc/mcp` |
40
+ | Webhook HMAC over parsed body | `verifySignature(req.rawBody, ...)` | `@classytic/arc/integrations/webhooks` |
41
+ | Repository classes over Mongoose | mongokit `createRepository` (see the mongokit skill) | `@classytic/mongokit` |
42
+
43
+ ## Golden path
44
+
45
+ 1. Read `package.json`: arc, mongokit, repo-core versions. No arc dependency means this skill does not apply.
46
+ 2. Find `createApp(` and every `defineResource(`; list per resource: permissions, presets, schema, cache, events.
47
+ 3. Sweep `src/` (skip tests and `dist`) with the greps in references/smells-*.md. Record file:line.
48
+ 4. Score with references/severity.md. Escalate write paths and auth, webhook or payment code.
49
+ 5. Write the report. Cite file:line for every finding and show before/after for the first hit of each pattern.
50
+ 6. Order the plan: auth and scope, then schemas, then CRUD consolidation, then data layer, then jobs and events.
83
51
 
84
52
  ```markdown
85
- # Arc Convention Audit — <project-name>
86
-
87
- **Arc version:** <installed version> · **Mongokit:** <version or "not installed"> · **Sqlitekit:** <version or "n/a"> · **Date:** <YYYY-MM-DD>
88
- **Files scanned:** <N> · **Findings:** <N critical · <N high · <N medium · <N low>
89
-
90
- ## Executive summary
91
- - <1-2 sentences: how much manual code could be deleted, biggest single risk>
92
- - Estimated LOC removable: ~<N> lines across <N> files
93
- - Estimated effort: <S/M/L> per resource (<N> resources affected)
94
-
95
- ## Critical findings
96
- ### C1. <short title> (<N occurrences>)
97
- **Pattern:** <what's wrong, in 1 sentence>
98
- **Locations:** `src/foo/bar.ts:42`, `src/foo/baz.ts:118`, ...
99
- **Why it matters:** <security / drift / maintainability impact>
100
- **Fix:** <link to migration recipe>
101
-
102
- ## High / Medium / Low findings
103
- (same shape)
104
-
105
- ## Migration plan (recommended order)
106
- 1. <Step 1 — usually scope/permissions because they're security-critical>
107
- 2. <Step 2 — usually CRUD consolidation>
108
- 3. ...
109
-
110
- ## Per-resource scorecard
111
- | Resource | defineResource? | presets used | permissions | cache | events | mongokit | Score |
112
- |---|---|---|---|---|---|---|---|
113
- | product | ✅ | softDelete | ✅ | ❌ | manual | ❌ | 6/10 |
53
+ # Arc audit: <project>
54
+ Arc <ver> | Mongokit <ver or none> | <YYYY-MM-DD> | findings: <c> critical, <h> high, <m> medium, <l> low
55
+ ## Summary
56
+ <removable LOC estimate, top 3 risks>
57
+ ## Findings (sorted by severity, then occurrence count)
58
+ ### C1. <title> (<n> hits)
59
+ Locations: `src/a.ts:42` Why: <impact> Fix: <recipe>
60
+ ## Plan
61
+ 1. ...
114
62
  ```
115
63
 
116
- ## Severity quick rule
117
-
118
- - **Critical:** auth bypass, scope leak, fields exposed that should be `hidden`, hand-rolled idempotency that diverges from arc's behavior under load.
119
- - **High:** duplicated CRUD that will rot (one resource gets a fix the others don't), manual permissions instead of combinators, mongoose imports leaking outside adapters.
120
- - **Medium:** manual query parsing, manual cache invalidation, missing presets, hand-written OpenAPI.
121
- - **Low:** style (default exports, `console.log`, `any`), naming conventions, missing `displayName`/`module` metadata.
64
+ ## Gotchas
122
65
 
123
- Full rubric → [severity.md](references/severity.md).
66
+ - Report arc misuse (a bug) separately from a missing arc feature (an opportunity).
67
+ - Do not suggest a feature the app has not enabled; say to enable it first (`arcPlugins.queryCache`, `eventPlugin`).
68
+ - A pattern repeated 30 times outranks one isolated high.
69
+ - `softDelete` preset adds routes only; filtering lives in the repository (`softDelete: true`).
70
+ - Hosts needing calendar cron or durable retries legitimately use `jobsPlugin`; do not flag them.
71
+ - `schemaGenerator: false` on the mongokit adapter silently drops OpenAPI and MCP bodies.
72
+ - Tenant config key is `tenantField`; an unknown key is ignored and queries go unscoped.
124
73
 
125
- ## Output discipline
74
+ ## Never
126
75
 
127
- - **Cite file:line for every finding.** Do not generalize.
128
- - **Show the before/after diff** for the first occurrence of each pattern. Subsequent occurrences just list locations.
129
- - **Quote arc's exact API** in fixes (e.g., `requireRoles(['admin'])` from `@classytic/arc`, not "use arc's role helper").
130
- - **Sort by severity, then by file count.** A pattern repeated 30× outranks an isolated critical bug for migration ROI.
131
- - **Distinguish "missing arc feature" from "arc misuse".** The first is opportunity; the second is a bug.
132
- - **Don't recommend arc features the project hasn't enabled.** If `arcPlugins.queryCache: false`, don't suggest cache tags — recommend enabling it first.
76
+ - Recommend a deep import or a driver import outside the model, repository and adapter files.
77
+ - Rewrite without citing the arc API and subpath in the fix.
78
+ - Edit client code unless asked.
133
79
 
134
80
  ## References
135
81
 
136
- - **[anti-patterns.md](references/anti-patterns.md)** — every greppable anti-pattern with detection regex, severity, and fix
137
- - **[migration-recipes.md](references/migration-recipes.md)** — concrete before/after diffs (manual CRUD → defineResource, manual perms → combinators, manual events, etc.)
138
- - **[mongokit-migration.md](references/mongokit-migration.md)** — Mongoose-only project → mongokit Repository + plugins
139
- - **[arc-cheatsheet.md](references/arc-cheatsheet.md)** — what arc provides at a glance (defineResource fields, presets, permissions, scope, hooks, events, cache, MCP)
140
- - **[scaffolding.md](references/scaffolding.md)** — arc CLI (`init`, `generate resource`, `docs`, `introspect`, `doctor`), `.arcrc`, file conventions
141
- - **[severity.md](references/severity.md)** — severity rubric and triage examples
82
+ - [references/smells-routes-schemas.md](references/smells-routes-schemas.md): read for route, schema, query, not-found, OpenAPI smells.
83
+ - [references/smells-auth-scope.md](references/smells-auth-scope.md): read for permission, scope, tenant, webhook, SSE smells.
84
+ - [references/smells-data-events.md](references/smells-data-events.md): read for driver, repository, event, cache, audit smells.
85
+ - [references/smells-platform.md](references/smells-platform.md): read for job, daily gate, preset, MCP, lifecycle smells.
86
+ - [references/smells-imports-style.md](references/smells-imports-style.md): read for canonical import homes and style smells.
87
+ - [references/severity.md](references/severity.md): read to score findings and size effort.
88
+ - [references/recipe-resource.md](references/recipe-resource.md): read for CRUD to defineResource, presets.
89
+ - [references/recipe-schemas-fields.md](references/recipe-schemas-fields.md): read for routeInput, crudInput, actions, hidden fields, errors.
90
+ - [references/recipe-scope-permissions.md](references/recipe-scope-permissions.md): read for permissions, scope accessors, tenancy recipes.
91
+ - [references/recipe-events-cache-jobs.md](references/recipe-events-cache-jobs.md): read for events, cache, schedules, idempotency, MCP.
92
+ - [references/mongokit-repositories.md](references/mongokit-repositories.md): read to replace Mongoose repository classes and wire the adapter.
93
+ - [references/arc-cheatsheet.md](references/arc-cheatsheet.md): read for the defineResource surface, scope kinds, presets, subpaths.
94
+ - [references/scaffolding.md](references/scaffolding.md): read for arc CLI and generated layout.
@@ -1,198 +1,99 @@
1
- # Arc capabilities at a glance — for gap detection
1
+ # Arc at a glance (for gap detection)
2
2
 
3
- A condensed map of what arc provides, so during audit you can spot what the team is **hand-rolling** vs what's already a one-liner. For full API details, read [`skills/arc/SKILL.md`](../../arc/SKILL.md) and its references.
3
+ For full API read the arc skill. Use this to recognize what a project hand-rolls.
4
4
 
5
- ## What arc replaces (audit signals)
5
+ ## defineResource surface
6
6
 
7
- | If you see this in the codebase… | …it should be this arc surface |
8
- |---|---|
9
- | 5× `fastify.get/post/patch/delete` for one resource | `defineResource({ name, adapter, permissions, … })` — CRUD auto-generated |
10
- | `if (req.user.role !== 'admin') return reply.code(403)…` | `permissions: { update: requireRoles(['admin']) }` |
11
- | `req.user._id`, `req.user.orgId` direct reads | `getUserId(scope)` / `getOrgId(scope)` from `@classytic/arc/scope` |
12
- | Hand-written `schema: { body, response }` per route | `schemaOptions.fieldRules` |
13
- | `schema.set('toJSON', { transform })` to strip `password`/`__v` | `fieldRules: { password: { hidden: true } }` |
14
- | Manual `req.query.filter` parsing, `$or`/`$and` building | `ArcQueryParser` / mongokit `QueryParser` |
15
- | Hand-maintained `openapi.yaml` | `arc docs ./openapi.json` |
16
- | `eventBus.emit('product.created', …)` in handler | CRUD events auto-emit; `events: { created: {} }` for custom |
17
- | `cache.del('products-*')` after mutation | `cache: { tags: ['catalog'] }` — auto-invalidated |
18
- | Soft-delete: hand-rolled `/deleted` route + `deletedAt` field + restore handler | `presets: ['softDelete']` |
19
- | `class UserRepository { async create() { Model.create() } }` | `new Repository(Model)` from mongokit |
20
- | Per-schema `schema.pre('save', …)` for timestamps/validation | mongokit's `timestampPlugin()`, `validationChainPlugin()` |
21
- | Hand-written MCP tool handlers | `mcpPlugin({ resources })` — auto-generated, same perms |
22
- | `Model.aggregate([…])` in route handler | `aggregations: { name: defineAggregation({ … }) }` |
23
- | Custom `withRetry` / `withDLQ` plumbing on events | `RedisStreamTransport` (durable, consumer groups, DLQ) |
24
- | Hand-rolled idempotency token check | `idempotencyPlugin` (header-based, configurable store) |
25
- | Manual SCIM provisioning endpoints | `@classytic/arc/scim` — `scimPlugin({ users, groups, bearer })` |
26
- | `setInterval` sweeps + hand-rolled leader lock / job registry | `schedulesPlugin` from `@classytic/arc/plugins` (2.21 — interval jobs, LockAdapter lease, no Redis) |
27
- | `as never` casts + spread-merges assembling resources in module packages | `mergeResourceConfig` + `ResourceSeams` (2.21) with kernel-typed engine ports |
28
- | Same `view`/`manage` gate repeated across 5 CRUD keys | `permissionMatrix({ read, write, delete? })` (2.21) |
29
- | DB connect + dynamic-import ordering in the composition root | `createApp({ beforeBoot })` (2.21 — runs before Fastify + all imports) |
30
- | `import { x } from 'better-auth/plugins'` (barrel) | dedicated path `better-auth/plugins/<name>` — tree-shaking (BA best practice) |
31
- | Hand-rolled per-tenant usage/billing counters | `usagePlugin` from `@classytic/arc/usage` (2.22 — per-actor per-period counters, fail-safe, `UsageStore` backends) |
32
- | Per-plan rate limits via custom middleware | `rateLimit.plan { resolve, limits, default }` (2.22 — `false` = unlimited, fail-safe fallback, tenant-keyed buckets) |
33
- | Hand-built audit-timeline endpoints (`GET /:id/history` handlers over audit rows) | `history: true` on `defineResource` (2.22 — implies `audit: true`, stricter-than-read gate) |
34
-
35
- ## Boot order (FIXED)
36
-
37
- ```
38
- 0. beforeBoot() ← pre-everything (DB connect; before Fastify + imports) — 2.21
39
- 0.5 module resolve ← thunk imports + dependsOn topo-sort; module errorMappers merge
40
- 1. Arc core (security, auth, events)
41
- 2. plugins() ← user infra (docs, webhooks)
42
- 3. bootstrap[] ← domain init (engines, singletons)
43
- 4. resources (factory runs after bootstrap)
44
- 5. resources[] ← register each
45
- 6. afterResources()
46
- 7. onReady / onClose
47
- ```
48
-
49
- **Lifecycle smell:** top-level `await ensureCatalogEngine()` in a `*.resource.ts` file. Fix: pass `resources` as `async (fastify) => [...]` so it runs after `bootstrap[]`.
50
-
51
- ## defineResource — full surface
52
-
53
- ```typescript
7
+ ```ts
54
8
  defineResource({
55
- name: 'product', // required
56
- adapter, // required — from kit's /adapter subpath
57
- controller?, // optional — auto-built if omitted
9
+ name, displayName, tag, prefix, skipGlobalPrefix, module,
10
+ adapter, // from the kit's /adapter subpath
11
+ controller, writes, transactional, concurrency,
58
12
  permissions: { list, get, create, update, delete },
59
- presets?: [...],
60
- schemaOptions?: { fieldRules, query },
61
- routes?, actions?, actionPermissions?,
62
- hooks?, events?, cache?,
63
- routeGuards?, middlewares?, pipe?,
64
- rateLimit?, tenantField?, idField?,
65
- prefix?, skipGlobalPrefix?,
66
- queryParser?, onFieldWriteDenied?,
67
- audit?, history?, mcp?, // mcp: false to exclude from MCP tool gen; history: true → GET /:id/history (2.22)
68
- displayName?, module?,
69
- onTenantDelete?, // GDPR cascade strategy
13
+ presets, hooks, pipe, middlewares, routeGuards,
14
+ routes, actions, actionPermissions, aggregations,
15
+ schemaOptions: { fieldRules, query, ... }, customSchemas, openApiSchemas,
16
+ fields, onFieldWriteDenied, onImmutableWrite,
17
+ tenantField, onTenantDelete, idField, lookupFields, defaultSort, defaultLimit, maxLimit,
18
+ cache, events, audit, history, rateLimit, idempotency, mcp, queryParser,
19
+ disableDefaultRoutes, disabledRoutes, crud,
20
+ strictPermissions, strictSchemas, skipValidation,
70
21
  });
71
22
  ```
72
23
 
24
+ `writes` binds a CRUD slot to a domain command while keeping sanitize, tenant injection and hooks. `transactional: true` runs each write in a retrying repository transaction. `concurrency` enables ETag and `If-Match`. `history: true` adds `GET /:id/history`.
25
+
73
26
  ## Permissions
74
27
 
75
- ```typescript
76
- allowPublic() requireOrgRole(['admin'])
77
- requireAuth() requireTeamMembership()
78
- requireRoles(['admin']) requireServiceScope('jobs:bulk')
79
- requireOwnership('userId') requireScopeContext('branchId')
80
- requireOrgMembership() requireOrgInScope(targetId)
81
- allOf(...) · anyOf(...) · not(...) · when(...) · denyAll()
82
- permissionMatrix({ read, write, delete? }) // 2.21 — expands to the full CRUD map
83
- createDynamicPermissionMatrix({ resolveRolePermissions, cacheStore })
28
+ ```ts
29
+ allowPublic() requireAuth() requireRoles(["admin"]) requireOwnership("userId")
30
+ requireOrgMembership() requireOrgRole("admin") requireTeamMembership()
31
+ requireServiceScope("jobs:bulk") requireScopeContext("branchId") requireOrgInScope(targetId)
32
+ allOf(...) anyOf(...) not(...) when(...) denyAll()
33
+ permissionMatrix({ read, write, delete? }) createDynamicPermissionMatrix({ ... })
84
34
  ```
85
35
 
86
- Returns `boolean | { granted, reason?, filters?, scope? }`. `filters` propagate into the repo query (row-level ABAC).
87
-
88
- Field-level: `fields.hidden()`, `fields.visibleTo([...])`, `fields.writableBy([...])`, `fields.redactFor([...], '***')`.
36
+ All from `@classytic/arc/permissions` (the common ones also from the root). A check returns `boolean` or a decision carrying `filters` (row-level policy) and `scope`. Field level: `fields.hidden()`, `visibleTo`, `writableBy`, `redactFor`, passed in the resource `fields` option.
89
37
 
90
38
  ## RequestScope
91
39
 
92
- ```typescript
40
+ ```ts
93
41
  type RequestScope =
94
- | { kind: 'public' }
95
- | { kind: 'authenticated'; userId?; userRoles? }
96
- | { kind: 'member'; userId?; userRoles; organizationId; orgRoles; teamId?; context?; ancestorOrgIds? }
97
- | { kind: 'service'; clientId; organizationId; scopes?; context?; ancestorOrgIds?; mandate?; dpopJkt? }
98
- | { kind: 'elevated'; userId?; organizationId?; elevatedBy; context?; ancestorOrgIds? };
42
+ | { kind: "public" }
43
+ | { kind: "authenticated"; userId?; userRoles? }
44
+ | { kind: "member"; userId?; userRoles; organizationId; orgRoles; teamId?; context?; ancestorOrgIds? }
45
+ | { kind: "service"; clientId; organizationId; scopes?; context?; ancestorOrgIds?; mandate?; dpopJkt? }
46
+ | { kind: "elevated"; userId?; organizationId?; elevatedBy; context?; ancestorOrgIds? };
99
47
  ```
100
48
 
101
- Always access via `@classytic/arc/scope`: `getUserId`, `getOrgId`, `hasOrgAccess`, `requireOrgId` (throws 403), `requireUserId` (throws 401), `getScopeContext`, `isOrgInScope`. **Never read `scope.organizationId` directly.**
49
+ Read only through `@classytic/arc/scope`: `getUserId`, `getOrgId`, `requireOrgId`, `requireUserId`, `getScopeContext`, `isOrgInScope`, `hasOrgAccess`.
102
50
 
103
51
  ## Presets
104
52
 
105
- | Preset | Routes added | Config |
53
+ | Preset | Adds | Config |
106
54
  |---|---|---|
107
- | `softDelete` | `GET /deleted`, `POST /:id/restore` | `{ deletedField }` |
108
- | `slugLookup` | `GET /slug/:slug` | `{ slugField }` |
109
- | `tree` | `GET /tree`, `GET /:parent/children` | `{ parentField }` |
110
- | `ownedByUser` | (middleware) | `{ ownerField }` |
111
- | `multiTenant` | (middleware) | `{ tenantField }` or `{ tenantFields: [...] }` |
112
- | `audited` | (middleware) | — |
113
- | `bulk` | `POST/PATCH/DELETE /bulk` | `{ operations?, maxCreateItems? }` |
114
- | `filesUpload` | `POST /upload`, `GET /:id`, `DELETE /:id` | `{ storage, sanitizeFilename?, … }` |
115
- | `search` | `POST /search`, `/search-similar`, `/embed` | `{ repository?, search?, similar?, embed? }` |
55
+ | `softDelete` | `GET /deleted`, `POST /:id/restore` | |
56
+ | `slugLookup` | `GET /slug/:slug` | `slugField` |
57
+ | `tree` | tree and children routes | `parentField` |
58
+ | `ownedByUser` | owner scoping | `ownerField` |
59
+ | `multiTenant` | tenant scoping | `tenantField` or `tenantFields` |
60
+ | `audited` | audit writes | |
61
+ | `bulk` | bulk create, update, delete | `operations`, `maxCreateItems` |
62
+ | `filesUpload` | upload routes | `storage`, `allowedMimeTypes`, `maxFileSize` |
63
+ | `search` | search, similar, embed routes | `search`, `similar`, `embed` |
116
64
 
117
65
  ## fieldRules flags
118
66
 
119
- `systemManaged` · `preserveForElevated` · `immutable` / `immutableAfterCreate` · `optional` · `nullable` · `hidden` · `minLength` / `maxLength` / `min` / `max` / `pattern` / `enum` · `description`.
120
-
121
- ## Aggregations
122
-
123
- ```typescript
124
- aggregations: {
125
- byMethod: defineAggregation({
126
- groupBy: 'method',
127
- measures: { total: 'sum:amount', count: 'count' },
128
- requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
129
- cache: { staleTime: 60, swr: true, tags: ['revenue'] },
130
- permissions: canViewRevenue(),
131
- }),
132
- }
133
- ```
134
-
135
- Registers `GET /:prefix/aggregations/:name`. Same perms + cache + tag invalidation + MCP tool as CRUD. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly.
136
-
137
- ## CLI
67
+ `systemManaged`, `preserveForElevated`, `immutable`, `immutableAfterCreate`, `optional`, `nullable`, `hidden`, `aggregable`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `enum`, `description`.
138
68
 
139
- ```bash
140
- arc init my-api --mongokit --better-auth --ts
141
- arc generate resource product [--mcp]
142
- arc docs ./openapi.json --entry ./dist/index.js
143
- arc introspect --entry ./dist/index.js
144
- arc describe ./dist/resources.js --json
145
- arc doctor
146
- ```
147
-
148
- Generated layout: `src/resources/{name}/{name}.{model,repository,resource,mcp}.ts`. Naming: `org-profile` (kebab input) → `OrgProfile` (class) / `orgProfile` (var) / `org-profile.*.ts` (files).
69
+ ## createApp options that replace host code
149
70
 
150
- ## Adapters
71
+ `auth`, `modules`, `resources`, `resourcePrefix`, `beforeBoot`, `plugins`, `bootstrap`, `afterResources`, `onReady`, `onClose`, `stores` (`events`, `cache`, `idempotency`, `queryCache`), `errorHandler`, `rateLimit`, `cors`, `helmet`, `elevation`, `multipart`, `rawBody`, `ports`, `moduleGraph`, `preset` (`production`, `development`, `testing`, `edge`, `worker`), and `arcPlugins`: `requestId`, `health`, `gracefulShutdown`, `emitEvents`, `events`, `schedules`, `caching`, `sse`, `realtime`, `queryCache`, `metrics`, `versioning`.
151
72
 
152
- Every kit ships its adapter from `@classytic/<kit>/adapter`. Arc has **zero** kit-bound adapters in `src/` since 2.12.
73
+ Boot order: `beforeBoot`, module resolve, arc core, `plugins`, `bootstrap`, `resources`, `afterResources`, `onReady`, `onClose`.
153
74
 
154
- ```typescript
155
- import { createMongooseAdapter } from '@classytic/mongokit/adapter';
156
- import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter';
157
- import { createPrismaAdapter } from '@classytic/prismakit/adapter';
75
+ ## Subpaths and what lives there
158
76
 
159
- import type { DataAdapter, RepositoryLike } from '@classytic/repo-core/adapter';
160
- // RepositoryLike<TDoc> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>
161
- ```
162
-
163
- | Plugin | Required repo methods |
77
+ | Subpath | Holds |
164
78
  |---|---|
165
- | `auditPlugin` | `create`, `findAll` |
166
- | `idempotencyPlugin` | `getOne`, `deleteMany`, `findOneAndUpdate` |
167
- | `EventOutbox` | `create`, `getOne`, `findAll`, `deleteMany`, `findOneAndUpdate` |
168
-
169
- ## Subpath imports — audit signals
170
-
171
- ```typescript
172
- import { defineResource, BaseController, allowPublic } from '@classytic/arc';
173
- import { mergeResourceConfig, type ResourceSeams } from '@classytic/arc'; // 2.21
174
- import { createApp, loadResources } from '@classytic/arc/factory';
175
- import { schedulesPlugin } from '@classytic/arc/plugins'; // 2.21
176
- import { MemoryCacheStore, RedisCacheStore, QueryCache } from '@classytic/arc/cache';
177
- import { eventPlugin, EventOutbox } from '@classytic/arc/events';
178
- import { RedisEventTransport, RedisStreamTransport } from '@classytic/arc/events/redis-stream';
179
- import { mcpPlugin, defineTool } from '@classytic/arc/mcp';
180
- import { bulkPreset, multiTenantPreset } from '@classytic/arc/presets';
181
- import { isMember, getUserId, getOrgId, requireOrgId } from '@classytic/arc/scope';
182
- import { createTestApp, expectArc } from '@classytic/arc/testing';
183
- import { multipartBody } from '@classytic/arc/middleware';
184
- import { defineGuard, withCompensation } from '@classytic/arc/utils';
185
- ```
186
-
187
- A project importing only from the root barrel is probably under-using subpath features (caching, scope accessors, presets, MCP, testing harness).
188
-
189
- ## Non-negotiables (mirror in client projects)
190
-
191
- 1. No `console.log` in `src/` (except `cli/`) — use logger.
192
- 2. No `mongoose` / `drizzle-orm` / `@prisma/client` imports outside the host's adapter wiring file.
193
- 3. No `any` — use `unknown`. No `@ts-ignore` — fix the type.
194
- 4. No default exports in `src/` (knip enforces in arc).
195
- 5. Always read `request.user` via guard, or use `@classytic/arc/scope` accessors.
196
- 6. Always use `req.rawBody` for `verifySignature(...)`, never parsed body.
197
- 7. Set response headers in `onRequest` or `preSerialization`, never `onSend`.
198
- 8. `request.user: Record<string, unknown> | undefined` — required property, NOT optional.
79
+ | `@classytic/arc` | `defineResource`, `defineAction`, `defineAggregation`, `mergeResourceConfig`, controllers, mixins, errors, common permissions |
80
+ | `/core` | `routeInput`, `crudInput`, `parsed`, `noPayloadSchema`, `defineAction` |
81
+ | `/factory` | `createApp`, `defineModule`, `getModuleExports`, `loadResources` |
82
+ | `/permissions`, `/scope` | checks, matrices, scope accessors |
83
+ | `/presets` | `multiTenantPreset`, `bulkPreset`, ... |
84
+ | `/plugins` | `schedulesPlugin`, `createDailyGate`, `createMemoryDailyLedger`, `errorHandlerPlugin`, `healthPlugin`, `ssePlugin` |
85
+ | `/cache`, `/events`, `/idempotency`, `/audit` | stores, transports, outbox, plugins |
86
+ | `/utils` | errors, `createDomainError`, `defineErrorMapper`, `ArcQueryParser` |
87
+ | `/mcp`, `/docs`, `/testing` | MCP plugin, OpenAPI, test harnesses |
88
+ | `/integrations/jobs`, `/integrations/webhooks`, `/integrations/websocket` | queue, signed webhooks, sockets |
89
+
90
+ Imports only from the root barrel suggest under-use of caching, scope, presets, MCP and testing.
91
+
92
+ ## Non-negotiables to mirror in client code
93
+
94
+ 1. No `console.log` in `src/`; use the logger.
95
+ 2. No driver imports outside model, repository and adapter files.
96
+ 3. No `any`, no `@ts-ignore`, no default exports.
97
+ 4. Read `request.user` only behind a guard, or use scope accessors.
98
+ 5. Verify webhooks over `req.rawBody`.
99
+ 6. Set headers in `onRequest` or `preSerialization`, never async `onSend`.
@@ -0,0 +1,104 @@
1
+ # Recipe: Mongoose repositories to mongokit
2
+
3
+ For the full mongokit API, see the mongokit skill. This file covers what an arc audit recommends.
4
+
5
+ mongokit wraps a Mongoose model in a `Repository<TDoc>` that satisfies repo-core's `StandardRepo`, so it plugs into arc through `createMongooseAdapter(Model, repo)` from `@classytic/mongokit/adapter` with no casts. It does not own the connection (`mongoose.connect()` stays in `beforeBoot`) and does not strip response fields (arc `fieldRules.hidden` does).
6
+
7
+ ## Signals
8
+
9
+ | Signal | Grep or check |
10
+ |---|---|
11
+ | mongoose without mongokit | `package.json` has `mongoose`, lacks `@classytic/mongokit` |
12
+ | per-model repository class | `class \w+Repository\b` |
13
+ | scattered hooks | `schema\.pre\(`, `schema\.post\(` |
14
+ | toJSON transform | `schema\.set\(['"]toJSON` |
15
+ | manual pagination | `skip\(.*page`, `countDocuments\(` |
16
+ | tenant filter per method | `organizationId` read from `req.user` beside `find` |
17
+ | session threading | `startSession\(`, `commitTransaction` |
18
+ | duplicate checks by lookup | `findOne\(\{ email` before `create` |
19
+
20
+ A 150-line repository class usually becomes about 10 lines.
21
+
22
+ ## Mapping
23
+
24
+ | Hand-rolled | mongokit |
25
+ |---|---|
26
+ | `class UserRepository { create() { Model.create() } ... }` | `createRepository(Model, config)` |
27
+ | `pre('save')` stamping `updatedAt` | `timestamps: true` |
28
+ | `{ deletedAt: null }` on every read, restore handler | `softDelete: true` |
29
+ | `organizationId` appended to every query | `tenant: { tenantField: "organizationId", required: true }` |
30
+ | skip/limit plus `countDocuments` | `repo.getAll({ mode: "offset", page, limit, filters, sort }, scope)` |
31
+ | cursor pagination by hand | `repo.getAll({ mode: "keyset", after, limit, sort }, scope)` |
32
+ | `findOne` then `create` uniqueness | unique index plus `validationChainPlugin([uniqueField("email")])`, `isDuplicateKeyError` |
33
+ | `findOneAndUpdate(..., { runValidators })` | `repo.update(id, data, scope)` |
34
+ | `startSession` plus `withTransaction` | `repo.withTransaction(async (tx) => ...)` or `withTransaction(connection, fn)` |
35
+ | cache around `find` | `cache: {...}` option |
36
+ | audit rows in handlers | `audit: {...}` option |
37
+ | prefixed ids (`ord_...`) | `customId: {...}`, `prefixedId`, `sequentialId` |
38
+ | status change with legality check | `repo.applyTransition` |
39
+ | URL query to filter | `QueryParser` |
40
+
41
+ ## Recipe
42
+
43
+ Before:
44
+
45
+ ```ts
46
+ export class UserRepository {
47
+ async getById(id: string, orgId: string) {
48
+ return User.findOne({ _id: id, organizationId: orgId, deletedAt: null }).lean();
49
+ }
50
+ async list(orgId: string, page: number, limit: number) {
51
+ const query = { organizationId: orgId, deletedAt: null };
52
+ const docs = await User.find(query).skip((page - 1) * limit).limit(limit).lean();
53
+ return { docs, total: await User.countDocuments(query) };
54
+ }
55
+ // update, softDelete, restore, uniqueness check: 60 more lines
56
+ }
57
+ userSchema.pre("save", function (next) { this.updatedAt = new Date(); next(); });
58
+ userSchema.set("toJSON", { transform: (_d, ret) => { delete ret.password; return ret; } });
59
+ ```
60
+
61
+ After:
62
+
63
+ ```ts
64
+ // user.repository.ts
65
+ import { createRepository } from "@classytic/mongokit";
66
+ import { User } from "./user.model.js";
67
+
68
+ export const userRepo = createRepository(User, {
69
+ tenant: { tenantField: "organizationId", required: true },
70
+ softDelete: true,
71
+ timestamps: true,
72
+ });
73
+
74
+ // user.resource.ts
75
+ import { defineResource, requireRoles } from "@classytic/arc";
76
+ import { createMongooseAdapter } from "@classytic/mongokit/adapter";
77
+
78
+ export const userResource = defineResource({
79
+ name: "user",
80
+ adapter: createMongooseAdapter(User, userRepo),
81
+ presets: ["softDelete"],
82
+ permissions: { list: requireRoles(["admin"]), get: requireRoles(["admin"]), create: requireRoles(["admin"]), update: requireRoles(["admin"]), delete: requireRoles(["admin"]) },
83
+ schemaOptions: { fieldRules: { password: { hidden: true }, organizationId: { systemManaged: true } } },
84
+ });
85
+ ```
86
+
87
+ `createRepository` installs plugins in the safe order (tenant before soft delete and cache, soft delete before batch). Hand-built `new Repository(Model, [...])` chains must keep that order.
88
+
89
+ ## Where tenancy lives
90
+
91
+ One layer. Arc's `multiTenant` preset is the HTTP and MCP boundary and threads scope into the repo call. The repository `tenant` option protects non-HTTP callers (jobs, CLI) and is a safe second layer. Reads through the raw Mongoose model skip tenant, soft delete and cache: flag them.
92
+
93
+ ## Order of adoption per model
94
+
95
+ 1. Replace the repository class with `createRepository`.
96
+ 2. Delete `pre('save')` stamping and the `toJSON` transform; declare `fieldRules` on the resource.
97
+ 3. Convert remaining schema hooks to `repo.on("before:create" | "after:update" | ..., fn)`.
98
+ 4. Replace pagination wrappers with `getAll`.
99
+ 5. Wire `createMongooseAdapter(Model, repo)`; leave `schemaGenerator` at its default.
100
+ 6. Run the existing tests unchanged; mongokit defaults match Mongoose semantics.
101
+
102
+ ## Not mongokit's job
103
+
104
+ Connection lifecycle, response transforms (`_id` to `id`, field stripping), runtime type generation, CLI scaffolding (`arc generate` does that).