@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
@@ -0,0 +1,73 @@
1
+ # Build and public types
2
+
3
+ ## tsdown.config.ts
4
+
5
+ ```ts
6
+ import { defineConfig } from "tsdown";
7
+
8
+ export default defineConfig({
9
+ entry: ["src/index.ts", "src/contract.ts"],
10
+ format: ["esm"],
11
+ dts: true,
12
+ sourcemap: false,
13
+ clean: true,
14
+ treeshake: true,
15
+ target: "node22",
16
+ outDir: "dist",
17
+ publint: { level: "error" },
18
+ attw: { profile: "esm-only" },
19
+ deps: { neverBundle: true },
20
+ });
21
+ ```
22
+
23
+ | Key | Why |
24
+ |---|---|
25
+ | `format: ["esm"]` | arc is ESM only |
26
+ | `deps.neverBundle: true` | arc, primitives, repo-core and kits stay external, so the host runs one copy |
27
+ | `publint`, `attw` with `level: "error"` | a broken exports map or unresolvable declaration fails the build |
28
+ | one `entry` per exported subpath | `exports` must point at files that exist |
29
+
30
+ Two copies of arc mean two plugin registries and two scope decorators: they diverge. Inlining any `@classytic/*` package causes it.
31
+
32
+ ## Public surface only
33
+
34
+ ```ts
35
+ import type { PermissionCheck } from "@classytic/arc/permissions";
36
+ import { getOrgId, requireOrgId } from "@classytic/arc/scope";
37
+ import type { ActionDefinition, RequestWithExtras } from "@classytic/arc/types";
38
+ import { createDomainError, NotFoundError } from "@classytic/arc/utils";
39
+ ```
40
+
41
+ If a symbol is not on a public subpath, file it against arc. Deep imports break when arc reorganizes internals.
42
+
43
+ ## Optional-peer types stay out of d.mts
44
+
45
+ A type from an optional peer in your public signature breaks hosts that did not install it. Describe the shape you need with a local interface.
46
+
47
+ ```ts
48
+ export interface StandardSchemaLike<T> {
49
+ readonly "~standard": { validate: (v: unknown) => { value: T } | { issues: unknown[] } };
50
+ }
51
+ export function withValidation<T>(schema: StandardSchemaLike<T>): void { /* ... */ }
52
+ ```
53
+
54
+ ## Schemas you ship
55
+
56
+ | Choice | Result |
57
+ |---|---|
58
+ | JSON Schema object (`type`, `properties`, `additionalProperties: false`) | no zod peer needed; AJV validates |
59
+ | zod v4 schema | declare `zod` as a peer (`>=4`) and a `^4` devDep; add `parse: true` so the handler gets the parsed value |
60
+ | Empty body | `noPayloadSchema` from `@classytic/arc/core` |
61
+
62
+ A shipped action `schema` is the body schema itself. `{ body: X }` validates nothing.
63
+
64
+ ## Structural ports
65
+
66
+ A repository the package calls is an interface listing only the methods used. Any kit repository satisfies it, so the package never imports a kit.
67
+
68
+ ```ts
69
+ export interface SubjectRepository<TDoc> {
70
+ getById(id: string, o: { organizationId?: string; throwOnNotFound: false; lean: true }): Promise<TDoc | null>;
71
+ update(id: string, patch: Record<string, unknown>, o: { organizationId?: string; lean: true }): Promise<TDoc | null>;
72
+ }
73
+ ```
@@ -0,0 +1,101 @@
1
+ # defineModule
2
+
3
+ Use a module when there is engine state to boot and several resources to register as a unit. A package exports one `createXModule(deps)` factory returning an `ArcModule`; the host lists it in `createApp({ modules })`.
4
+
5
+ ```ts
6
+ import { defineModule, getModuleExports } from "@classytic/arc/factory";
7
+ import { defineErrorMapper } from "@classytic/arc/utils";
8
+
9
+ export const accountingModule = (deps: AccountingDeps) =>
10
+ defineModule({
11
+ name: "accounting",
12
+ dependsOn: ["ledger"],
13
+ requires: { ports: ["outbox"] },
14
+
15
+ plugins: async (f) => {
16
+ await f.register(dbPlugin, { connection: deps.connection });
17
+ },
18
+
19
+ bootstrap: async (f, { defer, ports }) => {
20
+ const engine = await createAccountingEngine(deps, getModuleExports<LedgerEngine>(f, "ledger"), ports.outbox);
21
+ defer(() => engine.stop());
22
+ return engine;
23
+ },
24
+
25
+ resources: (f) => {
26
+ const engine = getModuleExports<AccountingEngine>(f, "accounting");
27
+ return [accountsResource(engine, deps), entriesResource(engine, deps)];
28
+ },
29
+
30
+ eventHandlers: [{ name: "accounting.on-invoice", event: ["invoice:posted"], handler: onInvoicePosted }],
31
+ scheduledJobs: [{ name: "accounting.sweep", every: 3_600_000, handler: () => sweep() }],
32
+ healthChecks: [{ name: "accounting-engine", check: () => engineReady() }],
33
+
34
+ errorMappers: [
35
+ defineErrorMapper({
36
+ type: AccountingError,
37
+ toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
38
+ }),
39
+ ],
40
+
41
+ onClose: async () => {
42
+ /* stop timers, flush outbox */
43
+ },
44
+ });
45
+ ```
46
+
47
+ ## Phases
48
+
49
+ Per phase the module runs before the app-level hook; `onClose` runs in reverse composition order.
50
+
51
+ ```
52
+ plugins -> bootstrap -> resources (factory form) -> afterResources -> onClose
53
+ ```
54
+
55
+ - `plugins` and `afterResources` are called by arc, not registered. Await `fastify.register(x)` inside; returning a plugin throws, a returned function is a disposer.
56
+ - The `bootstrap` return value is the public export at `fastify.arc.modules[name]`. Register teardown with `defer` because the return slot is taken.
57
+ - The `resources` factory form runs after every bootstrap, so engines are live.
58
+ - Boot is transactional: a failing phase closes every started module in reverse, then rethrows.
59
+
60
+ ## dependsOn orders composition
61
+
62
+ `dependsOn: ["ledger"]` makes ledger's bootstrap and export live before this module's phases. It does not delay importing: every input, thunks included, is resolved first. The sort is stable, so unrelated modules keep list order. Unknown names, self references and cycles fail at boot. Every hard sibling dependency belongs in `dependsOn`; omit it only for optional integrations read with `getOptionalModuleExports`.
63
+
64
+ | Field | Use |
65
+ |---|---|
66
+ | `requires: { ports, optionalPorts, modules }` | what the host must supply; every gap reported in one boot error |
67
+ | `kind` | `domain` (default), `bridge` (active only when all its `dependsOn` modules are composed), `platform`, `aggregator` |
68
+ | `publishes`, `eventNamespace` | events the module owns, checked by `createApp({ moduleGraph })` |
69
+ | `owns: "provided"` | supersede an app resource of the same name |
70
+
71
+ ## Typed cross-module exports
72
+
73
+ ```ts
74
+ declare module "@classytic/arc/factory" {
75
+ interface ArcModuleRegistry {
76
+ accounting: AccountingEngine;
77
+ ledger: LedgerEngine;
78
+ }
79
+ }
80
+ // getModuleExports(f, "accounting") now infers AccountingEngine
81
+ ```
82
+
83
+ `getModuleExports` throws when the module is not composed, composes later, or returned nothing. Wiring bugs surface at boot, not as `undefined`.
84
+
85
+ ## Lazy and region packs
86
+
87
+ ```ts
88
+ const taxPack = region === "BD"
89
+ ? () => import("@classytic/bd-tax").then((m) => m.createBdTaxModule(deps))
90
+ : () => import("@classytic/us-tax").then((m) => m.createUsTaxModule(deps));
91
+
92
+ await createApp({ modules: [coreModule(deps), taxPack] });
93
+ ```
94
+
95
+ The thunk decides whether to import; `dependsOn` orders what was selected.
96
+
97
+ ## Naming
98
+
99
+ - Package `@classytic/arc-<domain>`; third parties use their own scope.
100
+ - Module `name` is unique across the host (`"accounting"`, `"acme.billing"`); arc rejects duplicates at boot.
101
+ - One factory per package. To ship several domains, publish several packages; the host owns the flat `modules` list.
@@ -1,159 +1,71 @@
1
- # package.json + tsdown reference
1
+ # package.json for an arc package
2
2
 
