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