@revoengine/cli 1.0.10 → 1.0.12

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 (104) hide show
  1. package/README.md +314 -239
  2. package/dist/src/cli.js +126 -9
  3. package/dist/src/client.d.ts +373 -6
  4. package/dist/src/client.js +1005 -53
  5. package/dist/src/commands/auth.js +4 -2
  6. package/dist/src/commands/component.d.ts +67 -0
  7. package/dist/src/commands/component.js +555 -164
  8. package/dist/src/commands/database-tables.d.ts +2 -0
  9. package/dist/src/commands/database-tables.js +169 -0
  10. package/dist/src/commands/database-views.d.ts +2 -0
  11. package/dist/src/commands/database-views.js +126 -0
  12. package/dist/src/commands/endpoints.js +124 -0
  13. package/dist/src/commands/env.js +44 -24
  14. package/dist/src/commands/events.d.ts +2 -0
  15. package/dist/src/commands/events.js +144 -0
  16. package/dist/src/commands/groups.d.ts +2 -0
  17. package/dist/src/commands/groups.js +160 -0
  18. package/dist/src/commands/index.d.ts +9 -0
  19. package/dist/src/commands/index.js +9 -0
  20. package/dist/src/commands/job-templates.d.ts +2 -0
  21. package/dist/src/commands/job-templates.js +107 -0
  22. package/dist/src/commands/metadata.js +75 -10
  23. package/dist/src/commands/migrate.d.ts +6 -0
  24. package/dist/src/commands/migrate.js +658 -0
  25. package/dist/src/commands/project.js +10 -3
  26. package/dist/src/commands/role-groups.d.ts +2 -0
  27. package/dist/src/commands/role-groups.js +141 -0
  28. package/dist/src/commands/schedules.d.ts +2 -0
  29. package/dist/src/commands/schedules.js +140 -0
  30. package/dist/src/commands/terminal-browser.d.ts +16 -0
  31. package/dist/src/commands/terminal-browser.js +92 -0
  32. package/dist/src/commands/terminal-image.d.ts +7 -0
  33. package/dist/src/commands/terminal-image.js +40 -0
  34. package/dist/src/commands/terminal-patch-worker.d.ts +1 -0
  35. package/dist/src/commands/terminal-patch-worker.js +24 -0
  36. package/dist/src/commands/terminal-patch.d.ts +2 -0
  37. package/dist/src/commands/terminal-patch.js +156 -0
  38. package/dist/src/commands/terminal-sandbox.d.ts +8 -0
  39. package/dist/src/commands/terminal-sandbox.js +87 -0
  40. package/dist/src/commands/terminal-service.d.ts +38 -0
  41. package/dist/src/commands/terminal-service.js +210 -0
  42. package/dist/src/commands/terminal.d.ts +49 -0
  43. package/dist/src/commands/terminal.js +826 -0
  44. package/dist/src/component-lock.d.ts +111 -3
  45. package/dist/src/component-lock.js +363 -15
  46. package/dist/src/config.d.ts +10 -2
  47. package/dist/src/config.js +49 -14
  48. package/dist/src/database-table-artifacts.d.ts +7 -0
  49. package/dist/src/database-table-artifacts.js +8 -0
  50. package/dist/src/diff-details.d.ts +8 -0
  51. package/dist/src/diff-details.js +152 -0
  52. package/dist/src/env-sync.d.ts +0 -3
  53. package/dist/src/env-sync.js +11 -25
  54. package/dist/src/http-trace.d.ts +94 -0
  55. package/dist/src/http-trace.js +226 -0
  56. package/dist/src/metadata-backfill.d.ts +18 -7
  57. package/dist/src/metadata-backfill.js +1002 -27
  58. package/dist/src/migration.d.ts +141 -0
  59. package/dist/src/migration.js +1632 -0
  60. package/dist/src/project.d.ts +2 -0
  61. package/dist/src/project.js +4 -17
  62. package/dist/src/prompt.js +10 -18
  63. package/dist/src/resource-inventory.d.ts +28 -0
  64. package/dist/src/resource-inventory.js +85 -0
  65. package/dist/src/resource-metadata.d.ts +1 -0
  66. package/dist/src/resource-metadata.js +3 -0
  67. package/dist/src/resource-syncs/database-table-sync.d.ts +127 -0
  68. package/dist/src/resource-syncs/database-table-sync.js +2374 -0
  69. package/dist/src/resource-syncs/database-view-sync.d.ts +146 -0
  70. package/dist/src/resource-syncs/database-view-sync.js +1405 -0
  71. package/dist/src/resource-syncs/endpoint-sync.d.ts +123 -0
  72. package/dist/src/resource-syncs/endpoint-sync.js +1563 -0
  73. package/dist/src/resource-syncs/event-sync.d.ts +126 -0
  74. package/dist/src/resource-syncs/event-sync.js +1046 -0
  75. package/dist/src/resource-syncs/group-sync.d.ts +93 -0
  76. package/dist/src/resource-syncs/group-sync.js +928 -0
  77. package/dist/src/resource-syncs/job-template-sync.d.ts +106 -0
  78. package/dist/src/resource-syncs/job-template-sync.js +843 -0
  79. package/dist/src/resource-syncs/role-group-sync.d.ts +90 -0
  80. package/dist/src/resource-syncs/role-group-sync.js +635 -0
  81. package/dist/src/resource-syncs/schedule-sync.d.ts +140 -0
  82. package/dist/src/resource-syncs/schedule-sync.js +1396 -0
  83. package/dist/src/resource-syncs/util.d.ts +22 -0
  84. package/dist/src/resource-syncs/util.js +118 -0
  85. package/dist/src/resource-target.d.ts +11 -0
  86. package/dist/src/resource-target.js +48 -0
  87. package/dist/src/runtime-view.d.ts +1 -0
  88. package/dist/src/runtime-view.js +6 -1
  89. package/dist/src/sync-output.d.ts +66 -0
  90. package/dist/src/sync-output.js +268 -0
  91. package/dist/src/tracked-resources.d.ts +1 -1
  92. package/dist/src/tracked-resources.js +28 -2
  93. package/dist/src/types.d.ts +227 -0
  94. package/dist/src/ui.d.ts +3 -0
  95. package/dist/src/ui.js +76 -18
  96. package/dist/src/utils.d.ts +4 -0
  97. package/dist/src/utils.js +81 -0
  98. package/dist/src/workspace-component.d.ts +2 -0
  99. package/dist/src/workspace-component.js +34 -0
  100. package/dist/src/workspace-diff.d.ts +25 -0
  101. package/dist/src/workspace-diff.js +75 -0
  102. package/dist/src/workspace-resource.d.ts +2 -0
  103. package/dist/src/workspace-resource.js +52 -0
  104. package/package.json +12 -4
@@ -1,55 +1,284 @@
1
1
  import { randomBytes } from 'node:crypto';