3
- Copy-paste manifest for an arc ecosystem package, plus the dependency-field rules and the
4
- optional-peer typing pattern. Values below are the real shapes shipped by
5
- `@classytic/arc-approval` — adapt names, keep the structure.
6
-
7
- ---
8
-
9
- ## package.json
3
+ ## Manifest
10
4
 
11
5
  ```jsonc
12
6
  {
13
7
  "name": "@classytic/arc-<domain>",
14
8
  "version": "0.1.0",
15
- "description": "<one line — what this contributes to an arc host>",
9
+ "description": "<what this contributes to an arc host>",
16
10
  "type": "module",
17
-
18
- // Public entry. Add subpaths ("./adapter", "./testing") the same way if you split surfaces.
19
11
  "exports": {
20
- ".": {
21
- "types": "./dist/index.d.mts",
22
- "default": "./dist/index.mjs"
23
- }
12
+ ".": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" },
13
+ "./contract": { "types": "./dist/contract.d.mts", "default": "./dist/contract.mjs" }
24
14
  },
25
15
  "main": "./dist/index.mjs",
26
16
  "types": "./dist/index.d.mts",
27
-
28
- "sideEffects": false, // pure ESM, tree-shakable — no import-for-effect modules
29
- "files": ["dist"], // ship only build output; never src/, tests/, configs
17
+ "sideEffects": false,
18
+ "files": ["dist"],
30
19
  "publishConfig": { "access": "public" },
31
20
  "engines": { "node": ">=22" },
32
-
33
21
  "scripts": {
34
22
  "build": "tsdown",
35
23
  "typecheck": "tsc --noEmit",
36
24
  "lint": "biome check src/",
37
- "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
25
+ "test": "vitest run",
26
+ "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
38
27
  },
39
-
40
- // CONTRACTS — what the host must provide. `>=`, never `^`.
41
- // Floor >=2.21.0 if you use ResourceSeams / mergeResourceConfig / permissionMatrix /
42
- // schedulesPlugin / errorMappers — declare the floor that matches the APIs you import.
43
28
  "peerDependencies": {
44
- "@classytic/arc": ">=2.21.0",
45
- "@classytic/primitives": ">=0.9.0"
29
+ "@classytic/arc": ">=2.46.0",
30
+ "@classytic/primitives": ">=0.31.0",
31
+ "zod": ">=4.1.0"
46
32
  },
47
-
48
- // Optional peers: declared here AND marked optional below. Host installs only if used.
49
- // The floor is the major YOUR suite runs — never one below it. A floor you never test
50
- // is a compatibility claim, not a fact (arc shipped seven of those until 2.40).
51
- // "peerDependencies": { ..., "zod": ">=4.4.0", "ioredis": ">=6.0.0" },
52
- // "peerDependenciesMeta": {
53
- // "zod": { "optional": true },
54
- // "ioredis": { "optional": true }
55
- // },
56
-
57
- // TEST versions — pin with ^, floor >= each peer floor. Not shipped.
58
33
  "devDependencies": {
59
- "@classytic/arc": "^2.21.0",
60
- "@classytic/primitives": "^0.9.1",
61
- "@biomejs/biome": "^2.5.2",
62
- "@types/node": "^22.19.21",
63
- "tsdown": "^0.22.5",
64
- "typescript": "^7.0.2",
65
- "vitest": "^4.1.9"
34
+ "zod": "^4.4.0"
66
35
  },
67
-
68
- "keywords": ["arc", "fastify", "<domain>", "classytic"],
69
36
  "license": "MIT",
70
37
  "author": "Classytic",
71
- "repository": { "type": "git", "url": "https://github.com/classytic/arc-ecosystem.git", "directory": "packages/arc-<domain>" }
38
+ "repository": { "type": "git", "url": "git+https://github.com/classytic/arc-ecosystem.git", "directory": "packages/arc-<domain>" }
72
39
  }
73
40
  ```
