@revoengine/cli 1.0.11 → 1.0.13

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 (81) hide show
  1. package/README.md +275 -479
  2. package/dist/src/cli.js +71 -5
  3. package/dist/src/client.d.ts +28 -12
  4. package/dist/src/client.js +234 -66
  5. package/dist/src/commands/component.d.ts +67 -0
  6. package/dist/src/commands/component.js +299 -27
  7. package/dist/src/commands/database-tables.d.ts +2 -0
  8. package/dist/src/commands/{database-schemas.js → database-tables.js} +21 -40
  9. package/dist/src/commands/database-views.js +21 -18
  10. package/dist/src/commands/endpoints.js +26 -16
  11. package/dist/src/commands/events.js +18 -20
  12. package/dist/src/commands/groups.js +13 -22
  13. package/dist/src/commands/index.d.ts +2 -1
  14. package/dist/src/commands/index.js +2 -1
  15. package/dist/src/commands/job-templates.js +21 -15
  16. package/dist/src/commands/metadata.js +58 -15
  17. package/dist/src/commands/migrate.d.ts +6 -0
  18. package/dist/src/commands/migrate.js +658 -0
  19. package/dist/src/commands/project.js +4 -4
  20. package/dist/src/commands/role-groups.js +14 -25
  21. package/dist/src/commands/schedules.js +19 -20
  22. package/dist/src/commands/terminal-browser.d.ts +16 -0
  23. package/dist/src/commands/terminal-browser.js +92 -0
  24. package/dist/src/commands/terminal-image.d.ts +7 -0
  25. package/dist/src/commands/terminal-image.js +40 -0
  26. package/dist/src/commands/terminal-patch-worker.d.ts +1 -0
  27. package/dist/src/commands/terminal-patch-worker.js +24 -0
  28. package/dist/src/commands/terminal-patch.d.ts +2 -0
  29. package/dist/src/commands/terminal-patch.js +156 -0
  30. package/dist/src/commands/terminal-sandbox.d.ts +8 -0
  31. package/dist/src/commands/terminal-sandbox.js +87 -0
  32. package/dist/src/commands/terminal-service.js +2 -2
  33. package/dist/src/commands/terminal.d.ts +31 -4
  34. package/dist/src/commands/terminal.js +360 -45
  35. package/dist/src/component-lock.d.ts +12 -2
  36. package/dist/src/component-lock.js +60 -1
  37. package/dist/src/diff-details.d.ts +8 -0
  38. package/dist/src/diff-details.js +152 -0
  39. package/dist/src/env-sync.js +8 -6
  40. package/dist/src/http-trace.d.ts +94 -0
  41. package/dist/src/http-trace.js +226 -0
  42. package/dist/src/metadata-backfill.d.ts +5 -4
  43. package/dist/src/metadata-backfill.js +82 -158
  44. package/dist/src/migration.d.ts +141 -0
  45. package/dist/src/migration.js +1632 -0
  46. package/dist/src/resource-inventory.d.ts +28 -0
  47. package/dist/src/resource-inventory.js +85 -0
  48. package/dist/src/resource-syncs/{database-schema-sync.d.ts → database-table-sync.d.ts} +13 -3
  49. package/dist/src/resource-syncs/{database-schema-sync.js → database-table-sync.js} +147 -62
  50. package/dist/src/resource-syncs/database-view-sync.d.ts +24 -2
  51. package/dist/src/resource-syncs/database-view-sync.js +156 -68
  52. package/dist/src/resource-syncs/endpoint-sync.d.ts +27 -0
  53. package/dist/src/resource-syncs/endpoint-sync.js +362 -82
  54. package/dist/src/resource-syncs/event-sync.d.ts +27 -0
  55. package/dist/src/resource-syncs/event-sync.js +123 -26
  56. package/dist/src/resource-syncs/group-sync.d.ts +7 -0
  57. package/dist/src/resource-syncs/group-sync.js +60 -14
  58. package/dist/src/resource-syncs/job-template-sync.d.ts +21 -0
  59. package/dist/src/resource-syncs/job-template-sync.js +91 -30
  60. package/dist/src/resource-syncs/role-group-sync.d.ts +7 -0
  61. package/dist/src/resource-syncs/role-group-sync.js +47 -9
  62. package/dist/src/resource-syncs/schedule-sync.d.ts +30 -1
  63. package/dist/src/resource-syncs/schedule-sync.js +114 -20
  64. package/dist/src/resource-syncs/util.d.ts +3 -0
  65. package/dist/src/resource-syncs/util.js +8 -6
  66. package/dist/src/resource-target.d.ts +11 -0
  67. package/dist/src/resource-target.js +48 -0
  68. package/dist/src/sync-output.d.ts +29 -1
  69. package/dist/src/sync-output.js +139 -2
  70. package/dist/src/tracked-resources.d.ts +1 -1
  71. package/dist/src/tracked-resources.js +8 -6
  72. package/dist/src/types.d.ts +3 -0
  73. package/dist/src/ui.js +18 -9
  74. package/dist/src/utils.d.ts +2 -0
  75. package/dist/src/utils.js +17 -0
  76. package/dist/src/workspace-diff.d.ts +25 -0
  77. package/dist/src/workspace-diff.js +75 -0
  78. package/package.json +9 -6
  79. package/dist/src/commands/database-schemas.d.ts +0 -2
  80. /package/dist/src/{database-schema-artifacts.d.ts → database-table-artifacts.d.ts} +0 -0
  81. /package/dist/src/{database-schema-artifacts.js → database-table-artifacts.js} +0 -0
