@terreno/api 57.3.0 → 57.6.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/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
- package/README.md +11 -5
- package/bunfig.toml +1 -1
- package/dist/actions.js +197 -368
- package/dist/adminModelRouter.js +88 -173
- package/dist/adminTypes.d.ts +7 -0
- package/dist/adminTypes.js +6 -1
- package/dist/api.d.ts +10 -0
- package/dist/api.js +601 -792
- package/dist/audit/auditApp.d.ts +30 -0
- package/dist/audit/auditApp.js +114 -0
- package/dist/audit/auditEventModel.d.ts +29 -0
- package/dist/audit/auditEventModel.js +101 -0
- package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
- package/dist/audit/cloudTasksEnqueue.js +69 -0
- package/dist/audit/diff.d.ts +10 -0
- package/dist/audit/diff.js +140 -0
- package/dist/audit/processQueue.d.ts +6 -0
- package/dist/audit/processQueue.js +56 -0
- package/dist/audit/rbacSink.d.ts +2 -0
- package/dist/audit/rbacSink.js +41 -0
- package/dist/audit/record.d.ts +56 -0
- package/dist/audit/record.js +251 -0
- package/dist/auth.js +432 -681
- package/dist/authRecovery.js +155 -269
- package/dist/authTokens.js +43 -118
- package/dist/betterAuth.d.ts +6 -0
- package/dist/betterAuthApp.js +25 -26
- package/dist/betterAuthSetup.js +258 -413
- package/dist/browserLogsRoute.d.ts +6 -0
- package/dist/browserLogsRoute.js +97 -0
- package/dist/collectionRegistry.d.ts +3 -1
- package/dist/collectionRegistry.js +43 -33
- package/dist/config.js +53 -122
- package/dist/configurationApp.js +180 -361
- package/dist/configurationPlugin.js +130 -302
- package/dist/consentApp.js +276 -421
- package/dist/docLoader.js +78 -126
- package/dist/envConfigurationPlugin.js +25 -147
- package/dist/errors.js +151 -247
- package/dist/example.js +28 -34
- package/dist/expressServer.d.ts +10 -0
- package/dist/expressServer.js +109 -255
- package/dist/frameworkModelNames.d.ts +24 -0
- package/dist/frameworkModelNames.js +31 -0
- package/dist/githubAuth.js +152 -216
- package/dist/httpClient.js +176 -264
- package/dist/index.d.ts +28 -1
- package/dist/index.js +53 -2
- package/dist/logger.js +145 -278
- package/dist/mcp/auth.js +76 -128
- package/dist/mcp/createMCPRequest.js +4 -5
- package/dist/mcp/handlers.js +268 -480
- package/dist/mcp/query.d.ts +0 -13
- package/dist/mcp/query.js +57 -151
- package/dist/mcp/registry.js +17 -30
- package/dist/mcp/schemaGenerator.js +95 -181
- package/dist/mcp/server.js +28 -100
- package/dist/mcp/serviceTokens.js +102 -191
- package/dist/mcp/toolGenerator.js +78 -191
- package/dist/middleware.js +15 -27
- package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
- package/dist/migrations/fixtures/all-down/20260910120000-one.js +9 -0
- package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
- package/dist/migrations/fixtures/all-down/20260910120001-two.js +9 -0
- package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
- package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +7 -0
- package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
- package/dist/migrations/fixtures/bad-name/not-a-migration.js +7 -0
- package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
- package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
- package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
- package/dist/migrations/fixtures/valid/20260910120000-alpha.js +7 -0
- package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
- package/dist/migrations/fixtures/valid/20260910120001-beta.js +9 -0
- package/dist/migrations/generate.d.ts +17 -0
- package/dist/migrations/generate.js +155 -0
- package/dist/migrations/load.d.ts +20 -0
- package/dist/migrations/load.js +110 -0
- package/dist/migrations/lock.d.ts +13 -0
- package/dist/migrations/lock.js +73 -0
- package/dist/migrations/runner.d.ts +42 -0
- package/dist/migrations/runner.js +249 -0
- package/dist/migrations/schemaCatalog.d.ts +44 -0
- package/dist/migrations/schemaCatalog.js +185 -0
- package/dist/migrations/types.d.ts +87 -0
- package/dist/migrations/types.js +7 -0
- package/dist/models/consentForm.js +6 -6
- package/dist/models/consentResponse.js +5 -5
- package/dist/models/mcpServiceToken.js +66 -156
- package/dist/models/notification.d.ts +2 -0
- package/dist/models/notification.js +62 -0
- package/dist/models/notificationPreference.d.ts +2 -0
- package/dist/models/notificationPreference.js +49 -0
- package/dist/models/versionConfig.js +5 -5
- package/dist/notifications/notificationService.d.ts +40 -0
- package/dist/notifications/notificationService.js +183 -0
- package/dist/notifications/notificationsApp.d.ts +18 -0
- package/dist/notifications/notificationsApp.js +156 -0
- package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
- package/dist/notifications/notificationsBeforeSend.js +32 -0
- package/dist/notifiers/googleChatNotifier.js +36 -117
- package/dist/notifiers/slackNotifier.d.ts +31 -2
- package/dist/notifiers/slackNotifier.js +170 -119
- package/dist/notifiers/zoomNotifier.js +60 -111
- package/dist/openApi.d.ts +1 -7
- package/dist/openApi.js +113 -127
- package/dist/openApiBuilder.d.ts +14 -3
- package/dist/openApiBuilder.js +117 -159
- package/dist/openApiCompat.js +81 -148
- package/dist/openApiEtag.js +7 -7
- package/dist/openApiValidator.d.ts +13 -1
- package/dist/openApiValidator.js +301 -246
- package/dist/orgs/orgContext.d.ts +23 -0
- package/dist/orgs/orgContext.js +128 -0
- package/dist/orgs/orgPermissions.d.ts +4 -0
- package/dist/orgs/orgPermissions.js +38 -0
- package/dist/orgs/orgPlugin.d.ts +13 -0
- package/dist/orgs/orgPlugin.js +66 -0
- package/dist/orgs/organizationModel.d.ts +13 -0
- package/dist/orgs/organizationModel.js +200 -0
- package/dist/orgs/organizationSettings.d.ts +19 -0
- package/dist/orgs/organizationSettings.js +113 -0
- package/dist/orgs/orgsApp.d.ts +28 -0
- package/dist/orgs/orgsApp.js +416 -0
- package/dist/permissions.d.ts +7 -13
- package/dist/permissions.js +95 -211
- package/dist/plugins.js +125 -218
- package/dist/populate.js +130 -240
- package/dist/rateLimit/applyTrustProxy.js +1 -1
- package/dist/rateLimit/createStore.js +7 -8
- package/dist/rateLimit/memoryStore.js +22 -100
- package/dist/rateLimit/middleware.d.ts +0 -8
- package/dist/rateLimit/middleware.js +49 -101
- package/dist/rateLimit/mongoStore.d.ts +1 -0
- package/dist/rateLimit/mongoStore.js +55 -112
- package/dist/rateLimit/policies.d.ts +0 -4
- package/dist/rateLimit/policies.js +44 -80
- package/dist/rateLimit/redisStore.d.ts +1 -0
- package/dist/rateLimit/redisStore.js +40 -133
- package/dist/rbac/access.js +122 -253
- package/dist/rbac/assertAllowed.js +95 -171
- package/dist/rbac/auditModel.js +14 -58
- package/dist/rbac/backfillAdmins.js +24 -130
- package/dist/rbac/fieldViews.js +46 -141
- package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
- package/dist/rbac/membershipOrgAdminSource.js +51 -0
- package/dist/rbac/middleware.js +30 -96
- package/dist/rbac/modelRouterAccess.d.ts +3 -0
- package/dist/rbac/modelRouterAccess.js +133 -307
- package/dist/rbac/permissionUtils.js +40 -179
- package/dist/rbac/realtimeAccess.js +81 -147
- package/dist/rbac/resolve.d.ts +1 -1
- package/dist/rbac/resolve.js +154 -319
- package/dist/rbac/roleManager.js +318 -700
- package/dist/rbac/roleModel.d.ts +2 -5
- package/dist/rbac/roleModel.js +60 -173
- package/dist/rbac/routes.js +93 -196
- package/dist/rbac/scopes.js +39 -133
- package/dist/rbac/statements.d.ts +10 -1
- package/dist/rbac/statements.js +42 -93
- package/dist/rbac/types.d.ts +5 -0
- package/dist/rbac/userPlugin.js +3 -29
- package/dist/realtime/changeStreamWatcher.d.ts +10 -4
- package/dist/realtime/changeStreamWatcher.js +499 -764
- package/dist/realtime/deprecation.d.ts +1 -0
- package/dist/realtime/deprecation.js +9 -10
- package/dist/realtime/queryMatcher.js +110 -191
- package/dist/realtime/queryStore.js +35 -118
- package/dist/realtime/realtimeApp.d.ts +1 -0
- package/dist/realtime/realtimeApp.js +248 -401
- package/dist/realtime/registry.js +19 -30
- package/dist/realtime/sessionRevalidation.js +132 -358
- package/dist/realtime/socketAuth.js +89 -208
- package/dist/realtime/socketUser.js +10 -56
- package/dist/requestContext.js +93 -139
- package/dist/schemaMetadata.js +181 -265
- package/dist/scriptRunner.js +96 -266
- package/dist/scrubAdminFields.js +36 -108
- package/dist/secretProviders.js +130 -299
- package/dist/seedRunner.js +221 -514
- package/dist/sync/adminBroadcastScope.d.ts +40 -0
- package/dist/sync/adminBroadcastScope.js +82 -0
- package/dist/sync/adminWindowAccess.d.ts +13 -0
- package/dist/sync/adminWindowAccess.js +25 -0
- package/dist/sync/adminWindowMutation.d.ts +88 -0
- package/dist/sync/adminWindowMutation.js +176 -0
- package/dist/sync/executors.d.ts +9 -3
- package/dist/sync/executors.js +425 -598
- package/dist/sync/loadHarness.js +392 -689
- package/dist/sync/models.js +181 -341
- package/dist/sync/mutationHandler.d.ts +5 -2
- package/dist/sync/mutationHandler.js +549 -697
- package/dist/sync/registrationSideEffects.js +41 -95
- package/dist/sync/registry.js +31 -47
- package/dist/sync/routes.d.ts +13 -0
- package/dist/sync/routes.js +484 -760
- package/dist/sync/scripts/compactTombstones.js +83 -228
- package/dist/sync/serialize.js +18 -58
- package/dist/sync/socketHandlers.d.ts +8 -2
- package/dist/sync/socketHandlers.js +271 -402
- package/dist/sync/streams.d.ts +2 -0
- package/dist/sync/streams.js +54 -116
- package/dist/sync/syncApp.d.ts +2 -1
- package/dist/sync/syncApp.js +14 -16
- package/dist/sync/syncBatch.d.ts +5 -2
- package/dist/sync/syncBatch.js +63 -168
- package/dist/sync/syncSeqPlugin.js +430 -702
- package/dist/sync/types.d.ts +18 -0
- package/dist/syncConsents.js +113 -253
- package/dist/terrenoApp.d.ts +29 -0
- package/dist/terrenoApp.js +184 -257
- package/dist/tests/createTestData.d.ts +1 -3
- package/dist/tests/createTestData.js +147 -259
- package/dist/tests/models.d.ts +1 -0
- package/dist/tests/models.js +23 -56
- package/dist/tests/mongoTestSetup.js +42 -103
- package/dist/tests/testHelper.d.ts +0 -5
- package/dist/tests/testHelper.js +32 -101
- package/dist/tests.js +12 -51
- package/dist/transformers.js +61 -164
- package/dist/types/authToken.d.ts +3 -3
- package/dist/types/mcpServiceToken.d.ts +2 -2
- package/dist/types/membership.d.ts +23 -0
- package/dist/types/membership.js +2 -0
- package/dist/types/notification.d.ts +28 -0
- package/dist/types/notification.js +2 -0
- package/dist/types/notificationPreference.d.ts +20 -0
- package/dist/types/notificationPreference.js +2 -0
- package/dist/types/organization.d.ts +36 -0
- package/dist/types/organization.js +2 -0
- package/dist/utils.js +31 -93
- package/dist/vendor/wesleytodd-openapi/index.js +37 -51
- package/dist/vendor/wesleytodd-openapi/lib/generate-doc.js +32 -40
- package/dist/vendor/wesleytodd-openapi/lib/layer-schema.js +3 -3
- package/dist/vendor/wesleytodd-openapi/lib/ui.js +50 -19
- package/dist/vendor/wesleytodd-openapi/lib/validate.js +19 -47
- package/dist/versionCheckPlugin.js +52 -100
- package/dist/webhooks/headerValue.js +2 -2
- package/dist/webhooks/idempotency/memoryStore.js +16 -59
- package/dist/webhooks/idempotency/mongoStore.js +55 -130
- package/dist/webhooks/idempotency/webhookReceipt.d.ts +4 -49
- package/dist/webhooks/idempotency/webhookReceipt.js +14 -14
- package/dist/webhooks/rawBody.d.ts +1 -0
- package/dist/webhooks/rawBody.js +2 -1
- package/dist/webhooks/timingSafeEqual.js +4 -5
- package/dist/webhooks/verifiers/hmac.js +17 -18
- package/dist/webhooks/verifiers/sendgrid.js +20 -22
- package/dist/webhooks/verifiers/stripe.js +31 -65
- package/dist/webhooks/verifiers/twilio.js +23 -73
- package/dist/webhooks/webhooksApp.js +78 -177
- package/dist/zodOpenApi.js +2 -2
- package/package.json +34 -28
- package/src/__snapshots__/openApi.test.ts.snap +192 -54
- package/src/__snapshots__/openApiBuilder.test.ts.snap +0 -18
- package/src/__snapshots__/schemaMetadata.test.ts.snap +0 -1
- package/src/__tests__/browserLogsRoute.test.ts +165 -0
- package/src/adminTypes.ts +8 -0
- package/src/api.test.ts +39 -2
- package/src/api.ts +68 -0
- package/src/audit/auditApp.test.ts +243 -0
- package/src/audit/auditApp.ts +139 -0
- package/src/audit/auditEventModel.ts +160 -0
- package/src/audit/auditRouter.test.ts +456 -0
- package/src/audit/cloudTasksEnqueue.test.ts +124 -0
- package/src/audit/cloudTasksEnqueue.ts +104 -0
- package/src/audit/diff.ts +163 -0
- package/src/audit/processQueue.ts +69 -0
- package/src/audit/rbacSink.test.ts +86 -0
- package/src/audit/rbacSink.ts +42 -0
- package/src/audit/record.test.ts +402 -0
- package/src/audit/record.ts +329 -0
- package/src/auth.test.ts +1 -1
- package/src/auth.ts +1 -1
- package/src/authRecovery.test.ts +43 -0
- package/src/authRecovery.ts +16 -10
- package/src/authTokens.ts +6 -2
- package/src/authVerification.test.ts +22 -0
- package/src/betterAuth.ts +7 -0
- package/src/betterAuthSetup.test.ts +27 -0
- package/src/betterAuthSetup.ts +1 -0
- package/src/browserLogsRoute.ts +110 -0
- package/src/collectionRegistry.test.ts +8 -9
- package/src/collectionRegistry.ts +21 -1
- package/src/configurationPlugin.test.ts +1 -11
- package/src/express.d.ts +2 -0
- package/src/expressServer.test.ts +50 -2
- package/src/expressServer.ts +10 -0
- package/src/frameworkModelNames.test.ts +62 -0
- package/src/frameworkModelNames.ts +33 -0
- package/src/index.ts +76 -0
- package/src/isolated/migrateCliConnect.isolated.ts +51 -0
- package/src/mcp/auth.test.ts +34 -1
- package/src/mcp/handlers.test.ts +275 -0
- package/src/mcp/query.ts +3 -3
- package/src/mcp/toolGenerator.test.ts +81 -0
- package/src/migrations/cli.test.ts +353 -0
- package/src/migrations/cli.ts +283 -0
- package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
- package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
- package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
- package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
- package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
- package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
- package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
- package/src/migrations/generate.test.ts +333 -0
- package/src/migrations/generate.ts +216 -0
- package/src/migrations/load.test.ts +103 -0
- package/src/migrations/load.ts +124 -0
- package/src/migrations/lock.test.ts +133 -0
- package/src/migrations/lock.ts +118 -0
- package/src/migrations/runner.test.ts +504 -0
- package/src/migrations/runner.ts +358 -0
- package/src/migrations/schemaCatalog.test.ts +159 -0
- package/src/migrations/schemaCatalog.ts +262 -0
- package/src/migrations/types.ts +94 -0
- package/src/models/mcpServiceToken.ts +4 -3
- package/src/models/notification.ts +69 -0
- package/src/models/notificationPreference.ts +62 -0
- package/src/notifications/notificationService.ts +254 -0
- package/src/notifications/notificationsApp.test.ts +528 -0
- package/src/notifications/notificationsApp.ts +200 -0
- package/src/notifications/notificationsBeforeSend.ts +51 -0
- package/src/notifiers/slackNotifier.test.ts +186 -1
- package/src/notifiers/slackNotifier.ts +167 -8
- package/src/openApi.test.ts +0 -1
- package/src/openApi.ts +2 -1
- package/src/openApiBuilder.ts +14 -3
- package/src/openApiValidator.test.ts +221 -2
- package/src/openApiValidator.ts +218 -33
- package/src/orgs/orgAccessOptIn.test.ts +87 -0
- package/src/orgs/orgContext.test.ts +259 -0
- package/src/orgs/orgContext.ts +151 -0
- package/src/orgs/orgPermissions.test.ts +105 -0
- package/src/orgs/orgPermissions.ts +40 -0
- package/src/orgs/orgPlugin.test.ts +130 -0
- package/src/orgs/orgPlugin.ts +70 -0
- package/src/orgs/orgRbac.test.ts +267 -0
- package/src/orgs/orgSecurityDefects.test.ts +415 -0
- package/src/orgs/organizationModel.test.ts +205 -0
- package/src/orgs/organizationModel.ts +262 -0
- package/src/orgs/organizationSettings.test.ts +113 -0
- package/src/orgs/organizationSettings.ts +126 -0
- package/src/orgs/orgsApp.test.ts +382 -0
- package/src/orgs/orgsApp.ts +563 -0
- package/src/permissions.test.ts +62 -36
- package/src/permissions.ts +8 -30
- package/src/plugins.test.ts +5 -0
- package/src/plugins.ts +3 -0
- package/src/rateLimit/middleware.ts +1 -1
- package/src/rateLimit/mongoStore.ts +1 -0
- package/src/rateLimit/policies.ts +2 -2
- package/src/rateLimit/redisStore.ts +1 -0
- package/src/rbac/access.ts +11 -3
- package/src/rbac/membershipOrgAdminSource.ts +59 -0
- package/src/rbac/modelRouterAccess.ts +3 -0
- package/src/rbac/permissionUtils.test.ts +26 -5
- package/src/rbac/resolve.test.ts +34 -2
- package/src/rbac/resolve.ts +26 -7
- package/src/rbac/roleModel.test.ts +34 -1
- package/src/rbac/roleModel.ts +17 -1
- package/src/rbac/statements.test.ts +19 -0
- package/src/rbac/statements.ts +19 -1
- package/src/rbac/types.ts +5 -0
- package/src/realtime/changeStreamWatcher.ts +73 -33
- package/src/realtime/deprecation.ts +1 -0
- package/src/realtime/realtime.test.ts +357 -185
- package/src/realtime/realtimeApp.ts +2 -1
- package/src/schemaMetadata.test.ts +14 -0
- package/src/schemaMetadata.ts +5 -5
- package/src/sync/adminBroadcastConfig.test.ts +96 -0
- package/src/sync/adminBroadcastScope.test.ts +155 -0
- package/src/sync/adminBroadcastScope.ts +123 -0
- package/src/sync/adminWindowAccess.test.ts +57 -0
- package/src/sync/adminWindowAccess.ts +32 -0
- package/src/sync/adminWindowMutation.test.ts +450 -0
- package/src/sync/adminWindowMutation.ts +283 -0
- package/src/sync/executors.ts +33 -6
- package/src/sync/integration.test.ts +2 -2
- package/src/sync/mutationHandler.test.ts +277 -1
- package/src/sync/mutationHandler.ts +171 -29
- package/src/sync/registry.ts +4 -0
- package/src/sync/routes.ts +52 -8
- package/src/sync/socketHandlers.ts +154 -58
- package/src/sync/streams.ts +6 -0
- package/src/sync/sync.test.ts +3 -2
- package/src/sync/syncApp.ts +2 -1
- package/src/sync/syncBatch.ts +7 -2
- package/src/sync/syncRoutes.test.ts +297 -3
- package/src/sync/syncSocket.test.ts +229 -0
- package/src/sync/types.ts +20 -0
- package/src/terrenoApp.migrations.test.ts +114 -0
- package/src/terrenoApp.test.ts +41 -0
- package/src/terrenoApp.ts +97 -31
- package/src/tests/createTestData.ts +2 -2
- package/src/tests/models.ts +10 -2
- package/src/tests/testHelper.ts +1 -7
- package/src/types/authToken.ts +2 -4
- package/src/types/mcpServiceToken.ts +1 -7
- package/src/types/membership.ts +48 -0
- package/src/types/notification.ts +34 -0
- package/src/types/notificationPreference.ts +28 -0
- package/src/types/organization.ts +49 -0
- package/src/types.d.ts +1 -0
- package/src/webhooks/idempotency/webhookReceipt.ts +8 -10
- package/src/webhooks/rawBody.test.ts +33 -0
- package/src/webhooks/rawBody.ts +1 -0
- package/tsconfig.json +13 -54
- package/tsconfig.typedoc.json +4 -1
- package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
- package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
- package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
|
@@ -83,29 +83,40 @@ schema.statics = {
|
|
|
83
83
|
- Apply the standard plugins (`createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`) on every new model. Most existing models go through `addDefaultPlugins`.
|
|
84
84
|
- `checkModelsStrict()` runs at non-prod startup (`server.ts`) and validates schema consistency — keep it passing.
|
|
85
85
|
|
|
86
|
+
## Migration files
|
|
87
|
+
|
|
88
|
+
Schema and data changes that must run once per environment belong in
|
|
89
|
+
`migrations/<YYYYMMDDHHmmss>-<slug>.ts` with required `up` and optional `down`.
|
|
90
|
+
Generate a draft with `terreno-migrate generate --dir ./migrations --models ./src/models.ts`,
|
|
91
|
+
then `terreno-migrate up --dir ./migrations --dry` before wet apply.
|
|
92
|
+
See [Run MongoDB migrations](../../../../docs/how-to/run-mongodb-migrations.md).
|
|
93
|
+
|
|
94
|
+
Admin **Scripts** (`ScriptRunner` + `BackgroundTask`) stay for one-off operator
|
|
95
|
+
tools. Do not use Scripts as the primary path for versioned schema backfills.
|
|
96
|
+
|
|
86
97
|
## Schema Change Risk Matrix
|
|
87
98
|
|
|
88
99
|
| Change Type | Risk Level | Required Mitigation |
|
|
89
100
|
|-------------|-----------|---------------------|
|
|
90
101
|
| Add optional field | Low | Safe to ship directly (still requires `description`) |
|
|
91
|
-
| Add required field | High | Must provide a default value, OR write a
|
|
102
|
+
| Add required field | High | Must provide a default value, OR write a versioned migration (`terreno-migrate generate` / `up`) with a backfill before wet apply |
|
|
92
103
|
| Remove field | Medium | Soft-remove first (mark optional, stop writing); hard-remove in next PR after deploys settle |
|
|
93
|
-
| Rename field | High | Three-step: add new → backfill → remove old (separate PRs) |
|
|
94
|
-
| Change field type | Critical | Treat as rename: new field + migration + remove old |
|
|
95
|
-
| Add index | Medium |
|
|
104
|
+
| Rename field | High | Three-step: add new → backfill migration → remove old (separate PRs) |
|
|
105
|
+
| Change field type | Critical | Treat as rename: new field + versioned migration + remove old |
|
|
106
|
+
| Add index | Medium | Prefer `terreno-migrate generate` for the index; build can slow writes on large collections — coordinate with ops |
|
|
96
107
|
| Remove index | Low | Safe to ship directly |
|
|
97
|
-
| Add unique index | High | Dedup
|
|
108
|
+
| Add unique index | High | Dedup in a versioned migration first; otherwise the index build fails on existing duplicates |
|
|
98
109
|
|
|
99
|
-
##
|
|
110
|
+
## One-off admin scripts
|
|
100
111
|
|
|
101
|
-
|
|
112
|
+
Ad-hoc operator tools (counts, reseeds, support fixes) still live as admin
|
|
113
|
+
Scripts using `ScriptRunner` and `BackgroundTask`:
|
|
102
114
|
|
|
103
115
|
```typescript
|
|
104
116
|
import type {ScriptContext, ScriptResult, ScriptRunner} from "@terreno/api";
|
|
105
117
|
|
|
106
118
|
export const run: ScriptRunner = async (wetRun, ctx) => {
|
|
107
119
|
const results: string[] = [];
|
|
108
|
-
// ... do work ...
|
|
109
120
|
if (wetRun) {
|
|
110
121
|
// commit changes
|
|
111
122
|
}
|
|
@@ -113,7 +124,9 @@ export const run: ScriptRunner = async (wetRun, ctx) => {
|
|
|
113
124
|
};
|
|
114
125
|
```
|
|
115
126
|
|
|
116
|
-
Always run with `wetRun = false` first
|
|
127
|
+
Always run with `wetRun = false` first. Use `ctx.checkCancellation()`,
|
|
128
|
+
`ctx.addLog()`, and `ctx.updateProgress()` for long-running tasks. Do not put
|
|
129
|
+
repeatable schema backfills here — use `migrations/` and `terreno-migrate`.
|
|
117
130
|
|
|
118
131
|
## Cross-Package Ripple
|
|
119
132
|
|
|
@@ -131,7 +144,7 @@ A schema change in one place often ripples:
|
|
|
131
144
|
- [ ] For a new model: all five types (`Document`, `Methods`, `Statics`, `Model`, `Schema`) created
|
|
132
145
|
- [ ] Statics/methods assigned directly on schema (`schema.statics = {...}`, `schema.methods = {...}`) — not `.static()` / `.method()`
|
|
133
146
|
- [ ] Other model type files checked — any model that populates this one updated if its shape changed
|
|
134
|
-
- [ ]
|
|
147
|
+
- [ ] Versioned migration written (`migrations/` + `terreno-migrate`) and dry-run verified for any backfill; unique-index dedup runs before the index is added
|
|
135
148
|
- [ ] `modelRouter` config updated (`queryFields`, `populatePaths`, `responseHandler`) if needed
|
|
136
149
|
- [ ] `AdminApp` `listFields` updated if the model is in the admin panel
|
|
137
150
|
- [ ] `bun run sdk` run from `example-frontend/` if the API response shape changed
|
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ model instances.
|
|
|
18
18
|
- **Permissions** — Fine-grained access control (IsAuthenticated, IsOwner, IsAdmin, etc.)
|
|
19
19
|
- **OpenAPI** — Automatic spec generation from models and routes
|
|
20
20
|
- **Logging** — Winston-based logging with scoped & feature-flagged loggers, automatic request correlation, and Google Cloud / Sentry support
|
|
21
|
-
- **HTTP client** — Authenticated axios factory for third-party APIs with token caching, safe retries, and normalized error handling (see [Call external APIs](https://github.com/
|
|
21
|
+
- **HTTP client** — Authenticated axios factory for third-party APIs with token caching, safe retries, and normalized error handling (see [Call external APIs](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/call-external-apis.md))
|
|
22
22
|
|
|
23
23
|
## Install
|
|
24
24
|
|
|
@@ -167,7 +167,7 @@ setupServer({
|
|
|
167
167
|
});
|
|
168
168
|
```
|
|
169
169
|
|
|
170
|
-
**Learn more:** See the [GitHub OAuth how-to guide](https://github.com/
|
|
170
|
+
**Learn more:** See the [GitHub OAuth how-to guide](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/add-github-oauth.md) for complete setup instructions.
|
|
171
171
|
|
|
172
172
|
## Logging
|
|
173
173
|
|
|
@@ -219,7 +219,7 @@ In production, pass a structured transport (e.g. `@google-cloud/logging-winston`
|
|
|
219
219
|
`loggingOptions`/`setupLogging` so the correlation fields and labels reach Log Explorer as
|
|
220
220
|
`jsonPayload`.
|
|
221
221
|
|
|
222
|
-
**Learn more:** See the [Logging & Tracing reference](https://github.com/
|
|
222
|
+
**Learn more:** See the [Logging & Tracing reference](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/api.md#logging--tracing) for
|
|
223
223
|
the full API, label conventions, and Google Cloud Logging / Sentry details.
|
|
224
224
|
|
|
225
225
|
## Sentry
|
|
@@ -227,6 +227,12 @@ To enable Sentry, create a "src/sentryInstrumment.ts" file in your project.
|
|
|
227
227
|
|
|
228
228
|
> **Note:** Bun automatically loads `.env` files before your code runs, so there's no need for `dotenv`. Just place a `.env` file in your project root and `process.env` will have your variables available immediately. See [Bun .env docs](https://bun.sh/docs/runtime/env).
|
|
229
229
|
|
|
230
|
+
Install both SDK packages in the consuming backend:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
bun add @sentry/bun @sentry/profiling-node
|
|
234
|
+
```
|
|
235
|
+
|
|
230
236
|
```
|
|
231
237
|
import * as Sentry from "@sentry/bun";
|
|
232
238
|
import {nodeProfilingIntegration} from "@sentry/profiling-node";
|
|
@@ -293,8 +299,8 @@ A lot of dev may require using bun link. You'll want to keep the `bun run dev` w
|
|
|
293
299
|
|
|
294
300
|
## Documentation
|
|
295
301
|
|
|
296
|
-
Full API reference: [docs/reference/api.md](https://github.com/
|
|
302
|
+
Full API reference: [docs/reference/api.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/api.md)
|
|
297
303
|
|
|
298
304
|
## License and Contributing
|
|
299
305
|
|
|
300
|
-
Licensed under the [MIT License](https://github.com/
|
|
306
|
+
Licensed under the [MIT License](https://github.com/TerrenoLabs/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/TerrenoLabs/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.
|
package/bunfig.toml
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
preload = ["./src/tests/testEnv.ts", "./src/tests/bunSetup.ts"]
|
|
3
3
|
root = "./src"
|
|
4
4
|
coverage = true
|
|
5
|
-
coveragePathIgnorePatterns = ["dist/**", "**/*.test.ts", "**/tests/**", "**/vendor/**", "../**"]
|
|
5
|
+
coveragePathIgnorePatterns = ["dist/**", "**/*.test.ts", "**/*.isolated.ts", "**/isolated/**", "**/tests/**", "**/vendor/**", "../**"]
|
|
6
6
|
# Enforced by scripts/check-coverage.ts; Bun parses this key but does not
|
|
7
7
|
# fail the run when coverage is below threshold. See
|
|
8
8
|
# https://github.com/oven-sh/bun/issues/7367 and https://github.com/oven-sh/bun/pull/27933.
|