74
41
 
75
- In an **npm workspace**, devDeps common to all packages hoist to the root `package.json`; a
76
- package only lists devDeps unique to it. The peer-skew gate reads root + package devDeps
77
- together (see publishing-workflow.md).
78
-
79
- ---
80
-
81
- ## Dependency-field cheat sheet
42
+ Solo package (no workspace gate): `"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"`.
82
43
 
83
- | Field | What goes here | Range style | Why |
84
- |---|---|---|---|
85
- | `dependencies` | (usually nothing) truly-private bundled helpers only | `^` | Ships with you; host can't override. Almost never needed. |
86
- | `peerDependencies` | arc, fastify, primitives, kits, zod, ioredis | **`>=`** | A contract/floor. Host resolves the real version; don't block their upgrades. |
87
- | `peerDependenciesMeta` | mark optional peers `{ optional: true }` | — | Host installs only if they use that path. |
88
- | `devDependencies` | concrete versions your tests run against | `^` | The version you actually exercise; floor must be `>=` peer floor. |
44
+ ## Dependency fields
89
45
 
90
- **The trap:** putting `@classytic/arc` or `fastify` in `dependencies`, or writing a peer as
91
- `^2.20.0`. Both force the host into *your* version choice. A published arc package makes as
92
- few decisions for the host as possible — it states floors and gets out of the way.
46
+ | Field | Holds | Range |
47
+ |---|---|---|
48
+ | `dependencies` | nothing, or a private helper the host must never control | `^` |
49
+ | `peerDependencies` | `@classytic/arc`, `@classytic/primitives`, `@classytic/repo-core`, kits, `fastify`, `zod` | `>=` floor, no upper bound |
50
+ | `peerDependenciesMeta` | `{ "<name>": { "optional": true } }` for peers only some hosts use | none |
51
+ | `devDependencies` | the versions the test suite runs against | `^`, floor at or above the peer floor |
93
52
 
