@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
@@ -1,230 +1,93 @@
1
- # Arc CLI & Scaffolding — what `arc init` and `arc generate` produce
1
+ # Arc CLI and scaffolding
2
2
 
3
- When auditing a project, look for divergence between what `arc generate resource` would have created and what the team actually built. Hand-created files often:
4
- - Skip the `*.repository.ts` layer entirely (Mongoose calls inline in routes).
5
- - Misname files (`product-routes.ts`, `productController.ts` instead of `product.resource.ts`).
6
- - Co-mingle resources in one file, killing tree-shake and `loadResources()` discovery.
3
+ A project scaffolded by `arc init` and extended by `arc generate` has a recognizable shape. Divergence from it is an audit signal.
7
4
 
8
- ---
9
-
10
- ## `arc init [name] [options]`
11
-
12
- ```bash
13
- arc init my-api --mongokit --jwt --ts
14
- arc init billing --custom --better-auth --multi
15
- arc init edge-svc --mongokit --jwt --ts --edge
16
- ```
17
-
18
- | Flag | Meaning | Default if omitted |
19
- |---|---|---|
20
- | `--mongokit` | MongoDB + mongokit repository | (required choice) |
21
- | `--custom` | Custom adapter — template points at the `RepositoryLike` contract from `@classytic/repo-core/adapter`; pick any kit (mongokit, sqlitekit, prismakit, custom) | (required choice) |
22
- | `--jwt` | Arc JWT auth strategy | (required choice) |
23
- | `--better-auth` | Better Auth integration | (required choice) |
24
- | `--single` | Single-tenant template | `--single` |
25
- | `--multi` | Multi-tenant template (org context) | — |
26
- | `--ts` | TypeScript | `--ts` |
27
- | `--js` | JavaScript | — |
28
- | `--edge` | Serverless/edge runtime optimizations | — |
29
- | `--skip-install` | Don't run `npm install` | — |
30
- | `--force` | Overwrite existing dir | — |
31
-
32
- **Output structure:**
33
- ```
34
- my-api/
35
- ├── .arcrc # project config for arc generate
36
- ├── package.json # full deps + devDeps wired (npm install just works)
37
- ├── tsconfig.json
38
- ├── biome.json
39
- ├── .gitignore
40
- ├── .env.example
41
- └── src/
42
- ├── app.ts # createApp() entry
43
- ├── server.ts # listen()
44
- ├── resources/ # empty, populated by `arc generate resource`
45
- └── models/ # Mongoose schemas (--mongokit only)
46
- ```
47
-
48
- The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass. Audit signal: a project missing `.arcrc` but using arc was likely *not* scaffolded — every file was hand-created and may diverge.
49
-
50
- ---
51
-
52
- ## `arc generate resource [name] [options]`
5
+ ## Commands
53
6
 
54
7
  ```bash
55
- arc generate resource product
56
- arc generate resource product --mcp --soft-delete
57
- arc generate resource org-profile --bulk --tree
58
- ```
59
-
60
- Options:
61
- - `--mcp` — emit `{name}.mcp.ts` for custom MCP tools alongside the resource
62
- - `--tree` — wire `tree` preset (parent-child)
63
- - `--soft-delete` — wire `softDelete` preset
64
- - `--bulk` — wire `bulk` preset
65
-
66
- **Generated files (mongokit template):**
67
- ```
68
- src/resources/product/
69
- ├── product.model.ts # Mongoose schema (with required imports)
70
- ├── product.repository.ts # mongokit Repository or extends Repository<ProductDoc>
71
- ├── product.resource.ts # defineResource() with adapter wired
72
- └── product.mcp.ts # (--mcp only) extraTools / bridge stubs
73
- ```
74
-
75
- **Naming convention:**
76
- - Input: kebab-case (`org-profile`).
77
- - File names: `org-profile.model.ts`, `org-profile.repository.ts`, `org-profile.resource.ts`, `org-profile.mcp.ts`.
78
- - Class names: PascalCase (`OrgProfile`, `OrgProfileRepository`).
79
- - Variable names: camelCase (`orgProfile`, `orgProfileRepo`, `orgProfileResource`).
80
-
81
- **Audit signal:** files like `productRoutes.ts`, `product-controller.ts`, `productHandlers.js`, `models/Product.js` (no resource file) → not scaffolded; team is fighting arc's conventions.
82
-
83
- ---
84
-
85
- ## `.arcrc` — project config
86
-
87
- ```json
88
- {
89
- "adapter": "mongokit",
90
- "auth": "jwt",
91
- "tenancy": "multi",
92
- "language": "ts",
93
- "mcp": true,
94
- "templates": {
95
- "resourceDir": "src/resources",
96
- "modelDir": "src/models"
97
- }
98
- }
8
+ arc init my-api --mongokit --jwt --single --ts
9
+ arc init billing --mongokit --better-auth --multi
10
+ arc generate resource product --mcp
11
+ arc g r invoice
12
+ arc introspect ./dist/index.js
13
+ arc describe ./dist/index.js --json
14
+ arc docs ./dist/index.js openapi.json
15
+ arc doctor
99
16
  ```
