@terreno/api 57.2.0 → 57.3.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.
Files changed (277) hide show
  1. package/README.md +17 -7
  2. package/dist/actions.js +19 -7
  3. package/dist/api.d.ts +4 -0
  4. package/dist/api.js +12 -24
  5. package/dist/auth.d.ts +23 -10
  6. package/dist/auth.js +97 -32
  7. package/dist/authRecovery.d.ts +5 -0
  8. package/dist/authRecovery.js +350 -0
  9. package/dist/authTokens.d.ts +8 -0
  10. package/dist/authTokens.js +162 -0
  11. package/dist/betterAuth.d.ts +33 -0
  12. package/dist/betterAuthApp.d.ts +4 -0
  13. package/dist/betterAuthApp.js +26 -8
  14. package/dist/betterAuthSetup.d.ts +44 -2
  15. package/dist/betterAuthSetup.js +288 -18
  16. package/dist/collectionRegistry.d.ts +38 -0
  17. package/dist/collectionRegistry.js +72 -0
  18. package/dist/configurationApp.d.ts +11 -2
  19. package/dist/configurationApp.js +2 -4
  20. package/dist/docLoader.js +35 -6
  21. package/dist/expressServer.d.ts +26 -3
  22. package/dist/expressServer.js +79 -11
  23. package/dist/index.d.ts +16 -0
  24. package/dist/index.js +38 -2
  25. package/dist/mcp/auth.d.ts +1 -0
  26. package/dist/mcp/auth.js +47 -25
  27. package/dist/mcp/handlers.d.ts +1 -1
  28. package/dist/mcp/handlers.js +67 -233
  29. package/dist/mcp/query.d.ts +2 -2
  30. package/dist/mcp/registry.d.ts +1 -5
  31. package/dist/mcp/registry.js +31 -20
  32. package/dist/mcp/schemaGenerator.d.ts +2 -7
  33. package/dist/mcp/schemaGenerator.js +41 -116
  34. package/dist/mcp/server.d.ts +1 -0
  35. package/dist/mcp/server.js +1 -0
  36. package/dist/mcp/serviceTokens.d.ts +16 -0
  37. package/dist/mcp/serviceTokens.js +345 -0
  38. package/dist/mcp/types.d.ts +2 -2
  39. package/dist/models/mcpServiceToken.d.ts +3 -0
  40. package/dist/models/mcpServiceToken.js +208 -0
  41. package/dist/openApiBuilder.d.ts +5 -4
  42. package/dist/openApiBuilder.js +61 -8
  43. package/dist/openApiCompat.js +1 -1
  44. package/dist/openApiValidator.js +0 -2
  45. package/dist/plugins.d.ts +14 -1
  46. package/dist/plugins.js +17 -6
  47. package/dist/populate.d.ts +2 -2
  48. package/dist/populate.js +47 -42
  49. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  50. package/dist/rateLimit/applyTrustProxy.js +17 -0
  51. package/dist/rateLimit/createStore.d.ts +2 -0
  52. package/dist/rateLimit/createStore.js +28 -0
  53. package/dist/rateLimit/memoryStore.d.ts +2 -0
  54. package/dist/rateLimit/memoryStore.js +108 -0
  55. package/dist/rateLimit/middleware.d.ts +11 -0
  56. package/dist/rateLimit/middleware.js +110 -0
  57. package/dist/rateLimit/mongoStore.d.ts +3 -0
  58. package/dist/rateLimit/mongoStore.js +122 -0
  59. package/dist/rateLimit/policies.d.ts +14 -0
  60. package/dist/rateLimit/policies.js +151 -0
  61. package/dist/rateLimit/redisStore.d.ts +3 -0
  62. package/dist/rateLimit/redisStore.js +155 -0
  63. package/dist/rateLimit/types.d.ts +54 -0
  64. package/dist/rateLimit/types.js +9 -0
  65. package/dist/rbac/access.js +5 -1
  66. package/dist/rbac/assertAllowed.d.ts +9 -0
  67. package/dist/rbac/assertAllowed.js +182 -0
  68. package/dist/rbac/modelRouterAccess.d.ts +1 -0
  69. package/dist/rbac/modelRouterAccess.js +8 -4
  70. package/dist/rbac/permissionUtils.js +3 -2
  71. package/dist/rbac/resolve.js +5 -4
  72. package/dist/rbac/routes.js +15 -6
  73. package/dist/realtime/deprecation.d.ts +12 -0
  74. package/dist/realtime/deprecation.js +32 -0
  75. package/dist/realtime/realtimeApp.d.ts +1 -1
  76. package/dist/realtime/realtimeApp.js +10 -11
  77. package/dist/realtime/registry.d.ts +0 -31
  78. package/dist/realtime/registry.js +44 -31
  79. package/dist/realtime/socketAuth.d.ts +5 -5
  80. package/dist/realtime/socketAuth.js +11 -1
  81. package/dist/realtime/socketUser.d.ts +5 -1
  82. package/dist/realtime/types.d.ts +14 -4
  83. package/dist/schemaMetadata.d.ts +56 -0
  84. package/dist/schemaMetadata.js +513 -0
  85. package/dist/seedRunner.d.ts +88 -0
  86. package/dist/seedRunner.js +627 -0
  87. package/dist/sync/executors.d.ts +12 -2
  88. package/dist/sync/executors.js +8 -10
  89. package/dist/sync/loadHarness.js +28 -19
  90. package/dist/sync/models.js +26 -24
  91. package/dist/sync/mutationHandler.d.ts +9 -0
  92. package/dist/sync/mutationHandler.js +11 -6
  93. package/dist/sync/registrationSideEffects.d.ts +35 -0
  94. package/dist/sync/registrationSideEffects.js +151 -0
  95. package/dist/sync/registry.d.ts +2 -52
  96. package/dist/sync/registry.js +38 -187
  97. package/dist/sync/routes.js +3 -2
  98. package/dist/sync/scripts/compactTombstones.js +0 -2
  99. package/dist/sync/syncApp.d.ts +3 -3
  100. package/dist/sync/syncApp.js +4 -4
  101. package/dist/sync/syncBatch.js +3 -2
  102. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  103. package/dist/sync/syncSeqPlugin.js +20 -16
  104. package/dist/terrenoApp.d.ts +19 -5
  105. package/dist/terrenoApp.js +66 -18
  106. package/dist/tests/models.d.ts +2 -0
  107. package/dist/tests/models.js +6 -0
  108. package/dist/types/authToken.d.ts +33 -0
  109. package/dist/types/authToken.js +2 -0
  110. package/dist/types/mcpServiceToken.d.ts +41 -0
  111. package/dist/types/mcpServiceToken.js +2 -0
  112. package/dist/webhooks/headerValue.d.ts +2 -0
  113. package/dist/webhooks/headerValue.js +14 -0
  114. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  115. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  116. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  117. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  118. package/dist/webhooks/idempotency/webhookReceipt.d.ts +62 -0
  119. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  120. package/dist/webhooks/rawBody.d.ts +14 -0
  121. package/dist/webhooks/rawBody.js +22 -0
  122. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  123. package/dist/webhooks/timingSafeEqual.js +17 -0
  124. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  125. package/dist/webhooks/verifiers/hmac.js +49 -0
  126. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  127. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  128. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  129. package/dist/webhooks/verifiers/stripe.js +99 -0
  130. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  131. package/dist/webhooks/verifiers/twilio.js +112 -0
  132. package/dist/webhooks/webhooksApp.d.ts +33 -0
  133. package/dist/webhooks/webhooksApp.js +195 -0
  134. package/package.json +4 -5
  135. package/src/__snapshots__/openApi.test.ts.snap +270 -0
  136. package/src/__snapshots__/openApiBuilder.test.ts.snap +30 -12
  137. package/src/__snapshots__/schemaMetadata.test.ts.snap +197 -0
  138. package/src/actions.ts +20 -13
  139. package/src/adminModelRouter.test.ts +133 -0
  140. package/src/api.arrayOperations.test.ts +43 -31
  141. package/src/api.hooks.test.ts +38 -29
  142. package/src/api.query.test.ts +31 -31
  143. package/src/api.test.ts +95 -96
  144. package/src/api.ts +16 -27
  145. package/src/auth.test.ts +107 -51
  146. package/src/auth.ts +98 -29
  147. package/src/authRecovery.test.ts +281 -0
  148. package/src/authRecovery.ts +279 -0
  149. package/src/authTokens.test.ts +94 -0
  150. package/src/authTokens.ts +118 -0
  151. package/src/authVerification.test.ts +293 -0
  152. package/src/betterAuth.ts +24 -0
  153. package/src/betterAuthApp.test.ts +1 -0
  154. package/src/betterAuthApp.ts +27 -9
  155. package/src/betterAuthSetup.test.ts +568 -38
  156. package/src/betterAuthSetup.ts +260 -5
  157. package/src/collectionRegistry.test.ts +165 -0
  158. package/src/collectionRegistry.ts +115 -0
  159. package/src/configurationApp.ts +13 -7
  160. package/src/docLoader.test.ts +45 -1
  161. package/src/docLoader.ts +37 -6
  162. package/src/express.d.ts +1 -0
  163. package/src/expressServer.test.ts +130 -66
  164. package/src/expressServer.ts +75 -19
  165. package/src/githubAuth.test.ts +60 -55
  166. package/src/index.ts +58 -0
  167. package/src/mcp/auth.test.ts +47 -0
  168. package/src/mcp/auth.ts +32 -11
  169. package/src/mcp/handlers.ts +45 -172
  170. package/src/mcp/integration.test.ts +59 -9
  171. package/src/mcp/query.ts +2 -4
  172. package/src/mcp/registry.ts +29 -20
  173. package/src/mcp/schemaGenerator.test.ts +8 -0
  174. package/src/mcp/schemaGenerator.ts +49 -131
  175. package/src/mcp/server.ts +2 -0
  176. package/src/mcp/serviceTokens.test.ts +330 -0
  177. package/src/mcp/serviceTokens.ts +307 -0
  178. package/src/mcp/toolGenerator.test.ts +1 -1
  179. package/src/mcp/types.ts +2 -6
  180. package/src/models/mcpServiceToken.test.ts +129 -0
  181. package/src/models/mcpServiceToken.ts +158 -0
  182. package/src/openApi.test.ts +80 -64
  183. package/src/openApiBuilder.test.ts +95 -7
  184. package/src/openApiBuilder.ts +46 -9
  185. package/src/openApiCompat.ts +1 -1
  186. package/src/openApiValidator.test.ts +49 -54
  187. package/src/openApiValidator.ts +1 -3
  188. package/src/plugins.test.ts +14 -0
  189. package/src/plugins.ts +34 -9
  190. package/src/populate.test.ts +34 -0
  191. package/src/populate.ts +40 -29
  192. package/src/rateLimit/applyTrustProxy.ts +17 -0
  193. package/src/rateLimit/createStore.ts +25 -0
  194. package/src/rateLimit/memoryStore.ts +40 -0
  195. package/src/rateLimit/middleware.ts +79 -0
  196. package/src/rateLimit/mongoStore.test.ts +80 -0
  197. package/src/rateLimit/mongoStore.ts +76 -0
  198. package/src/rateLimit/policies.ts +130 -0
  199. package/src/rateLimit/rateLimit.test.ts +328 -0
  200. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  201. package/src/rateLimit/redisStore.test.ts +114 -0
  202. package/src/rateLimit/redisStore.ts +85 -0
  203. package/src/rateLimit/types.ts +64 -0
  204. package/src/rbac/access.ts +5 -1
  205. package/src/rbac/assertAllowed.test.ts +325 -0
  206. package/src/rbac/assertAllowed.ts +157 -0
  207. package/src/rbac/backfillAdmins.test.ts +124 -0
  208. package/src/rbac/fieldViews.test.ts +89 -0
  209. package/src/rbac/modelRouterAccess.test.ts +126 -0
  210. package/src/rbac/modelRouterAccess.ts +5 -2
  211. package/src/rbac/permissionUtils.ts +3 -2
  212. package/src/rbac/realtimeAccess.test.ts +109 -1
  213. package/src/rbac/resolve.ts +5 -4
  214. package/src/rbac/roleManager.test.ts +169 -0
  215. package/src/rbac/routes.test.ts +233 -0
  216. package/src/rbac/routes.ts +16 -6
  217. package/src/realtime/deprecation.test.ts +60 -0
  218. package/src/realtime/deprecation.ts +32 -0
  219. package/src/realtime/realtime.test.ts +8 -4
  220. package/src/realtime/realtimeApp.ts +10 -11
  221. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  222. package/src/realtime/registry.ts +48 -42
  223. package/src/realtime/sessionRevalidation.test.ts +57 -44
  224. package/src/realtime/socketAuth.test.ts +75 -23
  225. package/src/realtime/socketAuth.ts +17 -6
  226. package/src/realtime/socketUser.ts +5 -3
  227. package/src/realtime/types.ts +14 -4
  228. package/src/schemaMetadata.test.ts +405 -0
  229. package/src/schemaMetadata.ts +593 -0
  230. package/src/scrubAdminFields.test.ts +105 -0
  231. package/src/seedRunner.test.ts +591 -0
  232. package/src/seedRunner.ts +464 -0
  233. package/src/sync/docMatchesMutationData.test.ts +16 -0
  234. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  235. package/src/sync/executors.test.ts +40 -0
  236. package/src/sync/executors.ts +24 -12
  237. package/src/sync/integration.test.ts +15 -7
  238. package/src/sync/loadHarness.ts +28 -19
  239. package/src/sync/models.ts +32 -18
  240. package/src/sync/mutationHandler.test.ts +16 -16
  241. package/src/sync/mutationHandler.ts +9 -7
  242. package/src/sync/registrationSideEffects.test.ts +126 -0
  243. package/src/sync/registrationSideEffects.ts +131 -0
  244. package/src/sync/registry.ts +45 -171
  245. package/src/sync/routes.ts +3 -2
  246. package/src/sync/scripts/compactTombstones.ts +0 -2
  247. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  248. package/src/sync/sync.test.ts +25 -23
  249. package/src/sync/syncApp.ts +4 -4
  250. package/src/sync/syncBatch.ts +3 -2
  251. package/src/sync/syncFrontier.test.ts +17 -15
  252. package/src/sync/syncPhaseC.test.ts +54 -43
  253. package/src/sync/syncRoutes.test.ts +51 -36
  254. package/src/sync/syncSeqPlugin.ts +66 -44
  255. package/src/sync/syncSocket.test.ts +112 -81
  256. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  257. package/src/terrenoApp.ts +87 -15
  258. package/src/tests/models.ts +14 -1
  259. package/src/types/authToken.ts +43 -0
  260. package/src/types/mcpServiceToken.ts +54 -0
  261. package/src/webhooks/headerValue.test.ts +22 -0
  262. package/src/webhooks/headerValue.ts +12 -0
  263. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  264. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  265. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  266. package/src/webhooks/idempotency/webhookReceipt.ts +70 -0
  267. package/src/webhooks/rawBody.test.ts +74 -0
  268. package/src/webhooks/rawBody.ts +23 -0
  269. package/src/webhooks/timingSafeEqual.ts +16 -0
  270. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  271. package/src/webhooks/verifiers/hmac.ts +54 -0
  272. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  273. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  274. package/src/webhooks/verifiers/stripe.ts +67 -0
  275. package/src/webhooks/verifiers/twilio.ts +69 -0
  276. package/src/webhooks/webhooksApp.test.ts +221 -0
  277. package/src/webhooks/webhooksApp.ts +144 -0