94
- ---
53
+ ## Floor rules
95
54
 
96
- ## tsdown.config.ts
55
+ - The arc peer floor is the version of the newest arc feature you import. Adopting a newer helper without raising the floor ships a package that throws on the version it claims to support.
56
+ - A peer is a contract, not a pin: `>=` lets hosts upgrade without waiting on your release.
57
+ - Never cap `@classytic/primitives` or `@classytic/repo-core` (`<0.14.0`): a cap makes sibling packages uninstallable.
58
+ - A floor your suite never runs against is a claim, not a fact. Keep the devDep at or above every peer floor.
59
+ - Raising a peer floor narrows the host set: ship it as a minor.
97
60
 
98
- ```ts
99
- import { defineConfig } from "tsdown";
61
+ ## Optional peers
100
62
 
101
- export default defineConfig({
102
- entry: ["src/index.ts"], // add entries for extra subpaths: ["src/index.ts", "src/adapter.ts"]
103
- format: ["esm"], // ESM only — arc is ESM only
104
- dts: true, // emit .d.mts
105
- sourcemap: false,
106
- clean: true,
107
- treeshake: true,
108
- target: "node22",
109
- outDir: "dist",
110
- deps: {
111
- // Bundle NOTHING — same never-bundle contract as arc's own tsdown config.
112
- skipNodeModulesBundle: true,
113
- neverBundle: [/^@classytic\//],
114
- },
115
- });
116
- ```
117
-
118
- Why bundle nothing: if you inline `@classytic/arc` (or primitives, or a kit), the host ends up
119
- with two copies — yours frozen in `dist/`, theirs in `node_modules`. Arc's plugin registry,
120
- event transport, and scope decorators are identity-sensitive; two copies register twice and
121
- diverge. `neverBundle: [/^@classytic\//]` guarantees the host's single installed copy is the
122
- only one at runtime.
63
+ An optional peer (`ioredis`, a kit) is listed in `peerDependencies` and marked optional in `peerDependenciesMeta`. Keep its types out of the public `.d.mts`: see references/build-and-types.md.
123
64
 
124
- ---
65
+ ## Subpaths
125
66
 
126
- ## Optional peers: keep their types out of your public surface
67
+ Add `exports` entries for each public surface (`./contract`, `./events`, `./testing`) and one `entry` per subpath in tsdown. Hosts import only these; everything else is internal.
127
68
 
128
- If a peer is optional (a host might not install it), its types **must not** appear in your
129
- published `.d.mts` — otherwise a host without it gets a compile error importing your package.
130
- Use structural typing: describe the shape you need with a local interface, don't import the
131
- dependency's types into the public boundary.
69
+ ## Workspace
132
70
 
