@classytic/arc 2.45.2 → 2.47.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-DHb1tpu-.mjs → EventTransport-BHKy4_Bi.mjs} +5 -6
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-CAIDVoKC.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-23Ml6FNe.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-DoFX06fm.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-DXrlWHHK.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-DYiubkYw.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-CtdzpJ3X.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-CARdmPNo.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-QRiryDLs.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-BLecr1j3.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-Cx7BcnHT.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-0WyMuo0f.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-mLAGbpDV.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-BEAjn3dA.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-QDP4vYWH.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DzXHX0SO.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-CFNfvz-C.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.mjs → defineResource-BROJmhzJ.mjs} +80 -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-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- package/dist/{elevation-BJTsSnke.mjs → elevation-DrXeEWWk.mjs} +9 -10
- 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-BiBXtxj4.mjs} +16 -6
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{errors-grZkIA8N.mjs → errors-DnrUChAy.mjs} +2 -3
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-BhKLUe7H.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-CCIRGakw.mjs} +5 -8
- package/dist/events/index.d.mts +5 -17
- package/dist/events/index.mjs +9 -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-bzkWPt1f.d.mts} +4 -10
- package/dist/{fields-BRX0Krcj.mjs → fields-CYdpcV73.mjs} +2 -3
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-6kasezRH.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-DUkcbc4r.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-KxhrKevA.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-CRJg3IIq.mjs} +2 -3
- package/dist/{health-DyeP3mTW.mjs → health-jkYNdobJ.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/http-cache/index.d.mts +211 -0
- package/dist/http-cache/index.mjs +605 -0
- package/dist/http-cache/purgers/cloudflare.d.mts +13 -0
- package/dist/http-cache/purgers/cloudflare.mjs +46 -0
- package/dist/http-cache/purgers/fastly.d.mts +12 -0
- package/dist/http-cache/purgers/fastly.mjs +47 -0
- package/dist/http-cache/testing/index.d.mts +68 -0
- package/dist/http-cache/testing/index.mjs +168 -0
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +11 -14
- 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-BxZS-8So.d.mts} +67 -25
- package/dist/{index-WH7xgvxS.d.mts → index-Cy2-QffW.d.mts} +40 -92
- package/dist/{index-uhkUA5-U.d.mts → index-D1X_C_qz.d.mts} +13 -23
- package/dist/{index-CUJvoyw3.d.mts → index-DFCCQ9AE.d.mts} +2 -24
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-jC3rMPzb.mjs → init-CACwpktI.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 +5 -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-CzDBkCme.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-Cbwf6r1B.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Kr6vuljv.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-D2e0qoDR.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-C5bvCiAK.mjs → logger-C110X5Yz.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-4lIPr9OJ.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-D9qkhXiB.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.mjs → metrics-B-qrrWfI.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-BD8xHgrz.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-KZj8j1uJ.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-qU7KCn1l.mjs} +2 -3
- package/dist/observeSend-BnPtTotW.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.mjs → openapi-DoVa5SVP.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-5Mnwcycy.d.mts} +3 -9
- package/dist/outbox-module-DyITEIop.mjs +297 -0
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-B14c3OMp.mjs → permissions-BBy4bOGi.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-BOm2o4UA.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-DDIGwuxr.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.mjs → plugin-Bn4D_0XK.mjs} +156 -64
- 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-ClEjcKlG.mjs} +2 -3
- package/dist/policy.types-DPqToKG1.d.mts +50 -0
- 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-DK2jh5YR.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-BHH-sXyS.mjs} +3 -4
- package/dist/purger.types-2wNJK_89.mjs +24 -0
- package/dist/purger.types-DvPp4-yd.d.mts +26 -0
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-Ckqe98AM.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-CWAjlqcN.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.mjs → realtime-BIJi9USY.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-y9ZA-R_J.mjs} +7 -12
- package/dist/{outbox-module-B4FAkx3A.mjs → relay-BNrC1CEP.mjs} +8 -306
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CS43br5E.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-oZDzakGb.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-fWb_YaV2.mjs} +2 -3
- package/dist/{requirement-Cp_fsMDL.mjs → requirement--2hWyyHi.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-1WbcyMZY.mjs} +3 -4
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-yH2lHMo_.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-BSlRIA5c.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-CYCEtU1W.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-B5WGlYIT.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DtNvts-6.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-uS_RHqa3.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-BwVLSyNG.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-BJiJN7FT.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DGRLq-1k.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-B_50llZu.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-BjSo9Ult.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-D-n5cwy5.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-Dcgqa-hH.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-C9KhIXTF.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-COrhjPRZ.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BElWHytd.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-CaxKbRk_.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-8qKON0Nk.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-DVjVSsXO.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-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-DZHqOuJE.mjs} +5 -6
- package/dist/{types-D3Ixsh00.d.mts → types-DeLiuaNv.d.mts} +2 -4
- 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-_eGj6kf0.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-Dd6MWpye.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-BaF5wd0x.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.mjs → versioning-DyV7mwtK.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-CmCBUmPR.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +51 -22
- 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,84 @@
|
|
|
1
|
+
# WebSocket and event gateway
|
|
2
|
+
|
|
3
|
+
Peer: `@fastify/websocket`. Needs a persistent runtime (not serverless).
|
|
4
|
+
|
|
5
|
+
## websocketPlugin
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
import fastifyWebsocket from '@fastify/websocket';
|
|
9
|
+
import { websocketPlugin } from '@classytic/arc/integrations/websocket';
|
|
10
|
+
|
|
11
|
+
await app.register(fastifyWebsocket);
|
|
12
|
+
await app.register(websocketPlugin, {
|
|
13
|
+
path: '/ws',
|
|
14
|
+
auth: true, // default; fails at boot if no fastify.authenticate and no authenticate()
|
|
15
|
+
resources: ['product', 'order'], // auto-broadcast <resource>.created|updated|deleted to the room of that name
|
|
16
|
+
roomPolicy: (client, room) => ['product', 'order'].includes(room), // default allow all
|
|
17
|
+
authenticate: async (request) => ({ userId, organizationId }), // returns AuthResult | null
|
|
18
|
+
heartbeatInterval: 30000, // 0 disables
|
|
19
|
+
reauthInterval: 300000, // 0 disables; expired token closes with 4003
|
|
20
|
+
maxClientsPerRoom: 10000,
|
|
21
|
+
maxMessageBytes: 16384,
|
|
22
|
+
maxSubscriptionsPerClient: 100,
|
|
23
|
+
maxOutboundBytes: 5 * 1024 * 1024,
|
|
24
|
+
exposeStats: 'authenticated', // false (default) | true | 'authenticated'; route {path}/stats
|
|
25
|
+
onConnect, onDisconnect, onMessage,
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Org-scoped events (`meta.organizationId`) reach only clients of that org.
|
|
30
|
+
|
|
31
|
+
## Client protocol
|
|
32
|
+
|
|
33
|
+
| Direction | Message |
|
|
34
|
+
|---|---|
|
|
35
|
+
| server to client on connect | `{ type: 'connected', clientId, pushRef, resources }` |
|
|
36
|
+
| client to server | `{ type: 'subscribe', resource }` (or `channel`), `{ type: 'unsubscribe', resource }` |
|
|
37
|
+
| server reply | `{ type: 'subscribed', channel }`, `{ type: 'unsubscribed', channel }`, `{ type: 'error', error }` |
|
|
38
|
+
| CRUD push | `{ type: 'product.created', data, meta }` |
|
|
39
|
+
| room broadcast | `{ type: 'broadcast', channel, data }` |
|
|
40
|
+
| direct send | `{ type: 'direct', data }` |
|
|
41
|
+
|
|
42
|
+
Heartbeat uses RFC 6455 ping frames. `?pushRef=` on the upgrade URL resumes a session.
|
|
43
|
+
|
|
44
|
+
## Server API
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
app.ws.broadcast('product', { productId: '1' });
|
|
48
|
+
app.ws.broadcastToOrg('org-1', 'product', {});
|
|
49
|
+
app.ws.send({ userId }, data); // or { pushRef }; critical, ordered
|
|
50
|
+
app.ws.sendRealtime({ userId }, data, 'coalesce-key'); // droppable, coalesced
|
|
51
|
+
app.ws.getStats();
|
|
52
|
+
app.ws.rooms; // RoomManager
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Resume and scale-out
|
|
56
|
+
|
|
57
|
+
| Need | Option |
|
|
58
|
+
|---|---|
|
|
59
|
+
| Replay after reconnect | `messageEnvelope: 'seq'` (wraps critical sends as `{ seq, t, msg }`; client sends `{ type: 'resume', lastSeq }`), `deadQueueSize` (128), `pushRefTtlMs` (60000), `pushRefMaxEntries` (10000) |
|
|
60
|
+
| Multi-instance broadcast | `adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })` from `@classytic/arc/integrations/websocket-redis` |
|
|
61
|
+
| Resume across nodes | `pushRefStore: new RedisPushRefStore(redis, { keyPrefix, graceMs })` from `@classytic/arc/integrations/websocket-pushref-redis` |
|
|
62
|
+
|
|
63
|
+
The default `LocalWebSocketAdapter` is single-instance. Also exported: `RoomManager`, `GeoRoom`, `PushRefRegistry`, `MemoryPushRefStore`.
|
|
64
|
+
|
|
65
|
+
## eventGatewayPlugin (SSE plus WebSocket)
|
|
66
|
+
|
|
67
|
+
One config for both transports with shared auth, tenant scoping and room policy.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
|
|
71
|
+
|
|
72
|
+
await app.register(eventGatewayPlugin, {
|
|
73
|
+
auth: true, // default; boot fails without fastify.authenticate or authenticate()
|
|
74
|
+
roomPolicy: (client, room) => ['product', 'order'].includes(room),
|
|
75
|
+
maxMessageBytes: 8192,
|
|
76
|
+
maxSubscriptionsPerClient: 50,
|
|
77
|
+
sse: { path: '/api/events', patterns: ['order.*'], heartbeat: 30000, filter: (event, request) => true }, // false disables
|
|
78
|
+
ws: { path: '/ws', resources: ['product', 'order'], exposeStats: 'authenticated' }, // false disables
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
- `orgScoped` is forwarded to SSE only when set; SSE defaults to tenant-scoped. Set `false` only for a cross-tenant ops stream.
|
|
83
|
+
- Registers `@fastify/websocket` itself; throws with install instructions if missing (or pass `ws: false`).
|
|
84
|
+
- Prefer it over registering SSE and WebSocket separately.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Webhooks (outbound, signed)
|
|
2
|
+
|
|
3
|
+
```typescript
|
|
4
|
+
import { webhookPlugin, verifyWebhook, verifySignature, defaultWebhookUrlPolicy } from '@classytic/arc/integrations/webhooks';
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Auto-delivers bus events to registered endpoints. Needs the events plugin (registered by `createApp`).
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
await app.register(webhookPlugin, {
|
|
11
|
+
store, // WebhookStore { name, getAll, save, remove }; default in-memory
|
|
12
|
+
timeout: 10000,
|
|
13
|
+
concurrency: 5, // parallel deliveries per event
|
|
14
|
+
maxLogEntries: 1000,
|
|
15
|
+
retry: { attempts: 3, backoffMs: 1000 }, // best-effort in-process; network, timeout, 429, 5xx only
|
|
16
|
+
validateUrl: defaultWebhookUrlPolicy, // https only, blocks private, loopback, metadata hosts
|
|
17
|
+
// durable: { store: outboxStore }, // guaranteed delivery, exclusive with retry
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
await app.webhooks.register({ id: 'wh-1', url: 'https://c.example/hook', events: ['order.*'], secret });
|
|
21
|
+
await app.events.publish('order.created', { orderId: '1' }); // signed POST to matches
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`app.webhooks`: `register`, `unregister`, `list()` (secrets withheld), `getSecret(id)`, `deliveryLog(limit?)` (`{ subscriptionId, eventType, success, status?, error?, timestamp, attempts? }`).
|
|
25
|
+
|
|
26
|
+
- Patterns: exact, `order.*`, `*`.
|
|
27
|
+
- `validateUrl` runs on register, on every persisted subscription at init, and at delivery with `redirect: 'manual'` (a 3xx counts as failed). It checks the URL literal only; do DNS-rebinding defence at the egress boundary.
|
|
28
|
+
|
|
29
|
+
## Wire contract (v1)
|
|
30
|
+
|
|
31
|
+
Headers: `x-arc-webhook-signature: v1=<hex>`, `x-arc-webhook-timestamp` (epoch ms), `x-arc-webhook-delivery` (event `meta.id`, stable across retries). Body: `{ type, payload, meta }`. Signed string: `v1.<timestamp>.<deliveryId>.<body>` (HMAC-SHA256), so replay is bounded and dedupe uses an authenticated id. `signWebhook(body, secret, { timestamp, deliveryId })` produces it.
|
|
32
|
+
|
|
33
|
+
## Verify (receiver)
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
app.post('/hooks/arc', { config: { rawBody: true } }, async (req, reply) => {
|
|
37
|
+
const r = verifyWebhook({
|
|
38
|
+
body: req.rawBody as string, // exact bytes, never the parsed body
|
|
39
|
+
secret,
|
|
40
|
+
signature: req.headers['x-arc-webhook-signature'] as string,
|
|
41
|
+
timestamp: req.headers['x-arc-webhook-timestamp'] as string,
|
|
42
|
+
deliveryId: req.headers['x-arc-webhook-delivery'] as string,
|
|
43
|
+
toleranceMs: 300000, // default
|
|
44
|
+
});
|
|
45
|
+
if (!r.valid) return reply.status(401).send({ error: r.reason }); // missing_headers | bad_timestamp | expired | bad_signature
|
|
46
|
+
// dedupe on r.deliveryId, then handle
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Third-party senders: `verifySignature(rawBody, secret, header, { prefix: 'sha256=', algorithm: 'sha256' })` returns boolean (`prefix: ''` for bare hex). Both throw `TypeError` when the body is not a string or Buffer (re-serialised JSON breaks the HMAC).
|
|
51
|
+
|
|
52
|
+
## Durable delivery
|
|
53
|
+
|
|
54
|
+
Each (event x subscription) becomes one outbox row (`<event id>:wh:<subscription id>` as dedupe key); a relay performs the signed POST, retries and dead-letters.
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { createDurableWebhookModule, webhookDeliveryFailurePolicy } from '@classytic/arc/integrations/webhooks';
|
|
58
|
+
import { repositoryAsOutboxStore } from '@classytic/arc/events';
|
|
59
|
+
|
|
60
|
+
const store = repositoryAsOutboxStore(deliveryRepo);
|
|
61
|
+
await createApp({
|
|
62
|
+
modules: [createDurableWebhookModule({ store, delivery: { maxAttempts: 8, baseMs: 5000, maxMs: 900000 } })],
|
|
63
|
+
plugins: async (f) => { await f.register(webhookPlugin, { durable: { store } }); },
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- Module name defaults to `'webhook-delivery'`. It accepts the `createOutboxModule` options plus `fetch`, `timeout`, `validateUrl`, `resolveHeaders(sub, event)`, `delivery`, `failurePolicy`.
|
|
68
|
+
- `resolveHeaders` cannot override `content-type` or the `x-arc-webhook-*` headers.
|
|
69
|
+
- Non-transient failures (4xx, 3xx, URL policy rejection, malformed row) dead-letter at once; transient ones (network, timeout, 429, 5xx) retry with backoff.
|
|
70
|
+
- The delivering process must also register `webhookPlugin` with the shared subscription store (checked at boot). `role: 'api'` only enqueues, `role: 'relay'` delivers.
|
|
71
|
+
- Row type constant: `WEBHOOK_DELIVERY_EVENT`; errors: `WebhookDeliveryError` (`status`, `transient`); lower level `createWebhookDeliveryTransport`.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Streamline workflows
|
|
2
|
+
|
|
3
|
+
```typescript
|
|
4
|
+
import { streamlinePlugin } from '@classytic/arc/integrations/streamline';
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Peer: `@classytic/streamline`. Workflows come from `createWorkflow` there.
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
await app.register(streamlinePlugin, {
|
|
11
|
+
workflows: [orderWorkflow],
|
|
12
|
+
prefix: '/api/workflows', // default '/workflows'
|
|
13
|
+
auth: true, // default
|
|
14
|
+
bridgeEvents: true, // default: workflow.<id>.started|resumed|cancelled
|
|
15
|
+
bridgeBusEvents: false, // true: every engine event as workflow.<id>.<eventName>
|
|
16
|
+
enableStreaming: false, // true: SSE run stream
|
|
17
|
+
enableHookEndpoint: false, // true: POST <prefix>/hooks/:token
|
|
18
|
+
tenantResolver: (req) => req.user?.organizationId, // from auth, never the body
|
|
19
|
+
bypassTenantResolver: (req) => false,
|
|
20
|
+
permissions: { start: (req) => true, cancel: (req) => true }, // also resume, list, get, execute, pause, rewind
|
|
21
|
+
idempotency: { required: ['start'], workflows: ['order'] }, // needs idempotencyPlugin
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`execute` falls back to the `start` permission; `pause` and `rewind` fall back to `cancel`.
|
|
26
|
+
|
|
27
|
+
## Routes (per workflow `<prefix>/<id>`)
|
|
28
|
+
|
|
29
|
+
| Route | Purpose |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `GET <prefix>` | List workflows |
|
|
32
|
+
| `POST <prefix>/<id>/start` | Start a run |
|
|
33
|
+
| `GET <prefix>/<id>/runs`, `GET .../runs/:runId` | List, get runs |
|
|
34
|
+
| `POST .../runs/:runId/resume` | Resume a waiting run (`{ payload }`) |
|
|
35
|
+
| `POST .../runs/:runId/cancel`, `/execute`, `/pause`, `/rewind` | Run control (`pause`, `rewind`, `wait` depend on the engine) |
|
|
36
|
+
| `DELETE .../runs/:runId` | Cancel then delete, when the repository supports it |
|
|
37
|
+
| `GET .../runs/:runId/wait` | Poll until terminal, when the engine supports it |
|
|
38
|
+
| `GET .../runs/:runId/stream` | SSE with `enableStreaming`; closes on terminal state |
|
|
39
|
+
| `POST <prefix>/hooks/:token` | Resume via hook with `enableHookEndpoint`; workflow must pass `{ hookToken: hook.token }` to `ctx.wait` |
|
|
40
|
+
|
|
41
|
+
## Events and decorators
|
|
42
|
+
|
|
43
|
+
- Bridge payload: `{ runId, workflowId, status }` for started and resumed, `{ runId, workflowId }` for cancelled.
|
|
44
|
+
- Constants: `STREAMLINE_BUS_EVENTS`, `STREAMLINE_STREAM_EVENTS`, `STREAMLINE_TERMINAL_EVENTS`, `STREAMLINE_FAILURE_CODES`, `TERMINAL_RUN_STATUSES`, `isStreamTerminal(eventOrStatus, compensates, kind)`.
|
|
45
|
+
- Decorators: `app.workflows` (Map), `app.getWorkflow(id)`.
|
|
46
|
+
- A failed run with compensation keeps streaming its rollback; without it, `failed` is terminal.
|
|
47
|
+
- If `fastify.authenticate` is missing, auth middleware is skipped. A permission left unset allows.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# MCP: authentication modes
|
|
2
|
+
|
|
3
|
+
`auth` on `mcpPlugin` is one of: `false`, a Better Auth instance (OAuth 2.1), or an `McpAuthResolver`. A resolver returns `McpAuthResult` to allow or `null` to reject (401).
|
|
4
|
+
|
|
5
|
+
## 1. No auth (dev, stdio)
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
await app.register(mcpPlugin, { resources, auth: false });
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`ctx.user` is null and scope kind is `public`; guards like `!!ctx.user` still block. DNS rebinding protection defaults on.
|
|
12
|
+
|
|
13
|
+
## 2. Better Auth OAuth 2.1 (production SaaS)
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
// auth config
|
|
17
|
+
import { mcp } from 'better-auth/plugins/mcp';
|
|
18
|
+
betterAuth({ plugins: [mcp({ loginPage: '/login' })] });
|
|
19
|
+
|
|
20
|
+
// app
|
|
21
|
+
await app.register(mcpPlugin, { resources, auth: getAuth() });
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Arc registers `GET /.well-known/oauth-authorization-server` and `GET /.well-known/oauth-protected-resource` (forwarded to Better Auth). Each request resolves identity with `auth.api.getMcpSession({ headers })` (`userId`, `activeOrganizationId`).
|
|
25
|
+
|
|
26
|
+
## 3. Better Auth API key (machine clients)
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
import { createMcpAuthFromBetterAuthApiKey } from '@classytic/arc/mcp';
|
|
30
|
+
|
|
31
|
+
await app.register(mcpPlugin, {
|
|
32
|
+
resources,
|
|
33
|
+
auth: createMcpAuthFromBetterAuthApiKey(getAuth(), {
|
|
34
|
+
orgFromMetadata: true, // true (default) | false | (metadata, key) => string | undefined
|
|
35
|
+
metadataOrgField: 'tenantId', // default 'organizationId'
|
|
36
|
+
permissionScope: 'mcp', // key.permissions[scope] becomes scopes; false disables
|
|
37
|
+
}),
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- Requires the `apiKey()` plugin (`auth.api.verifyApiKey`), else throws at creation.
|
|
42
|
+
- Header order: `Authorization: Bearer <key>`, then `x-api-key`.
|
|
43
|
+
- User binding falls back `userId` then `referenceId`; a key with neither is a service principal (`clientId = key.id`).
|
|
44
|
+
- Disabled, expired or failing keys return null (fail closed).
|
|
45
|
+
|
|
46
|
+
## 4. Custom resolver
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
auth: async (headers) => {
|
|
50
|
+
const token = headers['authorization']?.replace('Bearer ', '');
|
|
51
|
+
if (!token) return null;
|
|
52
|
+
const p = await verifyJwt(token);
|
|
53
|
+
return p ? { userId: p.sub, organizationId: p.org, roles: p.roles, orgRoles: p.orgRoles } : null;
|
|
54
|
+
},
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`McpAuthResult` fields:
|
|
58
|
+
|
|
59
|
+
| Field | Use |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `userId` | Human id; optional for machine principals |
|
|
62
|
+
| `organizationId` | Tenant scope |
|
|
63
|
+
| `roles`, `orgRoles` | Read by `requireRole()` and permission checks |
|
|
64
|
+
| `clientId` | Present: scope kind `service`, `ctx.user` is null |
|
|
65
|
+
| `scopes` | OAuth scopes carried on the service scope |
|
|
66
|
+
| `teamId` | Carried on `member` scope |
|
|
67
|
+
| `context` | `Record<string, string>` custom scope dimensions (`branchId`, ...). Resources gated with `requireScopeContext()` deny until supplied |
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
// Service principal
|
|
71
|
+
auth: async (h) => h['x-service-key'] === process.env.SVC_KEY
|
|
72
|
+
? { clientId: 'ingestion', organizationId: 'org-123', scopes: ['write:events'] }
|
|
73
|
+
: null,
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Tenancy
|
|
77
|
+
|
|
78
|
+
`organizationId` becomes the request scope (`member`, or `service` with `clientId`); the controller adds the tenant filter to every query, same as REST. Resources with `tenantField: false` are visible to all authenticated callers.
|
|
79
|
+
|
|
80
|
+
## Gotchas
|
|
81
|
+
|
|
82
|
+
- Resolver results are cached `authCacheTtlMs` (5 s) keyed by a hash of `authorization`/`x-api-key`; revocation lags by that window.
|
|
83
|
+
- `auth: false` exposes every generated tool anonymously; combine with `expose` and permissions.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# MCP: custom tools, guards, AI SDK bridge
|
|
2
|
+
|
|
3
|
+
```typescript
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
import { createMcpServer, defineTool, definePrompt } from '@classytic/arc/mcp';
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
## defineTool and definePrompt
|
|
9
|
+
|
|
10
|
+
`input` is a flat Zod shape (`{ field: z.string() }`), not `z.object(...)`. The SDK wraps it in a stripping object.
|
|
11
|
+
|
|
12
|
+
```typescript
|
|
13
|
+
export const notifyTool = defineTool('send_notification', {
|
|
14
|
+
description: 'Send a notification',
|
|
15
|
+
input: { channel: z.enum(['email', 'telegram']), recipient: z.string(), message: z.string() },
|
|
16
|
+
annotations: { openWorldHint: true },
|
|
17
|
+
handler: async ({ channel, recipient, message }, ctx) => {
|
|
18
|
+
const result = await notifications.send(channel, recipient, message);
|
|
19
|
+
return { content: [{ type: 'text', text: JSON.stringify(result) }] };
|
|
20
|
+
},
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
export const planPrompt = definePrompt('content_calendar', {
|
|
24
|
+
description: 'Plan a content calendar',
|
|
25
|
+
args: { platforms: z.string(), theme: z.string().optional() },
|
|
26
|
+
handler: ({ platforms }) => ({
|
|
27
|
+
messages: [{ role: 'user', content: { type: 'text', text: `Plan content for ${platforms}` } }],
|
|
28
|
+
}),
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
// With the plugin
|
|
32
|
+
await app.register(mcpPlugin, { resources, extraTools: [notifyTool], extraPrompts: [planPrompt] });
|
|
33
|
+
|
|
34
|
+
// Standalone server
|
|
35
|
+
const server = await createMcpServer({ name: 'tools', version: '1.0.0', tools: [notifyTool], prompts: [planPrompt] });
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `ToolContext`: `{ session, log(level, msg), extra }`. `session` is the `McpAuthResult` or `null` (no auth).
|
|
39
|
+
- Handler returns `CallToolResult`: `{ content: [{ type: 'text', text }], isError? }`. `toCallToolResult`, `toCallToolSuccess`, `toCallToolError`, `permissionDeniedResult` build it.
|
|
40
|
+
- `defineTool<MySession>(...)` widens `ctx.session` to a host type extending `McpAuthResult`.
|
|
41
|
+
- Custom tools bypass resource permissions: guard them explicitly.
|
|
42
|
+
|
|
43
|
+
## Guards
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { guard, requireAuth, requireOrg, requireRole, requireOrgId, customGuard } from '@classytic/arc/mcp';
|
|
47
|
+
|
|
48
|
+
defineTool('purge', {
|
|
49
|
+
description: 'Purge records',
|
|
50
|
+
handler: guard(requireAuth, requireOrg, requireRole('admin', 'editor'), async (input, ctx) => {
|
|
51
|
+
return { content: [{ type: 'text', text: 'done' }] };
|
|
52
|
+
}),
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
const businessHours = customGuard(() => new Date().getHours() >= 9, 'Business hours only');
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
| Guard | Rejects when |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `requireAuth` | no session or anonymous |
|
|
61
|
+
| `requireOrg` | no `organizationId` |
|
|
62
|
+
| `requireRole(...roles)` | none of the roles in `session.roles` (OR) |
|
|
63
|
+
| `requireOrgId(id)` | session org differs |
|
|
64
|
+
| `customGuard(fn, msg)` | predicate false |
|
|
65
|
+
|
|
66
|
+
Inline: `isAuthenticated(ctx)`, `hasOrg(ctx)`, `isOrg(ctx, id)`, `getUserId(ctx)`, `getOrgId(ctx)`, `denied(msg)` (returns an `isError` result). `requireRole` needs the auth resolver to return `roles`.
|
|
67
|
+
|
|
68
|
+
## fieldRulesToZod
|
|
69
|
+
|
|
70
|
+
Build flat shapes from `schemaOptions.fieldRules`:
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
import { fieldRulesToZod } from '@classytic/arc/mcp';
|
|
74
|
+
|
|
75
|
+
const shape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
|
|
76
|
+
mode: 'create', // 'create' | 'update' | 'list'
|
|
77
|
+
hiddenFields: ['internalScore'],
|
|
78
|
+
readonlyFields: ['slug'],
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Compose controller calls
|
|
83
|
+
|
|
84
|
+
`invokeController(controller, op, input, options)` runs a controller method with the full pipeline (permissions, hooks, events) outside HTTP; `mcpHandlerAdapter(fn)` wraps a handler so thrown `ArcError`s become canonical error results.
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
import { defineTool, mcpHandlerAdapter, invokeController } from '@classytic/arc/mcp';
|
|
88
|
+
|
|
89
|
+
defineTool('archive_post', {
|
|
90
|
+
description: 'Archive a post',
|
|
91
|
+
input: { id: z.string() },
|
|
92
|
+
handler: mcpHandlerAdapter(async (input, ctx) =>
|
|
93
|
+
invokeController(postController, 'update', { id: input.id, archived: true },
|
|
94
|
+
{ session: ctx.session, resourceName: 'post' })),
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## AI SDK bridge
|
|
99
|
+
|
|
100
|
+
Expose one AI SDK `tool()` builder over MCP. The bridge rejects unauthenticated callers, runs the optional `guard`, maps `{ error }` results and thrown errors to `isError`, and calls `buildTool(ctx)` per request.
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
|
|
104
|
+
import { tool } from 'ai';
|
|
105
|
+
|
|
106
|
+
export const triggerJob: McpBridge = {
|
|
107
|
+
name: 'trigger_job',
|
|
108
|
+
description: 'Start a job.',
|
|
109
|
+
inputSchema: { phase: z.enum(['investigate', 'fix']) },
|
|
110
|
+
annotations: { destructiveHint: true },
|
|
111
|
+
buildTool: (ctx) => tool({
|
|
112
|
+
description: 'Start a job.',
|
|
113
|
+
inputSchema: z.object({ phase: z.enum(['investigate', 'fix']) }),
|
|
114
|
+
execute: async ({ phase }) => ({ jobId: `${getUserId(ctx)}-${phase}` }),
|
|
115
|
+
}),
|
|
116
|
+
guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
await app.register(mcpPlugin, {
|
|
120
|
+
resources,
|
|
121
|
+
extraTools: buildMcpToolsFromBridges([triggerJob], { exclude: readOnly ? ['trigger_job'] : [] }),
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`buildMcpToolsFromBridges` also takes `{ include: [...] }`. `bridgeToMcp(bridge)` converts one.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# MCP: plugin setup and generated tools
|
|
2
|
+
|
|
3
|
+
Peer deps: `@modelcontextprotocol/server` (>=2), `zod`. Tests also use `@modelcontextprotocol/client`.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { mcpPlugin } from '@classytic/arc/mcp';
|
|
7
|
+
import { createApp, loadResources } from '@classytic/arc/factory';
|
|
8
|
+
|
|
9
|
+
const resources = await loadResources('./src/resources');
|
|
10
|
+
const app = await createApp({
|
|
11
|
+
resources,
|
|
12
|
+
plugins: async (f) => {
|
|
13
|
+
await f.register(mcpPlugin, { resources, auth: false, expose: ['product', 'order'] });
|
|
14
|
+
},
|
|
15
|
+
});
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Generated tools (per resource)
|
|
19
|
+
|
|
20
|
+
| Source | Tool name | Annotations |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `list` | `list_{plural}` | `readOnlyHint` |
|
|
23
|
+
| `get` | `get_{name}` | `readOnlyHint` |
|
|
24
|
+
| `create` | `create_{name}` | `destructiveHint: false` |
|
|
25
|
+
| `update`, `delete` | `update_{name}`, `delete_{name}` | `destructiveHint`, `idempotentHint` |
|
|
26
|
+
| `actions` | `{action}_{name}` (input: `id` + action schema) | `destructiveHint` |
|
|
27
|
+
| custom routes (function or string handler) | `{operation or slug}_{name}` | GET: `readOnlyHint`, else `openWorldHint` |
|
|
28
|
+
|
|
29
|
+
- A CRUD op becomes a tool only when `permissions.<op>` is declared and the op is not in `disabledRoutes`.
|
|
30
|
+
- Tools run the same controller pipeline as REST: auth, tenant scope, permission policy, hooks, field masking, events.
|
|
31
|
+
- `list_*` accepts `page`, `limit`, `cursor` (keyset; `page` ignored when set), `sort`, `search`, `select`, `populate`, filters. `get_*` accepts `id`, `select`. `limit` max follows the resource `queryParser.maxLimit`.
|
|
32
|
+
- Mutating tools accept `_idempotencyKey` when an idempotency store is wired (register `idempotencyPlugin` before `mcpPlugin`). `idempotency.required` on a resource without a store throws at boot.
|
|
33
|
+
- Route/action tools: `mcp: false` hides, `mcp: { description, annotations }` customizes. `defineResource({ mcp: false })` removes the whole resource.
|
|
34
|
+
|
|
35
|
+
## McpPluginOptions
|
|
36
|
+
|
|
37
|
+
| Option | Default | Notes |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `resources` | required | |
|
|
40
|
+
| `auth` | `false` | `false`, Better Auth instance, or `McpAuthResolver` (see mcp-auth.md) |
|
|
41
|
+
| `expose` | none | Default-deny allowlist of resource names. Preferred |
|
|
42
|
+
| `exclude` | none | Default-allow blocklist. Mutually exclusive with `expose` (throws) |
|
|
43
|
+
| `prefix` | `/mcp` | Endpoint path |
|
|
44
|
+
| `serverName`, `serverVersion` | `arc-mcp`, `1.0.0` | |
|
|
45
|
+
| `instructions` | none | LLM guidance |
|
|
46
|
+
| `toolNamePrefix` | none | `'crm'` gives `crm_list_products` |
|
|
47
|
+
| `overrides` | none | Per-resource `McpResourceConfig` |
|
|
48
|
+
| `extraTools`, `extraPrompts` | none | Hand-written tools/prompts |
|
|
49
|
+
| `stateful`, `sessionTtlMs`, `maxSessions` | `false`, 1800000, 1000 | Session mode |
|
|
50
|
+
| `authCacheTtlMs` | 5000 | Stateless auth-result cache; `0` disables |
|
|
51
|
+
| `dnsRebindingProtection` | on if `auth: false` | See below |
|
|
52
|
+
|
|
53
|
+
## Per-resource overrides
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
await app.register(mcpPlugin, {
|
|
57
|
+
resources,
|
|
58
|
+
expose: ['job'],
|
|
59
|
+
overrides: {
|
|
60
|
+
job: {
|
|
61
|
+
operations: ['list', 'get'],
|
|
62
|
+
toolNamePrefix: 'db', // db_list_jobs
|
|
63
|
+
names: { get: 'get_job_by_id' },
|
|
64
|
+
hideFields: ['internalScore'],
|
|
65
|
+
descriptions: {
|
|
66
|
+
list: 'Browse jobs',
|
|
67
|
+
get: ({ defaultDescription }) => `${defaultDescription} Prefer isActive: true.`,
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Permissions
|
|
75
|
+
|
|
76
|
+
Resource `permissions` apply unchanged. A permission returning `allow({ policy })` scopes `list_*` by that policy; `deny('msg')` returns a tool error; boolean results work.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { allow, deny } from '@classytic/arc/permissions';
|
|
80
|
+
permissions: {
|
|
81
|
+
list: (ctx) => ctx.user ? allow({ policy: { orgId: ctx.user.orgId } }) : deny('Auth required'),
|
|
82
|
+
delete: () => deny('Read-only'),
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## DNS rebinding protection
|
|
87
|
+
|
|
88
|
+
Validates `Host`/`Origin`. Default on when `auth: false` (localhost set), off when auth is configured.
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
mcpPlugin({ resources, auth, dnsRebindingProtection: {} }); // localhost + auth
|
|
92
|
+
mcpPlugin({ resources, dnsRebindingProtection: { allowedHosts: ['mcp.example.com'] } });
|
|
93
|
+
mcpPlugin({ resources, auth: false, dnsRebindingProtection: false }); // public
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Absent `Origin` passes; present-but-unlisted is refused. `${prefix}/health` is exempt.
|
|
97
|
+
|
|
98
|
+
## Endpoints and modes
|
|
99
|
+
|
|
100
|
+
| Mode | Behavior |
|
|
101
|
+
|---|---|
|
|
102
|
+
| Stateless (default) | `POST /mcp` fresh server per request; `GET` returns 405; `DELETE` no-op. Use for scaling/serverless |
|
|
103
|
+
| `stateful: true` | `POST` reuses `Mcp-Session-Id`; `GET` is SSE; `DELETE` ends session. TTL cache, LRU eviction at `maxSessions` |
|
|
104
|
+
|
|
105
|
+
- `GET /mcp/health` returns `{ status, mode }`; with valid auth (or `auth: false`) it also returns `tools`, `resources`, `toolNames`, `sessions`.
|
|
106
|
+
- Resources `arc://schemas` and `arc://schemas/{name}` expose resource schemas to agents.
|
|
107
|
+
- Multiple endpoints: register `mcpPlugin` repeatedly with different `resources` and `prefix`.
|
|
108
|
+
|
|
109
|
+
## Tool-name collisions
|
|
110
|
+
|
|
111
|
+
`createMcpServer` resolves duplicates before the SDK sees them. A preset tool vs a user tool: the preset is renamed (`softdelete_restore_post`). Any other duplicate throws `ArcError` code `arc.mcp.tool_name_collision` naming both `source` labels. `resolveToolCollisions(tools)` is exported for tests.
|
|
112
|
+
|
|
113
|
+
## Scaffold
|
|
114
|
+
|
|
115
|
+
`arc generate resource order --mcp` or `arc generate mcp analytics` creates `<name>.mcp.ts`; pass its tools via `extraTools`.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# MCP: testing
|
|
2
|
+
|
|
3
|
+
`@classytic/arc/mcp/testing` serves the real Streamable HTTP transport on an ephemeral loopback port (needs `@modelcontextprotocol/client`). Always `await client.close()`.
|
|
4
|
+
|
|
5
|
+
## createTestMcpClient
|
|
6
|
+
|
|
7
|
+
Builds tools from resources and connects a client; no Fastify app needed.
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { createTestMcpClient } from '@classytic/arc/mcp/testing';
|
|
11
|
+
|
|
12
|
+
const client = await createTestMcpClient({
|
|
13
|
+
pluginOptions: { resources: [productResource], extraTools: [notifyTool] },
|
|
14
|
+
auth: { userId: 'u1', organizationId: 'org-1', roles: ['admin'] },
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
const tools = await client.listTools();
|
|
18
|
+
expect(tools.map((t) => t.name)).toContain('list_products');
|
|
19
|
+
|
|
20
|
+
const res = await client.callTool('list_products', { limit: 5 });
|
|
21
|
+
expect(res.isError).toBeFalsy();
|
|
22
|
+
await client.close();
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
| Option | Notes |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `pluginOptions` | `resources`, `overrides`, `expose`, `exclude`, `toolNamePrefix`, `extraTools`, `extraPrompts`, `instructions` |
|
|
28
|
+
| `auth` | `McpAuthResult` for the session; `null` or omitted runs anonymous |
|
|
29
|
+
| `serverName` | default `test-mcp` |
|
|
30
|
+
|
|
31
|
+
`callTool` returns `{ content: [{ type, text }], isError? }`; parse `content[0].text` as JSON.
|
|
32
|
+
|
|
33
|
+
## connectMcpTestClient
|
|
34
|
+
|
|
35
|
+
For a server you built with `createMcpServer`:
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { connectMcpTestClient } from '@classytic/arc/mcp/testing';
|
|
39
|
+
|
|
40
|
+
const server = await createMcpServer({ name: 't', tools: [notifyTool] });
|
|
41
|
+
const { client, close } = await connectMcpTestClient(server);
|
|
42
|
+
const result = await client.callTool({ name: 'send_notification', arguments: { /* ... */ } });
|
|
43
|
+
await close();
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`client` is the SDK `Client` (`listTools`, `callTool`, `listPrompts`).
|
|
47
|
+
|
|
48
|
+
## What to assert
|
|
49
|
+
|
|
50
|
+
- Tool list per `expose`/`exclude`/`operations` and the generated names.
|
|
51
|
+
- Anonymous session is denied where permissions require a user.
|
|
52
|
+
- Tenant isolation: two orgs, each sees only its rows.
|
|
53
|
+
- Custom tools reject without a role (`isError: true`).
|
|
54
|
+
|
|
55
|
+
## Manual check with Claude CLI
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
claude mcp add --transport http my-api http://localhost:3000/mcp
|
|
59
|
+
echo "List all products" | claude -p --allowedTools "mcp__my-api__*"
|
|
60
|
+
claude mcp remove my-api
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Check `GET /mcp/health` first to confirm the server is up.
|