100
17
 
101
- Fields:
102
- - `adapter`: `'mongokit' | 'custom'` — controls which template `arc generate resource` uses.
103
- - `auth`: `'jwt' | 'better-auth'` — auth example wiring in templates.
104
- - `tenancy`: `'single' | 'multi'` — multi-tenant adds `multiTenant` preset and scope wiring by default.
105
- - `language`: `'ts' | 'js'`.
106
- - `mcp`: `true | false` — when true, `arc generate resource` always emits `.mcp.ts` (equivalent to `--mcp`).
107
- - `templates.resourceDir` / `modelDir` — override default locations.
108
-
109
- Audit: a stale `.arcrc` (e.g., points at deleted dirs) is a sign the team has drifted from CLI scaffolding. Either update or remove.
18
+ | Command | Use in an audit |
19
+ |---|---|
20
+ | `arc introspect <entry>` | list every registered resource, first command on an unfamiliar repo |
21
+ | `arc describe <entry> --json` | per resource: routes, actions, permissions, field rules, presets, cache, events; compare with hand-rolled equivalents |
22
+ | `arc docs <entry> [out.json]` | OpenAPI from the registered resources; diff against a hand-kept spec |
23
+ | `arc doctor` | environment and peer checks; exits 1 on hard failures |
110
24
 
111
- ---
25
+ `arc init` flags: `--mongokit` or `--custom` (adapter), `--jwt` or `--better-auth` (auth), `--single` or `--multi` (tenancy), `--ts` or `--js`, `--edge`, `--api-key`, `--session cookie|bearer|both`, `--docker`, `--skip-install`, `--force`.
112
26
 
113
- ## Other CLI commands
114
-
115
- ```bash
116
- arc docs ./openapi.json --entry ./dist/index.js
117
- ```
118
- Boots the app in introspect mode and emits OpenAPI 3.x to the output path. Wire into `prebuild` or a CI artifact step. Use this in audits to diff against any hand-maintained `swagger.yaml` — discrepancies are bugs in either side.
27
+ `arc generate <resource|controller|model|repository|schemas|mcp> <name>`: aliases `g`, `r`, `c`, `m`, `repo`, `s`. The name is kebab-case; `--mcp` also emits the MCP file.
119
28
 
120
- ```bash
121
- arc introspect --entry ./dist/index.js
122
- ```
123
- Lists every registered resource: name, route count, presets, permissions summary. Good first command when auditing an unfamiliar codebase.
29
+ ## Generated layout
124
30
 
125
- ```bash
126
- arc describe product --entry ./dist/index.js
127
31
  ```
128
- Detail one resource: routes, actions, permissions, field rules, presets, cache config, events. Shows what arc *thinks* the resource is — compare against hand-rolled equivalents.
129
-
130
- ```bash
131
- arc doctor
32
+ src/resources/<name>/
33
+ <name>.model.ts
34
+ <name>.repository.ts
35
+ <name>.resource.ts
36
+ <name>.mcp.ts (with --mcp)
132
37
  ```
133
- Diagnose env (Node version, TS version, peer dep versions). Run before audit to confirm environment is sane.
134
-
135
- ---
136
38
 
137
- ## Resource file structure (canonical)
39
+ `arc init` also writes `.arcrc` (`adapter`, `auth`, `tenant`, `typescript`), `src/app.ts`, `src/index.ts`, and an agent guidance `CLAUDE.md`. Names: `org-profile` becomes class `OrgProfile`, variable `orgProfile`, files `org-profile.*.ts`.
138
40
 
139
- `src/resources/{name}/{name}.resource.ts`:
41
+ ## Canonical resource file
140
42
 
141
- ```typescript
142
- import { defineResource, requireRoles, allowPublic, fields } from '@classytic/arc';
143
- import { createMongooseAdapter } from '@classytic/mongokit/adapter'; // arc 2.12+
144
- import { Repository, buildCrudSchemasFromModel } from '@classytic/mongokit';
145
- import { Product } from './product.model.js';
43
+ ```ts
44
+ import { allowPublic, defineResource, requireRoles } from "@classytic/arc";
45
+ import { createRepository } from "@classytic/mongokit";
46
+ import { createMongooseAdapter } from "@classytic/mongokit/adapter";
47
+ import { Product } from "./product.model.js";
146
48
 
147
- const productRepo = new Repository(Product);
49
+ const productRepo = createRepository(Product, { softDelete: true, timestamps: true });
148
50
 
