@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.
- package/README.md +1 -1
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{EventTransport-4b0noGwa.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
- package/dist/{HookSystem-4pABQnGn.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-BBaN_Ne-.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
- package/dist/{acquire-kiZzy5bX.mjs → acquire-RbtvDg9s.mjs} +2 -3
- package/dist/{actionPermissions-BLnbDA6g.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
- package/dist/audit/index.d.mts +2 -10
- package/dist/audit/index.mjs +8 -12
- package/dist/auth/audit.d.mts +0 -2
- package/dist/auth/audit.mjs +2 -3
- package/dist/auth/index.d.mts +9 -17
- package/dist/auth/index.mjs +26 -29
- package/dist/auth/redis-session.d.mts +2 -4
- package/dist/auth/redis-session.mjs +2 -3
- package/dist/{authorizationDecision-CVlaTjAX.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DSy7KkeX.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
- package/dist/{buildHandler-B4IhILv9.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
- package/dist/cache/index.d.mts +4 -10
- package/dist/cache/index.mjs +5 -6
- package/dist/{caching-DqakP2vY.mjs → caching-BYRwYrUo.mjs} +3 -4
- package/dist/{claimed-XoiVrWZ2.mjs → claimed-DYlELdnm.mjs} +2 -3
- package/dist/cleanup/index.d.mts +9 -18
- package/dist/cleanup/index.mjs +12 -20
- package/dist/cli/commands/describe.d.mts +1 -3
- package/dist/cli/commands/describe.mjs +4 -5
- package/dist/cli/commands/docs.d.mts +1 -3
- package/dist/cli/commands/docs.mjs +4 -5
- package/dist/cli/commands/doctor.d.mts +1 -3
- package/dist/cli/commands/doctor.mjs +2 -3
- package/dist/cli/commands/generate.d.mts +1 -1
- package/dist/cli/commands/generate.mjs +2 -2
- package/dist/cli/commands/init.d.mts +1 -1
- package/dist/cli/commands/init.mjs +2 -2
- package/dist/cli/commands/introspect.d.mts +1 -3
- package/dist/cli/commands/introspect.mjs +3 -4
- package/dist/cli/index.d.mts +2 -2
- package/dist/cli/index.mjs +3 -3
- package/dist/{constants-CtWkmWn3.mjs → constants-CHZMUwBW.mjs} +2 -3
- package/dist/context/index.d.mts +0 -8
- package/dist/context/index.mjs +6 -7
- package/dist/core/index.d.mts +3 -3
- package/dist/core/index.mjs +8 -8
- package/dist/{core-Cro2v5a7.mjs → core-D9rS2BxO.mjs} +9 -12
- package/dist/{createActionRouter-k-gwiPv6.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
- package/dist/{createAggregationRouter-BqWqhAPG.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
- package/dist/{createApp-Dw7L72Hz.mjs → createApp-DZIXfDKD.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
- package/dist/{defineAggregation-pxbd7BBK.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
- package/dist/{defineResource-DwgEjLCO.mjs → defineResource-CGmdmGwh.mjs} +78 -29
- package/dist/discovery/index.d.mts +1 -3
- package/dist/discovery/index.mjs +2 -3
- package/dist/docs/index.d.mts +8 -8
- package/dist/docs/index.mjs +4 -5
- package/dist/{elevation-B9wF2Z1F.mjs → elevation-CzhqAyVN.mjs} +9 -10
- package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- package/dist/encryption/index.d.mts +1 -7
- package/dist/encryption/index.mjs +8 -13
- package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
- package/dist/{errorHandler-Dr2nG0Ui.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
- package/dist/{errors-BtHzrSA6.mjs → errors-BY8vzlP4.mjs} +2 -3
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-Dvs7OBw8.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
- package/dist/{eventTypes-BVoCTG5c.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
- package/dist/events/index.d.mts +4 -16
- package/dist/events/index.mjs +8 -9
- package/dist/events/transports/redis-stream-entry.d.mts +1 -1
- package/dist/events/transports/redis-stream-entry.mjs +5 -6
- package/dist/events/transports/redis.d.mts +2 -4
- package/dist/events/transports/redis.mjs +3 -4
- package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
- package/dist/factory/index.d.mts +4 -14
- package/dist/factory/index.mjs +12 -18
- package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{fields-C1e_7Fwi.mjs → fields-LnbCcvsw.mjs} +2 -3
- package/dist/{filter-merge-xaiEKtz8.mjs → filter-merge-BAWi019Q.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-DJiJMaXN.mjs → generate-oXoDnpJf.mjs} +7 -12
- package/dist/{headers-Dr-wt6Tr.mjs → headers-DBd3Qheo.mjs} +3 -4
- package/dist/{health-DkkWbJtQ.mjs → health-BlJu9GXS.mjs} +2 -3
- package/dist/{health-BLYn_Hds.mjs → health-Dp-3EC9o.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +10 -13
- package/dist/idempotency/redis.d.mts +1 -1
- package/dist/idempotency/redis.mjs +3 -4
- package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
- package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
- package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
- package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
- package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
- package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-CW3kJqNW.mjs → init-BOaNkLYb.mjs} +18 -35
- package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
- package/dist/integrations/event-gateway.d.mts +3 -5
- package/dist/integrations/event-gateway.mjs +3 -4
- package/dist/integrations/index.d.mts +3 -3
- package/dist/integrations/index.mjs +1 -1
- package/dist/integrations/jobs/index.d.mts +1 -1
- package/dist/integrations/jobs/index.mjs +7 -11
- package/dist/integrations/mcp/index.d.mts +7 -39
- package/dist/integrations/mcp/index.mjs +8 -14
- package/dist/integrations/mcp/testing.d.mts +3 -5
- package/dist/integrations/mcp/testing.mjs +3 -4
- package/dist/integrations/streamline.d.mts +1 -3
- package/dist/integrations/streamline.mjs +4 -5
- package/dist/integrations/webhooks.d.mts +2 -4
- package/dist/integrations/webhooks.mjs +4 -5
- package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
- package/dist/integrations/websocket-pushref-redis.mjs +2 -3
- package/dist/integrations/websocket-redis.d.mts +2 -4
- package/dist/integrations/websocket-redis.mjs +2 -3
- package/dist/integrations/websocket.d.mts +2 -2
- package/dist/integrations/websocket.mjs +13 -24
- package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
- package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
- package/dist/{jsonBody-DPU8yYwA.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
- package/dist/{keys-Dgn6OYhl.mjs → keys-FBz6Ull-.mjs} +2 -3
- package/dist/{loadResources-BtKj6P1P.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-Bmq6TnB7.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-qQNLlOAU.mjs → logger-CbFcIEBZ.mjs} +3 -5
- package/dist/{mcpPlugin-DDfe8jAP.mjs → mcpPlugin-yix548XX.mjs} +41 -60
- package/dist/{memory-C0Blueoh.mjs → memory-Bgw5dn8N.mjs} +4 -5
- package/dist/{metrics-DYka72iN.mjs → metrics-CZDQWVjS.mjs} +4 -5
- package/dist/middleware/index.d.mts +1 -5
- package/dist/middleware/index.mjs +4 -5
- package/dist/migrations/index.d.mts +0 -2
- package/dist/migrations/index.mjs +3 -4
- package/dist/{module-BszSyWbd.mjs → module-Dsc_nKL5.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
- package/dist/{multipartBody-RHvIkNmc.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
- package/dist/observeSend-BK-JN1jK.mjs +20 -0
- package/dist/{openapi-BrFPc3Ny.mjs → openapi-Co7hl073.mjs} +18 -28
- package/dist/outbox-admin/index.d.mts +2 -4
- package/dist/outbox-admin/index.mjs +6 -7
- package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
- package/dist/{outbox-module-DF4Bu_Qa.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-DN1CWH56.mjs → permissions-A1oKtpiC.mjs} +19 -29
- package/dist/{pipe-B8uq865o.mjs → pipe-Czpw9U2n.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-DUGfynNg.mjs → plan-KVseuBCL.mjs} +5 -9
- package/dist/{plugin-ByU3h-bR.mjs → plugin-DTWt_8C3.mjs} +130 -62
- package/dist/plugins/index.d.mts +8 -16
- package/dist/plugins/index.mjs +22 -26
- package/dist/plugins/response-cache.d.mts +2 -4
- package/dist/plugins/response-cache.mjs +10 -10
- package/dist/plugins/tracing-entry.d.mts +1 -1
- package/dist/plugins/tracing-entry.mjs +3 -4
- package/dist/{pluralize-Cdya8zYt.mjs → pluralize-msB9X3yw.mjs} +2 -3
- package/dist/presets/filesUpload.d.mts +4 -6
- package/dist/presets/filesUpload.mjs +6 -7
- package/dist/presets/index.d.mts +3 -19
- package/dist/presets/index.mjs +2 -2
- package/dist/presets/multiTenant.d.mts +1 -1
- package/dist/presets/multiTenant.mjs +7 -7
- package/dist/presets/search.d.mts +3 -5
- package/dist/presets/search.mjs +3 -4
- package/dist/{presets-CCOlKTZw.mjs → presets-qKCehiJM.mjs} +11 -18
- package/dist/{projection-BGty6ie4.mjs → projection-ClBqtsIw.mjs} +3 -4
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-B7itTkWu.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-DBWO59H9.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
- package/dist/{realtime-_59Rlje8.mjs → realtime-Ber8uJN2.mjs} +17 -19
- package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
- package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
- package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
- package/dist/registry/index.d.mts +2 -12
- package/dist/registry/index.mjs +3 -3
- package/dist/{registry-uG4wr541.mjs → registry-BA-_vFYk.mjs} +7 -12
- package/dist/{renewingLease-CiU3ZynH.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
- package/dist/{replyHelpers-Dr2pnXZg.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
- package/dist/{requestContext-DBKIdmDi.mjs → requestContext-GYO_0gEw.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{requirement-DxOaghWD.mjs → requirement-DeNjZIH3.mjs} +2 -3
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{resourceRateLimit-BBdj5yRq.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
- package/dist/{rolldown-runtime-DpVPUeXF.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
- package/dist/{routeValidator-BNTqM1Eh.mjs → routeValidator-C_H5NanI.mjs} +2 -3
- package/dist/{runtimeCapabilities-D_3eUO6V.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
- package/dist/{schedules-CVS7c1nv.mjs → schedules-eO_RzhCU.mjs} +132 -9
- package/dist/{schemaConverter-BQbg7loK.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
- package/dist/{schemaIR-CUI3hPQR.mjs → schemaIR-CEScKT2v.mjs} +3 -4
- package/dist/schemas/index.d.mts +0 -2
- package/dist/schemas/index.mjs +2 -3
- package/dist/scim/index.d.mts +0 -12
- package/dist/scim/index.mjs +10 -18
- package/dist/scope/index.d.mts +2 -6
- package/dist/scope/index.mjs +5 -5
- package/dist/{scope-DFXngazv.mjs → scope-B-Sm9m_E.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-BCXCwghd.mjs → shutdown-DzLFbe27.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-5jOzYQ_L.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
- package/dist/{sse-BilBz766.mjs → sse-2972pVwV.mjs} +8 -9
- package/dist/{sseStream-BG_uJL6J.mjs → sseStream-AWLEeNV-.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-CzLZdVa1.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
- package/dist/{streaming-DgUvMWlv.mjs → streaming-DvraWW6x.mjs} +2 -3
- package/dist/{subscriberIdentity-EWnIZ-U8.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
- package/dist/{tenancy-CVMvO5DH.mjs → tenancy-DSa_0hhw.mjs} +3 -4
- package/dist/{tenantPreparation-DIH-GX4g.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
- package/dist/testing/cleanupStoreContract.d.mts +2 -4
- package/dist/testing/cleanupStoreContract.mjs +2 -3
- package/dist/testing/index.d.mts +6 -32
- package/dist/testing/index.mjs +24 -37
- package/dist/testing/outboxStoreContract.d.mts +1 -3
- package/dist/testing/outboxStoreContract.mjs +3 -4
- package/dist/testing/requiredPorts.d.mts +2 -4
- package/dist/testing/requiredPorts.mjs +3 -4
- package/dist/testing/storageContract.d.mts +2 -4
- package/dist/testing/storageContract.mjs +2 -3
- package/dist/{timing-q9NITK04.mjs → timing-6rQTuCwg.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-NHmhDIOF.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
- package/dist/{typeGuards-CPYR9RCg.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
- package/dist/types/index.d.mts +4 -4
- package/dist/types/index.mjs +1 -1
- package/dist/types/storage.d.mts +1 -1
- package/dist/types/storage.mjs +1 -1
- package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
- package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
- package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
- package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
- package/dist/{types-BI4sbUJ3.mjs → types-CuGjhn83.mjs} +5 -6
- package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
- package/dist/usage/index.d.mts +2 -10
- package/dist/usage/index.mjs +8 -12
- package/dist/{userHelpers-oBTU3a_k.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
- package/dist/utils/index.d.mts +5 -39
- package/dist/utils/index.mjs +12 -12
- package/dist/{utils-BmE8zRrh.mjs → utils-CjjGOT4E.mjs} +20 -30
- package/dist/{validate-Dby08LhR.mjs → validate-4RlTKOJb.mjs} +5 -7
- package/dist/{versioning-P6JMNcJr.mjs → versioning-Dk2-19La.mjs} +4 -5
- package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
- package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
- package/dist/{workScope-BcMLKa3G.mjs → workScope-DoBsoVo4.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +9 -8
- package/skills/arc/SKILL.md +65 -844
- package/skills/arc/references/agent-auth.md +82 -193
- package/skills/arc/references/api-reference.md +41 -245
- package/skills/arc/references/auth-api-keys.md +99 -0
- package/skills/arc/references/auth-better-auth-overlay.md +87 -0
- package/skills/arc/references/auth-better-auth.md +78 -0
- package/skills/arc/references/auth-permissions.md +100 -0
- package/skills/arc/references/auth-strategies.md +122 -0
- package/skills/arc/references/boot.md +80 -0
- package/skills/arc/references/enterprise-auth.md +65 -81
- package/skills/arc/references/events-outbox.md +90 -0
- package/skills/arc/references/events.md +75 -440
- package/skills/arc/references/integrations-jobs.md +74 -0
- package/skills/arc/references/integrations-realtime.md +84 -0
- package/skills/arc/references/integrations-webhooks.md +71 -0
- package/skills/arc/references/integrations-workflows.md +47 -0
- package/skills/arc/references/mcp-auth.md +83 -0
- package/skills/arc/references/mcp-custom-tools.md +125 -0
- package/skills/arc/references/mcp-setup.md +115 -0
- package/skills/arc/references/mcp-testing.md +63 -0
- package/skills/arc/references/multi-tenancy.md +56 -230
- package/skills/arc/references/permissions-scope.md +81 -0
- package/skills/arc/references/production-api.md +119 -0
- package/skills/arc/references/production-audit.md +101 -0
- package/skills/arc/references/production-boot.md +91 -0
- package/skills/arc/references/production-caching.md +63 -0
- package/skills/arc/references/production-distributed.md +75 -0
- package/skills/arc/references/production-idempotency.md +83 -0
- package/skills/arc/references/production-observability.md +83 -0
- package/skills/arc/references/production-realtime.md +70 -0
- package/skills/arc/references/production-reliability.md +100 -0
- package/skills/arc/references/production-shutdown.md +43 -0
- package/skills/arc/references/querying.md +76 -0
- package/skills/arc/references/resources.md +97 -0
- package/skills/arc/references/schedules.md +79 -0
- package/skills/arc/references/scim.md +61 -208
- package/skills/arc/references/tenancy-scope-install.md +82 -0
- package/skills/arc/references/testing.md +101 -144
- package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
- package/skills/arc/references/validation.md +91 -0
- package/skills/arc/references/writes-hooks-errors.md +80 -0
- package/skills/arc-code-review/SKILL.md +67 -114
- package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
- package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
- package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
- package/skills/arc-code-review/references/recipe-resource.md +100 -0
- package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
- package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
- package/skills/arc-code-review/references/scaffolding.md +61 -198
- package/skills/arc-code-review/references/severity.md +49 -102
- package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
- package/skills/arc-code-review/references/smells-data-events.md +66 -0
- package/skills/arc-code-review/references/smells-imports-style.md +59 -0
- package/skills/arc-code-review/references/smells-platform.md +89 -0
- package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
- package/skills/arc-module-publishing/SKILL.md +82 -208
- package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
- package/skills/arc-module-publishing/references/build-and-types.md +73 -0
- package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
- package/skills/arc-module-publishing/references/package-manifest.md +34 -122
- package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
- package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
- package/skills/arc-module-publishing/references/testing-packages.md +82 -0
- package/skills/arc/references/auth.md +0 -729
- package/skills/arc/references/integrations.md +0 -452
- package/skills/arc/references/mcp.md +0 -691
- package/skills/arc/references/production.md +0 -835
- package/skills/arc-code-review/references/anti-patterns.md +0 -1008
- package/skills/arc-code-review/references/migration-recipes.md +0 -649
- package/skills/arc-code-review/references/mongokit-migration.md +0 -360
- package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Smells: canonical import homes and style
|
|
2
|
+
|
|
3
|
+
Each shared contract has one home. An import from another package drifts from the type the kit really returns.
|
|
4
|
+
|
|
5
|
+
## I1. Pagination types [high]
|
|
6
|
+
|
|
7
|
+
Grep: `OffsetPaginationResult|KeysetPaginationResult|AggregatePaginationResult|PaginationResult|toCanonicalList` imported from `@classytic/primitives` or `@classytic/mongokit`.
|
|
8
|
+
Fix:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
import type { OffsetPaginationResult, KeysetPaginationResult } from "@classytic/repo-core/pagination";
|
|
12
|
+
import { toCanonicalList } from "@classytic/repo-core/pagination";
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The wire envelope carries `method` (`offset`, `keyset`, `aggregate`) as the discriminant.
|
|
16
|
+
|
|
17
|
+
## I2. Event types [high]
|
|
18
|
+
|
|
19
|
+
Grep: `DomainEvent|EventMeta|EventHandler|EventTransport|createEvent|matchEventPattern` imported from `@classytic/arc/events`.
|
|
20
|
+
Fix: types and helpers from `@classytic/primitives/events`; only runtime pieces (`MemoryEventTransport`, `eventPlugin`, `EventOutbox`) come from arc.
|
|
21
|
+
|
|
22
|
+
## I3. Tenant config [medium]
|
|
23
|
+
|
|
24
|
+
Grep: `@classytic/primitives/tenant`.
|
|
25
|
+
Fix: `import type { TenantConfig } from "@classytic/repo-core/tenant"` and `resolveTenantConfig` from the same path.
|
|
26
|
+
|
|
27
|
+
## I4. Error contract [high]
|
|
28
|
+
|
|
29
|
+
Grep: `HttpError|ErrorContract|toErrorContract|statusToErrorCode` imported from `@classytic/primitives` or `@classytic/mongokit`.
|
|
30
|
+
Fix: `@classytic/repo-core/errors` owns `HttpError`, `ErrorContract`, `ErrorDetail`, `ERROR_CODES`, `toErrorContract`, `statusToErrorCode`. Arc's `ArcError` implements `HttpError`.
|
|
31
|
+
|
|
32
|
+
## I5. Adapters imported from arc [critical]
|
|
33
|
+
|
|
34
|
+
Grep: `createMongooseAdapter|createDrizzleAdapter|createPrismaAdapter|MongooseAdapter|DataAdapter|AdapterRepositoryInput|OpenApiSchemas|SchemaMetadata` imported from any `@classytic/arc` path, or any import from an arc `adapters` subpath.
|
|
35
|
+
Why: arc ships no kit adapters; the import does not resolve and the build breaks.
|
|
36
|
+
Fix: adapters come from the kit, contracts from repo-core.
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import { createMongooseAdapter } from "@classytic/mongokit/adapter";
|
|
40
|
+
import { createDrizzleAdapter } from "@classytic/sqlitekit/adapter";
|
|
41
|
+
import { createPrismaAdapter } from "@classytic/prismakit/adapter";
|
|
42
|
+
import type { DataAdapter, RepositoryLike } from "@classytic/repo-core/adapter";
|
|
43
|
+
import { mergeFieldRuleConstraints } from "@classytic/repo-core/schema";
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## I6. Dodged `schemaGenerator` [high]
|
|
47
|
+
|
|
48
|
+
Grep: `schemaGenerator:\s*false` on a mongokit adapter.
|
|
49
|
+
Why: the mongokit adapter derives CRUD schemas from the model by default; `false` silently removes OpenAPI bodies and MCP tool input schemas for the whole resource. It is usually a dodge for a wire-versus-model shape mismatch (minor-unit integers versus Money objects).
|
|
50
|
+
Fix: keep the generator on and declare the wire contract with zod: `...crudInput({ create, update })`. A custom part replaces the generated part wholesale. The Drizzle adapter takes `schemaGenerator: buildCrudSchemasFromTable` from `@classytic/sqlitekit/schema/crud`.
|
|
51
|
+
|
|
52
|
+
## I7. Style and edges [low]
|
|
53
|
+
|
|
54
|
+
- `console\.(log|warn|error|info|debug)\(` in `src/` outside CLI and scripts: use `request.log` or `app.log`.
|
|
55
|
+
- `:\s*any\b|as\s+any\b|@ts-ignore|@ts-expect-error`: use `unknown` and narrowing; fix the type.
|
|
56
|
+
- `^export\s+default\b` in `src/`: named exports (`export const productResource`). `loadResources()` finds the `default` export, `export const resource`, or any export with `.toPlugin()`; prefer named for grep.
|
|
57
|
+
- Resource files importing each other through tsconfig path aliases (`@/foo`): `loadResources()` uses Node's resolver, so aliases are not resolvable; use relative imports or `#` subpath imports.
|
|
58
|
+
- Code post-processing the `select` query value: pass it through; the repository owns its native shape.
|
|
59
|
+
- No `arc docs` script while a hand-kept spec exists, no `displayName` or `module` on resources: cosmetic.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Smells: jobs, presets, MCP, lifecycle, module packages
|
|
2
|
+
|
|
3
|
+
## P1. Hand-rolled recurring jobs [high]
|
|
4
|
+
|
|
5
|
+
Grep: `setInterval\s*\(`, `node-cron`, `cron\.schedule`, `new CronJob`, `acquireLock`, home-grown "leader lock" or "job registry" files.
|
|
6
|
+
Why: overlap prevention, multi-replica leases, shutdown cleanup and failure counters get re-grown per host and at least one is wrong (stacked runs, timers holding the process open, no failover after a crashed leader).
|
|
7
|
+
Fix: `schedulesPlugin` from `@classytic/arc/plugins`: no overlap by construction, optional `lock` (a repo-core `LockAdapter`, for example `createMongoLockAdapter` from `@classytic/mongokit/lock`), `jitterMs`, `runOnStart`, `leaseMs`, `fastify.getScheduleStats()`, clean drain on close. `createApp({ arcPlugins: { schedules: { lock } } })` configures the same runner for module `scheduledJobs`.
|
|
8
|
+
|
|
9
|
+
## P2. Hand-rolled once-a-day gate [high]
|
|
10
|
+
|
|
11
|
+
Grep: marker rows or flags like `lastRunDate`, `ranToday`, `daily_job_runs`, `toISOString().slice(0, 10)` compared in a timer, `new Date().getHours() ===`.
|
|
12
|
+
Why: UTC date strings skip or double a day around DST and zone offsets; two replicas both claim the slot; a crash mid-run leaves a stuck marker.
|
|
13
|
+
Fix: a `daily` block on the schedule. The decision is a civil date in the named IANA zone; the host supplies a `DailyLedger` whose `claimDay` is atomic across replicas (unique key).
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { createMemoryDailyLedger, schedulesPlugin, type DailyLedger } from "@classytic/arc/plugins";
|
|
17
|
+
|
|
18
|
+
await app.register(schedulesPlugin, {
|
|
19
|
+
schedules: [{
|
|
20
|
+
name: "daily-digest",
|
|
21
|
+
every: 60_000, // poll interval, keep well under an hour
|
|
22
|
+
daily: { hour: 8, minute: 30, zone: "Asia/Dhaka", ledger }, // createMemoryDailyLedger() in tests
|
|
23
|
+
handler: async (f, ctx) => sendDigest(f, ctx?.day),
|
|
24
|
+
}],
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
A throwing run releases the claim and retries on the next poll. `catchUpWindowMs` skips a day the process slept through; `staleAfterMs` re-grants a claim a crashed run never completed. `createDailyGate` serves hosts that tick elsewhere.
|
|
29
|
+
|
|
30
|
+
## P3. Hand-wired queue [medium]
|
|
31
|
+
|
|
32
|
+
Grep: `new Queue\(`, `new Worker\(` from `bullmq` in app code.
|
|
33
|
+
Fix: `jobsPlugin` and `defineJob` from `@classytic/arc/integrations/jobs`. Real cron expressions and durable retries are a legitimate BullMQ use; do not flag them. See the arc skill, references on jobs.
|
|
34
|
+
|
|
35
|
+
## P4. Reimplemented presets [medium]
|
|
36
|
+
|
|
37
|
+
Fingerprints in handler names and routes:
|
|
38
|
+
- softDelete: `getDeleted`, `restore`, `GET /deleted`, `POST /:id/restore` (preset adds the routes; the repository filters with `softDelete: true`).
|
|
39
|
+
- slugLookup: `getBySlug`, `GET /slug/:slug`.
|
|
40
|
+
- tree: `getChildren`, `getTree`, `parentId` plumbing.
|
|
41
|
+
- bulk: `bulkCreate`, `bulkUpdate`, `bulkDelete`, `POST /bulk`.
|
|
42
|
+
- multiTenant: every query appended with `organizationId: ...`.
|
|
43
|
+
- ownedByUser: every query appended with the caller's id.
|
|
44
|
+
- audited: a write to an audit collection on each mutation.
|
|
45
|
+
- filesUpload, search: ad hoc upload and `/search` routes.
|
|
46
|
+
|
|
47
|
+
Fix:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
presets: [
|
|
51
|
+
"softDelete",
|
|
52
|
+
"bulk",
|
|
53
|
+
{ name: "slugLookup", slugField: "slug" },
|
|
54
|
+
{ name: "multiTenant", tenantField: "organizationId" },
|
|
55
|
+
{ name: "ownedByUser", ownerField: "authorId" },
|
|
56
|
+
],
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Several tenant levels (branch, project): `multiTenantPreset({ tenantFields: [...] })` from `@classytic/arc/presets`; pass `tenantField` or `tenantFields`, never both.
|
|
60
|
+
|
|
61
|
+
## P5. Hand-written MCP tools [medium]
|
|
62
|
+
|
|
63
|
+
Grep: `CallToolRequestSchema`, `setRequestHandler\(\s*Call`, `inputSchema\s*:\s*\{\s*type\s*:\s*['"]object`, files named `tools.ts` or `mcp.ts` defining `name`, `description`, `handler`.
|
|
64
|
+
Fix: `mcpPlugin` from `@classytic/arc/mcp` with `resources: [...]`; CRUD, custom routes and actions become tools with the same permissions and field rules. Opt a resource out with `mcp: false`. Domain tools use `defineTool` and `buildMcpToolsFromBridges`.
|
|
65
|
+
|
|
66
|
+
## P6. Async engine at import time, wrong boot slot [high]
|
|
67
|
+
|
|
68
|
+
Grep: top-level `await` in `*.resource.ts`; `await ensure\w+Engine\(`; a composition root that connects the DB and then dynamic-imports the app.
|
|
69
|
+
Why: resource files evaluate before `bootstrap`, so the engine or connection is not ready.
|
|
70
|
+
Fix: connect the DB in `createApp({ beforeBoot })`, init engines in `bootstrap`, and pass `resources` as a factory so it runs after bootstrap. `loadResources(import.meta.url, { context })` hands each `*.resource.ts` a context.
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
createApp({
|
|
74
|
+
beforeBoot: async () => connectDatabase(),
|
|
75
|
+
bootstrap: [async () => { await ensureCatalogEngine(); }],
|
|
76
|
+
resources: async () => buildResources(await getCatalogEngine()),
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## P7. Casts on engine bags in module packages [high]
|
|
81
|
+
|
|
82
|
+
Grep: `as never`, `as unknown as` around `defineResource`, adapter construction or config spreads.
|
|
83
|
+
Why: each cast hides a real type; wrong repos pair with wrong models and spread merges clobber host arrays.
|
|
84
|
+
Fix: type the engine port with the kernel's own bags and assemble with `mergeResourceConfig` and `ResourceSeams` from `@classytic/arc`. See the arc-module-publishing skill.
|
|
85
|
+
|
|
86
|
+
## P8. Repeated CRUD gates [low]
|
|
87
|
+
|
|
88
|
+
Grep: the same `view` or `manage` check on all five permission keys.
|
|
89
|
+
Fix: `permissionMatrix({ read, write, delete? })` from `@classytic/arc/permissions`.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Smells: routes, schemas, parsing
|
|
2
|
+
|
|
3
|
+
Run each grep over `src/` excluding tests, `dist`, `node_modules`. Severity in brackets.
|
|
4
|
+
|
|
5
|
+
## R1. Manual CRUD routes [high]
|
|
6
|
+
|
|
7
|
+
Grep: `fastify\.(get|post|patch|put|delete)\(['"]/(\w+)`. Group by path stem; three or more methods on one stem is a `defineResource` candidate. Files named `*Routes.ts`, `*Controller.ts`, `*Handlers.js` signal the same.
|
|
8
|
+
Fix: one `defineResource` per entity. See recipe-resource.md.
|
|
9
|
+
|
|
10
|
+
## R2. Hand-written body schemas and per-handler parsing [medium]
|
|
11
|
+
|
|
12
|
+
Grep: `schema:\s*\{\s*body`, `properties:\s*\{` near a route, `\.parse\(req\.body`, `\.safeParse\(req\.(body|query)`, `Schema\.parse\(request`.
|
|
13
|
+
Smell: the same zod schema is parsed again inside each handler, or a JSON Schema duplicates the model.
|
|
14
|
+
Fix: declare the zod v4 schema once; AJV validates, a preHandler parses, the handler reads the parsed value.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
...routeInput({ body: createBody, querystring: listQuery }),
|
|
18
|
+
rawHandler: async (req, reply) => reply.send(await svc.create(parsed(createBody, req.body))),
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
CRUD writes use `...crudInput({ create, update, parse: true })`; actions use `defineAction({ schema, parse: true, handler })`. See recipe-schemas-fields.md.
|
|
22
|
+
|
|
23
|
+
## R3. `{ body: X }` wrapped action schema [high]
|
|
24
|
+
|
|
25
|
+
Grep: `schema:\s*\{\s*body\s*:` inside `actions:`, `actionSchemas`.
|
|
26
|
+
Why: an action `schema` is the body schema itself. A `{ body }` wrapper has no `type` or `properties`, so the action accepts any input. Arc logs `schema.slot_wrapper`; `strictSchemas: true` on `defineResource` (or `ARC_STRICT_SCHEMAS=true`) makes it a define-time error.
|
|
27
|
+
Fix: `schema: createBody` (zod v4) or a JSON Schema object with `type: "object"`.
|
|
28
|
+
|
|
29
|
+
## R4. Manual query parsing [medium]
|
|
30
|
+
|
|
31
|
+
Grep: `req\.query\.(filter|sort|page|limit|search|q)\b`, `parseInt\(req\.query`, `Number\(req\.query`, `\$regex`, `\$or\s*:\s*\[`.
|
|
32
|
+
Why: ReDoS exposure, no field allow-list, drift between resources.
|
|
33
|
+
Fix: arc's parser handles filters, operators, sort, pagination, populate, select with depth and length caps. Allow-lists live in `schemaOptions.query` (`filterableFields`, `allowedPopulate`); Mongo-specific grammar uses mongokit `QueryParser` passed as `queryParser`. Do not post-process `select`: arc forwards it untouched for the repository.
|
|
34
|
+
|
|
35
|
+
## R5. Custom not-found handler [low]
|
|
36
|
+
|
|
37
|
+
Grep: `setNotFoundHandler`.
|
|
38
|
+
Why: `createApp` already answers unknown routes with the ErrorContract 404 `arc.not_found`. Fastify allows one handler per scope, so a second one overrides arc's or throws.
|
|
39
|
+
Fix: delete it. To customize, `createApp({ errorHandler: { notFound: (req, reply) => ... } })`; to own it fully, `errorHandler: { notFound: false }`.
|
|
40
|
+
|
|
41
|
+
## R6. Hand-written error bodies [medium]
|
|
42
|
+
|
|
43
|
+
Grep: `reply\.code\(4\d\d\)\.send\(\{\s*(error|message)`, `throw new Error\(['"](Unauthorized|Forbidden|Not found)`.
|
|
44
|
+
Why: bodies differ per route; clients cannot branch on `code`.
|
|
45
|
+
Fix: throw `NotFoundError`, `ValidationError`, `ForbiddenError` or `createDomainError(code, message, status)` from `@classytic/arc/utils`. Map a domain error class once with `defineErrorMapper` in `errorHandler.errorMappers`.
|
|
46
|
+
|
|
47
|
+
## R7. Hand-maintained OpenAPI [medium]
|
|
48
|
+
|
|
49
|
+
Files: `openapi.yaml|json`, `swagger.*`, `api-spec.*`; `@fastify/swagger` with hand-written definitions.
|
|
50
|
+
Fix: `openApiPlugin` from `@classytic/arc/docs`, or `arc docs <entry-file> openapi.json` in CI. Diff against the old file; differences are bugs on one side.
|
|
51
|
+
|
|
52
|
+
## R8. Response field stripping by hand [critical]
|
|
53
|
+
|
|
54
|
+
Grep: `schema\.set\(['"]toJSON`, `toJSON\s*=\s*function`, `delete\s+(ret|obj|doc)\.(password|__v|secret)`.
|
|
55
|
+
Why: a new sensitive field leaks until someone remembers; lean reads skip the transform.
|
|
56
|
+
Fix: `schemaOptions: { fieldRules: { password: { hidden: true } } }`; role-gated visibility uses top-level `fields: { salary: fields.visibleTo(["admin"]) }`. See recipe-schemas-fields.md.
|
|
57
|
+
|
|
58
|
+
## R9. Custom search routes [medium]
|
|
59
|
+
|
|
60
|
+
Grep: `/search`, `/find`, `/lookup` routes with custom parameter parsing.
|
|
61
|
+
Fix: arc's `?search=` and filter grammar; for external engines `searchPreset` from `@classytic/arc/presets/search`.
|
|
62
|
+
|
|
63
|
+
## R10. Ad hoc multipart [medium]
|
|
64
|
+
|
|
65
|
+
Grep: `multer`, `formidable`, `busboy`, `@fastify/multipart` registered per route.
|
|
66
|
+
Fix: `multipartBody({ allowedMimeTypes, maxFileSize })` from `@classytic/arc/middleware` in `middlewares.create`, or `filesUploadPreset` from `@classytic/arc/presets/files-upload`.
|
|
@@ -1,243 +1,117 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: arc-module-publishing
|
|
3
|
-
description:
|
|
4
|
-
Author and publish an ecosystem package for @classytic/arc the way arc's own packages
|
|
5
|
-
are built — modules, action presets, and plugins that hosts install and compose.
|
|
6
|
-
Codifies the non-negotiable conventions: no hardcoded dependencies (host duty), peers
|
|
7
|
-
as `>=` ranges (stable API contract), bundle-nothing tsdown, public-subpath imports only,
|
|
8
|
-
one-way dependency (arc never depends on you), and the classytic release gate.
|
|
9
|
-
Use when creating a new @classytic/arc-<domain> package, extracting a domain out of an
|
|
10
|
-
app into a reusable module, deciding a package's package.json / tsdown / peer setup,
|
|
11
|
-
writing a defineModule() or an action preset, or preparing an arc module for npm publish.
|
|
12
|
-
Triggers: publish arc module, arc package, arc ecosystem, defineModule, ArcModule, arc
|
|
13
|
-
plugin package, arc action preset, extract domain to package, arc-approval, arc-involvement,
|
|
14
|
-
peer dependencies arc, tsdown arc package, arc module conventions, classytic publish,
|
|
15
|
-
mergeResourceConfig, ResourceSeams, kernel-typed engine port, module errorMappers.
|
|
3
|
+
description: Author and publish a package on top of @classytic/arc: an action preset, plugin, or defineModule() domain module that hosts install. Covers peers, tsdown, public subpaths, resource assembly, testing, release gate. Use when creating an arc-<domain> package or preparing npm publish. Triggers: arc package, defineModule, ArcModule, action preset, peerDependencies, mergeResourceConfig.
|
|
16
4
|
license: MIT
|
|
17
5
|
metadata:
|
|
18
6
|
author: Classytic
|
|
7
|
+
minVersion: "2.46.0"
|
|
19
8
|
tags:
|
|
20
9
|
- arc
|
|
21
10
|
- packaging
|
|
22
11
|
- publishing
|
|
23
12
|
- modules
|
|
24
|
-
- ecosystem
|
|
25
|
-
- tsdown
|
|
26
|
-
- peer-dependencies
|
|
27
|
-
- monorepo
|
|
28
13
|
---
|
|
29
14
|
|
|
30
15
|
# Publishing @classytic/arc ecosystem packages
|
|
31
16
|
|
|
32
|
-
|
|
33
|
-
preset, or a plugin — so it composes cleanly into any host and follows the same discipline
|
|
34
|
-
as arc's own first-party packages (`@classytic/arc-approval`, `@classytic/arc-involvement`,
|
|
35
|
-
`@classytic/arc-notifications`).
|
|
17
|
+
The package declares a contract, the host owns the installation. Node 22+, ESM only, strict TypeScript, tsdown, Biome.
|
|
36
18
|
|
|
37
|
-
|
|
19
|
+
## Do not hand-roll
|
|
38
20
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
21
|
+
| Need | Use | Import |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| Domain as one value (engine, resources, teardown) | `defineModule` | `@classytic/arc/factory` |
|
|
24
|
+
| Read another module's engine | `getModuleExports`, `getOptionalModuleExports` | `@classytic/arc/factory` |
|
|
25
|
+
| Module resources from host seams | `mergeResourceConfig`, `ResourceSeams` | `@classytic/arc` |
|
|
26
|
+
| Plugin with global and per-resource parts | `createPlugin` | `@classytic/arc/plugins` |
|
|
27
|
+
| Verbs on one resource | `defineAction` in an `actions` slice | `@classytic/arc/core` |
|
|
28
|
+
| Zod v4 body validated once, handler gets parsed value | `routeInput`, `crudInput`, `parsed`, `noPayloadSchema` | `@classytic/arc/core` |
|
|
29
|
+
| CRUD gates from read/write | `permissionMatrix` | `@classytic/arc/permissions` |
|
|
30
|
+
| Tenant and user ids | `getUserId`, `requireOrgId`, `requireUserId`, `scopeFirstCtx` | `@classytic/arc/scope` |
|
|
31
|
+
| Domain errors on the wire | `createDomainError`, `defineErrorMapper`, module `errorMappers` | `@classytic/arc/utils` |
|
|
32
|
+
| Recurring work | module `scheduledJobs`; `schedulesPlugin` with `daily: { hour, zone, ledger }` | `@classytic/arc/plugins` |
|
|
33
|
+
| Event subscriptions, readiness | module `eventHandlers`, `healthChecks` | `@classytic/arc/factory` |
|
|
34
|
+
| Background queue | `jobsPlugin`, `defineJob` | `@classytic/arc/integrations/jobs` |
|
|
35
|
+
| Boot proof for a module | `bootModuleApp`, `assertModuleBootsAlone` | `@classytic/arc/testing` |
|
|
36
|
+
| Store conformance | `runOutboxStoreContract`, `runStorageContract`, `runCleanupRunStoreContract` | `@classytic/arc/testing/{outbox,storage,cleanup}` |
|
|
51
37
|
|
|
52
|
-
##
|
|
38
|
+
## Golden path
|
|
53
39
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
| Shape | You export | Host uses it via | Example |
|
|
57
|
-
|---|---|---|---|
|
|
58
|
-
| **Action preset** | a function returning an `actions:` slice | spread into `defineResource({ actions })` | `withApprovalChain()` (arc-approval) |
|
|
59
|
-
| **Plugin** | an `fp()`-wrapped Fastify plugin (+ named export) | `app.register()` / `plugins:` slot | any cross-cutting decorator/hook |
|
|
60
|
-
| **Module** | `createXModule(deps) → ArcModule` | `createApp({ modules: [...] })` | a whole domain (engine + resources + wiring) |
|
|
61
|
-
|
|
62
|
-
- A preset adds **verbs to one resource**. No lifecycle, no engine — just a function that
|
|
63
|
-
returns `Record<string, ActionDefinition>`. Storage-agnostic via a **structural repository
|
|
64
|
-
port** (an interface with the two or three methods you actually call), never a kit import.
|
|
65
|
-
- A module owns a **whole domain**: it initializes an engine in `bootstrap`, registers its
|
|
66
|
-
resources, wires `afterResources`, and tears down in `onClose`. Use `defineModule` and let
|
|
67
|
-
the host list it in `modules:`. See [references/authoring-modules.md](references/authoring-modules.md).
|
|
68
|
-
|
|
69
|
-
When unsure, ship a **preset or plugin**. A module is the right call only when there is
|
|
70
|
-
engine state to boot and multiple resources to register as a unit.
|
|
71
|
-
|
|
72
|
-
---
|
|
40
|
+
Pick the smallest shape: preset (verbs on one resource), plugin (cross-cutting decorator), module (engine plus several resources).
|
|
73
41
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
This is where packages go wrong. Get the `package.json` dependency fields exactly right:
|
|
77
|
-
|
|
78
|
-
- **`dependencies`: usually empty.** Everything arc-shaped is a *peer*. Only add a real
|
|
79
|
-
`dependency` for a genuinely private, bundled-in helper the host should never see or
|
|
80
|
-
control — which is rare. If you're tempted to add `@classytic/*` or `fastify` here, stop:
|
|
81
|
-
that's a peer.
|
|
82
|
-
- **`peerDependencies`: `>=` ranges, never `^`.** A peer is a *contract*: "I work against
|
|
83
|
-
arc 2.20 and up." `^2.20.0` would wrongly forbid a host on arc 3.x that still satisfies the
|
|
84
|
-
API you use. Use `">=2.20.0"`. This keeps the API contract stable and lets hosts upgrade arc
|
|
85
|
-
without your package blocking them.
|
|
86
|
-
- **`devDependencies`: pin with `^`.** These are the versions your *test suite* runs against —
|
|
87
|
-
a concrete, current version (`"@classytic/arc": "^2.20.0"`). The floor of every devDep must
|
|
88
|
-
be `>=` the peer floor, or your tests never exercise the version you claim to support.
|
|
89
|
-
- **Optional peers** (zod, ioredis, a kit) go in `peerDependencies` **and**
|
|
90
|
-
`peerDependenciesMeta: { "<name>": { optional: true } }`. Never let their types leak into
|
|
91
|
-
your public `.d.mts` — use structural typing so a host that doesn't install them still
|
|
92
|
-
compiles. See [references/package-manifest.md](references/package-manifest.md).
|
|
93
|
-
|
|
94
|
-
**Why `>=` and not `^` for peers:** the host, not you, resolves the actual installed version.
|
|
95
|
-
Your job is to state the *floor* of the API you depend on and stay out of the host's upgrade
|
|
96
|
-
path. A caret peer turns every host major-bump into a forced wait on your release.
|
|
97
|
-
|
|
98
|
-
---
|
|
99
|
-
|
|
100
|
-
## Import discipline: public surface only
|
|
101
|
-
|
|
102
|
-
Import arc through its **published subpaths**, exactly as a third-party host would. Never
|
|
103
|
-
reach into `@classytic/arc/src/...` or a deep `dist/` path.
|
|
42
|
+
1. Preset: injected policy, zod v4 schema declared once, tenant from scope.
|
|
104
43
|
|
|
105
44
|
```ts
|
|
45
|
+
import { defineAction } from "@classytic/arc/core";
|
|
106
46
|
import type { PermissionCheck } from "@classytic/arc/permissions";
|
|
107
|
-
import {
|
|
108
|
-
import type { ActionDefinition
|
|
109
|
-
import {
|
|
47
|
+
import { requireOrgId } from "@classytic/arc/scope";
|
|
48
|
+
import type { ActionDefinition } from "@classytic/arc/types";
|
|
49
|
+
import { z } from "zod";
|
|
50
|
+
|
|
51
|
+
const closeBody = z.object({ note: z.string().trim().min(2) });
|
|
52
|
+
|
|
53
|
+
export function withClose(cfg: { permission: PermissionCheck; close(id: string, orgId: string, note: string): Promise<unknown> }): Record<"close", ActionDefinition> {
|
|
54
|
+
return {
|
|
55
|
+
close: defineAction({
|
|
56
|
+
schema: closeBody,
|
|
57
|
+
parse: true,
|
|
58
|
+
permissions: cfg.permission,
|
|
59
|
+
description: "Close the subject.",
|
|
60
|
+
handler: (id, data, req) => cfg.close(id, requireOrgId(req.scope), data.note),
|
|
61
|
+
}),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
110
64
|
```
|
|
111
65
|
|
|
112
|
-
|
|
113
|
-
`/utils`, `/factory` (for `defineModule`, `getModuleExports`), `/testing`. If something you
|
|
114
|
-
need isn't on a public subpath, that's a signal — file it against arc rather than deep-import
|
|
115
|
-
around it. Deep imports break the moment arc reorganizes internals, which it's free to do
|
|
116
|
-
because they were never public.
|
|
117
|
-
|
|
118
|
-
**One-way dependency:** your package depends on arc; **arc never depends on your package.**
|
|
119
|
-
If arc would need something from you, the abstraction belongs *in arc* (a port, a hook, a
|
|
120
|
-
preset seam), not as a back-edge. This keeps the dependency graph a DAG and arc publishable
|
|
121
|
-
on its own.
|
|
122
|
-
|
|
123
|
-
---
|
|
124
|
-
|
|
125
|
-
## Build: bundle nothing
|
|
126
|
-
|
|
127
|
-
tsdown, ESM only, and **bundle nothing that's a peer**. Every `@classytic/*` and `fastify`
|
|
128
|
-
stays external so the host's single installed copy is the one that runs (two copies of arc =
|
|
129
|
-
two plugin registries = subtle breakage).
|
|
66
|
+
2. Module: `bootstrap` return is the public export, `resources` factory runs after all bootstraps.
|
|
130
67
|
|
|
131
68
|
```ts
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
skipNodeModulesBundle: true, // don't inline node_modules
|
|
146
|
-
neverBundle: [/^@classytic\//], // arc + primitives + kits stay external, always
|
|
147
|
-
},
|
|
148
|
-
});
|
|
69
|
+
import { defineModule, getModuleExports } from "@classytic/arc/factory";
|
|
70
|
+
|
|
71
|
+
export const accountingModule = (deps: AccountingDeps) =>
|
|
72
|
+
defineModule({
|
|
73
|
+
name: "accounting",
|
|
74
|
+
dependsOn: ["ledger"],
|
|
75
|
+
bootstrap: async (f, { defer }) => {
|
|
76
|
+
const engine = createAccountingEngine(deps, getModuleExports<LedgerEngine>(f, "ledger"));
|
|
77
|
+
defer(() => engine.stop());
|
|
78
|
+
return engine;
|
|
79
|
+
},
|
|
80
|
+
resources: (f) => [accountsResource(getModuleExports<AccountingEngine>(f, "accounting"), deps)],
|
|
81
|
+
});
|
|
149
82
|
```
|
|
150
83
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
84
|
+
3. Manifest: arc, primitives, repo-core, kits and zod are peers with `>=` floors; tests pin `^` devDeps. See references/package-manifest.md.
|
|
85
|
+
4. Build: tsdown, bundle nothing. See references/build-and-types.md.
|
|
86
|
+
5. Prove composition: `bootModuleApp(({ connection }) => [accountingModule(deps)])`, hit routes with `t.app.inject`, `await t.close()`. See references/testing-packages.md.
|
|
87
|
+
6. Release: `npm run verify`, then `npm publish -w <pkg>`. See references/publishing-workflow.md.
|
|
154
88
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
## Bridge onto arc's primitives — don't reinvent them
|
|
158
|
-
|
|
159
|
-
A hard-won lesson: when a host already gets a capability from arc, **bridge onto it** instead
|
|
160
|
-
of shipping a second path.
|
|
161
|
-
|
|
162
|
-
- Need background work? Use `fastify.jobs` (arc's BullMQ bridge) — don't add your own BullMQ
|
|
163
|
-
dependency and stand up a parallel queue. Two job systems in one app is a footgun, not a
|
|
164
|
-
feature.
|
|
165
|
-
- Need guaranteed event delivery? Use arc's **outbox** and the `@classytic/primitives` event
|
|
166
|
-
contract (`createEvent`, `DomainEvent`, `EventTransport`) — don't invent an event shape.
|
|
167
|
-
- Need permissions/scope? Use `@classytic/arc/permissions` + `@classytic/arc/scope`
|
|
168
|
-
accessors (`getOrgId`, `requireUserId`) — don't re-derive tenant/user from `request.user`.
|
|
169
|
-
|
|
170
|
-
The test: *"Does arc already bless a primitive for this?"* If yes, your package composes onto
|
|
171
|
-
it. Shipping a competing path breaks the host's single-source-of-truth and doubles their ops
|
|
172
|
-
surface. Reinvent only when arc genuinely has no primitive — and then consider whether it
|
|
173
|
-
should live in arc.
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## Naming & versioning
|
|
178
|
-
|
|
179
|
-
- **Package name:** `@classytic/arc-<domain>` for first-party; third parties use their own
|
|
180
|
-
scope (`@acme/arc-billing`). The `arc-` prefix signals "arc ecosystem package."
|
|
181
|
-
- **Module `name`** (the `defineModule({ name })` identifier): namespace it so it can't
|
|
182
|
-
collide in a host that composes many modules — `"accounting"`, `"order"`, or a
|
|
183
|
-
vendor-qualified `"acme.billing"`. This is the key hosts use in `dependsOn` and
|
|
184
|
-
`getModuleExports`, and arc rejects duplicate module names at boot.
|
|
185
|
-
- **SemVer the public export**, not the internals. Your exported function signatures, the
|
|
186
|
-
`ArcModule` shape you return, and the action/schema surface are the contract. Bumping a peer
|
|
187
|
-
floor (e.g. requiring a newer arc) is at least a **minor**; changing an exported signature is
|
|
188
|
-
a **major**.
|
|
189
|
-
|
|
190
|
-
---
|
|
191
|
-
|
|
192
|
-
## Release gate
|
|
193
|
-
|
|
194
|
-
Every publish runs a gate — no `--no-verify`, ever. In a workspace, a shared script; in a
|
|
195
|
-
solo package, `prepublishOnly`:
|
|
196
|
-
|
|
197
|
-
```jsonc
|
|
198
|
-
"scripts": {
|
|
199
|
-
"build": "tsdown",
|
|
200
|
-
"typecheck": "tsc --noEmit",
|
|
201
|
-
"lint": "biome check src/",
|
|
202
|
-
"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
|
|
203
|
-
}
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
For a **monorepo of packages**, add a **peer-skew gate** that fails if any package's devDep
|
|
207
|
-
floor is below its declared peer floor — it's the mechanical guard that stops your suite from
|
|
208
|
-
silently testing against a version older than you promise to support. Full script and workspace
|
|
209
|
-
layout in [references/publishing-workflow.md](references/publishing-workflow.md).
|
|
89
|
+
## Gotchas
|
|
210
90
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
91
|
+
- Module `plugins` and `afterResources` are called by arc, not registered: `await fastify.register(x)` inside, never return a plugin.
|
|
92
|
+
- `dependsOn` orders composition, it does not delay imports; a thunk decides whether to import.
|
|
93
|
+
- Peer floor equals the newest arc feature you use, never the workspace baseline.
|
|
94
|
+
- No upper bound on peers; floors only.
|
|
95
|
+
- A shared `ErrorMapper` goes in module `errorMappers`; host mappers keep priority.
|
|
96
|
+
- An action `schema` is the body schema itself; `{ body: X }` validates nothing and logs `schema.slot_wrapper`.
|
|
97
|
+
- Reserved query names (`page`, `limit`, `cursor`, `after`, `sort`, `search`, `select`, `populate`) cannot be filter fields.
|
|
98
|
+
- Identity comes only from `req.scope` accessors, never `req.user` or `x-user-id` headers.
|
|
214
99
|
|
|
215
|
-
|
|
100
|
+
## Never
|
|
216
101
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
-
|
|
220
|
-
-
|
|
221
|
-
-
|
|
222
|
-
-
|
|
223
|
-
- [ ] tsdown `neverBundle: [/^@classytic\//]` + `skipNodeModulesBundle: true`
|
|
224
|
-
- [ ] imports use public subpaths only — no `@classytic/arc/src` or deep `dist` paths
|
|
225
|
-
- [ ] arc has **no** dependency on this package (grep arc for the package name → nothing)
|
|
226
|
-
- [ ] `sideEffects: false`, `files: ["dist"]`, `exports` map with `types`+`default`, `type: "module"`
|
|
227
|
-
- [ ] action schemas shipped as **JSON Schema** (zod stays an optional peer, never required)
|
|
228
|
-
- [ ] `prepublishOnly` gate green (typecheck + lint + test + build), no `--no-verify`
|
|
229
|
-
- [ ] module `name` is namespaced and can't collide across a multi-module host
|
|
230
|
-
- [ ] boots green in a **kit-backed testkit** (real in-memory store, prod-fidelity — not a fake repo)
|
|
231
|
-
- [ ] `.npmrc`: `auto-install-peers=false` + an install-script allowlist for any dep with a `postinstall`
|
|
232
|
-
|
|
233
|
-
---
|
|
102
|
+
- Put arc, fastify or a kit in `dependencies`; write a peer as `^`.
|
|
103
|
+
- Bundle `@classytic/*`; import arc `src` or `dist` paths.
|
|
104
|
+
- Make arc depend on your package; the port belongs in arc.
|
|
105
|
+
- Add a second job system or event shape when arc and primitives provide one.
|
|
106
|
+
- Use `--no-verify` or skip `prepublishOnly`.
|
|
107
|
+
- Use `Co-Authored-By` or global git config in classytic packages.
|
|
234
108
|
|
|
235
109
|
## References
|
|
236
110
|
|
|
237
|
-
- [references/package-manifest.md](references/package-manifest.md)
|
|
238
|
-
|
|
239
|
-
- [references/
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
- [references/
|
|
243
|
-
|
|
111
|
+
- [references/package-manifest.md](references/package-manifest.md): read when writing package.json, peers, devDeps, exports.
|
|
112
|
+
- [references/build-and-types.md](references/build-and-types.md): read when configuring tsdown or keeping optional-peer types out of d.mts.
|
|
113
|
+
- [references/action-presets-and-plugins.md](references/action-presets-and-plugins.md): read when shipping a preset or fp() plugin.
|
|
114
|
+
- [references/module-lifecycle.md](references/module-lifecycle.md): read when writing defineModule, dependsOn, ports, cross-module exports, thunks.
|
|
115
|
+
- [references/resource-assembly.md](references/resource-assembly.md): read when building resources from host seams, schemas and permissions.
|
|
116
|
+
- [references/testing-packages.md](references/testing-packages.md): read when writing boot tests and store conformance tests.
|
|
117
|
+
- [references/publishing-workflow.md](references/publishing-workflow.md): read when setting up gates, monorepo, bot identity, versioning.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Action presets and plugins
|
|
2
|
+
|
|
3
|
+
## Action preset: verbs on one resource
|
|
4
|
+
|
|
5
|
+
A function returning an `actions` slice. No lifecycle, no engine. The host spreads it into `defineResource`.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { defineAction } from "@classytic/arc/core";
|
|
9
|
+
import type { PermissionCheck } from "@classytic/arc/permissions";
|
|
10
|
+
import { getOrgId } from "@classytic/arc/scope";
|
|
11
|
+
import type { ActionDefinition } from "@classytic/arc/types";
|
|
12
|
+
import { createDomainError, NotFoundError } from "@classytic/arc/utils";
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
|
|
15
|
+
const flagBody = z.object({ reason: z.string().trim().min(3) });
|
|
16
|
+
|
|
17
|
+
export interface WithFlagConfig<TDoc> {
|
|
18
|
+
readonly repository: {
|
|
19
|
+
getById(id: string, o: { organizationId?: string; throwOnNotFound: false; lean: true }): Promise<TDoc | null>;
|
|
20
|
+
update(id: string, patch: Record<string, unknown>, o: { organizationId?: string; lean: true }): Promise<TDoc | null>;
|
|
21
|
+
};
|
|
22
|
+
readonly permissions: { readonly flag: PermissionCheck };
|
|
23
|
+
readonly tenancy?: "required" | "off";
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export function withFlag<TDoc>(cfg: WithFlagConfig<TDoc>): Record<"flag", ActionDefinition> {
|
|
27
|
+
return {
|
|
28
|
+
flag: defineAction({
|
|
29
|
+
schema: flagBody,
|
|
30
|
+
parse: true,
|
|
31
|
+
permissions: cfg.permissions.flag,
|
|
32
|
+
description: "Flag the subject for review.",
|
|
33
|
+
handler: async (id, data, req) => {
|
|
34
|
+
const organizationId = cfg.tenancy === "off" ? undefined : getOrgId(req.scope);
|
|
35
|
+
const doc = await cfg.repository.getById(id, { organizationId, throwOnNotFound: false, lean: true });
|
|
36
|
+
if (!doc) throw new NotFoundError("subject not found");
|
|
37
|
+
if ((doc as { flagged?: boolean }).flagged) throw createDomainError("subject.already_flagged", "Already flagged", 409);
|
|
38
|
+
return cfg.repository.update(id, { flagged: true, flagReason: data.reason }, { organizationId, lean: true });
|
|
39
|
+
},
|
|
40
|
+
}),
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Host:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
defineResource({
|
|
49
|
+
name: "ticket",
|
|
50
|
+
adapter,
|
|
51
|
+
actions: { ...withFlag({ repository, permissions: { flag: requireRoles(["admin"]) } }) },
|
|
52
|
+
});
|
|
53
|
+
// POST /tickets/:id/action { "action": "flag", "reason": "spam" }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Rules for a reusable preset
|
|
57
|
+
|
|
58
|
+
- Inject all policy (permissions, resolvers, side-effect hooks, tenancy mode). The preset owns mechanism, the host owns policy.
|
|
59
|
+
- Take a structural port, never a kit type.
|
|
60
|
+
- Read tenant and user through `getOrgId` or `requireOrgId` on `req.scope`. Support `tenancy: "required" | "off"`.
|
|
61
|
+
- Declare the body once: zod v4 plus `parse: true`, or JSON Schema. An empty body uses `noPayloadSchema`.
|
|
62
|
+
- Map domain failures to `createDomainError(code, message, status)` so the wire stays the ErrorContract.
|
|
63
|
+
- Model a mode as a discriminated field (`source: "literal" | "policy"`), not a boolean flag.
|
|
64
|
+
- `defineAction({ id: false })` mounts the verb at `POST /<prefix>/action` with no `:id`.
|
|
65
|
+
|
|
66
|
+
## Plugin: cross-cutting decorator or hook
|
|
67
|
+
|
|
68
|
+
`createPlugin` gives a global `forRoot` and a per-resource `forResource` slice. No `fastify-plugin` import needed.
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { createPlugin } from "@classytic/arc/plugins";
|
|
72
|
+
|
|
73
|
+
export const analytics = createPlugin<{ apiKey: string }, { track: boolean }>("analytics", {
|
|
74
|
+
forRoot: async (fastify, opts) => {
|
|
75
|
+
fastify.decorate("analytics", createClient(opts.apiKey));
|
|
76
|
+
},
|
|
77
|
+
forResource: (opts) => (opts.track ? { hooks: [] } : {}),
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
// host
|
|
81
|
+
await app.register(analytics.forRoot({ apiKey }));
|
|
82
|
+
defineResource({ name: "product", adapter, ...analytics.forResource({ track: true }) });
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
- Set response headers in `onRequest` or `preSerialization`, never in an async `onSend`.
|
|
86
|
+
- A plugin owned by a domain module is registered inside the module's `plugins` phase: `await fastify.register(x)`.
|
|
87
|
+
- Scheduled work in a package ships as module `scheduledJobs`; a once-per-local-day job sets `daily: { hour, minute?, zone, ledger }` and the host supplies the `DailyLedger`.
|