@@ -0,0 +1,464 @@
1
+ import isEqual from "lodash/isEqual";
2
+
3
+ import type {UserModel} from "./auth";
4
+ import type {BetterAuthUser} from "./betterAuth";
5
+ import {type BetterAuthInstance, syncBetterAuthUser} from "./betterAuthSetup";
6
+ import {APIError, errorMessage} from "./errors";
7
+ import {logger, type ScopedLogger} from "./logger";
8
+
9
+ export type SeedMode = "reset" | "sync";
10
+ export type SeedChange = "created" | "deleted" | "unchanged" | "updated";
11
+
12
+ interface SeedDocument {
13
+ get: (path: string) => unknown;
14
+ save: () => Promise<unknown>;
15
+ set: (pathOrValues: object, value?: unknown) => unknown;
16
+ }
17
+
18
+ /** The small structural subset of a Mongoose model used by seed helpers. */
19
+ export interface SeedModel {
20
+ new (): SeedDocument;
21
+ modelName: string;
22
+ countDocuments: (filter: Record<string, unknown>) => PromiseLike<number>;
23
+ deleteMany: (filter: Record<string, unknown>) => PromiseLike<unknown>;
24
+ find: (filter: Record<string, unknown>) => {
25
+ limit: (limit: number) => PromiseLike<SeedDocument[]>;
26
+ };
27
+ }
28
+
29
+ export interface SeedChangeResult {
30
+ change: SeedChange;
31
+ count: number;
32
+ key: string;
33
+ model: string;
34
+ }
35
+
36
+ export interface SeedContext {
37
+ dryRun: boolean;
38
+ mode: SeedMode;
39
+ changes: SeedChangeResult[];
40
+ deleteMany: (model: SeedModel, filter?: Record<string, unknown>) => Promise<SeedChangeResult>;
41
+ upsert: <TValues extends object>(
42
+ model: SeedModel,
43
+ key: Record<string, unknown>,
44
+ values: TValues
45
+ ) => Promise<SeedChangeResult>;
46
+ }
47
+
48
+ export interface SeedStep {
49
+ name: string;
50
+ description?: string;
51
+ dependsOn?: string[];
52
+ reset?: (context: SeedContext) => Promise<void>;
53
+ run: (context: SeedContext) => Promise<void>;
54
+ }
55
+
56
+ export interface SeedRunOptions {
57
+ name: string;
58
+ steps: SeedStep[];
59
+ mode?: SeedMode;
60
+ dryRun?: boolean;
61
+ only?: string[];
62
+ force?: boolean;
63
+ allowProductionReset?: boolean | (() => boolean | Promise<boolean>);
64
+ connect?: () => Promise<void>;
65
+ disconnect?: () => Promise<void>;
66
+ log?: ScopedLogger;
67
+ }
68
+
69
+ export interface SeedRunResult {
70
+ changes: SeedChangeResult[];
71
+ dryRun: boolean;
72
+ mode: SeedMode;
73
+ name: string;
74
+ steps: string[];
75
+ summary: Record<SeedChange, number>;
76
+ success: boolean;
77
+ }
78
+
79
+ export interface SeedCliOptions extends Omit<SeedRunOptions, "dryRun" | "force" | "mode" | "only"> {
80
+ argv?: string[];
81
+ }
82
+
83
+ export interface SeedCliResult {
84
+ exitCode: number;
85
+ help?: string;
86
+ result?: SeedRunResult;
87
+ }
88
+
89
+ export interface BetterAuthSeedUser {
90
+ email: string;
91
+ name: string;
92
+ password: string;
93
+ }
94
+
95
+ const EMPTY_SUMMARY: Record<SeedChange, number> = {
96
+ created: 0,
97
+ deleted: 0,
98
+ unchanged: 0,
99
+ updated: 0,
100
+ };
101
+
102
+ const formatKey = (key: Record<string, unknown>): string => {
103
+ return JSON.stringify(key);
104
+ };
105
+
106
+ const toComparableSeedValue = (value: unknown): unknown => {
107
+ if (value == null) {
108
+ return value;
109
+ }
110
+ if (value instanceof Date) {
111
+ return value.toISOString();
112
+ }
113
+ if (value instanceof Map) {
114
+ return Object.fromEntries(
115
+ [...value.entries()].map(([entryKey, nested]) => [
116
+ String(entryKey),
117
+ toComparableSeedValue(nested),
118
+ ])
119
+ );
120
+ }
121
+ if (typeof (value as {toObject?: () => unknown}).toObject === "function") {
122
+ return toComparableSeedValue((value as {toObject: () => unknown}).toObject());
123
+ }
124
+ if (Array.isArray(value)) {
125
+ return value.map(toComparableSeedValue);
126
+ }
127
+ if (typeof value === "object") {
128
+ const next: Record<string, unknown> = {};
129
+ for (const [field, nested] of Object.entries(value as Record<string, unknown>)) {
130
+ if (field === "_id") {
131
+ continue;
132
+ }
133
+ next[field] = toComparableSeedValue(nested);
134
+ }
135
+ return next;
136
+ }
137
+ return value;
138
+ };
139
+
140
+ const seedValuesEqual = (currentValues: unknown, nextValues: unknown): boolean => {
141
+ return isEqual(toComparableSeedValue(currentValues), toComparableSeedValue(nextValues));
142
+ };
143
+
144
+ /**
145
+ * Create a Better Auth credential user when missing, verify existing credentials,
146
+ * and reconcile the corresponding application user document.
147
+ */
148
+ export const seedBetterAuthUser = async ({
149
+ auth,
150
+ user,
151
+ userModel,
152
+ }: {
153
+ auth: BetterAuthInstance;
154
+ user: BetterAuthSeedUser;
155
+ userModel: UserModel;
156
+ }): Promise<Awaited<ReturnType<typeof syncBetterAuthUser>>> => {
157
+ let authUser: BetterAuthUser | undefined;
158
+ try {
159
+ const result = await auth.api.signUpEmail({body: user});
160
+ authUser = result.user as BetterAuthUser;
161
+ } catch {
162
+ const result = await auth.api.signInEmail({
163
+ body: {email: user.email, password: user.password},
164
+ });
165
+ authUser = result.user as BetterAuthUser;
166
+ }
167
+ if (!authUser) {
168
+ throw new APIError({
169
+ detail: user.email,
170
+ status: 500,
171
+ title: "Better Auth seed returned no user",
172
+ });
173
+ }
174
+ return syncBetterAuthUser(userModel, authUser);
175
+ };
176
+
177
+ const selectSteps = (steps: SeedStep[], only?: string[]): SeedStep[] => {
178
+ const stepByName = new Map(steps.map((step) => [step.name, step]));
179
+ if (stepByName.size !== steps.length) {
180
+ throw new APIError({status: 500, title: "Seed step names must be unique"});
181
+ }
182
+ if (!only || only.length === 0) {
183
+ return steps;
184
+ }
185
+
186
+ const selectedNames = new Set<string>();
187
+ const include = (name: string, ancestry: string[] = []): void => {
188
+ const step = stepByName.get(name);
189
+ if (!step) {
190
+ throw new APIError({
191
+ detail: `Unknown seed step "${name}". Available steps: ${steps.map((item) => item.name).join(", ")}`,
192
+ status: 400,
193
+ title: "Unknown seed step",
194
+ });
195
+ }
196
+ if (ancestry.includes(name)) {
197
+ throw new APIError({
198
+ detail: [...ancestry, name].join(" -> "),
199
+ status: 500,
200
+ title: "Seed step dependency cycle",
201
+ });
202
+ }
203
+ if (selectedNames.has(name)) {
204
+ return;
205
+ }
206
+ for (const dependency of step.dependsOn ?? []) {
207
+ include(dependency, [...ancestry, name]);
208
+ }
209
+ selectedNames.add(name);
210
+ };
211
+
212
+ for (const name of only) {
213
+ include(name);
214
+ }
215
+ return steps.filter((step) => selectedNames.has(step.name));
216
+ };
217
+
218
+ const isProductionResetAllowed = async ({
219
+ allowProductionReset,
220
+ force,
221
+ }: Pick<SeedRunOptions, "allowProductionReset" | "force">): Promise<boolean> => {
222
+ if (process.env.NODE_ENV !== "production") {
223
+ return true;
224
+ }
225
+ if (!force || allowProductionReset === undefined) {
226
+ return false;
227
+ }
228
+ return typeof allowProductionReset === "function"
229
+ ? await allowProductionReset()
230
+ : allowProductionReset;
231
+ };
232
+
233
+ const makeContext = ({dryRun, mode}: {dryRun: boolean; mode: SeedMode}): SeedContext => {
234
+ const changes: SeedChangeResult[] = [];
235
+ const record = (change: SeedChangeResult): SeedChangeResult => {
236
+ changes.push(change);
237
+ return change;
238
+ };
239
+
240
+ return {
241
+ changes,
242
+ deleteMany: async (
243
+ model: SeedModel,
244
+ filter: Record<string, unknown> = {}
245
+ ): Promise<SeedChangeResult> => {
246
+ const count = await model.countDocuments(filter);
247
+ if (!dryRun && count > 0) {
248
+ await model.deleteMany(filter);
249
+ }
250
+ return record({
251
+ change: count > 0 ? "deleted" : "unchanged",
252
+ count,
253
+ key: formatKey(filter),
254
+ model: model.modelName,
255
+ });
256
+ },
257
+ dryRun,
258
+ mode,
259
+ upsert: async <TValues extends object>(
260
+ model: SeedModel,
261
+ key: Record<string, unknown>,
262
+ values: TValues
263
+ ): Promise<SeedChangeResult> => {
264
+ const findByKey = async (filter: Record<string, unknown>): Promise<SeedDocument[]> => {
265
+ return [...(await model.find(filter).limit(100))];
266
+ };
267
+
268
+ let documents = await findByKey(key);
269
+ if (documents.length === 0) {
270
+ documents = await findByKey({...key, deleted: true});
271
+ }
272
+
273
+ const extras = documents.slice(1);
274
+ if (extras.length > 0) {
275
+ if (!dryRun) {
276
+ for (const extra of extras) {
277
+ const extraDeleted = extra.get("deleted");
278
+ if (extraDeleted === true || extraDeleted === false) {
279
+ extra.set({deleted: true});
280
+ await extra.save();
281
+ } else {
282
+ await model.deleteMany({_id: extra.get("_id")});
283
+ }
284
+ }
285
+ }
286
+ record({
287
+ change: "deleted",
288
+ count: extras.length,
289
+ key: formatKey(key),
290
+ model: model.modelName,
291
+ });
292
+ }
293
+
294
+ const document = documents[0];
295
+ if (!document) {
296
+ if (!dryRun) {
297
+ const createdDocument = new model();
298
+ createdDocument.set(key);
299
+ createdDocument.set(values);
300
+ await createdDocument.save();
301
+ }
302
+ return record({
303
+ change: "created",
304
+ count: 1,
305
+ key: formatKey(key),
306
+ model: model.modelName,
307
+ });
308
+ }
309
+
310
+ const isDeleted = document.get("deleted") === true;
311
+ const currentValues = Object.fromEntries(
312
+ Object.keys(values).map((field) => [field, document.get(field)])
313
+ );
314
+ if (!isDeleted && seedValuesEqual(currentValues, values)) {
315
+ return record({
316
+ change: "unchanged",
317
+ count: 1,
318
+ key: formatKey(key),
319
+ model: model.modelName,
320
+ });
321
+ }
322
+ if (!dryRun) {
323
+ document.set(isDeleted ? {...values, deleted: false} : values);
324
+ await document.save();
325
+ }
326
+ return record({
327
+ change: "updated",
328
+ count: 1,
329
+ key: formatKey(key),
330
+ model: model.modelName,
331
+ });
332
+ },
333
+ };
334
+ };
335
+
336
+ const summarizeChanges = (changes: SeedChangeResult[]): Record<SeedChange, number> => {
337
+ const summary = {...EMPTY_SUMMARY};
338
+ for (const item of changes) {
339
+ summary[item.change] += item.count;
340
+ }
341
+ return summary;
342
+ };
343
+
344
+ /** Run an ordered, idempotent seed plan in sync or reset-and-reseed mode. */
345
+ export const runSeeds = async (options: SeedRunOptions): Promise<SeedRunResult> => {
346
+ const mode = options.mode ?? "sync";
347
+ const dryRun = options.dryRun ?? false;
348
+ const log = options.log ?? logger;
349
+ const steps = selectSteps(options.steps, options.only);
350
+ if (
351
+ mode === "reset" &&
352
+ !(await isProductionResetAllowed({
353
+ allowProductionReset: options.allowProductionReset,
354
+ force: options.force,
355
+ }))
356
+ ) {
357
+ throw new APIError({
358
+ detail:
359
+ "Production resets require force: true and allowProductionReset: true (or an approving callback).",
360
+ status: 403,
361
+ title: "Production seed reset is disabled",
362
+ });
363
+ }
364
+
365
+ const context = makeContext({dryRun, mode});
366
+ await options.connect?.();
367
+ try {
368
+ log.info(
369
+ `${dryRun ? "Previewing" : "Running"} ${options.name} seeds in ${mode} mode (${steps.length} step(s))`
370
+ );
371
+ if (mode === "reset") {
372
+ for (const step of [...steps].reverse()) {
373
+ await step.reset?.(context);
374
+ }
375
+ }
376
+ for (const step of steps) {
377
+ log.info(`Seed step: ${step.name}`);
378
+ await step.run(context);
379
+ }
380
+ const summary = summarizeChanges(context.changes);
381
+ log.info(
382
+ `Seed complete: created=${summary.created} updated=${summary.updated} deleted=${summary.deleted} unchanged=${summary.unchanged}`
383
+ );
384
+ return {
385
+ changes: context.changes,
386
+ dryRun,
387
+ mode,
388
+ name: options.name,
389
+ steps: steps.map((step) => step.name),
390
+ success: true,
391
+ summary,
392
+ };
393
+ } finally {
394
+ await options.disconnect?.();
395
+ }
396
+ };
397
+
398
+ const seedHelp = (name: string, steps: SeedStep[]): string => {
399
+ return [
400
+ `Usage: ${name} [--reset] [--dry-run] [--only <step>] [--force]`,
401
+ "",
402
+ "Modes:",
403
+ " (default) Sync code-defined seed data into the database",
404
+ " --reset Run step reset handlers in reverse order, then reseed",
405
+ "",
406
+ "Options:",
407
+ " --dry-run Report changes without writing",
408
+ " --only Run one step plus its dependencies; may be repeated",
409
+ " --force Required with an explicitly allowed production reset",
410
+ " --help Show this help",
411
+ "",
412
+ `Steps: ${steps.map((step) => step.name).join(", ")}`,
413
+ ].join("\n");
414
+ };
415
+
416
+ const readRepeatedOption = (argv: string[], name: string): string[] => {
417
+ const values: string[] = [];
418
+ for (let index = 0; index < argv.length; index++) {
419
+ const token = argv[index];
420
+ if (token === `--${name}` && argv[index + 1]) {
421
+ values.push(argv[index + 1]);
422
+ index++;
423
+ continue;
424
+ }
425
+ if (token.startsWith(`--${name}=`)) {
426
+ values.push(token.slice(name.length + 3));
427
+ }
428
+ }
429
+ return values;
430
+ };
431
+
432
+ /** CLI adapter for runSeeds. It returns an exit code and never terminates the process. */
433
+ export const runSeedCli = async (options: SeedCliOptions): Promise<SeedCliResult> => {
434
+ const argv = options.argv ?? process.argv.slice(2);
435
+ const help = seedHelp(options.name, options.steps);
436
+ if (argv.includes("--help") || argv.includes("-h")) {
437
+ return {exitCode: 0, help};
438
+ }
439
+ const knownOptions = new Set(["--dry-run", "--force", "--help", "-h", "--only", "--reset"]);
440
+ const unknown = argv.filter(
441
+ (token, index) =>
442
+ token.startsWith("-") &&
443
+ !knownOptions.has(token) &&
444
+ !token.startsWith("--only=") &&
445
+ argv[index - 1] !== "--only"
446
+ );
447
+ if (unknown.length > 0) {
448
+ return {exitCode: 2, help: `Unknown option(s): ${unknown.join(", ")}\n\n${help}`};
449
+ }
450
+
451
+ try {
452
+ const result = await runSeeds({
453
+ ...options,
454
+ dryRun: argv.includes("--dry-run"),
455
+ force: argv.includes("--force"),
456
+ mode: argv.includes("--reset") ? "reset" : "sync",
457
+ only: readRepeatedOption(argv, "only"),
458
+ });
459
+ return {exitCode: 0, result};
460
+ } catch (error: unknown) {
461
+ (options.log ?? logger).error(`Seed failed: ${errorMessage(error)}`);
462
+ return {exitCode: 1};
463
+ }
464
+ };
@@ -0,0 +1,16 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import {DateTime} from "luxon";
3
+
4
+ import {docMatchesMutationData} from "./mutationHandler";
5
+
6
+ describe("docMatchesMutationData date compare", () => {
7
+ it("treats date-only ISO strings as UTC midnight like Date parsing", () => {
8
+ const stored = DateTime.fromISO("2024-01-15T00:00:00.000Z", {zone: "utc"}).toJSDate();
9
+ expect(docMatchesMutationData({due: stored}, {due: "2024-01-15"})).toBe(true);
10
+ });
11
+
12
+ it("returns false for invalid date strings instead of throwing", () => {
13
+ const stored = DateTime.fromISO("2024-01-15T00:00:00.000Z", {zone: "utc"}).toJSDate();
14
+ expect(docMatchesMutationData({due: stored}, {due: "not-a-date"})).toBe(false);
15
+ });
16
+ });
@@ -1,9 +1,9 @@
1
- // noExplicitAny: test model typing
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test model typing
3
1
  import {beforeEach, describe, expect, it} from "bun:test";