@@ -1,13 +1,17 @@
1
1
  import path from 'node:path';
2
+ import { describeFieldChanges } from "../diff-details.js";
2
3
  import { hashPortableComponentSource, hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
4
+ import { withHttpTraceContext } from "../http-trace.js";
3
5
  import { readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
4
6
  import { readJsonFile, sanitizeSegment } from "../utils.js";
5
7
  import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
6
- import { findManifestFiles, isRecord, localTargetPath, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
8
+ import { findManifestFiles, isRecord, localTargetPath, removeRelocatedManifest, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
7
9
  export const ENDPOINTS_DIRECTORY = 'Endpoints';
8
10
  export const ENDPOINT_MANIFEST_FILE = 'endpoint.json';
9
11
  const ENDPOINT_DEFAULT_TIMEOUT_SECONDS = 60;
10
12
  const ENDPOINT_DEFAULT_MEMORY_MB = 32;
13
+ const REMOTE_DETAIL_BATCH_SIZE = 10;
14
+ const REMOTE_DETAIL_REQUEST_TIMEOUT_MS = 30_000;
11
15
  const ENDPOINT_PLAN_STATUS_ORDER = [
12
16
  'create', 'restore', 'safe-update', 'remote-changed', 'conflict', 'missing-lock',
13
17
  'restore-blocked', 'collision', 'clean', 'orphan', 'skipped',
@@ -208,25 +212,66 @@ function readWorkspaceComponents(cwd, stableKeyName) {
208
212
  }
209
213
  return result;
210
214
  }
211
- async function loadRemoteEndpoints(client) {
212
- const { endpoints } = await client.listAllEndpoints();
213
- return Promise.all(endpoints.map(async (summary) => {
215
+ function createRemoteDetailScheduler() {
216
+ let available = REMOTE_DETAIL_BATCH_SIZE;
217
+ const waiting = [];
218
+ return async (task) => {
219
+ if (available > 0) {
220
+ available -= 1;
221
+ }
222
+ else {
223
+ await new Promise((resolve) => waiting.push(resolve));
224
+ }
225
+ try {
226
+ return await task();
227
+ }
228
+ finally {
229
+ const next = waiting.shift();
230
+ if (next) {
231
+ next();
232
+ }
233
+ else {
234
+ available += 1;
235
+ }
236
+ }
237
+ };
238
+ }
239
+ async function mapInBatches(items, mapper, schedule) {
240
+ const results = [];
241
+ for (let offset = 0; offset < items.length; offset += REMOTE_DETAIL_BATCH_SIZE) {
242
+ const batch = items.slice(offset, offset + REMOTE_DETAIL_BATCH_SIZE);
243
+ results.push(...await Promise.all(batch.map((item) => schedule(() => mapper(item)))));
244
+ }
245
+ return results;
246
+ }
247
+ async function loadRemoteEndpoints(client, schedule = createRemoteDetailScheduler()) {
248
+ const { endpoints } = await withHttpTraceContext({ operation: 'list' }, () => client.listAllEndpoints());
249
+ return mapInBatches(endpoints, async (summary) => {
214
250
  const endpointId = endpointIdOf(summary);
215
251
  if (!endpointId) {
216
252
  return summary;
217
253
  }
218
- return unwrapData(await client.getEndpoint(endpointId));
219
- }));
254
+ return unwrapData(await withHttpTraceContext({
255
+ operation: 'get',
256
+ entityId: endpointId,
257
+ ...(typeof summary.name === 'string' ? { entityName: summary.name } : {}),
258
+ }, () => client.getEndpoint(endpointId, { timeoutMs: REMOTE_DETAIL_REQUEST_TIMEOUT_MS })));
259
+ }, schedule);
220
260
  }
221
- async function loadRemoteComponents(client) {
222
- const { components } = await client.listAllComponents();
223
- return Promise.all(components.map(async (summary) => {
261
+ async function loadRemoteComponents(client, schedule = createRemoteDetailScheduler()) {
262
+ const { components } = await withHttpTraceContext({ dependency: 'component', operation: 'list' }, () => client.listAllComponents());
263
+ return mapInBatches(components, async (summary) => {
224
264
  const componentId = componentIdOf(summary);
225
265
  if (!componentId) {
226
266
  return summary;
227
267
  }
228
- return unwrapData(await client.getComponent(componentId));
229
- }));
268
+ return unwrapData(await withHttpTraceContext({
269
+ dependency: 'component',
270
+ operation: 'get',
271
+ entityId: componentId,
272
+ ...(typeof summary.name === 'string' ? { entityName: summary.name } : {}),
273
+ }, () => client.getComponent(componentId, { timeoutMs: REMOTE_DETAIL_REQUEST_TIMEOUT_MS })));
274
+ }, schedule);
230
275
  }
231
276
  async function componentBinding(input) {
232
277
  const component = input.componentsById.get(input.componentId);
@@ -237,10 +282,15 @@ async function componentBinding(input) {
237
282
  if (!stableKey) {
238
283
  throw new Error(`Endpoint "${input.endpointStableKey}" ${input.relation} component is unmanaged: missing ${input.stableKeyName}.`);
239
284
  }
240
- if (typeof input.componentVersion !== 'number') {
285
+ const componentVersion = input.componentVersion;
286
+ if (typeof componentVersion !== 'number') {
241
287
  return { stableKey, binding: 'latest' };
242
288
  }
243
- const snapshot = unwrapData(await input.client.getComponentSnapshotVersion(input.componentId, input.componentVersion));
289
+ const snapshot = unwrapData(await withHttpTraceContext({
290
+ dependency: 'component',
291
+ operation: 'get-snapshot',
292
+ entityId: input.componentId,
293
+ }, () => input.client.getComponentSnapshotVersion(input.componentId, componentVersion)));
244
294
  return { stableKey, binding: 'pinned', pinnedDigest: hashPortableComponentSource(snapshot) };
245
295
  }
246
296
  async function manifestFromRecord(input) {
@@ -311,9 +361,10 @@ async function manifestFromRecord(input) {
311
361
  }
312
362
  export async function pullEndpointsToWorkspace(input) {
313
363
  const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Endpoint');
364
+ const scheduleDetail = createRemoteDetailScheduler();
314
365
  const [records, components] = await Promise.all([
315
- loadRemoteEndpoints(input.client),
316
- loadRemoteComponents(input.client),
366
+ loadRemoteEndpoints(input.client, scheduleDetail),
367
+ loadRemoteComponents(input.client, scheduleDetail),
317
368
  ]);
318
369
  const componentsById = new Map(components.map((component) => [componentIdOf(component), component]));
319
370
  const manifests = [];
@@ -378,6 +429,17 @@ export async function pullEndpointsToWorkspace(input) {
378
429
  ...(existing ? { previousPath: existing.manifestPath } : {}),
379
430
  };
380
431
  });
432
+ const sourceStableKeys = new Set(manifests.map((manifest) => manifest.stableKey));
433
+ const pruned = input.pruneOrphans === true
434
+ ? [...existingByKey.values()]
435
+ .filter((entry) => !sourceStableKeys.has(entry.manifest.stableKey))
436
+ .map((entry) => ({
437
+ stableKey: entry.manifest.stableKey,
438
+ targetPath: localTargetPath(input.cwd, entry.manifestPath),
439
+ manifestPath: entry.manifestPath,
440
+ }))
441
+ .sort((left, right) => right.manifestPath.length - left.manifestPath.length || left.stableKey.localeCompare(right.stableKey))
442
+ : [];
381
443
  const candidatePathCounts = new Map();
382
444
  for (const write of writes) {
383
445
  const identity = portablePathIdentity(write.filePath);
@@ -429,6 +491,11 @@ export async function pullEndpointsToWorkspace(input) {
429
491
  }
430
492
  lock.endpoints[write.manifest.stableKey] = entry;
431
493
  }
494
+ for (const removed of pruned) {
495
+ removeRelocatedManifest(removed.manifestPath, root);
496
+ delete lock.endpoints[removed.stableKey];
497
+ lockChanged = true;
498
+ }
432
499
  if (lockChanged) {
433
500
  writeComponentLock(projectRoot, lock);
434
501
  }
@@ -437,6 +504,7 @@ export async function pullEndpointsToWorkspace(input) {
437
504
  manifest: write.manifest,
438
505
  targetPath: localTargetPath(input.cwd, write.filePath),
439
506
  })),
507
+ pruned: pruned.map(({ stableKey, targetPath }) => ({ stableKey, targetPath })),
440
508
  skipped,
441
509
  };
442
510
  }
@@ -484,7 +552,9 @@ function hasComponentElement(component, elementKey) {
484
552
  }
485
553
  function componentDependencyDiagnostics(input) {
486
554
  const blockers = [];
555
+ const warnings = [];
487
556
  const details = [];
557
+ const dependencies = [];
488
558
  const bindings = [
489
559
  ...(input.endpoint.execution ? [{ relation: 'execution', binding: input.endpoint.execution }] : []),
490
560
  ...(input.endpoint.schema ? [{ relation: 'schema', binding: input.endpoint.schema }] : []),
@@ -492,47 +562,95 @@ function componentDependencyDiagnostics(input) {
492
562
  for (const { relation, binding } of bindings) {
493
563
  const workspaceMatches = input.workspaceComponents.get(binding.stableKey) || [];
494
564
  const targetMatches = input.targetComponents.get(binding.stableKey) || [];
495
- if (workspaceMatches.length !== 1 || targetMatches.length !== 1) {
565
+ const projectedMatches = input.projectedComponents?.get(binding.stableKey) || [];
566
+ const usesProjection = input.projectedComponents !== undefined;
567
+ if (workspaceMatches.length !== 1 || (!usesProjection && targetMatches.length !== 1)) {
496
568
  const location = workspaceMatches.length !== 1 ? 'source' : 'target';
497
569
  const count = location === 'source' ? workspaceMatches.length : targetMatches.length;
498
570
  blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" is ${count === 0 ? 'missing' : 'ambiguous'} in ${location}; align Components before Endpoints.`);
499
571
  continue;
500
572
  }
573
+ if (usesProjection && projectedMatches.length !== 1) {
574
+ blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" is ${projectedMatches.length === 0 ? 'missing' : 'ambiguous'} in projected post-Component state.`);
575
+ continue;
576
+ }
501
577
  const workspace = workspaceMatches[0];
502
- const target = targetMatches[0];
578
+ const target = targetMatches.length === 1 ? targetMatches[0] : undefined;
503
579
  const workspaceDigest = hashPortableComponentSource(workspace);
504
- const targetDigest = hashPortableComponentSource(target);
580
+ const targetDigest = target ? hashPortableComponentSource(target) : null;
581
+ const projected = usesProjection ? projectedMatches[0] : undefined;
582
+ const expectedHash = binding.binding === 'pinned' ? binding.pinnedDigest || '' : workspaceDigest;
583
+ const projectedHash = projected?.desiredHash ?? targetDigest;
584
+ const readiness = projected?.state === 'pending-create'
585
+ ? 'pending-component-create'
586
+ : projected?.state === 'pending-update'
587
+ ? 'pending-component-update'
588
+ : projected?.state === 'pending-adopt'
589
+ ? 'pending-component-adopt'
590
+ : 'ready';
591
+ dependencies.push({
592
+ relation,
593
+ stableKey: binding.stableKey,
594
+ binding: binding.binding,
595
+ expectedHash,
596
+ projectedHash,
597
+ actualHash: targetDigest,
598
+ readiness,
599
+ ...(relation === 'schema' && binding.element
600
+ ? { element: binding.element }
601
+ : {}),
602
+ });
603
+ if (usesProjection) {
604
+ details.push({ label: `${relation} expected`, values: expectedHash }, { label: `${relation} projected`, values: projectedHash || '<missing>' }, { label: `${relation} actual`, values: targetDigest || '<missing>' });
605
+ }
505
606
  if (binding.binding === 'pinned') {
506
- details.push({ label: `${relation} A (pinned)`, values: binding.pinnedDigest || '' });
607
+ if (!usesProjection) {
608
+ details.push({ label: `${relation} A (pinned)`, values: binding.pinnedDigest || '' });
609
+ }
610
+ }
611
+ if (!usesProjection) {
612
+ details.push({ label: `${relation} B (source)`, values: workspaceDigest }, { label: `${relation} C (target)`, values: targetDigest || '' });
507
613
  }
508
- details.push({ label: `${relation} B (source)`, values: workspaceDigest }, { label: `${relation} C (target)`, values: targetDigest });
509
614
  if (relation === 'execution') {
510
615
  const allowed = new Set(['CODE_JS', 'CODE_TS']);
511
- if (!allowed.has(componentType(workspace)) || !allowed.has(componentType(target))) {
616
+ if (!allowed.has(componentType(workspace)) || (!usesProjection && (!target || !allowed.has(componentType(target))))) {
512
617
  blockers.push(`Endpoint "${input.endpoint.stableKey}" execution Component "${binding.stableKey}" must be CODE_JS or CODE_TS in source and target.`);
513
618
  }
514
619
  }
515
620
  else {
516
- if (componentType(workspace) !== 'JSON_VALIDATOR' || componentType(target) !== 'JSON_VALIDATOR') {
621
+ if (componentType(workspace) !== 'JSON_VALIDATOR'
622
+ || (!usesProjection && (!target || componentType(target) !== 'JSON_VALIDATOR'))) {
517
623
  blockers.push(`Endpoint "${input.endpoint.stableKey}" schema Component "${binding.stableKey}" must be JSON_VALIDATOR in source and target.`);
518
624
  }
519
625
  const schema = binding;
520
626
  if (schema.element
521
- && (!hasComponentElement(workspace, schema.element) || !hasComponentElement(target, schema.element))) {
627
+ && (!hasComponentElement(workspace, schema.element)
628
+ || (!usesProjection && (!target || !hasComponentElement(target, schema.element))))) {
522
629
  blockers.push(`Endpoint "${input.endpoint.stableKey}" schema element "${schema.element}" is missing from Component "${binding.stableKey}" in source or target.`);
523
630
  }
524
- else if (!schema.element && ((workspace.elements || []).length === 0 || (target.elements || []).length === 0)) {
631
+ else if (!schema.element && ((workspace.elements || []).length === 0
632
+ || (!usesProjection && (!target || (target.elements || []).length === 0)))) {
525
633
  blockers.push(`Endpoint "${input.endpoint.stableKey}" schema Component "${binding.stableKey}" has no default first element in source or target.`);
526
634
  }
527
635
  }
528
- const digestMatches = binding.binding === 'latest'
529
- ? workspaceDigest === targetDigest
530
- : binding.pinnedDigest === workspaceDigest && workspaceDigest === targetDigest;
636
+ const digestMatches = usesProjection
637
+ ? expectedHash === projectedHash
638
+ : binding.binding === 'latest'
639
+ ? workspaceDigest === targetDigest
640
+ : binding.pinnedDigest === workspaceDigest && workspaceDigest === targetDigest;
531
641
  if (!digestMatches) {
532
- blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" portable content does not match (${binding.binding}); align Components before Endpoints.`);
642
+ blockers.push(usesProjection
643
+ ? `Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" projected portable content does not match the expected ${binding.binding} digest.`
644
+ : `Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" portable content does not match (${binding.binding}); align Components before Endpoints.`);
645
+ }
646
+ else if (usesProjection && readiness !== 'ready') {
647
+ warnings.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" is ${readiness}; Endpoint migration will wait for verified Component readback.`);
648
+ }
649
+ else if (usesProjection && targetDigest !== projectedHash) {
650
+ blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" is marked ready but actual target content differs from projected content.`);
533
651
  }
534
652
  }
535
- return { blockers, details };
653
+ return { blockers, warnings, details, dependencies };
536
654
  }
537
655
  function targetComponentsByStableKey(components, stableKeyName) {
538
656
  const result = new Map();
@@ -620,6 +738,7 @@ export async function buildEndpointsPlan(input) {
620
738
  const { projectRoot } = requireProjectLayout(input.cwd, 'Endpoint');
621
739
  const items = [];
622
740
  const blockers = [];
741
+ const warnings = [];
623
742
  const exclusions = [];
624
743
  const localByStableKey = new Map();
625
744
  for (const entry of readWorkspaceEndpoints(input.cwd)) {
@@ -642,12 +761,22 @@ export async function buildEndpointsPlan(input) {
642
761
  }
643
762
  }
644
763
  }
764
+ const scheduleDetail = createRemoteDetailScheduler();
645
765
  const [targetEndpoints, targetComponents] = await Promise.all([
646
- loadRemoteEndpoints(input.client),
647
- loadRemoteComponents(input.client),
766
+ loadRemoteEndpoints(input.client, scheduleDetail),
767
+ loadRemoteComponents(input.client, scheduleDetail),
648
768
  ]);
649
769
  const workspaceComponents = readWorkspaceComponents(input.cwd, input.stableKeyName);
650
770
  const targetComponentsByKey = targetComponentsByStableKey(targetComponents, input.stableKeyName);
771
+ const projectedComponentsByKey = input.projectedComponents === undefined
772
+ ? undefined
773
+ : new Map();
774
+ for (const component of input.projectedComponents || []) {
775
+ projectedComponentsByKey?.set(component.stableKey, [
776
+ ...(projectedComponentsByKey.get(component.stableKey) || []),
777
+ component,
778
+ ]);
779
+ }
651
780
  for (const [stableKey, matches] of workspaceComponents) {
652
781
  if (matches.length > 1) {
653
782
  blockers.push(`Duplicate source Component stableKey "${stableKey}"; align Components before Endpoints.`);
@@ -687,7 +816,11 @@ export async function buildEndpointsPlan(input) {
687
816
  if (routeKey) {
688
817
  targetRouteOwners.set(routeKey, [
689
818
  ...(targetRouteOwners.get(routeKey) || []),
690
- { ...(stableKey ? { stableKey } : {}), name: endpointLabel(record, 'unknown') },
819
+ {
820
+ ...(stableKey ? { stableKey } : {}),
821
+ name: endpointLabel(record, 'unknown'),
822
+ deleted: Boolean(record.deletedAt || record.deletedBy),
823
+ },
691
824
  ]);
692
825
  }
693
826
  if (record.deletedAt || record.deletedBy) {
@@ -747,13 +880,16 @@ export async function buildEndpointsPlan(input) {
747
880
  }
748
881
  }
749
882
  const desiredRouteOwners = new Map();
883
+ const desiredRoutesByStableKey = new Map();
750
884
  for (const [stableKey, entries] of localByStableKey) {
751
885
  if (entries.length === 1) {
752
886
  const routeKey = endpointRouteKey(entries[0].manifest.route);
753
887
  desiredRouteOwners.set(routeKey, [...(desiredRouteOwners.get(routeKey) || []), stableKey]);
888
+ desiredRoutesByStableKey.set(stableKey, routeKey);
754
889
  }
755
890
  }
756
891
  const routeBlockedKeys = new Set(targetRouteBlockedKeys);
892
+ const routeDependencies = new Map();
757
893
  for (const [routeKey, stableKeys] of desiredRouteOwners) {
758
894
  if (stableKeys.length > 1) {
759
895
  blockers.push(`Endpoint route collision on ${routeKey}: ${stableKeys.join(', ')}.`);
@@ -764,14 +900,56 @@ export async function buildEndpointsPlan(input) {
764
900
  }
765
901
  for (const stableKey of stableKeys) {
766
902
  const collisions = (targetRouteOwners.get(routeKey) || []).filter((owner) => owner.stableKey !== stableKey);
767
- if (collisions.length > 0) {
903
+ const movingOwners = collisions.filter((owner) => (!owner.deleted
904
+ && owner.stableKey
905
+ && desiredRoutesByStableKey.has(owner.stableKey)
906
+ && desiredRoutesByStableKey.get(owner.stableKey) !== routeKey));
907
+ for (const owner of movingOwners) {
908
+ routeDependencies.set(stableKey, new Set([
909
+ ...(routeDependencies.get(stableKey) || []),
910
+ owner.stableKey,
911
+ ]));
912
+ }
913
+ const retainedCollisions = collisions.filter((owner) => !movingOwners.includes(owner));
914
+ if (retainedCollisions.length > 0) {
768
915
  routeBlockedKeys.add(stableKey);
769
- const collisionNames = collisions.map((owner) => owner.stableKey || owner.name).sort();
916
+ const collisionNames = retainedCollisions.map((owner) => owner.stableKey || owner.name).sort();
770
917
  blockers.push(`Endpoint route collision on ${routeKey}: "${stableKey}" conflicts with target ${collisionNames.join(', ')}.`);
771
918
  items.push({ status: 'collision', stableKey, reason: `target route ${routeKey} is owned by another Endpoint` });
772
919
  }
773
920
  }
774
921
  }
922
+ const routeVisitState = new Map();
923
+ const routeCycleKeys = new Set();
924
+ const visitRouteDependency = (stableKey, trail) => {
925
+ const state = routeVisitState.get(stableKey);
926
+ if (state === 'visiting') {
927
+ const cycleStart = trail.indexOf(stableKey);
928
+ for (const key of trail.slice(cycleStart)) {
929
+ routeCycleKeys.add(key);
930
+ }
931
+ return;
932
+ }
933
+ if (state === 'visited') {
934
+ return;
935
+ }
936
+ routeVisitState.set(stableKey, 'visiting');
937
+ for (const dependency of routeDependencies.get(stableKey) || []) {
938
+ visitRouteDependency(dependency, [...trail, stableKey]);
939
+ }
940
+ routeVisitState.set(stableKey, 'visited');
941
+ };
942
+ for (const stableKey of [...routeDependencies.keys()].sort()) {
943
+ visitRouteDependency(stableKey, []);
944
+ }
945
+ if (routeCycleKeys.size > 0) {
946
+ const keys = [...routeCycleKeys].sort();
947
+ blockers.push(`Endpoint route changes contain a cycle that cannot be applied atomically: ${keys.join(', ')}.`);
948
+ for (const stableKey of keys) {
949
+ routeBlockedKeys.add(stableKey);
950
+ items.push({ status: 'collision', stableKey, reason: 'cyclic route reassignment requires manual staging' });
951
+ }
952
+ }
775
953
  const lock = readComponentLock(projectRoot);
776
954
  const consumedTargets = new Set();
777
955
  for (const [stableKey, localEntries] of localByStableKey) {
@@ -783,7 +961,9 @@ export async function buildEndpointsPlan(input) {
783
961
  endpoint: desired,
784
962
  workspaceComponents,
785
963
  targetComponents: targetComponentsByKey,
964
+ projectedComponents: projectedComponentsByKey,
786
965
  });
966
+ warnings.push(...dependency.warnings);
787
967
  const desiredHash = hashPortableEndpoint(desired);
788
968
  if (ambiguousTargetKeys.has(stableKey) || targetIssueKeys.has(stableKey)) {
789
969
  continue;
@@ -814,6 +994,8 @@ export async function buildEndpointsPlan(input) {
814
994
  ? { reason: restoreSafety[0] || 'Component compatibility gate failed; align Components before Endpoints.' }
815
995
  : { reason: 'exact soft-deleted target Stable Key match' }),
816
996
  details: dependency.details,
997
+ dependencies: dependency.dependencies,
998
+ routeDependencies: [...(routeDependencies.get(stableKey) || [])].sort(),
817
999
  });
818
1000
  continue;
819
1001
  }
@@ -838,6 +1020,8 @@ export async function buildEndpointsPlan(input) {
838
1020
  ? { reason: 'Component compatibility gate failed; align Components before Endpoints.' }
839
1021
  : {}),
840
1022
  details: dependency.details,
1023
+ dependencies: dependency.dependencies,
1024
+ routeDependencies: [...(routeDependencies.get(stableKey) || [])].sort(),
841
1025
  });
842
1026
  continue;
843
1027
  }
@@ -851,6 +1035,9 @@ export async function buildEndpointsPlan(input) {
851
1035
  currentHash: current.hash,
852
1036
  ...(baselineHash ? { baselineHash } : {}),
853
1037
  details: dependency.details,
1038
+ dependencies: dependency.dependencies,
1039
+ routeDependencies: [...(routeDependencies.get(stableKey) || [])].sort(),
1040
+ fieldChanges: describeFieldChanges(desired, current.manifest, diffEndpoints(desired, current.manifest)),
854
1041
  };
855
1042
  if (desiredHash === current.hash) {
856
1043
  items.push({ status: 'clean', ...common });
@@ -906,6 +1093,7 @@ export async function buildEndpointsPlan(input) {
906
1093
  env: input.envName,
907
1094
  counts,
908
1095
  blockers: [...new Set(blockers)].sort(),
1096
+ warnings: [...new Set(warnings)].sort(),
909
1097
  items,
910
1098
  exclusions: [...new Set(exclusions)].sort(),
911
1099
  };
@@ -1104,6 +1292,85 @@ async function executeEndpointPushItem(input) {
1104
1292
  };
1105
1293
  }
1106
1294
  }
1295
+ const ENDPOINT_UPDATE_STATUSES = new Set([
1296
+ 'safe-update',
1297
+ 'remote-changed',
1298
+ 'conflict',
1299
+ 'missing-lock',
1300
+ ]);
1301
+ function orderedRouteReleaseUpdates(plan) {
1302
+ const updatesByStableKey = new Map(plan.items
1303
+ .filter((item) => item.stableKey && ENDPOINT_UPDATE_STATUSES.has(item.status))
1304
+ .map((item) => [item.stableKey, item]));
1305
+ const releaseKeys = new Set(plan.items.flatMap((item) => item.routeDependencies || []));
1306
+ const ordered = [];
1307
+ const visited = new Set();
1308
+ const visit = (stableKey) => {
1309
+ if (visited.has(stableKey)) {
1310
+ return;
1311
+ }
1312
+ visited.add(stableKey);
1313
+ const item = updatesByStableKey.get(stableKey);
1314
+ if (!item) {
1315
+ return;
1316
+ }
1317
+ for (const dependency of item.routeDependencies || []) {
1318
+ visit(dependency);
1319
+ }
1320
+ ordered.push(item);
1321
+ };
1322
+ for (const stableKey of [...releaseKeys].sort()) {
1323
+ visit(stableKey);
1324
+ }
1325
+ return ordered;
1326
+ }
1327
+ async function pushEndpointUpdate(input) {
1328
+ return executeEndpointPushItem({
1329
+ ...input,
1330
+ action: 'update',
1331
+ mutate: async (prepared) => {
1332
+ const liveEndpoints = await loadRemoteEndpoints(input.client);
1333
+ const matches = liveEndpoints.filter((record) => (!record.deletedAt
1334
+ && !record.deletedBy
1335
+ && readConfiguredResourceMetadataStableKey(record, input.stableKeyName) === prepared.stableKey));
1336
+ if (matches.length !== 1) {
1337
+ throw new Error(`expected one live target match, found ${matches.length}`);
1338
+ }
1339
+ const target = matches[0];
1340
+ const targetId = endpointIdOf(target);
1341
+ if (!targetId) {
1342
+ throw new Error('live target did not include endpointId');
1343
+ }
1344
+ const targetComponents = await loadRemoteComponents(input.client);
1345
+ const targetManifest = await manifestFromRecord({
1346
+ client: input.client,
1347
+ record: target,
1348
+ stableKey: prepared.stableKey,
1349
+ stableKeyName: input.stableKeyName,
1350
+ componentsById: new Map(targetComponents.map((component) => [componentIdOf(component), component])),
1351
+ });
1352
+ const targetHash = hashPortableEndpoint(targetManifest);
1353
+ if (targetHash !== input.item.currentHash) {
1354
+ throw new Error('target changed after planning');
1355
+ }
1356
+ if (typeof target.version !== 'number') {
1357
+ throw new Error('live target did not include version');
1358
+ }
1359
+ await updateEndpointConfigurationAndActivation({
1360
+ client: input.client,
1361
+ cwd: input.cwd,
1362
+ stableKeyName: input.stableKeyName,
1363
+ endpointId: targetId,
1364
+ stableKey: prepared.stableKey,
1365
+ manifest: prepared.manifest,
1366
+ expectedRevisionHash: endpointRevisionHash(target),
1367
+ targetLabel: 'target',
1368
+ workspaceComponents: input.workspaceComponents,
1369
+ });
1370
+ return targetId;
1371
+ },
1372
+ });
1373
+ }
1107
1374
  export async function pushEndpoints(input) {
1108
1375
  const plan = await buildEndpointsPlan(input);
1109
1376
  if (plan.blockers.length > 0) {
@@ -1117,7 +1384,41 @@ export async function pushEndpoints(input) {
1117
1384
  const localByKey = readValidWorkspaceEndpoints(input.cwd, input.stableKeyName);
1118
1385
  const workspaceComponents = readWorkspaceComponents(input.cwd, input.stableKeyName);
1119
1386
  const results = [];
1387
+ const releaseUpdates = orderedRouteReleaseUpdates(plan);
1388
+ const releaseUpdateKeys = new Set(releaseUpdates.map((item) => item.stableKey || ''));
1389
+ const completedReleaseKeys = new Set();
1390
+ for (const item of releaseUpdates) {
1391
+ const unresolvedRouteDependency = (item.routeDependencies || [])
1392
+ .find((stableKey) => !completedReleaseKeys.has(stableKey));
1393
+ if (unresolvedRouteDependency) {
1394
+ results.push({
1395
+ stableKey: item.stableKey || '',
1396
+ action: 'update',
1397
+ status: 'failed',
1398
+ targetPath: item.stableKey || item.name || '',
1399
+ error: `route dependency "${unresolvedRouteDependency}" did not deploy`,
1400
+ });
1401
+ continue;
1402
+ }
1403
+ const result = await pushEndpointUpdate({ ...input, item, localByKey, workspaceComponents });
1404
+ results.push(result);
1405
+ if (result.status === 'deployed') {
1406
+ completedReleaseKeys.add(result.stableKey);
1407
+ }
1408
+ }
1120
1409
  for (const item of plan.items.filter((candidate) => candidate.status === 'create')) {
1410
+ const unresolvedRouteDependency = (item.routeDependencies || [])
1411
+ .find((stableKey) => !completedReleaseKeys.has(stableKey));
1412
+ if (unresolvedRouteDependency) {
1413
+ results.push({
1414
+ stableKey: item.stableKey || '',
1415
+ action: 'create',
1416
+ status: 'failed',
1417
+ targetPath: item.stableKey || item.name || '',
1418
+ error: `route dependency "${unresolvedRouteDependency}" did not deploy`,
1419
+ });
1420
+ continue;
1421
+ }
1121
1422
  results.push(await executeEndpointPushItem({
1122
1423
  ...input,
1123
1424
  item,
@@ -1147,6 +1448,18 @@ export async function pushEndpoints(input) {
1147
1448
  }));
1148
1449
  }
1149
1450
  for (const item of plan.items.filter((candidate) => candidate.status === 'restore')) {
1451
+ const unresolvedRouteDependency = (item.routeDependencies || [])
1452
+ .find((stableKey) => !completedReleaseKeys.has(stableKey));
1453
+ if (unresolvedRouteDependency) {
1454
+ results.push({
1455
+ stableKey: item.stableKey || '',
1456
+ action: 'restore',
1457
+ status: 'failed',
1458
+ targetPath: item.stableKey || item.name || '',
1459
+ error: `route dependency "${unresolvedRouteDependency}" did not deploy`,
1460
+ });
1461
+ continue;
1462
+ }
1150
1463
  results.push(await executeEndpointPushItem({
1151
1464
  ...input,
1152
1465
  item,
@@ -1203,55 +1516,22 @@ export async function pushEndpoints(input) {
1203
1516
  },
1204
1517
  }));
1205
1518
  }
1206
- const updateItems = plan.items.filter((candidate) => (['safe-update', 'remote-changed', 'conflict', 'missing-lock'].includes(candidate.status)));
1519
+ const updateItems = plan.items.filter((candidate) => (ENDPOINT_UPDATE_STATUSES.has(candidate.status)
1520
+ && !releaseUpdateKeys.has(candidate.stableKey || '')));
1207
1521
  for (const item of updateItems) {
1208
- results.push(await executeEndpointPushItem({
1209
- ...input,
1210
- item,
1211
- localByKey,
1212
- action: 'update',
1213
- mutate: async (prepared) => {
1214
- const liveEndpoints = await loadRemoteEndpoints(input.client);
1215
- const matches = liveEndpoints.filter((record) => (!record.deletedAt
1216
- && !record.deletedBy
1217
- && readConfiguredResourceMetadataStableKey(record, input.stableKeyName) === prepared.stableKey));
1218
- if (matches.length !== 1) {
1219
- throw new Error(`expected one live target match, found ${matches.length}`);
1220
- }
1221
- const target = matches[0];
1222
- const targetId = endpointIdOf(target);
1223
- if (!targetId) {
1224
- throw new Error('live target did not include endpointId');
1225
- }
1226
- const targetComponents = await loadRemoteComponents(input.client);
1227
- const targetManifest = await manifestFromRecord({
1228
- client: input.client,
1229
- record: target,
1230
- stableKey: prepared.stableKey,
1231
- stableKeyName: input.stableKeyName,
1232
- componentsById: new Map(targetComponents.map((component) => [componentIdOf(component), component])),
1233
- });
1234
- const targetHash = hashPortableEndpoint(targetManifest);
1235
- if (targetHash !== item.currentHash) {
1236
- throw new Error('target changed after planning');
1237
- }
1238
- if (typeof target.version !== 'number') {
1239
- throw new Error('live target did not include version');
1240
- }
1241
- await updateEndpointConfigurationAndActivation({
1242
- client: input.client,
1243
- cwd: input.cwd,
1244
- stableKeyName: input.stableKeyName,
1245
- endpointId: targetId,
1246
- stableKey: prepared.stableKey,
1247
- manifest: prepared.manifest,
1248
- expectedRevisionHash: endpointRevisionHash(target),
1249
- targetLabel: 'target',
1250
- workspaceComponents,
1251
- });
1252
- return targetId;
1253
- },
1254
- }));
1522
+ const unresolvedRouteDependency = (item.routeDependencies || [])
1523
+ .find((stableKey) => !completedReleaseKeys.has(stableKey));
1524
+ if (unresolvedRouteDependency) {
1525
+ results.push({
1526
+ stableKey: item.stableKey || '',
1527
+ action: 'update',
1528
+ status: 'failed',
1529
+ targetPath: item.stableKey || item.name || '',
1530
+ error: `route dependency "${unresolvedRouteDependency}" did not deploy`,
1531
+ });
1532
+ continue;
1533
+ }
1534
+ results.push(await pushEndpointUpdate({ ...input, item, localByKey, workspaceComponents }));
1255
1535
  }
1256
1536
  for (const item of plan.items.filter((candidate) => candidate.status === 'clean')) {
1257
1537
  const stableKey = item.stableKey || '';