@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.
- package/README.md +1 -1
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.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-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
- package/dist/cache/index.d.mts +4 -10
- package/dist/cache/index.mjs +5 -6
- package/dist/{caching-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
- package/dist/cleanup/index.d.mts +4 -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-D_aiew34.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-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.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-BJTsSnke.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-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
- package/dist/{errors-grZkIA8N.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-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.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-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
- package/dist/{health-DyeP3mTW.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-jC3rMPzb.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-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.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-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.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-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
- package/dist/observeSend-BK-JN1jK.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.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-B4FAkx3A.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-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.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-C3VJKRGp.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-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.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-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.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-Bevxy_ST.mjs → scope-B-Sm9m_E.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.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-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.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-D9NWjpYc.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-BHig1kHq.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-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.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-DPPfM4m6.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
|
@@ -1,1008 +0,0 @@
|
|
|
1
|
-
# Arc Anti-Pattern Detection Catalog
|
|
2
|
-
|
|
3
|
-
Every entry below has: **detection** (greppable regex / file pattern), **severity**, **why it matters**, and **fix** (with arc API citation). Run each detection against `src/` (excluding `node_modules`, `dist`, `coverage`, `*.test.*`).
|
|
4
|
-
|
|
5
|
-
Severity legend: 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## §1. Manual query parsing 🟡
|
|
10
|
-
|
|
11
|
-
**Detection (Grep):**
|
|
12
|
-
```
|
|
13
|
-
pattern: "req\\.query\\.(filter|sort|page|limit|search|q)\\b"
|
|
14
|
-
glob: "**/*.{ts,js}"
|
|
15
|
-
output_mode: content
|
|
16
|
-
```
|
|
17
|
-
Also: `\\$or\\s*:\\s*\\[`, `\\$and\\s*:\\s*\\[`, `\\$regex`, `Number\\(req\\.query\\.`, `parseInt\\(req\\.query\\.`.
|
|
18
|
-
|
|
19
|
-
**Anti-pattern:**
|
|
20
|
-
```typescript
|
|
21
|
-
const filters: any = {};
|
|
22
|
-
if (req.query.status) filters.status = req.query.status;
|
|
23
|
-
if (req.query.minPrice) filters.price = { $gte: Number(req.query.minPrice) };
|
|
24
|
-
if (req.query.q) {
|
|
25
|
-
filters.$or = [
|
|
26
|
-
{ name: { $regex: req.query.q, $options: 'i' } },
|
|
27
|
-
{ description: { $regex: req.query.q, $options: 'i' } },
|
|
28
|
-
];
|
|
29
|
-
}
|
|
30
|
-
const items = await Product.find(filters)
|
|
31
|
-
.skip((Number(req.query.page) - 1) * 20)
|
|
32
|
-
.limit(20);
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
**Why critical-adjacent:** ad-hoc parsing is a ReDoS vector (no regex bounds), bypasses field whitelists, and silently diverges across resources.
|
|
36
|
-
|
|
37
|
-
**Fix:** Arc's built-in parser handles filters, operators, sort, pagination, populate, select.
|
|
38
|
-
```typescript
|
|
39
|
-
defineResource({
|
|
40
|
-
name: 'product',
|
|
41
|
-
schemaOptions: {
|
|
42
|
-
query: {
|
|
43
|
-
filterableFields: { status: { type: 'string' }, price: { type: 'number' } },
|
|
44
|
-
allowedPopulate: ['category'],
|
|
45
|
-
},
|
|
46
|
-
},
|
|
47
|
-
});
|
|
48
|
-
// GET /products?status=active&price[gte]=100&sort=-createdAt&page=2&limit=20&populate=category
|
|
49
|
-
```
|
|
50
|
-
For MongoDB-specific operators (`$lookup`, geo): use `QueryParser` from `@classytic/mongokit`:
|
|
51
|
-
```typescript
|
|
52
|
-
import { QueryParser } from '@classytic/mongokit';
|
|
53
|
-
defineResource({
|
|
54
|
-
queryParser: new QueryParser({
|
|
55
|
-
allowedFilterFields: ['status', 'category'],
|
|
56
|
-
allowedSortFields: ['createdAt', 'price'],
|
|
57
|
-
allowedOperators: ['eq', 'gte', 'lte', 'in'],
|
|
58
|
-
}),
|
|
59
|
-
});
|
|
60
|
-
```
|
|
61
|
-
ReDoS protection, max-depth, max-limit are enforced.
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## §2. Hand-written Fastify route schemas 🟡
|
|
66
|
-
|
|
67
|
-
**Detection:**
|
|
68
|
-
```
|
|
69
|
-
pattern: "fastify\\.(get|post|patch|put|delete)\\([^,]+,\\s*\\{\\s*schema\\s*:"
|
|
70
|
-
multiline: true
|
|
71
|
-
```
|
|
72
|
-
Or: `properties\\s*:\\s*\\{` near `route\\(|fastify\\.(get|post|patch)`.
|
|
73
|
-
|
|
74
|
-
**Anti-pattern:**
|
|
75
|
-
```typescript
|
|
76
|
-
fastify.post('/products', {
|
|
77
|
-
schema: {
|
|
78
|
-
body: {
|
|
79
|
-
type: 'object',
|
|
80
|
-
properties: {
|
|
81
|
-
name: { type: 'string', minLength: 1 },
|
|
82
|
-
price: { type: 'number', minimum: 0 },
|
|
83
|
-
},
|
|
84
|
-
required: ['name', 'price'],
|
|
85
|
-
},
|
|
86
|
-
response: { 200: { type: 'object', properties: { id: {...}, name: {...} } } },
|
|
87
|
-
},
|
|
88
|
-
handler: async (req) => Product.create(req.body),
|
|
89
|
-
});
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
**Why:** Schema duplicates Mongoose model + diverges over time. No OpenAPI sync.
|
|
93
|
-
|
|
94
|
-
**Fix:**
|
|
95
|
-
```typescript
|
|
96
|
-
defineResource({
|
|
97
|
-
name: 'product',
|
|
98
|
-
schemaOptions: {
|
|
99
|
-
fieldRules: {
|
|
100
|
-
name: { type: 'string', minLength: 1, required: true },
|
|
101
|
-
price: { type: 'number', minimum: 0, required: true },
|
|
102
|
-
},
|
|
103
|
-
},
|
|
104
|
-
});
|
|
105
|
-
```
|
|
106
|
-
Body, response, and OpenAPI auto-derive. Mongoose model constraints take precedence; `fieldRules` supplements.
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
|
-
## §3. Manual CRUD routes 🟠
|
|
111
|
-
|
|
112
|
-
**Detection:** Multiple `fastify.(get|post|patch|delete)` calls for the same path stem.
|
|
113
|
-
```
|
|
114
|
-
pattern: "fastify\\.(get|post|patch|put|delete)\\(['\"]\\/(\\w+)"
|
|
115
|
-
output_mode: content
|
|
116
|
-
```
|
|
117
|
-
Group hits by capture group 2 (path stem). Three or more methods on the same stem ⇒ candidate for `defineResource`.
|
|
118
|
-
|
|
119
|
-
**Anti-pattern:** A `routes/products.ts` file with `GET /products`, `GET /products/:id`, `POST /products`, `PATCH /products/:id`, `DELETE /products/:id` each implemented inline.
|
|
120
|
-
|
|
121
|
-
**Why high:** One resource gets a fix (e.g., pagination, error handling) and the others drift. Arc generates all five identically.
|
|
122
|
-
|
|
123
|
-
**Fix:** Replace the whole file with one `defineResource`. See [migration-recipes.md §1](migration-recipes.md).
|
|
124
|
-
|
|
125
|
-
---
|
|
126
|
-
|
|
127
|
-
## §4. Manual permission checks inside handlers 🔴
|
|
128
|
-
|
|
129
|
-
**Detection:**
|
|
130
|
-
```
|
|
131
|
-
pattern: "(req|request)\\.user\\.(role|roles)\\b|user\\.role\\s*[!=]==|roles\\.includes\\("
|
|
132
|
-
output_mode: content
|
|
133
|
-
```
|
|
134
|
-
Also: `if\\s*\\(\\s*!\\s*req\\.user\\s*\\)`, `throw\\s+new\\s+Error\\(['\"](Unauthorized|Forbidden)`.
|
|
135
|
-
|
|
136
|
-
**Anti-pattern:**
|
|
137
|
-
```typescript
|
|
138
|
-
fastify.post('/products', async (req, reply) => {
|
|
139
|
-
if (!req.user) throw new Error('Unauthorized'); // 401 hand-rolled
|
|
140
|
-
if (!req.user.roles.includes('admin')) throw new Error('Forbidden'); // 403 hand-rolled
|
|
141
|
-
if (product.createdBy !== req.user.id) throw new Error('Not yours'); // ownership
|
|
142
|
-
// proceed
|
|
143
|
-
});
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
**Why critical:**
|
|
147
|
-
- Inconsistent error shape (Error vs ArcError). Frontend gets unpredictable bodies.
|
|
148
|
-
- `req.user.id` vs `req.user._id` mismatches between routes silently bypass ownership.
|
|
149
|
-
- No row-level filter — admin sees `Product.find()` with no tenant scope.
|
|
150
|
-
|
|
151
|
-
**Fix:** Declarative permission combinators. Permissions run at framework level, `filters` propagate into the repo query (row-level ABAC):
|
|
152
|
-
```typescript
|
|
153
|
-
import {
|
|
154
|
-
allowPublic, requireAuth, requireRoles, requireOwnership,
|
|
155
|
-
requireOrgMembership, requireOrgRole, requireServiceScope,
|
|
156
|
-
allOf, anyOf,
|
|
157
|
-
} from '@classytic/arc';
|
|
158
|
-
|
|
159
|
-
defineResource({
|
|
160
|
-
permissions: {
|
|
161
|
-
list: allowPublic(),
|
|
162
|
-
get: allowPublic(),
|
|
163
|
-
create: requireRoles(['admin', 'editor']),
|
|
164
|
-
update: anyOf(requireRoles(['admin']), requireOwnership('createdBy')),
|
|
165
|
-
delete: requireRoles(['admin']),
|
|
166
|
-
},
|
|
167
|
-
});
|
|
168
|
-
```
|
|
169
|
-
For mixed human + service: `anyOf(requireOrgRole('admin'), requireServiceScope('jobs:bulk-write'))`.
|
|
170
|
-
|
|
171
|
-
---
|
|
172
|
-
|
|
173
|
-
## §5. Manual `toJSON` transforms / response field stripping 🔴
|
|
174
|
-
|
|
175
|
-
**Detection:**
|
|
176
|
-
```
|
|
177
|
-
pattern: "schema\\.set\\(['\"]toJSON['\"]|toJSON\\s*=\\s*function|delete\\s+(ret|obj|doc)\\.(password|__v|secret)"
|
|
178
|
-
output_mode: content
|
|
179
|
-
```
|
|
180
|
-
Also: `onSerialization` Fastify hook bodies that delete fields.
|
|
181
|
-
|
|
182
|
-
**Anti-pattern:**
|
|
183
|
-
```typescript
|
|
184
|
-
userSchema.set('toJSON', {
|
|
185
|
-
transform: (_doc, ret) => {
|
|
186
|
-
delete ret.password;
|
|
187
|
-
delete ret.__v;
|
|
188
|
-
delete ret.secretToken;
|
|
189
|
-
return ret;
|
|
190
|
-
},
|
|
191
|
-
});
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
**Why critical:** Easy to forget on a new field; password leaks happen this way. Also breaks lean reads (the transform doesn't fire on `.lean()` results).
|
|
195
|
-
|
|
196
|
-
**Fix:** `fieldRules.hidden` (or field-level read permission) — applies at framework serialization for both REST and MCP, and works with lean reads:
|
|
197
|
-
```typescript
|
|
198
|
-
import { fields } from '@classytic/arc';
|
|
199
|
-
|
|
200
|
-
defineResource({
|
|
201
|
-
schemaOptions: {
|
|
202
|
-
fieldRules: {
|
|
203
|
-
password: { hidden: true },
|
|
204
|
-
__v: { hidden: true },
|
|
205
|
-
secretToken: { hidden: true },
|
|
206
|
-
salary: fields.visibleTo(['admin', 'hr']),
|
|
207
|
-
email: fields.redactFor(['viewer'], '***'),
|
|
208
|
-
},
|
|
209
|
-
},
|
|
210
|
-
});
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
---
|
|
214
|
-
|
|
215
|
-
## §6. Hand-maintained OpenAPI / Swagger 🟡
|
|
216
|
-
|
|
217
|
-
**Detection:**
|
|
218
|
-
- Files: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json`, `api-spec.*` checked into the repo.
|
|
219
|
-
- `@fastify/swagger` registered with hand-written `swagger.definitions`.
|
|
220
|
-
|
|
221
|
-
**Why medium:** Spec drifts from code; consumers integrate against stale docs.
|
|
222
|
-
|
|
223
|
-
**Fix:** `arc docs ./openapi.json --entry ./dist/index.js` — emits OpenAPI from registered resources. Wire into `prebuild` or CI.
|
|
224
|
-
```typescript
|
|
225
|
-
import { SpecGenerator } from '@classytic/arc/docs';
|
|
226
|
-
const spec = await app.arc.docs.getSpec({ title: 'My API', version: '1.0.0' });
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## §7. Manual event emission 🟠
|
|
232
|
-
|
|
233
|
-
**Detection:**
|
|
234
|
-
```
|
|
235
|
-
pattern: "(eventBus|emitter|events|pubsub)\\.(emit|publish)\\(['\"](\\w+)\\.(created|updated|deleted)"
|
|
236
|
-
output_mode: content
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
**Anti-pattern:**
|
|
240
|
-
```typescript
|
|
241
|
-
const product = await Product.create(req.body);
|
|
242
|
-
await eventBus.emit('product.created', { id: product._id });
|
|
243
|
-
// ... and somebody forgets it on PATCH
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
**Why high:** Inconsistent emission breaks downstream consumers (search index, audit log, cache invalidation). Test coverage rarely catches missing emits.
|
|
247
|
-
|
|
248
|
-
**Fix:** Arc auto-emits `{resource}.created` / `.updated` / `.deleted` on every CRUD. Custom events go through hooks:
|
|
249
|
-
```typescript
|
|
250
|
-
defineResource({
|
|
251
|
-
name: 'product',
|
|
252
|
-
events: {
|
|
253
|
-
created: { description: 'Product created' },
|
|
254
|
-
priceChanged: { description: 'Price updated', schema: { oldPrice, newPrice } },
|
|
255
|
-
},
|
|
256
|
-
hooks: {
|
|
257
|
-
afterUpdate: async (ctx) => {
|
|
258
|
-
if (ctx.data.price !== ctx.meta?.existing?.price) {
|
|
259
|
-
await ctx.fastify.events.publish('product.priceChanged', {
|
|
260
|
-
id: ctx.data._id,
|
|
261
|
-
oldPrice: ctx.meta.existing.price,
|
|
262
|
-
newPrice: ctx.data.price,
|
|
263
|
-
});
|
|
264
|
-
}
|
|
265
|
-
},
|
|
266
|
-
},
|
|
267
|
-
});
|
|
268
|
-
```
|
|
269
|
-
For guaranteed delivery, use `EventOutbox` (transactional outbox pattern).
|
|
270
|
-
|
|
271
|
-
---
|
|
272
|
-
|
|
273
|
-
## §8. Manual cache invalidation 🟡
|
|
274
|
-
|
|
275
|
-
**Detection:**
|
|
276
|
-
```
|
|
277
|
-
pattern: "(redis|cache)\\.(del|invalidate|set)\\(['\"](\\w+)[-:_]"
|
|
278
|
-
output_mode: content
|
|
279
|
-
```
|
|
280
|
-
Also: hand-rolled cache key strings.
|
|
281
|
-
|
|
282
|
-
**Anti-pattern:**
|
|
283
|
-
```typescript
|
|
284
|
-
const product = await Product.create(req.body);
|
|
285
|
-
await cache.del(`product-${product._id}`);
|
|
286
|
-
await cache.del('products-list'); // forgot the org-scoped key
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
**Fix:** Arc's `QueryCache` invalidates by tag on every mutation. Enable via `arcPlugins.queryCache: true` and declare tags per resource:
|
|
290
|
-
```typescript
|
|
291
|
-
defineResource({
|
|
292
|
-
cache: {
|
|
293
|
-
staleTime: 30,
|
|
294
|
-
gcTime: 300,
|
|
295
|
-
tags: ['catalog'],
|
|
296
|
-
invalidateOn: { 'category.*': ['catalog'] }, // cross-resource
|
|
297
|
-
},
|
|
298
|
-
});
|
|
299
|
-
```
|
|
300
|
-
Modes: `memory` (default) / `distributed` (requires `stores.queryCache: RedisCacheStore`). Response header: `x-cache: HIT | STALE | MISS`.
|
|
301
|
-
|
|
302
|
-
---
|
|
303
|
-
|
|
304
|
-
## §9. Bypassing RequestScope 🔴
|
|
305
|
-
|
|
306
|
-
**Detection:**
|
|
307
|
-
```
|
|
308
|
-
pattern: "req(uest)?\\.user\\.(_id|id|orgId|organizationId|tenantId|parentOrgId|teamId)"
|
|
309
|
-
output_mode: content
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
**Anti-pattern:**
|
|
313
|
-
```typescript
|
|
314
|
-
const userId = req.user._id; // crashes on public route
|
|
315
|
-
const orgId = req.user.orgId; // undefined for service tokens
|
|
316
|
-
const parent = req.user.parentOrgId; // not real — fragile custom field
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
**Why critical:**
|
|
320
|
-
- Crashes on public routes (`request.user` is `Record<string, unknown> | undefined`).
|
|
321
|
-
- Doesn't differentiate `member` vs `service` vs `elevated` scope kinds.
|
|
322
|
-
- Org hierarchy not honored (no ancestor lookup).
|
|
323
|
-
- Inconsistent across routes.
|
|
324
|
-
|
|
325
|
-
**Fix:** Always use accessors from `@classytic/arc/scope`:
|
|
326
|
-
```typescript
|
|
327
|
-
import {
|
|
328
|
-
getUserId, getOrgId, getOrgRoles, getServiceScopes,
|
|
329
|
-
getScopeContext, getAncestorOrgIds,
|
|
330
|
-
isMember, isService, isElevated, isAuthenticated, hasOrgAccess,
|
|
331
|
-
isOrgInScope,
|
|
332
|
-
} from '@classytic/arc/scope';
|
|
333
|
-
|
|
334
|
-
if (!isAuthenticated(req.scope)) return reply.unauthorized();
|
|
335
|
-
const userId = getUserId(req.scope); // typed, undefined-safe
|
|
336
|
-
const orgId = getOrgId(req.scope);
|
|
337
|
-
const branch = getScopeContext(req.scope, 'branchId');
|
|
338
|
-
const inOrg = isOrgInScope(req.scope, 'acme-eu');
|
|
339
|
-
```
|
|
340
|
-
For permissions, prefer combinators (`requireOrgRole`, `requireScopeContext`, `requireOrgInScope`) over accessor logic in handlers.
|
|
341
|
-
|
|
342
|
-
---
|
|
343
|
-
|
|
344
|
-
## §10. Mongoose/Prisma imports outside adapters 🟠
|
|
345
|
-
|
|
346
|
-
**Detection:**
|
|
347
|
-
```
|
|
348
|
-
pattern: "^import\\s+.*\\b(mongoose|@prisma/client|drizzle-orm)\\b"
|
|
349
|
-
glob: "src/**/*.{ts,js}"
|
|
350
|
-
output_mode: content
|
|
351
|
-
```
|
|
352
|
-
Then exclude allowed paths: `src/**/adapter*.ts` (host-side adapter file), `src/db/**` (depending on convention), and `src/**/*.model.ts` (model definition is OK).
|
|
353
|
-
|
|
354
|
-
**Anti-pattern:** `import mongoose from 'mongoose'` in `src/services/`, `src/hooks/`, `src/routes/`, or any `.resource.ts`.
|
|
355
|
-
|
|
356
|
-
**Why high:** Defeats arc's DB-agnostic boundary. Forces every consumer of that file to pull a database driver. Migration to a different DB becomes a multi-thousand-LOC rewrite instead of swapping one adapter file.
|
|
357
|
-
|
|
358
|
-
**Fix:** Mongoose calls go in:
|
|
359
|
-
1. `*.model.ts` — schema definition only.
|
|
360
|
-
2. `*.repository.ts` — extends `Repository<TDoc>` from `@classytic/mongokit` (or implements `MinimalRepo`).
|
|
361
|
-
3. `*.adapter.ts` — `createMongooseAdapter({ model, repository })`.
|
|
362
|
-
|
|
363
|
-
Resources, hooks, and services consume `RepositoryLike<TDoc>` — never the model directly.
|
|
364
|
-
|
|
365
|
-
---
|
|
366
|
-
|
|
367
|
-
## §11. `console.log` in `src/` 🟢
|
|
368
|
-
|
|
369
|
-
**Detection:**
|
|
370
|
-
```
|
|
371
|
-
pattern: "console\\.(log|warn|error|info|debug)\\("
|
|
372
|
-
glob: "src/**/*.{ts,js}"
|
|
373
|
-
output_mode: content
|
|
374
|
-
```
|
|
375
|
-
Allowed: `src/cli/**`, scripts, examples.
|
|
376
|
-
|
|
377
|
-
**Fix:** Use Fastify's logger via `request.log` / `app.log`, or arc's logger if exposed.
|
|
378
|
-
|
|
379
|
-
---
|
|
380
|
-
|
|
381
|
-
## §12. `any` and `@ts-ignore` 🟢
|
|
382
|
-
|
|
383
|
-
**Detection:**
|
|
384
|
-
```
|
|
385
|
-
pattern: ":\\s*any\\b|<any>|as\\s+any\\b|@ts-ignore|@ts-expect-error"
|
|
386
|
-
glob: "src/**/*.ts"
|
|
387
|
-
```
|
|
388
|
-
|
|
389
|
-
**Fix:** Use `unknown` + type narrowing. `as unknown as X` is a last resort, not a shortcut. Never `@ts-ignore` — fix the type. For repo casts, prefer `RepositoryLike<TDoc>` from `@classytic/arc`.
|
|
390
|
-
|
|
391
|
-
---
|
|
392
|
-
|
|
393
|
-
## §13. Default exports 🟢
|
|
394
|
-
|
|
395
|
-
**Detection:**
|
|
396
|
-
```
|
|
397
|
-
pattern: "^export\\s+default\\b"
|
|
398
|
-
glob: "src/**/*.ts"
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
**Fix:** Named exports only. `export const productResource = defineResource({...})`. Knip enforces in arc itself; client projects should follow.
|
|
402
|
-
|
|
403
|
-
**Exception:** `*.resource.ts` files used by `loadResources()` may use `export default` because the loader recognizes both `default` export AND `export const resource`. Prefer named for grep-ability.
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
## §14. Reimplementing presets manually 🟡
|
|
408
|
-
|
|
409
|
-
**Detection:** Look for handler names + route paths that match preset signatures:
|
|
410
|
-
|
|
411
|
-
| Preset | Handler / route fingerprint |
|
|
412
|
-
|---|---|
|
|
413
|
-
| `softDelete` | `getDeleted`, `restore`, `GET /deleted`, `POST /:id/restore`, field `deletedAt` with manual filtering on every read |
|
|
414
|
-
| `slugLookup` | `getBySlug`, `GET /slug/:slug`, `GET /by-slug/:slug` |
|
|
415
|
-
| `tree` | `getChildren`, `getTree`, `GET /tree`, `GET /:id/children`, manual `parentId` field |
|
|
416
|
-
| `bulk` | `bulkCreate`, `bulkUpdate`, `bulkDelete`, `POST /bulk`, `PATCH /bulk`, `DELETE /bulk` |
|
|
417
|
-
| `multiTenant` | Every find call appended with `organizationId: req.user.orgId` |
|
|
418
|
-
| `ownedByUser` | Every find call appended with `userId: req.user.id` |
|
|
419
|
-
| `audited` | Manual write to an audit collection on every mutation |
|
|
420
|
-
| `filesUpload` | `multer`, `@fastify/multipart` ad-hoc routes per resource |
|
|
421
|
-
| `search` | `POST /search`, `/search-similar`, `/embed` hand-rolled |
|
|
422
|
-
|
|
423
|
-
**Fix:**
|
|
424
|
-
```typescript
|
|
425
|
-
defineResource({
|
|
426
|
-
presets: [
|
|
427
|
-
'softDelete',
|
|
428
|
-
{ name: 'multiTenant', tenantField: 'organizationId' },
|
|
429
|
-
{ name: 'slugLookup', slugField: 'slug' },
|
|
430
|
-
'bulk',
|
|
431
|
-
{ name: 'filesUpload', storage: s3Storage, allowedMimeTypes: ['image/*'] },
|
|
432
|
-
],
|
|
433
|
-
});
|
|
434
|
-
```
|
|
435
|
-
Multi-level tenancy (branch/project/region) — use `multiTenantPreset({ tenantFields: TenantFieldSpec[] })`.
|
|
436
|
-
|
|
437
|
-
---
|
|
438
|
-
|
|
439
|
-
## §15. Hand-written MCP tools 🟡
|
|
440
|
-
|
|
441
|
-
**Detection:**
|
|
442
|
-
```
|
|
443
|
-
pattern: "CallToolRequestSchema|setRequestHandler\\(\\s*Call|inputSchema\\s*:\\s*\\{\\s*type\\s*:\\s*['\"]object"
|
|
444
|
-
output_mode: content
|
|
445
|
-
```
|
|
446
|
-
Or: a file pattern of `tools.ts`/`mcp.ts` defining `name`, `description`, `inputSchema`, `handler` objects manually.
|
|
447
|
-
|
|
448
|
-
**Fix:** Resources auto-generate MCP tools (5 CRUD + custom routes + actions). Permissions and field rules carry over.
|
|
449
|
-
```typescript
|
|
450
|
-
import { mcpPlugin } from '@classytic/arc/mcp';
|
|
451
|
-
|
|
452
|
-
await app.register(mcpPlugin, {
|
|
453
|
-
resources: [productResource, orderResource],
|
|
454
|
-
auth: false, // or getAuth() / custom
|
|
455
|
-
exclude: ['credential'],
|
|
456
|
-
overrides: { product: { operations: ['list', 'get'] } },
|
|
457
|
-
});
|
|
458
|
-
```
|
|
459
|
-
For domain-specific tools, use `extraTools` + `buildMcpToolsFromBridges([...])` instead of hand-rolling MCP server plumbing.
|
|
460
|
-
|
|
461
|
-
---
|
|
462
|
-
|
|
463
|
-
## §16. Custom search routes / query language 🟡
|
|
464
|
-
|
|
465
|
-
**Detection:** `GET /search`, `GET /:resource/search`, `/find`, `/lookup` with custom param parsing.
|
|
466
|
-
|
|
467
|
-
**Fix:** Either use arc's standard `QueryParser` syntax (`?search=...&filter=...`), or `searchPreset` for full-text/vector backends:
|
|
468
|
-
```typescript
|
|
469
|
-
import { searchPreset } from '@classytic/arc/presets/search';
|
|
470
|
-
|
|
471
|
-
defineResource({
|
|
472
|
-
presets: [searchPreset({
|
|
473
|
-
search: { handler: (req) => elastic.search({ index: 'products', q: req.body.q }) },
|
|
474
|
-
similar: { handler: (req) => pinecone.query({ vector: req.body.vector, topK: 10 }) },
|
|
475
|
-
})],
|
|
476
|
-
});
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
---
|
|
480
|
-
|
|
481
|
-
## §17. `request.user` access without guard on public routes 🔴
|
|
482
|
-
|
|
483
|
-
**Detection:**
|
|
484
|
-
```
|
|
485
|
-
pattern: "(req|request)\\.user\\.\\w+"
|
|
486
|
-
output_mode: content
|
|
487
|
-
```
|
|
488
|
-
Then for each hit, check whether the enclosing route is `allowPublic()` or has no `permissions`. Crashes happen on public routes.
|
|
489
|
-
|
|
490
|
-
**Fix:** Always guard:
|
|
491
|
-
```typescript
|
|
492
|
-
if (req.user) {
|
|
493
|
-
const userId = req.user.id;
|
|
494
|
-
// ...
|
|
495
|
-
}
|
|
496
|
-
// or: use scope accessors which return undefined safely
|
|
497
|
-
```
|
|
498
|
-
Arc rule: `request.user: Record<string, unknown> | undefined`. The property is required (not optional `?:`), but the value is union-with-undefined.
|
|
499
|
-
|
|
500
|
-
---
|
|
501
|
-
|
|
502
|
-
## §18. Custom controller without forwarding `tenantField`/`schemaOptions`/`idField` 🟠
|
|
503
|
-
|
|
504
|
-
**Detection:** A `class FooController extends BaseController` where the constructor doesn't forward `tenantField`, `idField`, `schemaOptions`, `cache`, `onFieldWriteDenied`.
|
|
505
|
-
|
|
506
|
-
**Why:** When you pass your own controller to `defineResource({ controller })`, arc CANNOT thread these into it. They must be forwarded through `super(repo, opts)` AND mirrored on the `defineResource` call.
|
|
507
|
-
|
|
508
|
-
**Fix:**
|
|
509
|
-
```typescript
|
|
510
|
-
class ProductController extends BaseController<Product> {
|
|
511
|
-
constructor(opts: { tenantField?: string | false; idField?: string } = {}) {
|
|
512
|
-
super(productRepo, { resourceName: 'product', ...opts });
|
|
513
|
-
}
|
|
514
|
-
}
|
|
515
|
-
|
|
516
|
-
defineResource({
|
|
517
|
-
name: 'product',
|
|
518
|
-
controller: new ProductController({ tenantField: 'organizationId', idField: '_id' }),
|
|
519
|
-
tenantField: 'organizationId', // mirror!
|
|
520
|
-
idField: '_id', // mirror!
|
|
521
|
-
});
|
|
522
|
-
```
|
|
523
|
-
Or skip the custom controller entirely — arc's auto-built `BaseController` handles 90% of cases. Use `BaseCrudController` + `SoftDeleteMixin`/`BulkMixin`/etc. for slim CRUD-only.
|
|
524
|
-
|
|
525
|
-
---
|
|
526
|
-
|
|
527
|
-
## §19. `tenantField` left at default for company-wide tables 🟠
|
|
528
|
-
|
|
529
|
-
**Detection:** Resources for lookup tables, platform settings, or cross-org reports that don't set `tenantField: false`.
|
|
530
|
-
|
|
531
|
-
**Why:** Default `tenantField: 'organizationId'` silently scopes queries to caller's org. For an `account-type` lookup table or `currency` table, this returns empty results forever.
|
|
532
|
-
|
|
533
|
-
**Fix:**
|
|
534
|
-
```typescript
|
|
535
|
-
defineResource({ name: 'account-type', tenantField: false }); // company-wide
|
|
536
|
-
defineResource({ name: 'workspace-item', tenantField: 'workspaceId' }); // different scope
|
|
537
|
-
```
|
|
538
|
-
|
|
539
|
-
---
|
|
540
|
-
|
|
541
|
-
## §20. Wrong lifecycle slot for async-booted engines 🟠
|
|
542
|
-
|
|
543
|
-
**Detection:** A resource adapter that depends on an engine initialized inside the same module (e.g., `await ensureCatalogEngine()`) is exported as a static `defineResource()` at module top — which runs before `bootstrap[]`.
|
|
544
|
-
|
|
545
|
-
**Anti-pattern:**
|
|
546
|
-
```typescript
|
|
547
|
-
// product.resource.ts — runs at IMPORT time, before bootstrap
|
|
548
|
-
const engine = await ensureCatalogEngine(); // top-level await
|
|
549
|
-
export const productResource = defineResource({ adapter: engine.adapter() });
|
|
550
|
-
```
|
|
551
|
-
|
|
552
|
-
**Fix:** Use the factory form for `resources` so it runs *after* `bootstrap[]`:
|
|
553
|
-
```typescript
|
|
554
|
-
const app = await createApp({
|
|
555
|
-
bootstrap: [async () => { await ensureCatalogEngine(); }],
|
|
556
|
-
resources: async () => {
|
|
557
|
-
const engine = await getCatalogEngine();
|
|
558
|
-
return [buildProductResource(engine), buildCategoryResource(engine)];
|
|
559
|
-
},
|
|
560
|
-
});
|
|
561
|
-
```
|
|
562
|
-
Or via `loadResources` with `context`:
|
|
563
|
-
```typescript
|
|
564
|
-
resources: async () => loadResources(import.meta.url, { context: { engine } }),
|
|
565
|
-
// Each *.resource.ts then exports: (ctx) => defineResource({ adapter: ctx.engine.adapter() })
|
|
566
|
-
```
|
|
567
|
-
|
|
568
|
-
For the DB **connection** itself (as opposed to engines), arc 2.21 adds `createApp({ beforeBoot: async () => connectDatabase() })` — awaited before Fastify exists, before module thunks resolve, and before any resource file imports. A composition root that connects the DB then dynamic-imports the app to control evaluation order is the pre-2.21 workaround; flag it and move the connect into `beforeBoot`.
|
|
569
|
-
|
|
570
|
-
---
|
|
571
|
-
|
|
572
|
-
## §21. Field-write denied as silent strip when reject is needed (or vice versa) 🟡
|
|
573
|
-
|
|
574
|
-
**Detection:** Resources with sensitive fields (`role`, `permissions`, `tenantId`, `organizationId`) that don't declare `onFieldWriteDenied`. Default is `reject` (403 with denied list) — usually correct. If client set `'strip'`, sensitive denied writes silently disappear.
|
|
575
|
-
|
|
576
|
-
**Fix:** Explicit choice per resource:
|
|
577
|
-
```typescript
|
|
578
|
-
defineResource({ onFieldWriteDenied: 'reject' }); // default — explicit
|
|
579
|
-
defineResource({ onFieldWriteDenied: 'strip' }); // only for low-stakes UX flows
|
|
580
|
-
```
|
|
581
|
-
Tests should assert 403 on protected-field write attempts.
|
|
582
|
-
|
|
583
|
-
---
|
|
584
|
-
|
|
585
|
-
## §22. Manual idempotency 🟠
|
|
586
|
-
|
|
587
|
-
**Detection:** Hand-rolled deduplication via `Idempotency-Key` header reads, custom Redis/Mongo lookup, retry tables.
|
|
588
|
-
|
|
589
|
-
**Fix:** Arc ships `idempotencyPlugin`:
|
|
590
|
-
```typescript
|
|
591
|
-
import { idempotencyPlugin } from '@classytic/arc/idempotency';
|
|
592
|
-
await app.register(idempotencyPlugin, { repository: idempotencyRepo, ttlMs: 24 * 3600_000 });
|
|
593
|
-
```
|
|
594
|
-
Requires `getOne`, `deleteMany`, `findOneAndUpdate` on the repo (mongokit + sqlitekit conform).
|
|
595
|
-
|
|
596
|
-
---
|
|
597
|
-
|
|
598
|
-
## §23. Manual audit log 🟡
|
|
599
|
-
|
|
600
|
-
**Detection:** Every mutation handler appends to an `audit_logs` / `events` / `history` collection inline.
|
|
601
|
-
|
|
602
|
-
**Fix:** Per-resource opt-in via `auditPlugin`:
|
|
603
|
-
```typescript
|
|
604
|
-
await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
|
|
605
|
-
defineResource({ name: 'order', audit: true });
|
|
606
|
-
defineResource({ name: 'payment', audit: { operations: ['delete'] } });
|
|
607
|
-
```
|
|
608
|
-
Or `presets: ['audited']`.
|
|
609
|
-
|
|
610
|
-
---
|
|
611
|
-
|
|
612
|
-
## §24. Manual rate limiting per route 🟡
|
|
613
|
-
|
|
614
|
-
**Detection:** `@fastify/rate-limit` registered per-route with hand-tuned configs.
|
|
615
|
-
|
|
616
|
-
**Fix:** Per-resource `rateLimit: RateLimitConfig` on `defineResource`, or global at `createApp({ rateLimit })`.
|
|
617
|
-
|
|
618
|
-
---
|
|
619
|
-
|
|
620
|
-
## §25. Webhook signature verification on parsed body 🔴
|
|
621
|
-
|
|
622
|
-
**Detection:**
|
|
623
|
-
```
|
|
624
|
-
pattern: "verifySignature\\(.*req\\.body"
|
|
625
|
-
output_mode: content
|
|
626
|
-
```
|
|
627
|
-
|
|
628
|
-
**Why critical:** `verifySignature(body, ...)` throws `TypeError` if body isn't string/Buffer. Parsed body silently fails verification → forged webhooks accepted.
|
|
629
|
-
|
|
630
|
-
**Fix:** `verifySignature(req.rawBody, ...)`. Declare webhook routes via `rawHandler` and ensure `@fastify/raw-body` is registered (arc registers it automatically when needed).
|
|
631
|
-
|
|
632
|
-
---
|
|
633
|
-
|
|
634
|
-
## §26. Multipart/file upload handled with multer or ad-hoc parsing 🟡
|
|
635
|
-
|
|
636
|
-
**Detection:** `multer`, `formidable`, `busboy` used directly; or `req.body` consumed without `multipartBody` middleware.
|
|
637
|
-
|
|
638
|
-
**Fix:**
|
|
639
|
-
```typescript
|
|
640
|
-
import { multipartBody } from '@classytic/arc/middleware';
|
|
641
|
-
defineResource({
|
|
642
|
-
middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5 * 1024 * 1024 })] },
|
|
643
|
-
});
|
|
644
|
-
```
|
|
645
|
-
Or `presets: [{ name: 'filesUpload', storage, allowedMimeTypes, maxFileSize }]`.
|
|
646
|
-
`multipartBody()` is a no-op for JSON requests — safe to always add to create/update.
|
|
647
|
-
|
|
648
|
-
---
|
|
649
|
-
|
|
650
|
-
## §27. SSE auth via query string without `preAuth` 🔴
|
|
651
|
-
|
|
652
|
-
**Detection:** SSE/EventSource routes that read `req.query.token` and call `verify()` inline.
|
|
653
|
-
|
|
654
|
-
**Fix:** EventSource can't set headers, so arc's `preAuth` slot copies `?token=` into the `Authorization` header before auth runs:
|
|
655
|
-
```typescript
|
|
656
|
-
routes: [
|
|
657
|
-
{
|
|
658
|
-
method: 'GET', path: '/stream',
|
|
659
|
-
preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }],
|
|
660
|
-
permissions: requireAuth(),
|
|
661
|
-
rawHandler: async (req, reply) => reply.send(stream),
|
|
662
|
-
},
|
|
663
|
-
],
|
|
664
|
-
```
|
|
665
|
-
|
|
666
|
-
---
|
|
667
|
-
|
|
668
|
-
## §28. Mongoose without mongokit 🟠
|
|
669
|
-
|
|
670
|
-
**Detection:** `package.json` has `mongoose` but not `@classytic/mongokit`. Or `import { Schema, model } from 'mongoose'` paired with hand-rolled repository classes (`class FooRepository`).
|
|
671
|
-
|
|
672
|
-
**Why high:** Every Mongoose model + repo class is duplicating mongokit's hook engine, plugin system, pagination, multi-tenant scoping, soft-delete, audit trail, transaction helpers. A 150 LOC repo class typically reduces to ~30 LOC with mongokit.
|
|
673
|
-
|
|
674
|
-
**Fix:** Full migration recipe → [mongokit-migration.md](mongokit-migration.md).
|
|
675
|
-
|
|
676
|
-
---
|
|
677
|
-
|
|
678
|
-
## §29. `app.register(authPlugin)` instead of `createApp({ auth })` 🟢
|
|
679
|
-
|
|
680
|
-
**Detection:** Manual JWT plugin registration with `@fastify/jwt`, hand-rolled `app.authenticate` decorator.
|
|
681
|
-
|
|
682
|
-
**Fix:** `createApp({ auth: { type: 'jwt', jwt: { secret, ... } } })` decorates `app.authenticate`, `app.optionalAuthenticate`, `app.authorize` and wires permission checks. For Better Auth, `createApp({ auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth, orgContext: true }) } })`.
|
|
683
|
-
|
|
684
|
-
---
|
|
685
|
-
|
|
686
|
-
## §30. Missing `arc-discovered` resources because of tsconfig path aliases 🟢
|
|
687
|
-
|
|
688
|
-
**Detection:** Resources defined under `import.meta.url`-discovered directories don't appear in routes; resource files import other resource files via `@/foo` aliases.
|
|
689
|
-
|
|
690
|
-
**Why:** `loadResources()` uses Node's resolver. `@/*` path aliases are compile-time only, not Node-resolvable. Auto-discovery silently misses these files.
|
|
691
|
-
|
|
692
|
-
**Fix:** Use relative imports OR Node's `#` subpath imports (`"imports": { "#foo/*": "./src/foo/*.js" }` in `package.json`) for files that participate in `loadResources`. Path aliases work fine for type-only imports.
|
|
693
|
-
|
|
694
|
-
---
|
|
695
|
-
|
|
696
|
-
## §31. `select` field manipulated client-side 🟢
|
|
697
|
-
|
|
698
|
-
**Detection:** Code post-processing `select` value from query (normalizing case, splitting, building projection objects).
|
|
699
|
-
|
|
700
|
-
**Why:** Arc preserves `select` as-is for DB-agnosticism (Mongo `'name email'` vs SQL `['name', 'email']`). Client normalization is wasted work and divergent across resources.
|
|
701
|
-
|
|
702
|
-
**Fix:** Pass through. The repository / adapter handles its native shape.
|
|
703
|
-
|
|
704
|
-
---
|
|
705
|
-
|
|
706
|
-
## §32a. Importing pagination types from primitives or mongokit 🟠
|
|
707
|
-
|
|
708
|
-
**Detection:**
|
|
709
|
-
```
|
|
710
|
-
pattern: "from\\s+['\"]@classytic/(primitives/pagination|mongokit)['\"][^\\n]*\\b(OffsetPaginationResult|KeysetPaginationResult|AggregatePaginationResult|PaginationResult|toCanonicalList)\\b"
|
|
711
|
-
output_mode: content
|
|
712
|
-
```
|
|
713
|
-
Also `@classytic/arc-next/api` for `OffsetPaginationResponse` / `KeysetPaginationResponse` / `AggregatePaginationResponse` / `PaginatedResponse`.
|
|
714
|
-
|
|
715
|
-
**Why high:** Pagination types and the `toCanonicalList()` helper now live in `@classytic/repo-core/pagination` as the single source of truth (primitives' duplicate dropped, mongokit's local declarations dropped, arc-next's response types removed). Importing from any other package risks drift between the type the host believes and the one the kit actually returns.
|
|
716
|
-
|
|
717
|
-
**Fix:**
|
|
718
|
-
```typescript
|
|
719
|
-
import type {
|
|
720
|
-
OffsetPaginationResult, KeysetPaginationResult,
|
|
721
|
-
AggregatePaginationResult, PaginationResult,
|
|
722
|
-
} from '@classytic/repo-core/pagination';
|
|
723
|
-
import { toCanonicalList } from '@classytic/repo-core/pagination';
|
|
724
|
-
```
|
|
725
|
-
The wire envelope carries `method` ('offset' | 'keyset' | 'aggregate') as the discriminant; arc's `reply.sendList()` calls `toCanonicalList` internally.
|
|
726
|
-
|
|
727
|
-
---
|
|
728
|
-
|
|
729
|
-
## §32b. Importing event types from arc 🟠
|
|
730
|
-
|
|
731
|
-
**Detection:**
|
|
732
|
-
```
|
|
733
|
-
pattern: "from\\s+['\"]@classytic/arc/events['\"][^\\n]*\\b(EventMeta|DomainEvent|EventHandler|EventLogger|EventTransport|DeadLetteredEvent|PublishManyResult|createEvent|createChildEvent|matchEventPattern)\\b"
|
|
734
|
-
output_mode: content
|
|
735
|
-
```
|
|
736
|
-
|
|
737
|
-
**Why high:** Event types now live in `@classytic/primitives/events` as the single source of truth. Arc only re-exports the runtime `MemoryEventTransport`. Hosts importing event types from arc lock themselves to arc's version even when the type lives in primitives.
|
|
738
|
-
|
|
739
|
-
**Fix:**
|
|
740
|
-
```typescript
|
|
741
|
-
import type {
|
|
742
|
-
EventMeta, DomainEvent, EventHandler, EventLogger, EventTransport,
|
|
743
|
-
DeadLetteredEvent, PublishManyResult,
|
|
744
|
-
} from '@classytic/primitives/events';
|
|
745
|
-
import { createEvent, createChildEvent, matchEventPattern } from '@classytic/primitives/events';
|
|
746
|
-
import { MemoryEventTransport } from '@classytic/arc/events'; // runtime stays at arc
|
|
747
|
-
```
|
|
748
|
-
|
|
749
|
-
---
|
|
750
|
-
|
|
751
|
-
## §32c. Importing tenant config from primitives 🟡
|
|
752
|
-
|
|
753
|
-
**Detection:**
|
|
754
|
-
```
|
|
755
|
-
pattern: "from\\s+['\"]@classytic/primitives/tenant['\"]"
|
|
756
|
-
output_mode: content
|
|
757
|
-
```
|
|
758
|
-
|
|
759
|
-
**Why medium:** `TenantConfig`, `TenantStrategy`, `TenantFieldType`, `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig` now live in `@classytic/repo-core/tenant`. Mongokit and sqlitekit both `extends Pick<TenantConfig, ...>` from repo-core.
|
|
760
|
-
|
|
761
|
-
**Fix:**
|
|
762
|
-
```typescript
|
|
763
|
-
import type { TenantConfig, ResolvedTenantConfig } from '@classytic/repo-core/tenant';
|
|
764
|
-
import { resolveTenantConfig, DEFAULT_TENANT_CONFIG } from '@classytic/repo-core/tenant';
|
|
765
|
-
```
|
|
766
|
-
|
|
767
|
-
---
|
|
768
|
-
|
|
769
|
-
## §32d. Importing error types from primitives or mongokit 🟠
|
|
770
|
-
|
|
771
|
-
**Detection:**
|
|
772
|
-
```
|
|
773
|
-
pattern: "from\\s+['\"]@classytic/(primitives/errors|mongokit)['\"][^\\n]*\\bHttpError\\b"
|
|
774
|
-
output_mode: content
|
|
775
|
-
```
|
|
776
|
-
|
|
777
|
-
**Why high:** `HttpError` (throwable contract), `ErrorContract` (wire shape), `ErrorDetail`, `ErrorCode`, `ERROR_CODES`, `toErrorContract()`, `statusToErrorCode()` all live in `@classytic/repo-core/errors`. `ArcError implements HttpError` from repo-core. Mongokit no longer publishes its own `HttpError`.
|
|
778
|
-
|
|
779
|
-
**Fix:**
|
|
780
|
-
```typescript
|
|
781
|
-
import type { HttpError, ErrorContract, ErrorDetail, ErrorCode } from '@classytic/repo-core/errors';
|
|
782
|
-
import { toErrorContract, statusToErrorCode, ERROR_CODES } from '@classytic/repo-core/errors';
|
|
783
|
-
```
|
|
784
|
-
|
|
785
|
-
---
|
|
786
|
-
|
|
787
|
-
## §32e. Hand-rolled `if (!getOrgId(scope)) throw …` 🟡
|
|
788
|
-
|
|
789
|
-
**Detection:**
|
|
790
|
-
```
|
|
791
|
-
pattern: "if\\s*\\(\\s*!\\s*getOrgId\\s*\\("
|
|
792
|
-
output_mode: content
|
|
793
|
-
```
|
|
794
|
-
Also: `if (!getUserId(...))`, `if (!getClientId(...))`, `if (!getTeamId(...))` followed by a manual throw.
|
|
795
|
-
|
|
796
|
-
**Why medium:** Arc 2.12 ships `requireOrgId(scope, hint?)` / `requireUserId(scope, hint?)` / `requireClientId(scope, hint?)` / `requireTeamId(scope, hint?)` which return the value or throw a 403 `ArcError`. Hand-rolled guards usually throw a generic `Error` (wrong status), forget the optional hint, or duplicate the same boilerplate at every call site.
|
|
797
|
-
|
|
798
|
-
**Fix:**
|
|
799
|
-
```typescript
|
|
800
|
-
import { requireOrgId, requireUserId } from '@classytic/arc/scope';
|
|
801
|
-
|
|
802
|
-
const orgId = requireOrgId(scope); // throws 403 if missing
|
|
803
|
-
const userId = requireUserId(scope, 'finalize-checkout'); // hint surfaces in error.details
|
|
804
|
-
```
|
|
805
|
-
|
|
806
|
-
---
|
|
807
|
-
|
|
808
|
-
## §32f. Missing / dodged `schemaGenerator` 🟠
|
|
809
|
-
|
|
810
|
-
**Detection:**
|
|
811
|
-
```
|
|
812
|
-
pattern: "createMongooseAdapter\\s*\\(\\s*\\{[^}]*\\}\\s*\\)"
|
|
813
|
-
multiline: true
|
|
814
|
-
```
|
|
815
|
-
Then check the `schemaGenerator:` key — what to flag depends on the kit version:
|
|
816
|
-
|
|
817
|
-
- **mongokit >=3.21**: `schemaGenerator` DEFAULTS to `buildCrudSchemasFromModel` — omitting it is now correct. Flag the opposite: `schemaGenerator: false` used to dodge a wire-vs-model shape mismatch (minor-unit integers vs Money objects, enums, etc.). That opt-out silently kills OpenAPI bodies AND MCP tool input schemas for the whole resource. The right fix is a real wire contract: `customSchemas: { create: { body }, update: { body } }` with the generator ON — in arc 2.21 a custom part REPLACES the generated part wholesale (no `required[]` union), so wire and model shapes can differ cleanly.
|
|
818
|
-
- **mongokit <3.21**: omitted `schemaGenerator` emits `null` OpenAPI bodies (arc 2.12 deleted the built-in fallback). Fix: upgrade the kit, or wire `schemaGenerator: buildCrudSchemasFromModel` explicitly.
|
|
819
|
-
|
|
820
|
-
For drizzle: `createDrizzleAdapter` still wants `schemaGenerator: buildCrudSchemasFromTable` from `@classytic/sqlitekit` — check the kit's own version before flagging.
|
|
821
|
-
|
|
822
|
-
---
|
|
823
|
-
|
|
824
|
-
## §32g. Importing kit-specific adapters from `@classytic/arc` (any subpath) 🔴
|
|
825
|
-
|
|
826
|
-
**Detection:**
|
|
827
|
-
```
|
|
828
|
-
pattern: "from\\s+['\"]@classytic/arc(/adapters)?['\"][^\\n]*\\b(createMongooseAdapter|MongooseAdapter|createDrizzleAdapter|DrizzleAdapter|createPrismaAdapter|PrismaAdapter|PrismaQueryParser|InferMongooseDoc|MongooseDocument|isMongooseModel|MongooseAdapterOptions|DrizzleAdapterOptions|DrizzleColumnLike|DrizzleTableLike)\\b"
|
|
829
|
-
output_mode: content
|
|
830
|
-
```
|
|
831
|
-
|
|
832
|
-
Also: adapter contract types imported from arc — `import type { DataAdapter, AdapterRepositoryInput, AdapterFactory, OpenApiSchemas, SchemaMetadata, FieldMetadata, RelationMetadata, AdapterValidationResult, AdapterSchemaContext } from '@classytic/arc'` (any subpath). And: `mergeFieldRuleConstraints` from `@classytic/arc/adapters`. Any `from '@classytic/arc/adapters'` import — the entire subpath was removed in arc 2.12.
|
|
833
|
-
|
|
834
|
-
**Why critical:** `@classytic/arc/adapters` does not exist. Kit-specific adapters (Mongoose, Drizzle, Prisma) live in their kit; the cross-framework contract lives in `@classytic/repo-core/adapter`. Importing these names from arc fails to resolve — the build breaks at install time. The rule is **strict**: kit-specific things come from the kit, the contract comes from repo-core.
|
|
835
|
-
|
|
836
|
-
**Fix:**
|
|
837
|
-
```typescript
|
|
838
|
-
// Mongoose
|
|
839
|
-
import {
|
|
840
|
-
createMongooseAdapter, MongooseAdapter,
|
|
841
|
-
type MongooseAdapterOptions, type InferMongooseDoc,
|
|
842
|
-
type MongooseDocument, isMongooseModel,
|
|
843
|
-
} from '@classytic/mongokit/adapter';
|
|
844
|
-
|
|
845
|
-
// Drizzle
|
|
846
|
-
import {
|
|
847
|
-
createDrizzleAdapter, DrizzleAdapter,
|
|
848
|
-
type DrizzleAdapterOptions, type DrizzleColumnLike, type DrizzleTableLike,
|
|
849
|
-
} from '@classytic/sqlitekit/adapter';
|
|
850
|
-
|
|
851
|
-
// Prisma
|
|
852
|
-
import {
|
|
853
|
-
createPrismaAdapter, PrismaAdapter, PrismaQueryParser,
|
|
854
|
-
} from '@classytic/prismakit/adapter';
|
|
855
|
-
|
|
856
|
-
// Cross-framework adapter contract
|
|
857
|
-
import type {
|
|
858
|
-
DataAdapter, RepositoryLike, AdapterRepositoryInput,
|
|
859
|
-
AdapterFactory, AdapterValidationResult, AdapterSchemaContext,
|
|
860
|
-
OpenApiSchemas, SchemaMetadata, FieldMetadata, RelationMetadata,
|
|
861
|
-
} from '@classytic/repo-core/adapter';
|
|
862
|
-
import { asRepositoryLike, isRepository } from '@classytic/repo-core/adapter';
|
|
863
|
-
|
|
864
|
-
// Schema helpers
|
|
865
|
-
import { mergeFieldRuleConstraints, applyNullable } from '@classytic/repo-core/schema';
|
|
866
|
-
```
|
|
867
|
-
|
|
868
|
-
The `@classytic/arc/adapters` subpath has been **removed** in arc 2.12 — no symbols ship there anymore. `RepositoryLike` is re-exported from `@classytic/arc` for convenience, but importing from `@classytic/repo-core/adapter` is canonical. Custom kits implementing `DataAdapter<TDoc>` from `@classytic/repo-core/adapter` plug in identically.
|
|
869
|
-
|
|
870
|
-
---
|
|
871
|
-
|
|
872
|
-
## §32. Headers set in `onSend` hook 🔴
|
|
873
|
-
|
|
874
|
-
**Detection:**
|
|
875
|
-
```
|
|
876
|
-
pattern: "addHook\\(['\"]onSend"
|
|
877
|
-
output_mode: content
|
|
878
|
-
```
|
|
879
|
-
Then check whether the hook body sets headers (`reply.header(`, `reply.headers[`).
|
|
880
|
-
|
|
881
|
-
**Why critical:** Async `onSend` races with Fastify's `onSendEnd → safeWriteHead` flush path and produces `ERR_HTTP_HEADERS_SENT` under slow responses. Intermittent prod failures, hard to reproduce.
|
|
882
|
-
|
|
883
|
-
**Fix:** Set headers in `onRequest` (before handler) or `preSerialization` (before flush). Never `onSend`.
|
|
884
|
-
|
|
885
|
-
---
|
|
886
|
-
|
|
887
|
-
## §33. Hand-rolled aggregation routes when `aggregations: { … }` would do 🟠
|
|
888
|
-
|
|
889
|
-
**Detection:**
|
|
890
|
-
```
|
|
891
|
-
pattern: "Model\\.aggregate\\(\\["
|
|
892
|
-
output_mode: content
|
|
893
|
-
```
|
|
894
|
-
Also: `\\.aggregate\\(\\s*\\[`, `\\$group\\b`, `\\$match\\b` inside resource handler files. Plus inline mongoose pipeline imports inside route handlers (vs. inside the kit's repository).
|
|
895
|
-
|
|
896
|
-
**Anti-pattern:**
|
|
897
|
-
```typescript
|
|
898
|
-
// In a custom GET /aggregate/byPaymentMethod route:
|
|
899
|
-
const orgId = getOrgId(getScope(req));
|
|
900
|
-
const rows = await Transaction.aggregate([
|
|
901
|
-
{ $match: { organizationId: new mongoose.Types.ObjectId(orgId), status: 'verified' } },
|
|
902
|
-
{ $group: { _id: '$method', total: { $sum: '$amount' }, count: { $sum: 1 } } },
|
|
903
|
-
{ $sort: { total: -1 } },
|
|
904
|
-
]);
|
|
905
|
-
return reply.send({ rows });
|
|
906
|
-
```
|
|
907
|
-
|
|
908
|
-
**Why high:** loses every cross-cutting feature arc's aggregation router gives for free — per-aggregation permissions, OpenAPI schema, MCP tool export, SWR cache + tag invalidation, `requireFilters` / `requireDateRange` safety guards, `maxGroups` cap, multi-tenant scope without manual `ObjectId` casting. The hand-rolled version also drifts: every new bucket needs a new route, no central declaration, no unified shape across kits.
|
|
909
|
-
|
|
910
|
-
**Fix:** declare `aggregations: { name: defineAggregation({ groupBy, measures, sort, cache, permissions }) }` on the resource. Arc registers `GET /:prefix/aggregations/:name` per entry, threads `tenantOptions` to `repo.aggregate(req, options)`, and the kit's multi-tenant plugin handles type-coercion. Type-coercion (string → ObjectId / UUID / text) is **the kit's responsibility, not the framework's** — never inject the tenant key into `aggReq.filter` from arc-host code.
|
|
911
|
-
|
|
912
|
-
```typescript
|
|
913
|
-
import { defineAggregation } from '@classytic/arc';
|
|
914
|
-
|
|
915
|
-
aggregations: {
|
|
916
|
-
byPaymentMethod: defineAggregation({
|
|
917
|
-
groupBy: 'method',
|
|
918
|
-
measures: { total: 'sum:amount', count: 'count' },
|
|
919
|
-
sort: { total: -1 },
|
|
920
|
-
cache: { staleTime: 60, swr: true, tags: ['revenue'] },
|
|
921
|
-
permissions: canViewRevenue(),
|
|
922
|
-
}),
|
|
923
|
-
}
|
|
924
|
-
```
|
|
925
|
-
|
|
926
|
-
For backends without `repo.aggregate`, declare a `materialized` hook on the aggregation — the router calls it instead of the kit and keeps the same `{ rows }` envelope, permission gate, and cache contract.
|
|
927
|
-
|
|
928
|
-
---
|
|
929
|
-
|
|
930
|
-
## §34. `as never` / `as unknown as` casts on engine bags in module packages 🟠
|
|
931
|
-
|
|
932
|
-
**Detection:**
|
|
933
|
-
```
|
|
934
|
-
pattern: "as never|as unknown as"
|
|
935
|
-
```
|
|
936
|
-
Concentrated hits in `@classytic/arc-*` (or `@scope/arc-*`) module packages — especially around `defineResource(...)` assembly, adapter construction from an engine, or hand-rolled config spread-merges.
|
|
937
|
-
|
|
938
|
-
**Anti-pattern (pre-2.21 module-author tax):**
|
|
939
|
-
```typescript
|
|
940
|
-
interface EngineLike { models: Record<string, unknown>; repositories: Record<string, unknown> }
|
|
941
|
-
adapter: createMongooseAdapter(engine.models.Party as never, repo as never),
|
|
942
|
-
...(cfg.extraRoutes ? { routes: [...base.routes, ...cfg.extraRoutes] as never } : {}),
|
|
943
|
-
```
|
|
944
|
-
|
|
945
|
-
**Why high:** every cast is a hole where the kernel's real types (optional sub-module members, role unions, doc shapes) stop flowing — typos compile, wrong repos pair with wrong models, and hand-rolled spread-merges clobber host arrays.
|
|
946
|
-
|
|
947
|
-
**Fix (arc 2.21):** type the engine port with the KERNEL's own bags and assemble via `mergeResourceConfig`:
|
|
948
|
-
```typescript
|
|
949
|
-
import { mergeResourceConfig, type ResourceSeams, type AdapterLike } from '@classytic/arc';
|
|
950
|
-
|
|
951
|
-
interface CatalogEngineLike { // kernel is already a peer — no new coupling
|
|
952
|
-
models: CatalogEngine['models'];
|
|
953
|
-
repositories: CatalogEngine['repositories'];
|
|
954
|
-
}
|
|
955
|
-
defineResource(mergeResourceConfig(
|
|
956
|
-
{ name: 'product', adapter: createMongooseAdapter({ model: models.Product, repository: repositories.product }), ... },
|
|
957
|
-
hostSeams, // typed ResourceSeams — arrays concat, objects deep-merge,
|
|
958
|
-
)); // instances last-win, undefined never clobbers
|
|
959
|
-
```
|
|
960
|
-
Remaining honest boundaries (hydrated-vs-lean id widening at a kernel bridge, wire-body narrowing in action handlers) get a comment, not a blanket `as never`.
|
|
961
|
-
|
|
962
|
-
---
|
|
963
|
-
|
|
964
|
-
## §35. Hand-rolled recurring jobs (`setInterval` / cron + DB lock) 🟠
|
|
965
|
-
|
|
966
|
-
**Detection:**
|
|
967
|
-
```
|
|
968
|
-
pattern: "setInterval\\s*\\(|node-cron|cron\\.schedule|new CronJob"
|
|
969
|
-
```
|
|
970
|
-
Plus home-grown "job registry" / "leader lock" / "acquireLock" modules paired with timers.
|
|
971
|
-
|
|
972
|
-
**Why high:** every host regrows the same layer — overlap prevention, multi-replica leader lock, shutdown timer cleanup, failure counters — and gets at least one of them wrong (stacking `setInterval` runs, timers holding the process open, no lease recovery after a crashed leader).
|
|
973
|
-
|
|
974
|
-
**Fix (arc 2.21):** `schedulesPlugin` from `@classytic/arc/plugins` — interval jobs with no-overlap by construction (timeout chain), optional `lock` (any `LockAdapter`: `@classytic/mongokit/lock`, sqlitekit, memory) for multi-replica lease safety, `jitterMs`, `runOnStart`, `getScheduleStats()`, clean `onClose` drain. Calendar cron-expressions / durable retries stay in the BullMQ tier (`@classytic/arc/integrations/jobs`) — don't flag hosts that need real cron semantics for using it.
|
|
975
|
-
|
|
976
|
-
---
|
|
977
|
-
|
|
978
|
-
## §36. Wrong tenant config key — `{ field }` instead of `{ tenantField }` 🔴
|
|
979
|
-
|
|
980
|
-
**Detection:**
|
|
981
|
-
```
|
|
982
|
-
pattern: "tenant:\\s*\\{\\s*field\\s*:"
|
|
983
|
-
```
|
|
984
|
-
Also any object passed as tenant config whose keys aren't in repo-core's `TenantConfig`.
|
|
985
|
-
|
|
986
|
-
**Why critical:** unknown keys are **silently ignored** — `{ tenant: { field: 'branchId' } }` compiles (loose host types), the resource falls back to the default tenant field, and cross-tenant reads/writes go unscoped for hosts on a custom field name. Found live in published spine packages (arc-assets / arc-pricelist 0.1.x).
|
|
987
|
-
|
|
988
|
-
**Fix:** the key is `tenantField` (repo-core `TenantConfig`). In arc resources prefer the top-level `tenantField: 'branchId'` shorthand or the `multiTenant` preset; when passing a tenant object through a module seam, type it as `TenantConfig` so unknown keys fail the build.
|
|
989
|
-
|
|
990
|
-
---
|
|
991
|
-
|
|
992
|
-
## Detection checklist (run-order)
|
|
993
|
-
|
|
994
|
-
Run sweeps in this order — early hits often invalidate later context:
|
|
995
|
-
|
|
996
|
-
1. §10 — driver imports outside adapters (most architecturally significant)
|
|
997
|
-
2. §28 — mongoose without mongokit (scope of mongokit migration)
|
|
998
|
-
3. §3 — manual CRUD route count (scope of defineResource migration)
|
|
999
|
-
4. §4 + §9 + §17 — auth/scope (security-critical)
|
|
1000
|
-
5. §5 — toJSON / response stripping (security-critical)
|
|
1001
|
-
6. §25, §27, §32 — webhook/SSE/header gotchas (security-critical)
|
|
1002
|
-
7. §1, §2, §6, §16 — query/schema/openapi/search (style + drift)
|
|
1003
|
-
8. §7, §8, §22, §23 — events/cache/idempotency/audit (silent inconsistency)
|
|
1004
|
-
9. §14, §18, §19 — preset adoption + custom controller wiring
|
|
1005
|
-
10. §11, §12, §13, §29, §30, §31 — style and edges
|
|
1006
|
-
11. §32a–§32g — canonical-contract drift (pagination / events / tenant / errors / adapter imports), missing `requireOrgId` accessors, missing/dodged `schemaGenerator`, kit-specific adapter imports from arc (3.0 break)
|
|
1007
|
-
12. §33 — hand-rolled `Model.aggregate([...])` in resource routes vs declarative `aggregations: { … }`
|
|
1008
|
-
13. §36 — tenant config `{ field }` key (security: silent unscoped queries), then §34–§35 — module-package `as never` casts vs 2.21 seams; hand-rolled recurring jobs vs `schedulesPlugin`
|