133
- ```ts
134
- // ❌ leaks zod into dist/index.d.mts — breaks hosts that didn't install zod
135
- import type { ZodType } from "zod";
136
- export function withValidation(schema: ZodType) { /* ... */ }
137
-
138
- // ✅ structural: the public signature owes nothing to zod's package
139
- export interface StandardSchemaLike<T> {
140
- readonly "~standard": { validate: (v: unknown) => { value: T } | { issues: unknown[] } };
141
- }
142
- export function withValidation<T>(schema: StandardSchemaLike<T>) { /* ... */ }
143
- ```
144
-
145
- For **shipped action/route schemas, use JSON Schema**, not zod objects. Arc converts JSON
146
- Schema natively; zod stays an *optional* convenience peer for hosts that prefer it. A package
147
- that hard-requires zod for its schemas has made zod a non-optional dependency by the back door.
148
-
149
- ```ts
150
- schema: {
151
- type: "object",
152
- required: ["stepId", "decision"],
153
- properties: {
154
- stepId: { type: "string", minLength: 1 },
155
- decision: { type: "string", enum: ["approved", "rejected"] },
156
- },
157
- additionalProperties: false,
158
- }
159
- ```
71
+ In an npm workspace, shared devDeps (arc, primitives, repo-core, mongokit, fastify, biome, tsdown, typescript, vitest, mongodb-memory-server, mongoose) live in the root `package.json`; a package lists only its own. The peer-skew gate reads root plus package devDeps together.
@@ -1,182 +1,86 @@
1
1
  # Publishing workflow
2
2
 
3
- Monorepo layout, the release gates, and the classytic bot-identity publish steps.
3
+ ## Workspace layout (npm workspaces)
4
4
 
5
- ---
6
-
7
- ## Monorepo layout (npm workspaces)
8
-
9
- Prefer **one workspace holding many small packages** over one repo per package — they release
10
- together and share tooling. The `@classytic/arc-ecosystem` layout:
5
+ One workspace holds many small packages that release together and share tooling.
11
6
 
12
7
  ```
13
8
  arc-ecosystem/
14
- package.json # workspaces: ["packages/*"], shared devDeps, verify script
9
+ package.json workspaces: ["packages/*"], shared devDeps, verify script
15
10
  scripts/
16
- check-peer-skew.mjs # gate: every peer floor covered by a devDep floor
17
- prepublish-gate.mjs # per-package publish gate
18
- packages/
19
- arc-approval/ # @classytic/arc-approval — one package, one surface
20
- package.json
21
- tsdown.config.ts
22
- src/index.ts
23
- arc-involvement/
24
- arc-notifications/
11
+ check-peer-skew.mjs every peer floor covered by a devDep floor
12
+ check-identity-sources.mjs identity read only through request.scope
13
+ prepublish-gate.mjs per-package prepublishOnly, runs root verify
14
+ packages/arc-<domain>/{package.json,tsdown.config.ts,src/,tests/}
25
15
  ```
26
16
 
27
- Root `package.json` scripts:
17
+ Root scripts:
28
18
 
29
19
  ```jsonc
30
20
  {
31
- "workspaces": ["packages/*"],
32
21
  "scripts": {
33
22
  "build": "npm run build --workspaces",
34
23
  "typecheck": "npm run typecheck --workspaces",
35
24
  "lint": "biome check packages/",
36
25
  "test": "vitest run",
37
26
  "check:peer-skew": "node scripts/check-peer-skew.mjs",
38
- "verify": "npm run check:peer-skew && npm run typecheck && npm run lint && npm run test && npm run build"
27
+ "verify": "npm run check:peer-skew && npm run check:identity && npm run typecheck && npm run lint && npm run test && npm run build",
28
+ "push": "classytic-push",
29
+ "release:<pkg>": "npm run verify && npm publish -w @classytic/arc-<pkg>"
39
30
  }
40
31
  }
41
32
  ```
42
33
 