2
- import { buildStableKey, buildResourceIdentityStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "./resource-metadata.js";
2
+ import { readResourceInventory, resourceIdOf, unwrapResource, } from "./resource-inventory.js";
3
+ import { isDatabaseBackupArtifact } from "./database-table-artifacts.js";
4
+ import { buildStableKey, buildResourceIdentityStableKeyValue, normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "./resource-metadata.js";
3
5
  import { shouldTrackResource } from "./tracked-resources.js";
4
6
  function isRecord(value) {
5
7
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
6
8
  }
7
- function unwrapComponent(value) {
8
- if (isRecord(value) && isRecord(value.data)) {
9
- return value.data;
10
- }
11
- return value;
12
- }
13
- function componentIdOf(component) {
14
- return String(component.componentId || component.id || '');
15
- }
16
9
  function normalizeValue(value, fallback = null) {
17
10
  return value ?? fallback;
18
11
  }
12
+ function rawConfiguredStableKey(resource, stableKeyName) {
13
+ for (const metadata of [resource.metadata, resource.metaData, resource.resourceMetadata]) {
14
+ if (isRecord(metadata) && Object.prototype.hasOwnProperty.call(metadata, stableKeyName)) {
15
+ return { present: true, value: metadata[stableKeyName] };
16
+ }
17
+ }
18
+ return { present: false, value: undefined };
19
+ }
20
+ function metadataStableKeyIdentity(resourceType, stableKey) {
21
+ // TODO(APP-918): Align Role Groups with the exact Stable Key contract used by
22
+ // Components and Job Templates. Update role-group pull, plan, push and
23
+ // filesystem-path collision handling together before changing this branch.
24
+ const identityValue = resourceType === 'role-group'
25
+ ? normalizeStableKeyValue(stableKey)
26
+ : stableKey;
27
+ return `${resourceType}:${identityValue}`;
28
+ }
19
29
  export function generateStableKeySuffix(bytes = 4) {
20
30
  return randomBytes(bytes).toString('hex');
21
31
  }
22
- export function buildGeneratedStableKey(component) {
23
- return `${buildResourceIdentityStableKeyValue(component)}#${generateStableKeySuffix()}`;
32
+ export function buildGeneratedStableKey(resource) {
33
+ return `${buildResourceIdentityStableKeyValue(resource)}#${generateStableKeySuffix()}`;
34
+ }
35
+ function buildNamedResourceGeneratedStableKey(resource) {
36
+ const category = typeof resource.category === 'string' && resource.category.trim()
37
+ ? resource.category.trim()
38
+ : 'Uncategorized';
39
+ const name = typeof resource.name === 'string' ? resource.name.trim() : '';
40
+ return `${category}/${name}#${generateStableKeySuffix()}`;
41
+ }
42
+ function isDatabaseSchemaPartition(database) {
43
+ return Boolean(database.parentId || database.parent);
44
+ }
45
+ function databaseDefinitions(database) {
46
+ return Array.isArray(database.definition)
47
+ ? database.definition.filter(isRecord)
48
+ : [];
49
+ }
50
+ function columnStableKeyValue(definition, stableKeyName) {
51
+ const metadata = definition.metadata;
52
+ if (!isRecord(metadata) || !Object.hasOwn(metadata, stableKeyName)) {
53
+ return { present: false, value: undefined };
54
+ }
55
+ return { present: true, value: metadata[stableKeyName] };
56
+ }
57
+ function buildGeneratedDatabaseColumnStableKey(database, columnName) {
58
+ const category = typeof database.category === 'string' && database.category.trim()
59
+ ? database.category.trim()
60
+ : 'Uncategorized';
61
+ const databaseName = typeof database.name === 'string' ? database.name.trim() : '';
62
+ return `${category}/${databaseName}/${columnName}#${generateStableKeySuffix()}`;
63
+ }
64
+ function buildColumnStableKeyMetadata(definition, stableKeyName, stableKey) {
65
+ return {
66
+ ...sanitizeUserMetadata(definition.metadata),
67
+ [stableKeyName]: stableKey,
68
+ };
69
+ }
70
+ function buildDatabaseColumnMetadataUpdatePayload(input) {
71
+ if (!Number.isInteger(input.database.version)) {
72
+ throw new Error('database schema version is required to update column metadata');
73
+ }
74
+ if (input.assignments.length === 0) {
75
+ throw new Error('at least one database schema column metadata assignment is required');
76
+ }
77
+ const definitions = databaseDefinitions(input.database);
78
+ const assignmentsByDefinition = new Map(input.assignments.map((assignment) => [
79
+ assignment.definition,
80
+ assignment.stableKey,
81
+ ]));
82
+ for (const assignment of input.assignments) {
83
+ const name = typeof assignment.definition.name === 'string' ? assignment.definition.name : 'unknown';
84
+ if (!definitions.includes(assignment.definition)) {
85
+ throw new Error(`database schema column "${name}" no longer exists`);
86
+ }
87
+ }
88
+ for (const definition of definitions) {
89
+ const name = typeof definition.name === 'string' ? definition.name : 'unknown';
90
+ if (typeof definition.databaseDefinitionId !== 'string' || !definition.databaseDefinitionId) {
91
+ throw new Error(`database schema column "${name}" is missing databaseDefinitionId; refusing to rewrite the full definition for metadata backfill`);
92
+ }
93
+ }
94
+ return {
95
+ version: input.database.version,
96
+ definition: definitions.map((definition) => {
97
+ const { metadata: _metadata, ...withoutMetadata } = definition;
98
+ const stableKey = assignmentsByDefinition.get(definition);
99
+ if (!stableKey) {
100
+ const metadata = sanitizeUserMetadata(definition.metadata);
101
+ return Object.keys(metadata).length > 0
102
+ ? { ...withoutMetadata, metadata }
103
+ : withoutMetadata;
104
+ }
105
+ return {
106
+ ...withoutMetadata,
107
+ metadata: buildColumnStableKeyMetadata(definition, input.stableKeyName, stableKey),
108
+ };
109
+ }),
110
+ };
111
+ }
112
+ function groupMetadataBackfillReason(group, existingStableKey, force) {
113
+ const baseReason = existingStableKey
114
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
115
+ : 'stable key missing';
116
+ const reservedKeys = new Set();
117
+ for (const metadata of [group.resourceMetadata, group.metaData, group.metadata]) {
118
+ if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
119
+ continue;
120
+ }
121
+ for (const key of Object.keys(metadata)) {
122
+ if (key.startsWith('__')) {
123
+ reservedKeys.add(key);
124
+ }
125
+ }
126
+ }
127
+ if (reservedKeys.size === 0) {
128
+ return baseReason;
129
+ }
130
+ return `${baseReason}; backend-reserved metadata keys excluded: ${[...reservedKeys].sort((left, right) => left.localeCompare(right)).join(', ')}`;
131
+ }
132
+ function groupExclusionReason(group) {
133
+ return group.deletedAt || group.deletedBy ? 'deleted group is excluded' : null;
134
+ }
135
+ function waitForMutationSlot() {
136
+ return new Promise((resolve) => setTimeout(resolve, 100));
137
+ }
138
+ function scheduleExclusionReason(schedule) {
139
+ if (schedule.systemManaged === true) {
140
+ return 'system-managed schedule is excluded';
141
+ }
142
+ const materializedViewRefresh = schedule.targetType === 'PLATFORM_OPERATION'
143
+ && isRecord(schedule.targetConfig)
144
+ && schedule.targetConfig.kind === 'refresh_materialized_view';
145
+ if (schedule.targetType !== 'JOB_TEMPLATE' && !materializedViewRefresh) {
146
+ return `target type ${String(schedule.targetType || 'unknown')} is outside Schedule migration scope`;
147
+ }
148
+ return null;
149
+ }
150
+ function eventExclusionReason(event) {
151
+ if (event.deletedAt || event.deletedBy) {
152
+ return 'deleted event is excluded';
153
+ }
154
+ if (event.targetType !== 'JOB_TEMPLATE') {
155
+ return `target type ${String(event.targetType || 'unknown')} is outside Event migration scope`;
156
+ }
157
+ return null;
158
+ }
159
+ function endpointExclusionReason(endpoint) {
160
+ return endpoint.deletedAt || endpoint.deletedBy ? 'deleted endpoint is excluded' : null;
24
161
  }
25
- function buildComponentMetadataUpdatePayload(component, stableKeyName, stableKey) {
26
- if (!Number.isInteger(component.version)) {
27
- throw new Error('component version is required to update metadata');
162
+ function buildMetadataUpdatePayload(resource, stableKeyName, stableKey, resourceType) {
163
+ if (!Number.isInteger(resource.version)) {
164
+ throw new Error(`${resourceType} version is required to update metadata`);
28
165
  }
29
166
  return {
30
- version: component.version,
167
+ version: resource.version,
31
168
  metadata: {
32
- ...sanitizeUserMetadata(component.metadata),
169
+ ...sanitizeUserMetadata(resource.resourceMetadata),
170
+ ...sanitizeUserMetadata(resource.metaData),
171
+ ...sanitizeUserMetadata(resource.metadata),
33
172
  [stableKeyName]: stableKey,
34
173
  },
35
174
  };
36
175
  }
176
+ function databaseViewPrincipalIds(entries, property) {
177
+ if (!Array.isArray(entries)) {
178
+ throw new Error(`database view ${property === 'userId' ? 'users' : 'groups'} are required to preserve its access policy`);
179
+ }
180
+ return entries.map((entry) => {
181
+ const value = typeof entry === 'string'
182
+ ? entry
183
+ : isRecord(entry) && typeof entry[property] === 'string'
184
+ ? entry[property]
185
+ : undefined;
186
+ if (typeof value !== 'string' || !value.trim()) {
187
+ throw new Error(`database view ${property === 'userId' ? 'user' : 'group'} access policy contains an invalid principal`);
188
+ }
189
+ return value;
190
+ });
191
+ }
192
+ function databaseViewIndexesForUpdate(view) {
193
+ if (view.indexes === undefined) {
194
+ return undefined;
195
+ }
196
+ if (!Array.isArray(view.indexes)) {
197
+ throw new Error('materialized database view indexes are invalid and cannot be preserved safely');
198
+ }
199
+ return JSON.parse(JSON.stringify(view.indexes));
200
+ }
201
+ function buildDatabaseViewMetadataUpdatePayload(view, stableKeyName, stableKey) {
202
+ if (typeof view.name !== 'string' || !view.name.trim()) {
203
+ throw new Error('database view name is required for a full update');
204
+ }
205
+ if (view.type !== 'VIEW' && view.type !== 'MATERIALIZED_VIEW') {
206
+ throw new Error(`database view type ${String(view.type || 'unknown')} cannot be updated`);
207
+ }
208
+ if (view.definitionMode !== 'STRUCTURED' && view.definitionMode !== 'RAW_SQL') {
209
+ throw new Error(`database view definitionMode ${String(view.definitionMode || 'unknown')} cannot be updated`);
210
+ }
211
+ if (typeof view.restricted !== 'boolean') {
212
+ throw new Error('database view restricted access policy is required to preserve it');
213
+ }
214
+ if (!Number.isInteger(view.version) || view.version < 0) {
215
+ throw new Error('database view version is required for a full update');
216
+ }
217
+ if (view.type === 'MATERIALIZED_VIEW' && !Array.isArray(view.uniqueKey)) {
218
+ throw new Error('materialized database view uniqueKey is required to preserve its definition');
219
+ }
220
+ const payload = {
221
+ name: view.name,
222
+ ...(typeof view.category === 'string' ? { category: view.category } : {}),
223
+ ...(typeof view.desc === 'string'
224
+ ? { desc: view.desc }
225
+ : typeof view.description === 'string'
226
+ ? { desc: view.description }
227
+ : {}),
228
+ ...buildMetadataUpdatePayload(view, stableKeyName, stableKey, 'database-view'),
229
+ type: view.type,
230
+ definitionMode: view.definitionMode,
231
+ restricted: view.restricted,
232
+ users: databaseViewPrincipalIds(view.users, 'userId'),
233
+ groups: databaseViewPrincipalIds(view.groups, 'groupId'),
234
+ };
235
+ const indexes = view.type === 'MATERIALIZED_VIEW'
236
+ ? databaseViewIndexesForUpdate(view)
237
+ : undefined;
238
+ const materialized = view.type === 'MATERIALIZED_VIEW'
239
+ ? {
240
+ uniqueKey: view.uniqueKey,
241
+ ...(indexes === undefined ? {} : { indexes }),
242
+ }
243
+ : {};
244
+ if (view.definitionMode === 'STRUCTURED') {
245
+ if (!isRecord(view.request)) {
246
+ throw new Error('structured database view request is required for a full update');
247
+ }
248
+ return { ...payload, ...materialized, request: view.request };
249
+ }
250
+ if (typeof view.rawQuery !== 'string' || !view.rawQuery.trim()) {
251
+ throw new Error('raw SQL database view query is required for a full update');
252
+ }
253
+ return {
254
+ ...payload,
255
+ ...materialized,
256
+ rawQuery: view.rawQuery,
257
+ };
258
+ }
259
+ function buildJobTemplateMetadataUpdatePayload(jobTemplate, stableKeyName, stableKey) {
260
+ if (!Object.hasOwn(jobTemplate, 'options') || jobTemplate.options === undefined || jobTemplate.options === null) {
261
+ throw new Error(`Job-template ${resourceIdOf(jobTemplate) || 'unknown'} is missing options in the API response; refusing metadata update to preserve its configuration.`);
262
+ }
263
+ return {
264
+ ...buildMetadataUpdatePayload(jobTemplate, stableKeyName, stableKey, 'job-template'),
265
+ options: jobTemplate.options,
266
+ };
267
+ }
37
268
  export async function buildMetadataBackfillPlan(input) {
38
- const { client, envName, stableKeyName, trackedResources, force = false } = input;
269
+ const { client, envName, stableKeyName, trackedResources, force = false, skipPartitions = false } = input;
39
270
  const items = [];
40
271
  if (shouldTrackResource(trackedResources, 'component')) {
41
- const { components } = await client.listAllComponents();
42
- for (const summary of components) {
43
- const summaryId = componentIdOf(summary);
44
- if (!summaryId) {
272
+ for await (const { listedId, resource: component } of readResourceInventory(client, 'component')) {
273
+ if (!listedId) {
45
274
  continue;
46
275
  }
47
- const component = unwrapComponent(await client.getComponent(summaryId));
48
- const resourceId = componentIdOf(component) || summaryId;
276
+ const resourceId = resourceIdOf(component) || listedId;
49
277
  const existingStableKey = readConfiguredResourceMetadataStableKey(component, stableKeyName);
50
278
  const stableKey = existingStableKey && !force
51
279
  ? undefined
52
280
  : buildGeneratedStableKey(component);
281
+ const plannedStableKey = stableKey || existingStableKey || undefined;
53
282
  items.push({
54
283
  resourceType: 'component',
55
284
  resourceId,
@@ -58,19 +287,402 @@ export async function buildMetadataBackfillPlan(input) {
58
287
  action: existingStableKey && !force ? 'skip' : 'update',
59
288
  metadataField: 'metadata',
60
289
  stableKeyName,
61
- ...(stableKey ? { stableKey } : {}),
290
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
291
+ reason: existingStableKey
292
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
293
+ : 'stable key missing',
294
+ });
295
+ }
296
+ }
297
+ if (shouldTrackResource(trackedResources, 'database-table') && typeof client.listAllDatabaseSchemas === 'function') {
298
+ for await (const { resource: database } of readResourceInventory(client, 'database-table', { skipPartitions })) {
299
+ if (isDatabaseBackupArtifact(database)) {
300
+ continue;
301
+ }
302
+ const resourceId = resourceIdOf(database);
303
+ if (!resourceId) {
304
+ continue;
305
+ }
306
+ const category = normalizeValue(database.category);
307
+ const name = String(database.name || '');
308
+ const partition = isDatabaseSchemaPartition(database);
309
+ const parentName = typeof database.parent === 'string' && database.parent.trim()
310
+ ? database.parent.trim()
311
+ : typeof database.parentId === 'string' && database.parentId.trim()
312
+ ? database.parentId.trim()
313
+ : undefined;
314
+ const rawStableKey = rawConfiguredStableKey(database, stableKeyName);
315
+ const invalidDatabaseStableKey = rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim());
316
+ if (invalidDatabaseStableKey) {
317
+ const reason = `Invalid database-table stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
318
+ items.push({
319
+ resourceType: 'database-table', resourceId, name, category, action: 'blocked',
320
+ resourceKind: partition ? 'database-partition' : 'resource',
321
+ ...(parentName ? { parentName } : {}),
322
+ metadataField: 'metadata', stableKeyName, reason,
323
+ });
324
+ }
325
+ else {
326
+ const existingStableKey = readConfiguredResourceMetadataStableKey(database, stableKeyName);
327
+ const stableKey = existingStableKey || buildNamedResourceGeneratedStableKey(database);
328
+ items.push({
329
+ resourceType: 'database-table', resourceId, name, category,
330
+ resourceKind: partition ? 'database-partition' : 'resource',
331
+ ...(parentName ? { parentName } : {}),
332
+ action: existingStableKey ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
333
+ stableKey,
334
+ reason: existingStableKey ? 'stable key already exists' : 'assign-stable-key',
335
+ });
336
+ }
337
+ if (partition) {
338
+ continue;
339
+ }
340
+ const definitions = databaseDefinitions(database);
341
+ const columnsByStableKey = new Map();
342
+ const columnsByName = new Map();
343
+ const columnsByDefinitionId = new Map();
344
+ for (const definition of definitions) {
345
+ const columnName = typeof definition.name === 'string' ? definition.name.trim() : '';
346
+ if (columnName) {
347
+ columnsByName.set(columnName, [...(columnsByName.get(columnName) || []), definition]);
348
+ }
349
+ const columnDefinitionId = typeof definition.databaseDefinitionId === 'string'
350
+ ? definition.databaseDefinitionId.trim()
351
+ : '';
352
+ if (columnDefinitionId) {
353
+ columnsByDefinitionId.set(columnDefinitionId, [
354
+ ...(columnsByDefinitionId.get(columnDefinitionId) || []),
355
+ definition,
356
+ ]);
357
+ }
358
+ const rawColumnStableKey = columnStableKeyValue(definition, stableKeyName);
359
+ if (typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()) {
360
+ columnsByStableKey.set(rawColumnStableKey.value, [
361
+ ...(columnsByStableKey.get(rawColumnStableKey.value) || []),
362
+ { definition, name: columnName },
363
+ ]);
364
+ }
365
+ }
366
+ const duplicateColumnStableKeys = new Set([...columnsByStableKey]
367
+ .filter(([, columns]) => columns.length > 1)
368
+ .map(([stableKeyValue]) => stableKeyValue));
369
+ const duplicateColumnNames = new Set([...columnsByName]
370
+ .filter(([, columns]) => columns.length > 1)
371
+ .map(([columnName]) => columnName));
372
+ const duplicateColumnDefinitionIds = new Set([...columnsByDefinitionId]
373
+ .filter(([, columns]) => columns.length > 1)
374
+ .map(([columnDefinitionId]) => columnDefinitionId));
375
+ for (const definition of definitions) {
376
+ const columnName = typeof definition.name === 'string' ? definition.name.trim() : '';
377
+ const columnDefinitionId = typeof definition.databaseDefinitionId === 'string'
378
+ ? definition.databaseDefinitionId.trim()
379
+ : '';
380
+ const rawColumnStableKey = columnStableKeyValue(definition, stableKeyName);
381
+ const existingColumnStableKey = typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()
382
+ ? rawColumnStableKey.value
383
+ : undefined;
384
+ const duplicate = existingColumnStableKey && duplicateColumnStableKeys.has(existingColumnStableKey);
385
+ const duplicateName = columnName && duplicateColumnNames.has(columnName);
386
+ const duplicateDefinitionId = columnDefinitionId && duplicateColumnDefinitionIds.has(columnDefinitionId);
387
+ const invalid = rawColumnStableKey.present && !existingColumnStableKey;
388
+ const columnReason = !columnName
389
+ ? `Database column on ${resourceId} is missing a non-empty name; refusing to generate a Stable Key.`
390
+ : !columnDefinitionId
391
+ ? `Database column "${columnName}" on ${resourceId} is missing databaseDefinitionId; refusing to rewrite the full definition.`
392
+ : duplicateName
393
+ ? `Duplicate database column name "${columnName}" on root database schema ${resourceId}.`
394
+ : duplicateDefinitionId
395
+ ? `Duplicate database column databaseDefinitionId "${columnDefinitionId}" on root database schema ${resourceId}.`
396
+ : invalid
397
+ ? `Invalid database column stableKey on ${resourceId}.${columnName}: definition[].metadata.${stableKeyName} must be a non-empty string.`
398
+ : duplicate
399
+ ? `Duplicate database column stableKey "${existingColumnStableKey}" on root database schema ${resourceId}.`
400
+ : existingColumnStableKey
401
+ ? 'column stable key already exists'
402
+ : 'assign-column-stable-key';
403
+ items.push({
404
+ resourceType: 'database-table',
405
+ resourceKind: 'database-column',
406
+ resourceId,
407
+ name: `${name}.${columnName || '<unnamed>'}`,
408
+ category,
409
+ action: !columnName || !columnDefinitionId || duplicateName || duplicateDefinitionId || invalid || duplicate
410
+ ? 'blocked'
411
+ : existingColumnStableKey ? 'skip' : 'update',
412
+ metadataField: 'definition[].metadata',
413
+ stableKeyName,
414
+ ...(columnName && existingColumnStableKey ? { stableKey: existingColumnStableKey } : columnName ? {
415
+ stableKey: buildGeneratedDatabaseColumnStableKey(database, columnName),
416
+ } : {}),
417
+ ...(columnName ? { columnName } : {}),
418
+ ...(columnDefinitionId ? { columnDefinitionId } : {}),
419
+ reason: columnReason,
420
+ });
421
+ }
422
+ }
423
+ }
424
+ if (shouldTrackResource(trackedResources, 'database-view') && typeof client.listAllDatabaseViewsForSync === 'function') {
425
+ for await (const { resource: view } of readResourceInventory(client, 'database-view')) {
426
+ const resourceId = resourceIdOf(view);
427
+ if (!resourceId) {
428
+ continue;
429
+ }
430
+ const category = normalizeValue(view.category);
431
+ const name = String(view.name || '');
432
+ const rawStableKey = rawConfiguredStableKey(view, stableKeyName);
433
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
434
+ const reason = `Invalid database-view stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
435
+ items.push({ resourceType: 'database-view', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
436
+ continue;
437
+ }
438
+ const existingStableKey = readConfiguredResourceMetadataStableKey(view, stableKeyName);
439
+ const stableKey = existingStableKey || buildNamedResourceGeneratedStableKey(view);
440
+ items.push({
441
+ resourceType: 'database-view',
442
+ resourceId,
443
+ name,
444
+ category,
445
+ action: existingStableKey ? 'skip' : 'update',
446
+ metadataField: 'metadata',
447
+ stableKeyName,
448
+ stableKey,
449
+ reason: existingStableKey ? 'stable key already exists' : 'assign-stable-key',
450
+ });
451
+ }
452
+ }
453
+ if (shouldTrackResource(trackedResources, 'endpoint') && typeof client.listAllEndpoints === 'function') {
454
+ for await (const { listedId, resource: endpoint } of readResourceInventory(client, 'endpoint')) {
455
+ if (!listedId) {
456
+ continue;
457
+ }
458
+ const resourceId = resourceIdOf(endpoint) || listedId;
459
+ const category = normalizeValue(endpoint.category);
460
+ const name = String(endpoint.name || '');
461
+ const exclusionReason = endpointExclusionReason(endpoint);
462
+ if (exclusionReason) {
463
+ items.push({
464
+ resourceType: 'endpoint', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
465
+ reason: exclusionReason,
466
+ });
467
+ continue;
468
+ }
469
+ const rawStableKey = rawConfiguredStableKey(endpoint, stableKeyName);
470
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
471
+ const reason = `Invalid endpoint stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
472
+ items.push({ resourceType: 'endpoint', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
473
+ continue;
474
+ }
475
+ const existingStableKey = readConfiguredResourceMetadataStableKey(endpoint, stableKeyName);
476
+ const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(endpoint);
477
+ const plannedStableKey = stableKey || existingStableKey || undefined;
478
+ items.push({
479
+ resourceType: 'endpoint', resourceId, name, category,
480
+ action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
481
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
482
+ reason: existingStableKey
483
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
484
+ : 'stable key missing',
485
+ });
486
+ }
487
+ }
488
+ if (shouldTrackResource(trackedResources, 'role-group') && typeof client.listAllRoleGroups === 'function') {
489
+ for await (const { listedId, resource: roleGroup } of readResourceInventory(client, 'role-group')) {
490
+ if (!listedId) {
491
+ continue;
492
+ }
493
+ const resourceId = resourceIdOf(roleGroup) || listedId;
494
+ const existingStableKey = readConfiguredResourceMetadataStableKey(roleGroup, stableKeyName);
495
+ const stableKey = existingStableKey && !force
496
+ ? undefined
497
+ : buildGeneratedStableKey(roleGroup);
498
+ const plannedStableKey = stableKey || existingStableKey || undefined;
499
+ items.push({
500
+ resourceType: 'role-group',
501
+ resourceId,
502
+ name: String(roleGroup.name || ''),
503
+ category: normalizeValue(roleGroup.category),
504
+ action: existingStableKey && !force ? 'skip' : 'update',
505
+ metadataField: 'metadata',
506
+ stableKeyName,
507
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
508
+ reason: existingStableKey
509
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
510
+ : 'stable key missing',
511
+ });
512
+ }
513
+ }
514
+ if (shouldTrackResource(trackedResources, 'group') && typeof client.listAllGroups === 'function') {
515
+ for await (const { listedId, resource: group } of readResourceInventory(client, 'group')) {
516
+ if (!listedId) {
517
+ continue;
518
+ }
519
+ const resourceId = resourceIdOf(group) || listedId;
520
+ const exclusionReason = groupExclusionReason(group);
521
+ if (exclusionReason) {
522
+ items.push({
523
+ resourceType: 'group',
524
+ resourceId,
525
+ name: String(group.name || ''),
526
+ category: normalizeValue(group.category),
527
+ action: 'skip',
528
+ metadataField: 'metadata',
529
+ stableKeyName,
530
+ reason: exclusionReason,
531
+ });
532
+ continue;
533
+ }
534
+ const existingStableKey = readConfiguredResourceMetadataStableKey(group, stableKeyName);
535
+ const stableKey = existingStableKey && !force
536
+ ? undefined
537
+ : buildNamedResourceGeneratedStableKey(group);
538
+ const plannedStableKey = stableKey || existingStableKey || undefined;
539
+ items.push({
540
+ resourceType: 'group',
541
+ resourceId,
542
+ name: String(group.name || ''),
543
+ category: normalizeValue(group.category),
544
+ action: existingStableKey && !force ? 'skip' : 'update',
545
+ metadataField: 'metadata',
546
+ stableKeyName,
547
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
548
+ reason: groupMetadataBackfillReason(group, existingStableKey, force),
549
+ });
550
+ }
551
+ }
552
+ if (shouldTrackResource(trackedResources, 'job-template') && typeof client.listAllJobTemplates === 'function') {
553
+ for await (const { listedId, resource: jobTemplate } of readResourceInventory(client, 'job-template')) {
554
+ if (!listedId) {
555
+ continue;
556
+ }
557
+ const resourceId = resourceIdOf(jobTemplate) || listedId;
558
+ const rawStableKey = rawConfiguredStableKey(jobTemplate, stableKeyName);
559
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
560
+ const reason = `Invalid job-template stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
561
+ items.push({
562
+ resourceType: 'job-template', resourceId, name: String(jobTemplate.name || ''), category: normalizeValue(jobTemplate.category),
563
+ action: 'blocked', metadataField: 'metadata', stableKeyName, reason,
564
+ });
565
+ continue;
566
+ }
567
+ const existingStableKey = readConfiguredResourceMetadataStableKey(jobTemplate, stableKeyName);
568
+ const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(jobTemplate);
569
+ const plannedStableKey = stableKey || existingStableKey || undefined;
570
+ items.push({
571
+ resourceType: 'job-template',
572
+ resourceId,
573
+ name: String(jobTemplate.name || ''),
574
+ category: normalizeValue(jobTemplate.category),
575
+ action: existingStableKey && !force ? 'skip' : 'update',
576
+ metadataField: 'metadata',
577
+ stableKeyName,
578
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
579
+ reason: existingStableKey
580
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
581
+ : 'stable key missing',
582
+ });
583
+ }
584
+ }
585
+ if (shouldTrackResource(trackedResources, 'schedule') && typeof client.listAllSchedules === 'function') {
586
+ for await (const { listedId, resource: schedule } of readResourceInventory(client, 'schedule')) {
587
+ if (!listedId) {
588
+ continue;
589
+ }
590
+ const resourceId = resourceIdOf(schedule) || listedId;
591
+ const category = normalizeValue(schedule.category);
592
+ const name = String(schedule.name || '');
593
+ const exclusionReason = scheduleExclusionReason(schedule);
594
+ if (exclusionReason) {
595
+ items.push({
596
+ resourceType: 'schedule', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
597
+ reason: exclusionReason,
598
+ });
599
+ continue;
600
+ }
601
+ const rawStableKey = rawConfiguredStableKey(schedule, stableKeyName);
602
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
603
+ const reason = `Invalid schedule stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
604
+ items.push({ resourceType: 'schedule', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
605
+ continue;
606
+ }
607
+ const existingStableKey = readConfiguredResourceMetadataStableKey(schedule, stableKeyName);
608
+ const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(schedule);
609
+ const plannedStableKey = stableKey || existingStableKey || undefined;
610
+ items.push({
611
+ resourceType: 'schedule', resourceId, name, category,
612
+ action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
613
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
614
+ reason: existingStableKey
615
+ ? (force ? 'stable key will be regenerated' : 'stable key already exists')
616
+ : 'stable key missing',
617
+ });
618
+ }
619
+ }
620
+ if (shouldTrackResource(trackedResources, 'event') && typeof client.listAllEvents === 'function') {
621
+ for await (const { listedId, resource: event } of readResourceInventory(client, 'event')) {
622
+ if (!listedId) {
623
+ continue;
624
+ }
625
+ const resourceId = resourceIdOf(event) || listedId;
626
+ const category = normalizeValue(event.category);
627
+ const name = String(event.name || '');
628
+ const exclusionReason = eventExclusionReason(event);
629
+ if (exclusionReason) {
630
+ items.push({
631
+ resourceType: 'event', resourceId, name, category, action: 'skip', metadataField: 'metadata', stableKeyName,
632
+ reason: exclusionReason,
633
+ });
634
+ continue;
635
+ }
636
+ const rawStableKey = rawConfiguredStableKey(event, stableKeyName);
637
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
638
+ const reason = `Invalid event stableKey on ${resourceId}: metadata.${stableKeyName} must be a non-empty string.`;
639
+ items.push({ resourceType: 'event', resourceId, name, category, action: 'blocked', metadataField: 'metadata', stableKeyName, reason });
640
+ continue;
641
+ }
642
+ const existingStableKey = readConfiguredResourceMetadataStableKey(event, stableKeyName);
643
+ const stableKey = existingStableKey && !force ? undefined : buildNamedResourceGeneratedStableKey(event);
644
+ const plannedStableKey = stableKey || existingStableKey || undefined;
645
+ items.push({
646
+ resourceType: 'event', resourceId, name, category,
647
+ action: existingStableKey && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
648
+ ...(plannedStableKey ? { stableKey: plannedStableKey } : {}),
62
649
  reason: existingStableKey
63
650
  ? (force ? 'stable key will be regenerated' : 'stable key already exists')
64
651
  : 'stable key missing',
65
652
  });
66
653
  }
67
654
  }
655
+ const blockers = items.filter((item) => item.action === 'blocked').map((item) => item.reason);
656
+ const itemsByStableKey = new Map();
657
+ for (const item of items) {
658
+ if (item.metadataField !== 'metadata'
659
+ || !item.stableKey
660
+ || ((item.resourceType === 'schedule' || item.resourceType === 'event') && item.action === 'skip' && item.reason !== 'stable key already exists')) {
661
+ continue;
662
+ }
663
+ const identity = metadataStableKeyIdentity(item.resourceType, item.stableKey);
664
+ itemsByStableKey.set(identity, [...(itemsByStableKey.get(identity) || []), item]);
665
+ }
666
+ for (const duplicates of itemsByStableKey.values()) {
667
+ if (duplicates.length < 2) {
668
+ continue;
669
+ }
670
+ const stableKey = duplicates[0].stableKey;
671
+ const resourceType = duplicates[0].resourceType;
672
+ const reason = `Duplicate ${resourceType} stableKey "${stableKey}" on ${envName}.`;
673
+ blockers.push(reason);
674
+ for (const item of duplicates) {
675
+ item.action = 'blocked';
676
+ item.reason = reason;
677
+ }
678
+ }
68
679
  items.sort((left, right) => left.resourceType.localeCompare(right.resourceType)
69
680
  || buildStableKey({ name: left.name, category: left.category }).localeCompare(buildStableKey({ name: right.name, category: right.category }))
70
681
  || left.resourceId.localeCompare(right.resourceId));
71
682
  const counts = {
72
683
  update: items.filter((item) => item.action === 'update').length,
73
684
  skip: items.filter((item) => item.action === 'skip').length,
685
+ blocked: items.filter((item) => item.action === 'blocked').length,
74
686
  };
75
687
  return {
76
688
  schemaVersion: 1,
@@ -80,27 +692,125 @@ export async function buildMetadataBackfillPlan(input) {
80
692
  instance: client.instance,
81
693
  stableKeyName,
82
694
  trackedResources,
695
+ force,
696
+ ...(skipPartitions ? { skipPartitions: true } : {}),
83
697
  counts,
698
+ blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
84
699
  items,
85
700
  };
86
701
  }
87
702
  export async function applyMetadataBackfillPlan(input) {
88
703
  const { client, plan } = input;
704
+ if (client.baseUrl !== plan.baseUrl || client.instance !== plan.instance) {
705
+ throw new Error(`Metadata plan target ${plan.baseUrl} (${plan.instance}) does not match selected target ${client.baseUrl} (${client.instance || 'unknown'}).`);
706
+ }
707
+ if (plan.blockers.length > 0) {
708
+ throw new Error(`Metadata plan has ${plan.blockers.length} blocking validation error(s): ${plan.blockers.join(' ')}`);
709
+ }
710
+ if (plan.items.some((item) => item.action === 'blocked')) {
711
+ throw new Error('Metadata plan contains blocked items and cannot be applied.');
712
+ }
713
+ const currentResources = new Map();
714
+ const resourceTypes = new Set(plan.items.map((item) => item.resourceType));
715
+ const readOrder = [
716
+ 'component', 'database-table', 'database-view', 'endpoint',
717
+ 'role-group', 'group', 'job-template', 'schedule', 'event',
718
+ ];
719
+ for (const resourceType of readOrder) {
720
+ if (!resourceTypes.has(resourceType)) {
721
+ continue;
722
+ }
723
+ for await (const { listedId, resource } of readResourceInventory(client, resourceType, {
724
+ skipPartitions: plan.skipPartitions,
725
+ })) {
726
+ if (!listedId || (resourceType === 'database-table' && isDatabaseBackupArtifact(resource))) {
727
+ continue;
728
+ }
729
+ currentResources.set(`${resourceType}:${listedId}`, resource);
730
+ }
731
+ }
732
+ const stableKeyOwners = new Map();
733
+ for (const [identity, resource] of currentResources) {
734
+ const resourceType = identity.slice(0, identity.indexOf(':'));
735
+ if (resourceType === 'schedule' && scheduleExclusionReason(resource)) {
736
+ continue;
737
+ }
738
+ if (resourceType === 'event' && eventExclusionReason(resource)) {
739
+ continue;
740
+ }
741
+ if (resourceType === 'endpoint' && endpointExclusionReason(resource)) {
742
+ continue;
743
+ }
744
+ const stableKey = readConfiguredResourceMetadataStableKey(resource, plan.stableKeyName);
745
+ if (!stableKey)
746
+ continue;
747
+ const key = metadataStableKeyIdentity(resourceType, stableKey);
748
+ if (stableKeyOwners.has(key))
749
+ throw new Error(`Duplicate ${resourceType} stableKey "${stableKey}" detected before apply.`);
750
+ stableKeyOwners.set(key, identity);
751
+ }
752
+ for (const item of plan.items.filter((candidate) => candidate.action === 'update' && candidate.stableKey)) {
753
+ if (item.metadataField !== 'metadata') {
754
+ continue;
755
+ }
756
+ const owner = stableKeyOwners.get(metadataStableKeyIdentity(item.resourceType, item.stableKey));
757
+ if (owner && owner !== `${item.resourceType}:${item.resourceId}`) {
758
+ throw new Error(`Planned ${item.resourceType} stableKey "${item.stableKey}" is already assigned to another resource.`);
759
+ }
760
+ }
761
+ if (!plan.force) {
762
+ for (const item of plan.items.filter((candidate) => (candidate.resourceType === 'endpoint'
763
+ || candidate.resourceType === 'job-template'
764
+ || candidate.resourceType === 'schedule'
765
+ || candidate.resourceType === 'event') && candidate.action === 'update')) {
766
+ const resource = currentResources.get(`${item.resourceType}:${item.resourceId}`);
767
+ if (!resource) {
768
+ continue;
769
+ }
770
+ const rawStableKey = rawConfiguredStableKey(resource, plan.stableKeyName);
771
+ if (rawStableKey.present && (typeof rawStableKey.value !== 'string' || !rawStableKey.value.trim())) {
772
+ throw new Error(`Invalid ${item.resourceType} stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it without --force.`);
773
+ }
774
+ }
775
+ }
89
776
  const results = [];
777
+ let databaseMutationStarted = false;
778
+ const columnUpdatesByDatabase = new Map();
779
+ for (const item of plan.items) {
780
+ if (item.resourceType === 'database-table' && item.metadataField === 'definition[].metadata' && item.action === 'update') {
781
+ columnUpdatesByDatabase.set(item.resourceId, [
782
+ ...(columnUpdatesByDatabase.get(item.resourceId) || []),
783
+ item,
784
+ ]);
785
+ }
786
+ }
787
+ const processedColumnUpdateDatabases = new Set();
90
788
  for (const item of plan.items) {
91
789
  if (item.action === 'skip') {
92
790
  results.push({
93
791
  resourceType: item.resourceType,
94
792
  resourceId: item.resourceId,
793
+ ...(item.columnName ? { columnName: item.columnName } : {}),
794
+ ...(item.stableKey ? { stableKey: item.stableKey } : {}),
95
795
  action: 'skip',
96
796
  });
97
797
  continue;
98
798
  }
799
+ if (item.action !== 'update') {
800
+ throw new Error(`Unsupported metadata plan action: ${item.action}.`);
801
+ }
99
802
  try {
100
803
  if (item.resourceType === 'component') {
101
- const component = unwrapComponent(await client.getComponent(item.resourceId));
804
+ const component = currentResources.get(`component:${item.resourceId}`);
805
+ if (!component)
806
+ throw new Error('component no longer exists');
807
+ const currentStableKey = readConfiguredResourceMetadataStableKey(component, plan.stableKeyName);
808
+ if (currentStableKey && !plan.force) {
809
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
810
+ continue;
811
+ }
102
812
  const stableKey = item.stableKey || buildGeneratedStableKey(component);
103
- await client.updateComponent(item.resourceId, buildComponentMetadataUpdatePayload(component, plan.stableKeyName, stableKey));
813
+ await client.updateComponent(item.resourceId, buildMetadataUpdatePayload(component, plan.stableKeyName, stableKey, item.resourceType));
104
814
  results.push({
105
815
  resourceType: item.resourceType,
106
816
  resourceId: item.resourceId,
@@ -109,6 +819,236 @@ export async function applyMetadataBackfillPlan(input) {
109
819
  });
110
820
  continue;
111
821
  }
822
+ if (item.resourceType === 'database-table') {
823
+ const listed = currentResources.get(`database-table:${item.resourceId}`);
824
+ if (!listed) {
825
+ throw new Error('database schema no longer exists');
826
+ }
827
+ if (item.metadataField === 'definition[].metadata' && processedColumnUpdateDatabases.has(item.resourceId)) {
828
+ continue;
829
+ }
830
+ const live = unwrapResource(await client.getDatabaseSchema(item.resourceId));
831
+ if (item.metadataField === 'definition[].metadata') {
832
+ if (isDatabaseSchemaPartition(live)) {
833
+ throw new Error('database schema became a partition; column stable keys are inherited from the root');
834
+ }
835
+ const assignments = [];
836
+ for (const columnItem of columnUpdatesByDatabase.get(item.resourceId) || []) {
837
+ const columnName = columnItem.columnName;
838
+ const columnDefinitionId = columnItem.columnDefinitionId;
839
+ if (!columnName || !columnDefinitionId) {
840
+ throw new Error(`database schema column metadata plan for ${item.resourceId} is missing its live identity`);
841
+ }
842
+ const definitions = databaseDefinitions(live).filter((candidate) => candidate.databaseDefinitionId === columnDefinitionId);
843
+ if (definitions.length !== 1 || definitions[0].name !== columnName) {
844
+ throw new Error(`database schema column "${columnName}" no longer matches databaseDefinitionId "${columnDefinitionId}"`);
845
+ }
846
+ const definition = definitions[0];
847
+ const rawColumnStableKey = columnStableKeyValue(definition, plan.stableKeyName);
848
+ if (typeof rawColumnStableKey.value === 'string' && rawColumnStableKey.value.trim()) {
849
+ results.push({
850
+ resourceType: columnItem.resourceType,
851
+ resourceId: columnItem.resourceId,
852
+ columnName,
853
+ stableKey: rawColumnStableKey.value,
854
+ action: 'skip',
855
+ });
856
+ continue;
857
+ }
858
+ if (rawColumnStableKey.present) {
859
+ throw new Error(`Invalid database column stableKey appeared before apply on ${item.resourceId}.${columnName}; refusing to overwrite it.`);
860
+ }
861
+ assignments.push({
862
+ item: columnItem,
863
+ definition,
864
+ stableKey: columnItem.stableKey || buildGeneratedDatabaseColumnStableKey(live, columnName),
865
+ });
866
+ }
867
+ processedColumnUpdateDatabases.add(item.resourceId);
868
+ if (assignments.length === 0) {
869
+ continue;
870
+ }
871
+ if (databaseMutationStarted) {
872
+ await waitForMutationSlot();
873
+ }
874
+ databaseMutationStarted = true;
875
+ await client.updateDatabaseSchema(item.resourceId, buildDatabaseColumnMetadataUpdatePayload({
876
+ database: live,
877
+ assignments,
878
+ stableKeyName: plan.stableKeyName,
879
+ }));
880
+ for (const assignment of assignments) {
881
+ results.push({
882
+ resourceType: assignment.item.resourceType,
883
+ resourceId: assignment.item.resourceId,
884
+ columnName: assignment.item.columnName,
885
+ stableKey: assignment.stableKey,
886
+ action: 'update',
887
+ });
888
+ }
889
+ continue;
890
+ }
891
+ const currentStableKey = readConfiguredResourceMetadataStableKey(live, plan.stableKeyName);
892
+ if (currentStableKey) {
893
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
894
+ continue;
895
+ }
896
+ const rawStableKey = rawConfiguredStableKey(live, plan.stableKeyName);
897
+ if (rawStableKey.present) {
898
+ throw new Error(`Invalid database-table stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it.`);
899
+ }
900
+ if (databaseMutationStarted) {
901
+ await waitForMutationSlot();
902
+ }
903
+ databaseMutationStarted = true;
904
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(live);
905
+ await client.updateDatabaseSchemaMetadata(item.resourceId, buildMetadataUpdatePayload(live, plan.stableKeyName, stableKey, item.resourceType));
906
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
907
+ continue;
908
+ }
909
+ if (item.resourceType === 'database-view') {
910
+ const view = currentResources.get(`database-view:${item.resourceId}`);
911
+ if (!view) {
912
+ throw new Error('database view no longer exists');
913
+ }
914
+ const currentStableKey = readConfiguredResourceMetadataStableKey(view, plan.stableKeyName);
915
+ if (currentStableKey) {
916
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
917
+ continue;
918
+ }
919
+ const rawStableKey = rawConfiguredStableKey(view, plan.stableKeyName);
920
+ if (rawStableKey.present) {
921
+ throw new Error(`Invalid database-view stableKey appeared before apply on ${item.resourceId}; refusing to overwrite it.`);
922
+ }
923
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(view);
924
+ await client.updateDatabaseView(item.resourceId, buildDatabaseViewMetadataUpdatePayload(view, plan.stableKeyName, stableKey));
925
+ const verified = unwrapResource(await client.getDatabaseView(item.resourceId));
926
+ const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, plan.stableKeyName);
927
+ if (verifiedStableKey !== stableKey) {
928
+ throw new Error('updated database view did not retain the planned stable key');
929
+ }
930
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
931
+ continue;
932
+ }
933
+ if (item.resourceType === 'endpoint') {
934
+ const endpoint = currentResources.get(`endpoint:${item.resourceId}`);
935
+ if (!endpoint) {
936
+ throw new Error('endpoint no longer exists');
937
+ }
938
+ const exclusionReason = endpointExclusionReason(endpoint);
939
+ if (exclusionReason) {
940
+ throw new Error(`endpoint moved outside migration scope: ${exclusionReason}`);
941
+ }
942
+ const currentStableKey = readConfiguredResourceMetadataStableKey(endpoint, plan.stableKeyName);
943
+ if (currentStableKey && !plan.force) {
944
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
945
+ continue;
946
+ }
947
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(endpoint);
948
+ await client.updateEndpoint(item.resourceId, buildMetadataUpdatePayload(endpoint, plan.stableKeyName, stableKey, item.resourceType));
949
+ const verifiedEndpoint = unwrapResource(await client.getEndpoint(item.resourceId));
950
+ const verifiedStableKey = readConfiguredResourceMetadataStableKey(verifiedEndpoint, plan.stableKeyName);
951
+ if (verifiedStableKey !== stableKey) {
952
+ throw new Error('updated endpoint did not retain the planned stable key');
953
+ }
954
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
955
+ continue;
956
+ }
957
+ if (item.resourceType === 'role-group') {
958
+ const roleGroup = currentResources.get(`role-group:${item.resourceId}`);
959
+ if (!roleGroup)
960
+ throw new Error('role-group no longer exists');
961
+ const currentStableKey = readConfiguredResourceMetadataStableKey(roleGroup, plan.stableKeyName);
962
+ if (currentStableKey && !plan.force) {
963
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
964
+ continue;
965
+ }
966
+ const stableKey = item.stableKey || buildGeneratedStableKey(roleGroup);
967
+ await client.updateRoleGroup(item.resourceId, buildMetadataUpdatePayload(roleGroup, plan.stableKeyName, stableKey, item.resourceType));
968
+ results.push({
969
+ resourceType: item.resourceType,
970
+ resourceId: item.resourceId,
971
+ stableKey,
972
+ action: 'update',
973
+ });
974
+ continue;
975
+ }
976
+ if (item.resourceType === 'group') {
977
+ const group = currentResources.get(`group:${item.resourceId}`);
978
+ if (!group) {
979
+ throw new Error('group no longer exists');
980
+ }
981
+ const exclusionReason = groupExclusionReason(group);
982
+ if (exclusionReason) {
983
+ throw new Error(`group moved outside migration scope: ${exclusionReason}`);
984
+ }
985
+ const currentStableKey = readConfiguredResourceMetadataStableKey(group, plan.stableKeyName);
986
+ if (currentStableKey && !plan.force) {
987
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
988
+ continue;
989
+ }
990
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(group);
991
+ await client.updateGroup(item.resourceId, buildMetadataUpdatePayload(group, plan.stableKeyName, stableKey, item.resourceType));
992
+ results.push({
993
+ resourceType: item.resourceType,
994
+ resourceId: item.resourceId,
995
+ stableKey,
996
+ action: 'update',
997
+ });
998
+ continue;
999
+ }
1000
+ if (item.resourceType === 'job-template') {
1001
+ const jobTemplate = currentResources.get(`job-template:${item.resourceId}`);
1002
+ if (!jobTemplate)
1003
+ throw new Error('job-template no longer exists');
1004
+ const currentStableKey = readConfiguredResourceMetadataStableKey(jobTemplate, plan.stableKeyName);
1005
+ if (currentStableKey && !plan.force) {
1006
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
1007
+ continue;
1008
+ }
1009
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(jobTemplate);
1010
+ await client.updateJobTemplate(item.resourceId, buildJobTemplateMetadataUpdatePayload(jobTemplate, plan.stableKeyName, stableKey));
1011
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
1012
+ continue;
1013
+ }
1014
+ if (item.resourceType === 'schedule') {
1015
+ const schedule = currentResources.get(`schedule:${item.resourceId}`);
1016
+ if (!schedule) {
1017
+ throw new Error('schedule no longer exists');
1018
+ }
1019
+ const exclusionReason = scheduleExclusionReason(schedule);
1020
+ if (exclusionReason) {
1021
+ throw new Error(`schedule moved outside migration scope: ${exclusionReason}`);
1022
+ }
1023
+ const currentStableKey = readConfiguredResourceMetadataStableKey(schedule, plan.stableKeyName);
1024
+ if (currentStableKey && !plan.force) {
1025
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
1026
+ continue;
1027
+ }
1028
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(schedule);
1029
+ await client.updateSchedule(item.resourceId, buildMetadataUpdatePayload(schedule, plan.stableKeyName, stableKey, item.resourceType));
1030
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
1031
+ continue;
1032
+ }
1033
+ if (item.resourceType === 'event') {
1034
+ const event = currentResources.get(`event:${item.resourceId}`);
1035
+ if (!event) {
1036
+ throw new Error('event no longer exists');
1037
+ }
1038
+ const exclusionReason = eventExclusionReason(event);
1039
+ if (exclusionReason) {
1040
+ throw new Error(`event moved outside migration scope: ${exclusionReason}`);
1041
+ }
1042
+ const currentStableKey = readConfiguredResourceMetadataStableKey(event, plan.stableKeyName);
1043
+ if (currentStableKey && !plan.force) {
1044
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: currentStableKey, action: 'skip' });
1045
+ continue;
1046
+ }
1047
+ const stableKey = item.stableKey || buildNamedResourceGeneratedStableKey(event);
1048
+ await client.updateEvent(item.resourceId, buildMetadataUpdatePayload(event, plan.stableKeyName, stableKey, item.resourceType));
1049
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey, action: 'update' });
1050
+ continue;
1051
+ }
112
1052
  throw new Error(`unsupported resource type: ${item.resourceType}`);
113
1053
  }
114
1054
  catch (error) {
@@ -116,10 +1056,45 @@ export async function applyMetadataBackfillPlan(input) {
116
1056
  resourceType: item.resourceType,
117
1057
  resourceId: item.resourceId,
118
1058
  stableKey: item.stableKey,
1059
+ ...(item.columnName ? { columnName: item.columnName } : {}),
119
1060
  action: 'failed',
120
1061
  error: error instanceof Error ? error.message : String(error),
121
1062
  });
122
1063
  }
123
1064
  }
1065
+ if (resourceTypes.has('database-table')) {
1066
+ try {
1067
+ const { databases } = await client.listAllDatabaseSchemas({
1068
+ projection: 'pull',
1069
+ skipPartitions: plan.skipPartitions,
1070
+ });
1071
+ const verified = new Map(databases
1072
+ .filter((database) => !isDatabaseBackupArtifact(database))
1073
+ .map((database) => [resourceIdOf(database), database]));
1074
+ for (const result of results.filter((candidate) => candidate.resourceType === 'database-table' && candidate.action === 'update')) {
1075
+ const database = verified.get(result.resourceId);
1076
+ const definition = result.columnName && database
1077
+ ? databaseDefinitions(database).find((candidate) => candidate.name === result.columnName)
1078
+ : undefined;
1079
+ const stableKey = result.columnName
1080
+ ? (definition
1081
+ ? columnStableKeyValue(definition, plan.stableKeyName).value
1082
+ : null)
1083
+ : (database
1084
+ ? readConfiguredResourceMetadataStableKey(database, plan.stableKeyName)
1085
+ : null);
1086
+ if (stableKey !== result.stableKey) {
1087
+ result.action = 'failed';
1088
+ result.error = 'final verification did not find the assigned stable key';
1089
+ }
1090
+ }
1091
+ }
1092
+ catch (error) {
1093
+ for (const result of results.filter((candidate) => candidate.resourceType === 'database-table' && candidate.action === 'update')) {
1094
+ result.action = 'failed';
1095
+ result.error = `final verification failed: ${error instanceof Error ? error.message : String(error)}`;
1096
+ }
1097
+ }
1098
+ }
124
1099
  return results;
125
1100
  }