149
51
  export const productResource = defineResource({
150
- name: 'product',
151
- displayName: 'Products',
152
- module: 'catalog',
153
- adapter: createMongooseAdapter({ model: Product, repository: productRepo, schemaGenerator: buildCrudSchemasFromModel }),
154
- presets: ['softDelete'],
52
+ name: "product",
53
+ displayName: "Products",
54
+ module: "catalog",
55
+ adapter: createMongooseAdapter(Product, productRepo),
56
+ presets: ["softDelete"],
155
57
  permissions: {
156
- list: allowPublic(),
157
- get: allowPublic(),
158
- create: requireRoles(['admin']),
159
- update: requireRoles(['admin']),
160
- delete: requireRoles(['admin']),
161
- },
162
- schemaOptions: {
163
- fieldRules: {
164
- name: { type: 'string', minLength: 1, required: true },
165
- price: { type: 'number', minimum: 0, required: true },
166
- slug: { type: 'string', readonly: true },
167
- deletedAt: { type: 'date', nullable: true, hidden: true },
168
- },
58
+ list: allowPublic(),
59
+ get: allowPublic(),
60
+ create: requireRoles(["admin"]),
61
+ update: requireRoles(["admin"]),
62
+ delete: requireRoles(["admin"]),
169
63
  },
170
- cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
64
+ cache: { staleTime: 30, gcTime: 300, tags: ["catalog"] },
171
65
  });
172
-
173
- export default productResource;
174
66
  ```
175
67
 
176
- `loadResources(import.meta.url)` discovers:
177
- - `default` export (`export default productResource`)
178
- - `export const resource`
179
- - Any named export with `.toPlugin()`
180
-
181
- Works with relative imports + Node `#` subpath imports — **NOT** tsconfig path aliases (`@/*`). See [anti-patterns.md §30](anti-patterns.md).
68
+ `loadResources(import.meta.url)` discovers the default export, `export const resource`, or any named export with `.toPlugin()`. Discovery uses Node's resolver: relative imports and `#` subpath imports work, tsconfig path aliases do not.
182
69
 
183
- ---
70
+ ## Audit checks against the scaffold
184
71
 
185
- ## Audit checks against scaffolding output
186
-
187
- When you walk a client repo, compare against this baseline:
188
-
189
- | Expected | Found | Implication |
72
+ | Expected | Found | Meaning |
190
73
  |---|---|---|
191
- | `.arcrc` at project root | missing | Team didn't scaffold — likely diverged conventions |
192
- | `src/resources/{name}/{name}.resource.ts` | `src/routes/{name}.ts` | Hand-rolled — flag for §3 (manual CRUD) |
193
- | `src/resources/{name}/{name}.repository.ts` extends `Repository` | `class FooRepository` with `Model.find` directly | Mongokit not adopted — flag for §28 |
194
- | `src/app.ts` calls `createApp({ resources: [...] })` | manual `app.register(productPlugin)` per resource | Not using arc factory — possible boot-order issues |
195
- | `src/resources/{name}/{name}.mcp.ts` (if `.arcrc` has `mcp: true`) | missing | MCP feature mentioned but not wired |
196
- | `package.json` script `"docs:openapi": "arc docs ..."` | hand-maintained `openapi.yaml` | Out-of-band spec — flag for §6 |
197
- | `npm run smoke` (CLI + subpath imports) | missing | No release gate — recommend wiring |
198
-
199
- ---
74
+ | `.arcrc` in the root | missing | not scaffolded; conventions may have diverged |
75
+ | `src/resources/<n>/<n>.resource.ts` | `src/routes/<n>.ts`, `*Controller.ts` | hand-rolled CRUD (R1) |
76
+ | `<n>.repository.ts` built with `createRepository` | `class FooRepository` over `Model.find` | mongokit not adopted (D2) |
77
+ | `createApp({ resources })` | `app.register(productPlugin)` per resource | arc factory bypassed; boot order risk |
78
+ | `.mcp.ts` when MCP is enabled | missing | MCP claimed but not wired |
79
+ | script running `arc docs` | hand-kept `openapi.yaml` | out-of-band spec (R7) |
200
80
 
201
- ## Smoke commands worth running during audit
81
+ ## Smoke commands
202
82
 