43
- Shared devDeps (arc, primitives, biome, tsdown, typescript, vitest, fastify, @types/node) live
44
- in the **root** `package.json` so every package tests against one aligned set. During
45
- pre-publish development the root can carry `"@classytic/arc": "file:../arc"` to test against
46
- unreleased arc; **switch it to the published range (`"^2.20.0"`) once arc ships** and reinstall
47
- so packages resolve arc from the registry tarball, not the local symlink.
48
-
49
- **pnpm + turborepo + changesets** is the heavier-duty alternative to npm workspaces once the
50
- package count grows: turbo gives cached, topo-ordered builds (`dependsOn: ["^build"]`);
51
- changesets drive versioning + changelogs (`access: "public"`, `updateInternalDependencies:
52
- "patch"`). Wire the peer-skew gate into the release path so it can't be skipped — e.g.
53
- `"release": "pnpm run check:peer-skew && turbo typecheck test build && changeset publish"`.
54
- Local workspace links use `workspace:*` (pnpm) instead of `file:`; the peer-skew gate treats
55
- `workspace:` / `link:` / `file:` as covering any floor (the checked-out source *is* the version
56
- under development).
57
-
58
- ### Supply-chain hygiene (.npmrc / pnpm-workspace.yaml)
59
-
60
- Belt-and-suspenders settings worth adopting for a published ecosystem:
61
-
62
- ```ini
63
- # .npmrc
64
- auto-install-peers=false # peers are the HOST's duty — never silently fetch them
65
- save-workspace-protocol=rolled
66
- ```
67
-
68
- ```yaml
69
- # pnpm-workspace.yaml
70
- onlyBuiltDependencies: # allowlist packages permitted to run install scripts
71
- - esbuild
72
- - mongodb-memory-server
73
- minimumReleaseAgeExclude: # cooldown on brand-new registry versions, with explicit escapes
74
- - '@classytic/repo-core@0.7.0'
75
- ```
76
-
77
- - `auto-install-peers=false` enforces the contract mechanically: if a host forgets a peer, they
78
- get an error, not a silently-resolved wrong version. It also stops your *dev* environment from
79
- masking a missing peer declaration.
80
- - `onlyBuiltDependencies` is a lifecycle-script allowlist — nothing runs `postinstall` unless you
81
- named it. A cheap, real guard against a compromised transitive dep executing on `pnpm install`.
82
- - A `minimumReleaseAge` cooldown blunts the "malicious version published minutes ago" attack;
83
- the `Exclude` list is your escape hatch for versions you've vetted.
84
-
85
- ---
86
-
87
- ## Gate 1 — peer-skew (monorepo)
88
-
89
- `scripts/check-peer-skew.mjs` fails the build if any package declares a peer floor higher than
90
- the devDep floor it actually tests against. Without it, a package can claim `">=2.20.0"` while
91
- its suite runs against 2.18 — a lie that ships. The gate reads root + package devDeps together
92
- (`file:` links count as covering any floor, since the link *is* the version under development).
93
-
94
- ```js
95
- // Core check, per package, per peer:
96
- // devFloor = floorOf(devDeps[name]) // from root + package devDeps merged
97
- // peerFloor = floorOf(peers[name])
98
- // if (devFloor < peerFloor) FAIL // suite tests below what you promise
99
- // Optional peers (peerDependenciesMeta.optional) with no devDep are allowed to be absent.
100
- ```
101
-
102
- Run it first in `verify` so a skew fails fast before the slower typecheck/test/build.
103
-
104
- ---
105
-
106
- ## Gate 2 — prepublish (per package)
107
-
108
- No package publishes without a green gate. No `--no-verify`, ever.
34
+ The arc devDep is a registry range, so packages resolve the published tarball. To co-develop arc locally, temporarily point the root devDep at `file:../arc`; the peer-skew gate treats `file:` as covering any floor.
109
35
 
110
- - **Solo package:** `"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"`.
111
- - **Workspace:** a shared `scripts/prepublish-gate.mjs` invoked from each package's
112
- `prepublishOnly`, running the full workspace `verify` (peer-skew + typecheck + lint + test +
113
- build) so no package ships against a skewed or broken tree.
36
+ ## Gates
114
37
 
115
- The gate is the contract with consumers: if it's green, the published `dist/` was typechecked,
116
- linted, tested, and built from the source in the same commit.
38
+ | Gate | Fails when |
39
+ |---|---|
40
+ | peer-skew | a peer floor is above the devDep floor the suite runs |
41
+ | identity | code reads `req.user.*` or `x-user-id` instead of `request.scope` accessors |
42
+ | typecheck, lint, test, build | any; build also runs publint and attw |
43
+ | `prepublishOnly` | runs the full workspace `verify`; never bypass |
117
44
 
118
- ---
45
+ A solo package puts `npm run typecheck && npm run lint && npm run test && npm run build` in `prepublishOnly`.
119
46
 
120
- ## Release — classytic packages (bot identity)
47
+ ## Release (classytic packages)
121
48
 
122
- Every commit in a classytic package is authored as **`classytic-bot[bot]`** — the maintainer
123
- identity, never an individual. **Per-invocation git env vars only; never `git config
124
- --global`; no `Co-Authored-By` trailers.**
49
+ Commits are authored as `classytic-bot[bot]` with per-invocation environment variables. Never run `git config --global`, never add `Co-Authored-By`.
125
50
 