2
+ import {assert} from "chai";
4
3
  import express from "express";
5
4
  import {model, Schema} from "mongoose";
6
5
  import type {ModelRouterOptions} from "../api";
6
+ import {APIError} from "../errors";
7
7
  import {Permissions} from "../permissions";
8
8
  import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
9
9
  import {setupDb} from "../tests";
@@ -21,7 +21,8 @@ import {syncPlugin} from "./syncSeqPlugin";
21
21
  * (`SyncCounter.stream` / `SyncMutation.mutationId` uniques, the scope-move lookups,
22
22
  * `SyncKey.userId`), so they exist after startup without any manual `ensureIndexes()`
23
23
  * call — without the unique indexes, duplicate mutation deliveries double-apply and the
24
- * counter upsert race mints duplicate seqs.
24
+ * counter upsert race mints duplicate seqs. Index work must remain deferred until this
25
+ * function runs because model registration can happen before MongoDB connects.
25
26
  */
26
27
 
27
28
  interface IndexTodo extends IsDeleted {
@@ -50,7 +51,7 @@ const authedOptions = {
50
51
  read: [Permissions.IsAuthenticated],
51
52
  update: [Permissions.IsAuthenticated],
52
53
  },
53
- } as unknown as ModelRouterOptions<any>;
54
+ } as unknown as ModelRouterOptions<IndexTodo>;
54
55
 