203
83
  ```bash
204
- # Confirm arc + mongokit + sqlitekit + repo-core versions
205
- npm ls @classytic/arc @classytic/mongokit @classytic/sqlitekit @classytic/repo-core
206
-
207
- # List all defineResource calls
84
+ npm ls @classytic/arc @classytic/mongokit @classytic/repo-core
208
85
  grep -rn "defineResource(" src/
209
-
210
- # List all manual fastify routes
211
- grep -rnE "fastify\\.(get|post|patch|put|delete)\\(" src/
212
-
213
- # Find driver imports outside adapter dirs
214
- grep -rln "from 'mongoose'\\|from '@prisma/client'\\|from 'drizzle-orm'" src/ \
215
- | grep -v 'adapter\\|\\.model\\.'
216
-
217
- # Check for hand-rolled toJSON
218
- grep -rn "schema.set('toJSON'\\|toJSON = function" src/
219
-
220
- # Count manual permission checks
221
- grep -rcE "user\\.role|roles\\.includes|throw.*(Unauthorized|Forbidden)" src/
222
-
223
- # Verify OpenAPI source of truth
224
- ls -la openapi.* swagger.* api-spec.* 2>/dev/null
225
-
226
- # Check arc CLI is wired
227
- grep -E "arc (init|generate|docs)" package.json
86
+ grep -rnE "fastify\.(get|post|patch|put|delete)\(" src/
87
+ grep -rln "from 'mongoose'\|from \"mongoose\"" src/ | grep -v "model\|repository\|adapter"
88
+ grep -rn "schema.set('toJSON'" src/
89
+ grep -rcE "user\.role|roles\.includes|throw.*(Unauthorized|Forbidden)" src/
90
+ ls openapi.* swagger.* 2>/dev/null
228
91
  ```
229
92
 
230
- Use the counts to fill in the per-resource scorecard in the SKILL.md report template.
93
+ Use the counts for the report summary.
@@ -1,127 +1,74 @@
1
- # Severity Rubric
1
+ # Severity rubric
2
2
 
3
- Score every finding by **blast radius × likelihood of harm × ease of detection in current tests**. Don't grade by code volume — a one-line auth bypass beats 200 lines of duplicated CRUD.
3
+ Score by blast radius times likelihood of harm times how well current tests would catch it. A one-line auth bypass outranks 200 lines of duplicated CRUD.
4
4
 
5
- Severity legend: 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low
5
+ ## Critical: fix this release
6
6
 
7
- ---
7
+ - Auth or authorization bypass: unguarded identity reads, missing tenant filter, webhook signature over a parsed body.
8
+ - Data leakage: manual `toJSON` stripping, sensitive fields not `hidden`.
9
+ - Security wiring drift: a custom controller that does not forward `tenantField`; a wrong tenant config key.
10
+ - Silent failure: headers set in async `onSend`, SSE token verified inline.
11
+ - Runtime crash: `req.user._id` on a public route.
8
12
 
9
- ## 🔴 Critical — fix this release
13
+ Smells: A1, A2, A5, A8, A9, A10, R8, I5. Action: stop the audit, write the hot-fix note, then continue. These ship as standalone PRs ahead of the rest.
10
14
 
11
- A finding is **critical** if it meets any of:
15
+ ## High: fix this quarter
12
16
 
13
- - **Auth/authorization bypass.** `req.user.role` accessed without scope guard on a public route, missing tenant filter, hand-rolled idempotency that double-charges under retry, webhook signature verification on parsed body.
14
- - **Data leakage.** Manual `toJSON` transform with sensitive fields not declared `hidden`. New sensitive fields (added later) inherit the leak silently.
15
- - **Drift in security-critical wiring.** Custom controller that doesn't forward `tenantField`, so multi-tenant injection silently fails.
16
- - **Silent failure modes.** Headers set in `onSend` (intermittent `ERR_HTTP_HEADERS_SENT` under load), `failOpen` events on a path that needs delivery guarantees.
17
- - **Runtime crashes.** `req.user._id` access on `allowPublic()` routes (crashes only when unauthenticated request hits — usually missed in dev).
17
+ - Duplicated arc behavior that will drift: five hand-written routes per entity, per-route schemas, parsing in every handler, `{ body }`-wrapped action schemas that validate nothing.
18
+ - Wrong layer: driver imports in services, hooks, routes.
19
+ - Missing capability already causing pain: hand-rolled idempotency, jobs, daily gates, aggregation, event emission.
20
+ - No mongokit: every Mongoose model with a hand-written repository class.
21
+ - Wrong default left on: `tenantField` on company-wide tables.
18
22
 
19
- **Examples (from anti-patterns.md):** §4, §5, §9, §17, §18, §25, §27, §32.
23
+ Smells: R1, R3, A4, A6, D1 to D4, D6, P1, P2, P6, P7, I1, I2, I4, I6. Action: rank by occurrence count.
20
24
 
21
- **Action:** stop the audit, write a hot-fix recommendation, then continue. These can ship as standalone PRs ahead of the broader migration.
25
+ ## Medium: fix opportunistically
22
26
 
23
- ---
27
+ - Drift surface not yet harmful: manual query parsing, manual cache invalidation, hand-kept OpenAPI, reimplemented presets, hand-written MCP tools, per-route rate limits, hand-written error bodies.
24
28
 
25
- ## 🟠 High — fix this quarter
29
+ Smells: R2, R4, R6, R7, R9, R10, A3, A7, D5, D7, D8, P3, P4, P5, I3. Action: bundle into the per-resource refactor PR.
26
30
 
27
- A finding is **high** if:
31
+ ## Low: fix when adjacent
28
32
 