126
51
  ```bash
127
52
  GIT_AUTHOR_NAME="classytic-bot[bot]" \
128
53
  GIT_AUTHOR_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
129
54
  GIT_COMMITTER_NAME="classytic-bot[bot]" \
130
55
  GIT_COMMITTER_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
131
- git commit -m "feat(arc-x): …"
132
- ```
133
-
134
- Push through `@classytic/dev-tools` so the commit and pusher both carry the `[bot]` badge (it
135
- mints a short-lived GitHub App installation token, pushes, and never persists it):
56
+ git commit -m "feat(arc-x): add flag action"
136
57
 
137
- ```bash
138
- npm run push -- main # push current work to main
58
+ npm run push -- main # classytic-push: short-lived app token, never persisted
59
+ npm run release:<pkg> # verify, then npm publish -w (public access)
139
60
  ```
140
61
 
141
- Publish to **public npm** (`publishConfig.access: "public"` is already set):
142
-
143
- ```bash
144
- npm publish -w @classytic/arc-<domain> # prepublishOnly gate runs automatically
145
- ```
62
+ Third-party packages use their own git identity; the gates and public npm publish are the same.
146
63
 
147
- Third-party (non-classytic) packages: normal git identity, same gates and same
148
- public/scoped-npm publish — only the bot identity and `classytic-push` are classytic-specific.
64
+ ## Versioning the public export
149
65
 
150
- ---
66
+ SemVer the contract, not the internals: exported signatures, the `ArcModule` you return, and the action and schema surface.
151
67
 
152
- ## Versioning a public export
68
+ | Change | Bump |
69
+ |---|---|
70
+ | New optional config field, helper or action | minor |
71
+ | Raise a peer floor | minor |
72
+ | Change or remove an export, rename an action or field | major |
73
+ | Internal refactor, dep bump inside range, docs or tests | patch |
153
74
 
154
- SemVer the **contract**, not the internals:
75
+ ## Common publish failures
155
76
 
156
- | Change | Bump |
77
+ | Symptom | Fix |
157
78
  |---|---|
158
- | New optional config field, new exported helper, new action | **minor** |
159
- | Raising a peer floor (e.g. now requires arc ≥2.21) | **minor** (it narrows the host set) |
160
- | Changing an exported function signature, removing an export, renaming an action/field | **major** |
161
- | Internal refactor, dep bump within range, doc/test-only | **patch** |
162
-
163
- The `ArcModule` shape you return, your exported function signatures, and your action/schema
164
- surface are the contract consumers pin against. Internals (private helpers, how the engine is
165
- built) are free to change under a patch.
166
-
167
- ---
168
-
169
- ## Common publish failures (and the fix)
170
-
171
- - **Peer written as `^` instead of `>=`** → blocks hosts on a newer major that still satisfies
172
- your API. Fix: `">=X.Y.0"`.
173
- - **arc/fastify in `dependencies`** → host gets a bundled duplicate; plugin registry splits.
174
- Fix: move to `peerDependencies`.
175
- - **Optional-peer types in `dist/*.d.mts`** → hosts without that peer fail to compile your
176
- package. Fix: structural typing at the public boundary (see package-manifest.md).
177
- - **Deep import (`@classytic/arc/src/...`)** → breaks on any arc internal reorg. Fix: use a
178
- public subpath, or file the missing export against arc.
179
- - **A back-edge: arc depending on your package** → un-publishable cycle. Fix: the abstraction
180
- belongs in arc as a port/hook, not as a dependency on you.
181
- - **Skewed devDep below peer floor** → suite tests a version you claim to support but don't.
182
- Fix: raise the devDep, reinstall, re-run peer-skew.
79
+ | Peer written `^` | `>=` floor |
80
+ | arc or fastify in `dependencies` | move to `peerDependencies` |
81
+ | Optional-peer type in `dist/*.d.mts` | structural type at the boundary |
82
+ | Deep import of arc internals | public subpath, or request the export |
83
+ | arc depends on the package | move the port or hook into arc |
84
+ | devDep below peer floor | raise the devDep, reinstall, rerun peer-skew |
85
+ | Uses a newer arc helper than the floor | raise the peer floor |
86
+ | Hand-rolled helper that repo-core or arc already ships | search `@classytic/repo-core` and `@classytic/arc` first |