55
56
  describe("ensureSyncIndexes (C8)", () => {
56
57
  beforeEach(() => {
@@ -65,28 +66,58 @@ describe("ensureSyncIndexes (C8)", () => {
65
66
  const IndexTodoModel = buildModel("EnsureIndexTodoOk");
66
67
  registerSync({
67
68
  config: {scope: {type: "owner"}},
68
- model: IndexTodoModel as any,
69
+ model: IndexTodoModel,
69
70
  options: authedOptions,
70
71
  routePath: "/ensureIndexTodosOk",
71
72
  });
72
73
  await expect(ensureSyncIndexes()).resolves.toBeUndefined();
73
74
  });
74
75
 
76
+ it("defers snapshot index creation until startup ensures indexes", async () => {
77
+ const IndexTodoModel = buildModel("EnsureIndexTodoDeferred");
78
+ let createIndexCalls = 0;
79
+ IndexTodoModel.collection.createIndex = async (): Promise<string> => {
80
+ createIndexCalls += 1;
81
+ return "ownerId_1__syncSeq_1";
82
+ };
83
+
84
+ registerSync({
85
+ config: {scope: {type: "owner"}},
86
+ model: IndexTodoModel,
87
+ options: authedOptions,
88
+ routePath: "/ensureIndexTodosDeferred",
89
+ });
90
+
91
+ assert.strictEqual(createIndexCalls, 0);
92
+ await ensureSyncIndexes();
93
+ assert.strictEqual(createIndexCalls, 1);
94
+ });
95
+
75
96
  it("rejects with an actionable error when createIndex fails, so startup fails loudly", async () => {
76
97
  const IndexTodoModel = buildModel("EnsureIndexTodoFail");
98
+ const sentinel = new Error("boom-sentinel-snapshot-index");
77
99
  // Force the collection's createIndex to reject, simulating a DB/schema failure.
78
- (IndexTodoModel.collection as any).createIndex = async () => {
79
- throw new Error("boom: index build failed");
100
+ IndexTodoModel.collection.createIndex = async (): Promise<string> => {
101
+ throw sentinel;
80
102
  };
81
103
  registerSync({
82
104
  config: {scope: {type: "owner"}},
83
- model: IndexTodoModel as any,
105
+ model: IndexTodoModel,
84
106
  options: authedOptions,
85
107
  routePath: "/ensureIndexTodosFail",
86
108
  });
87
- await expect(ensureSyncIndexes()).rejects.toThrow(
109
+ const rejection = ensureSyncIndexes();
110
+ await expect(rejection).rejects.toThrow(
88
111
  /Failed to create sync snapshot index for EnsureIndexTodoFail/
89
112
  );
113
+ const error = await rejection.catch((caught: unknown) => caught);
114
+ expect(error).toBeInstanceOf(APIError);
115
+ const apiError = error as APIError;
116
+ expect(apiError.code).toBe("sync-snapshot-index-failed");
117
+ expect(apiError.cause).toBe(sentinel);
118
+ expect(apiError.status).toBe(500);
119
+ expect(apiError.message).not.toContain(sentinel.message);
120
+ expect(apiError.detail).toContain(sentinel.message);
90
121
  });
91
122
  });
92
123
 
@@ -129,16 +160,24 @@ describe("sync bookkeeping indexes at startup (Task 9.9)", () => {
129
160
 
130
161
  it("rejects with an actionable error when a bookkeeping index build fails", async () => {
131
162
  const originalEnsure = SyncMutation.ensureIndexes.bind(SyncMutation);
132
- (SyncMutation as any).ensureIndexes = async () => {
133
- throw new Error("boom: mutationId index build failed");
163
+ const sentinel = new Error("boom-sentinel-mutation-index");
164
+ SyncMutation.ensureIndexes = async (): Promise<void> => {
165
+ throw sentinel;
134
166
  };
135
167
  try {
136
168
  new SyncApp().register(express());
137
- await expect(ensureSyncIndexes()).rejects.toThrow(
138
- /Failed to ensure sync indexes for SyncMutation/
139
- );
169
+ const rejection = ensureSyncIndexes();
170
+ await expect(rejection).rejects.toThrow(/Failed to ensure sync indexes for SyncMutation/);
171
+ const error = await rejection.catch((caught: unknown) => caught);
172
+ expect(error).toBeInstanceOf(APIError);
173
+ const apiError = error as APIError;
174
+ expect(apiError.code).toBe("sync-indexes-failed");
175
+ expect(apiError.cause).toBe(sentinel);
176
+ expect(apiError.status).toBe(500);
177
+ expect(apiError.message).not.toContain(sentinel.message);
178
+ expect(apiError.detail).toContain(sentinel.message);
140
179
  } finally {
141
- (SyncMutation as any).ensureIndexes = originalEnsure;
180
+ SyncMutation.ensureIndexes = originalEnsure;
142
181
  }
143
182
  });
144
183
  });
@@ -59,6 +59,17 @@ const execHardSchema = new Schema<ExecHardStuff>({
59
59
  });
60
60
  const ExecHardModel = model<ExecHardStuff>("ExecHardStuff", execHardSchema);
61
61
 
62
+ interface ExecUserish {
63
+ email: string;
64
+ roles?: string[];
65
+ }
66
+
67
+ const execUserishSchema = new Schema<ExecUserish>({
68
+ email: {description: "Login email", required: true, type: String},
69
+ roles: {description: "Authority-bearing roles stripped after hooks", type: [String]},
70
+ });
71
+ const ExecUserishModel = model<ExecUserish>("ExecUserish", execUserishSchema);
72
+
62
73
  const owner = {_id: "u-owner", admin: false, id: "u-owner"} as unknown as User;
63
74
  const stranger = {_id: "u-stranger", admin: false, id: "u-stranger"} as unknown as User;
64
75
 
@@ -133,6 +144,35 @@ describe("executeCreate", () => {
133
144
  expect(error.title).toContain("Access to CREATE on ExecStuff");
134
145
  });
135
146
 
147
+ it("strips User roles after preCreate when writeModelName is User", async () => {
148
+ await ExecUserishModel.deleteMany({});
149
+ let seenRoles: unknown;
150
+ const {doc} = await executeCreate<ExecUserish>({
151
+ body: {email: "exec-roles@example.com", roles: ["superadmin"]},
152
+ model: ExecUserishModel,
153
+ options: {
154
+ accessControl: {} as never,
155
+ permissions: {
156
+ create: [Permissions.IsAuthenticated],
157
+ delete: [],
158
+ list: [],
159
+ read: [],
160
+ update: [],
161
+ },
162
+ preCreate: (body) => {
163
+ seenRoles = (body as ExecUserish).roles;
164
+ return body;
165
+ },
166
+ } as ModelRouterOptions<ExecUserish>,
167
+ user: owner,
168
+ writeModelName: "User",
169
+ });
170
+ assert.deepEqual(seenRoles, ["superadmin"]);
171
+ assert.deepEqual(doc.roles ?? [], []);
172
+ const stored = await ExecUserishModel.findById(doc._id).lean();
173
+ assert.deepEqual(stored?.roles ?? [], []);
174
+ });
175
+
136
176
  it("passes a {user} stub request to preCreate when no req is provided", async () => {
137
177
  const options = baseOptions({
138
178
  preCreate: (body, request) => ({