29
- - **Duplicated arc behavior** that *will* drift. Five `fastify.get/post/patch/delete` calls per resource where one `defineResource` would do — one resource gets a fix the others don't.
30
- - **Wrong abstraction layer.** Driver imports (`mongoose`, `@prisma/client`, `drizzle-orm`) leaking into `services/`, `hooks/`, `routes/`. Forces every consumer to pull a database driver; complicates testing.
31
- - **Missing arc capability** that's already a pain point. Manual idempotency, manual rate-limiting, manual event emission inconsistency, hand-rolled audit trail. The team is building tools arc already provides.
32
- - **Whole-suite refactor.** No mongokit adoption (§28). Each Mongoose model is a 100+ LOC reduction.
33
+ - Style: `console.log`, `any`, default exports, path aliases, custom not-found handler, hand-wired auth, repeated CRUD gates, missing `displayName`.
33
34
 
34
- **Examples:** §3, §7, §10, §19, §20, §22, §28.
35
+ Smells: R5, A11, P8, I7.
35
36
 
36
- **Action:** prioritize by occurrence count. A pattern repeated 30 times outranks an isolated high.
37
+ ## Escalate one tier when
37
38
 
38
- ---
39
+ - The code is on a write path (`POST`, `PATCH`, `DELETE`).
40
+ - The path is under auth, webhooks, payments, audit or anything touching customer money (minimum high).
41
+ - Git history shows a hot-fix for a related bug.
42
+ - No tests cover the path.
39
43
 
40
- ## 🟡 Medium — fix opportunistically
44
+ ## Lower one tier when
41
45
 
42
- A finding is **medium** if:
43
-
44
- - **Drift surface, not yet harmful.** Manual query parsing where the fields parsed are well-known and stable; manual cache invalidation where the cache strategy works today but breaks on rollout.
45
- - **Documentation drift.** Hand-maintained OpenAPI/Swagger that's currently in sync but will inevitably diverge.
46
- - **Preset adoption gap.** Soft-delete/multi-tenant/bulk wired manually instead of via preset. Code works but doesn't benefit from preset upgrades.
47
- - **Style of contract.** Custom controller without forwarding hooks (works today, breaks when arc updates).
48
-
49
- **Examples:** §1, §2, §6, §8, §14, §16, §21, §23, §24, §26.
50
-
51
- **Action:** bundle into resource-by-resource refactor PRs. Don't open a separate "fix all medium" PR.
52
-
53
- ---
54
-
55
- ## 🟢 Low — fix when adjacent
56
-
57
- A finding is **low** if:
58
-
59
- - **Code-style only.** `console.log`, `any`, `@ts-ignore`, default exports, tsconfig path aliases breaking auto-discovery.
60
- - **Cosmetic config.** Missing `displayName` / `module` on `defineResource`, no `arc-cheatsheet` subpath imports, missing `arc docs` script in package.json.
61
- - **Nicety, not problem.** Manual auth registration instead of `createApp({ auth })` — works fine if app is small.
62
-
63
- **Examples:** §11, §12, §13, §29, §30, §31.
64
-
65
- **Action:** fix when touching the file for another reason. Don't write a dedicated PR.
66
-
67
- ---
46
+ - The path is feature-flagged off in production.
47
+ - It is admin-only with fewer than five verified admins.
48
+ - A fix for the same pattern is already in flight.
68
49
 
69
50
  ## Triage examples
70
51
 
71
- ### "Found 47 manual permission checks across 12 resources"
72
- 🔴 Critical (auth surface) → list each as a separate finding **only if** the check pattern differs. If they're all `if (!req.user.roles.includes('admin')) throw ...`, group as one finding with 47 occurrences.
73
-
74
- ### "Found `mongoose` imported in 8 service files"
75
- 🟠 High → architectural. Group by service module, not file, since a service rewrite touches all files in the module together.
76
-
77
- ### "Found 3 separate `softDelete` reimplementations across resources"
78
- 🟡 Medium → preset adoption. Bundle with the resource refactor.
79
-
80
- ### "Found `console.log` in 23 places"
81
- 🟢 Low → unless any are inside a hot path with sensitive data (then escalate to High for *those* specific calls).
82
-
83
- ---
84
-
85
- ## When to escalate severity
86
-
87
- Escalate one tier higher if:
88
-
89
- - **The pattern is in a write path.** Any pattern in `POST/PATCH/DELETE` is one tier worse than the same pattern in `GET`.
90
- - **The pattern is in `auth/`, `webhooks/`, `payments/`, `audit/`, or anything customer-money-touching.** All findings in these paths are at minimum 🟠.
91
- - **The team has been bitten before.** If `git log` shows a hot-fix commit for a related bug, the underlying pattern is at minimum 🟠.
92
- - **No tests cover the path.** A medium pattern with no test cover is high — drift will land in prod.
93
-
94
- Escalate one tier lower if:
95
-
96
- - **The path is feature-flagged off** in production.
97
- - **The path is admin-only and there are <5 admins** with manually verified scope.
98
- - **A migration is already in flight** for this pattern (don't double-count).
99
-
100
- ---
101
-
102
- ## Reporting cadence
103
-
104
- For a single audit:
105
-
106
- - **Top 3 criticals** in the executive summary.
107
- - **All highs** in the body.
108
- - **Mediums grouped by category** (one row each: "12× manual query parsing").
109
- - **Lows in an appendix** or omitted.
110
-
111
- Don't dump every finding into one giant table — readers will skip. Give them the headline first.
52
+ | Finding | Severity and grouping |
53
+ |---|---|
54
+ | 47 inline role checks across 12 resources | critical; one finding if the pattern is identical, split if it differs |
55
+ | `mongoose` imported in 8 service files | high; group by service module |
56
+ | 3 soft-delete reimplementations | medium; bundle with the resource refactor |
57
+ | `console.log` in 23 places | low; high only for the calls that log sensitive data |
112
58
 
113
- ---
59
+ ## Reporting
114
60
 
115
- ## Score → migration estimate
61
+ - Top 3 critical findings in the summary, all highs in the body, mediums grouped by category ("12 manual query parsers"), lows in an appendix.
62
+ - Lead with the headline; do not dump every finding into one table.
116
63
 
117
- Rough conversion for the executive summary's "estimated effort" line:
64
+ ## Effort estimate
118
65
 
119
- | Critical findings | Highs | Mediums | Lows | Effort |
120
- |---|---|---|---|---|
121
- | 0 | <5 | <10 | any | S (1–3 days, 1 dev) |
122
- | 0 | 5–15 | 10–30 | any | M (1–2 weeks, 1 dev) |
123
- | 1–3 | 5–15 | 10–30 | any | M+ (2 weeks, 2 devs — split critical fixes) |
124
- | any | >15 | >30 | any | L (1 month+, plan in phases) |
125
- | >3 | any | any | any | Stop the audit, raise critical fixes first, then re-audit |
66
+ | Critical | High | Medium | Effort |
67
+ |---|---|---|---|
68
+ | 0 | under 5 | under 10 | S: 1 to 3 days, one dev |
69
+ | 0 | 5 to 15 | 10 to 30 | M: 1 to 2 weeks, one dev |
70
+ | 1 to 3 | 5 to 15 | 10 to 30 | M+: 2 weeks, two devs; split the critical fixes |
71
+ | any | over 15 | over 30 | L: a month or more, phase it |
72
+ | over 3 | any | any | stop, fix criticals, then re-audit |
126
73
 
127
- These are heuristics. Adjust for codebase size and test coverage.
74
+ Heuristics: adjust for codebase size and test coverage.
@@ -0,0 +1,80 @@
1
+ # Smells: auth, scope, tenancy
2
+
3
+ ## A1. Permission checks inside handlers [critical]
4
+
5
+ Grep: `(req|request)\.user\.(role|roles)\b`, `roles\.includes\(`, `if\s*\(\s*!\s*req\.user\s*\)`, `throw new Error\(['"](Unauthorized|Forbidden)`.
6
+ Why: error shapes diverge, `id` versus `_id` mismatches silently bypass ownership, and no row-level filter reaches the query.
7
+ Fix: declare checks in `permissions`; an ownership grant carries a data policy that scopes the query.
8
+
9
+ ```ts
10
+ permissions: {
11
+ list: allowPublic(),
12
+ create: requireRoles(["admin", "editor"]),
13
+ update: anyOf(requireRoles(["admin"]), requireOwnership("createdBy")),
14
+ delete: requireRoles(["admin"]),
15
+ }
16
+ ```
17
+
18
+ Human plus service callers: `anyOf(requireOrgRole("admin"), requireServiceScope("jobs:bulk-write"))`. Import from `@classytic/arc/permissions`.
19
+
20
+ ## A2. Reading `req.user` fields for identity [critical]
21
+
22
+ Grep: `req(uest)?\.user\.(_id|id|orgId|organizationId|tenantId|teamId|parentOrgId)`.
23
+ Why: `request.user` is undefined on public routes (crash only when an anonymous caller arrives), service tokens carry no user, org hierarchy is ignored.
24
+ Fix: scope accessors from `@classytic/arc/scope`: `getUserId`, `getOrgId`, `getOrgRoles`, `getServiceScopes`, `getScopeContext`, `getAncestorOrgIds`, `isAuthenticated`, `isMember`, `isService`, `isElevated`, `hasOrgAccess`, `isOrgInScope`. Prefer permission combinators (`requireOrgRole`, `requireScopeContext`, `requireOrgInScope`) over accessor logic in handlers. Never `x-user-id` or `x-role` headers as identity.
25
+
26
+ ## A3. Hand-rolled "missing org" guard [medium]
27
+
28
+ Grep: `if\s*\(\s*!\s*getOrgId\(`, same with `getUserId`, `getClientId`, `getTeamId`.
29
+ Fix: `requireOrgId(scope, hint?)`, `requireUserId(scope, hint?)`, `requireClientId`, `requireTeamId`. They return the value or throw an ArcError with the right status.
30
+
31
+ ```ts
32
+ const orgId = requireOrgId(req.scope);
33
+ const userId = requireUserId(req.scope, "finalize-checkout");
34
+ ```
35
+
36
+ ## A4. Default `tenantField` on company-wide tables [high]
37
+
38
+ Grep: resources for lookup, currency, platform settings without `tenantField`.
39
+ Why: the default `organizationId` silently scopes reads to the caller's org; a shared table returns empty forever.
40
+ Fix: `defineResource({ name: "currency", tenantField: false })`; a different scope key is `tenantField: "workspaceId"`.
41
+
42
+ ## A5. Wrong tenant config key [critical]
43
+
44
+ Grep: `tenant:\s*\{\s*field\s*:`, any tenant object whose keys are not `strategy`, `enabled`, `tenantField`, `fieldType`, `ref`.
45
+ Why: unknown keys are ignored, the default field applies, and a host with a custom field reads and writes unscoped.
46
+ Fix: use `tenantField` (top-level resource option, `multiTenant` preset, or a repo-core `TenantConfig`). Type seam objects as `TenantConfig` from `@classytic/repo-core/tenant` so a wrong key fails the build.
47
+
48
+ ## A6. Custom controller drops resource options [high]
49
+
50
+ Grep: `extends (BaseController|BaseCrudController)` whose constructor does not forward `tenantField`, `idField`, `schemaOptions`, `cache`, `onFieldWriteDenied`.
51
+ Why: arc cannot thread options into a controller you built.
52
+ Fix: forward through `super(repo, opts)` and mirror on `defineResource`, or delete the controller; the auto-built one covers most cases. Compose `SoftDeleteMixin`, `BulkMixin`, `TreeMixin`, `SlugMixin` rather than rewriting methods. Domain commands that must keep the pipeline belong in `writes` or `actions`.
53
+
54
+ ## A7. Silent strip of denied field writes [medium]
55
+
56
+ Grep: sensitive fields (`role`, `permissions`, `organizationId`) on a resource with `onFieldWriteDenied: "strip"`.
57
+ Why: the default is `"reject"` (403 with the denied list); `"strip"` hides privilege-escalation attempts.
58
+ Fix: keep `reject` for sensitive resources; tests assert 403 on protected-field writes.
59
+
60
+ ## A8. Webhook signature over parsed body [critical]
61
+
62
+ Grep: `verifySignature\(.*req\.body`, `JSON\.stringify\(req\.body\)` near a hash or HMAC.
63
+ Why: the signature covers the exact bytes sent. A parsed or re-serialized body does not match them; `verifySignature` throws `TypeError` for a non-string, non-Buffer body.
64
+ Fix: route `config: { rawBody: true }` and `verifySignature(req.rawBody, secret, signature)` from `@classytic/arc/integrations/webhooks`.
65
+
66
+ ## A9. SSE token in query string without `preAuth` [critical]
67
+
68
+ Grep: EventSource routes reading `req.query.token` and verifying inline.
69
+ Fix: route `preAuth: [(req) => { req.headers.authorization = \`Bearer ${(req.query as { token: string }).token}\`; }]` so normal auth and `permissions` still run.
70
+
71
+ ## A10. Headers set in async `onSend` [critical]
72
+
73
+ Grep: `addHook\(['"]onSend`; check whether the body calls `reply.header(`.
74
+ Why: races Fastify's flush and surfaces as intermittent `ERR_HTTP_HEADERS_SENT` under slow responses.
75
+ Fix: set headers in `onRequest` or `preSerialization`.
76
+
77
+ ## A11. Hand-wired authentication [low]
78
+
79
+ Grep: `@fastify/jwt` registered by hand, custom `app.authenticate` decorator.
80
+ Fix: `createApp({ auth: { type: "jwt", jwt: { secret } } })`, or `{ type: "betterAuth", betterAuth: createBetterAuthAdapter({ auth }) }` from `@classytic/arc/auth`. Arc decorates `authenticate`, `optionalAuthenticate`, `authorize` and wires permission checks.
@@ -0,0 +1,66 @@
1
+ # Smells: data layer, events, cache, audit
2
+
3
+ ## D1. Driver imports outside model, repository, adapter files [high]
4
+
5
+ Grep: `^import .*\b(mongoose|@prisma/client|drizzle-orm)\b` in `src/**`, then drop `*.model.ts`, `*.repository.ts`, `*.adapter.ts` and `src/db/**`.
6
+ Why: services, hooks and routes pull a database driver; tests need a live DB; swapping stores becomes a rewrite.
7
+ Fix: services take a repository interface (`RepositoryLike<TDoc>` from `@classytic/repo-core/adapter`); mongoose stays in model, repository and adapter files. Transactions go through `repo.withTransaction(...)`.
8
+
9
+ ## D2. Mongoose models with hand-rolled repository classes [high]
10
+
11
+ Detect: `package.json` has `mongoose` but not `@classytic/mongokit`; `class \w+Repository`; `schema\.(pre|post)\(`; `skip\(.*page`; `countDocuments\(`; `startSession\(`; `runValidators`.
12
+ Why: each class re-implements tenant filters, soft delete, timestamps, pagination, transactions and uniqueness checks, and drifts.
13
+ Fix: mongokit `createRepository` per model, wired into arc with `createMongooseAdapter(Model, repo)`. See mongokit-repositories.md and the mongokit skill.
14
+
15
+ ## D3. Hand-rolled aggregation routes [high]
16
+
17
+ Grep: `Model\.aggregate\(\[`, `\$group\b`, `\$match\b` inside route or resource files.
18
+ Why: loses per-aggregation permissions, OpenAPI, MCP tool, cache and tag invalidation, `requireFilters`, `requireDateRange` and `maxGroups` guards, and tenant scoping without ObjectId casts. Tenant type coercion is the kit's job; never inject the tenant key into the filter from host code.
19
+ Fix:
20
+
21
+ ```ts
22
+ aggregations: {
23
+ byMethod: defineAggregation({
24
+ groupBy: "method",
25
+ measures: { total: "sum:amount", count: "count" },
26
+ sort: { total: -1 },
27
+ cache: { staleTime: 60, swr: true, tags: ["revenue"] },
28
+ permissions: requireRoles(["admin", "finance"]),
29
+ }),
30
+ },
31
+ ```
32
+
33
+ Registers `GET /<prefix>/aggregations/byMethod`. A backend without `repo.aggregate` declares a `materialized` hook and keeps the same envelope, permission gate and cache contract.
34
+
35
+ ## D4. Manual event emission [high]
36
+
37
+ Grep: `(eventBus|emitter|events|pubsub)\.(emit|publish)\(['"]\w+\.(created|updated|deleted)`.
38
+ Why: a missed emit on PATCH breaks search indexing, cache invalidation and audit consumers, and tests rarely notice.
39
+ Fix: arc emits `<resource>.created`, `.updated`, `.deleted` for every CRUD write (`arcPlugins.emitEvents` defaults on). Keep custom domain events in actions or module `eventHandlers`. Guaranteed delivery uses the outbox (`EventOutbox`, `createOutboxModule` from `@classytic/arc/events`). Event types come from `@classytic/primitives/events`.
40
+
41
+ ## D5. Manual cache and invalidation [medium]
42
+
43
+ Grep: `(redis|cache)\.(get|set|setex|del|invalidate)\(['"]\w+[-:_]`, hand-built key strings.
44
+ Fix: enable the query cache and declare policy per resource.
45
+
46
+ ```ts
47
+ createApp({ arcPlugins: { queryCache: true }, stores: { queryCache: new RedisCacheStore({ client }) }, resources });
48
+ defineResource({ name: "product", adapter, cache: { staleTime: 30, gcTime: 300, tags: ["catalog"], invalidateOn: { "category.*": ["catalog"] } } });
49
+ ```
50
+
51
+ `RedisCacheStore` is from `@classytic/arc/cache`; the default store is memory. Responses carry `x-cache: HIT | STALE | MISS`. Do not suggest cache tags to an app that left `queryCache` off; say to enable it first.
52
+
53
+ ## D6. Manual idempotency [high]
54
+
55
+ Grep: `idempotency-key` header reads, custom lookup tables, retry tables.
56
+ Fix: `idempotencyPlugin` from `@classytic/arc/idempotency` with `repository` (needs `getOne`, `deleteMany`, `findOneAndUpdate`) or a `store`, plus `ttlMs`. A write that must never run twice sets `idempotency: { required: ["create"] }` on the resource, or `idempotency: { required: true }` on an action.
57
+
58
+ ## D7. Manual audit trail [medium]
59
+
60
+ Grep: every mutation handler appending to `audit_logs`, `history`, `events` collections.
61
+ Fix: `auditPlugin` from `@classytic/arc/audit`, then `audit: true` or `audit: { operations: ["delete"] }` per resource, or `presets: ["audited"]`. A read endpoint over audit rows is `history: true`.
62
+
63
+ ## D8. Per-route rate limiting [medium]
64
+
65
+ Grep: `@fastify/rate-limit` registered per route with hand-tuned values.
66
+ Fix: `rateLimit: { max, timeWindow }` on `defineResource` (`false` disables), or `createApp({ rateLimit })` globally.