@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
@@ -4,14 +4,57 @@ import { execFileSync } from 'node:child_process';
4
4
  import { randomUUID } from 'node:crypto';
5
5
  import { ApiError, COMPONENT_LIST_PAGE_SIZE, PermissionDeniedError } from "../client.js";
6
6
  import { getConfigDir } from "../config.js";
7
- import { REVO_LOCK_FILE, buildPortableComponentUpdatePayload, componentLockMatchesIdentity, diffPortableComponentSource, getComponentLockEntry, getComponentLockEntries, hashComponentSource, hashPortableComponentSource, hashStable, readComponentLock, sanitizeComponentSource, upsertComponentLockEntry, writeComponentLock, } from "../component-lock.js";
7
+ import { REVO_LOCK_FILE, buildPortableComponentUpdatePayload, componentLockMatchesIdentity, diffPortableComponentSource, getComponentLockEntry, getComponentLockEntries, hashComponentSource, hashPortableComponentSource, hashStable, normalizePortableComponentSource, readComponentLock, removeComponentLockBaseline, sanitizeComponentSource, upsertComponentLockEntry, writeComponentLock, } from "../component-lock.js";
8
+ import { describeFieldChanges, formatDiffValue, unifiedLineDiff } from "../diff-details.js";
8
9
  import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, readProjectComponentIdentity, readProjectMetadata, resolveProjectRoot, resolveProjectWorkspace, } from "../project.js";
9
10
  import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
10
11
  import { readComponentIdentityValue, sanitizeUserMetadata, } from "../resource-metadata.js";
11
12
  import { printSyncPlan, printSyncNotice, printSyncStatus, printSyncSummary, } from "../sync-output.js";
12
- import { deepClone, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
13
+ import { deepClone, mapWithConcurrency, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
13
14
  import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
14
15
  import { replaceWorkspaceResourceDirectory } from "../workspace-resource.js";
16
+ function componentElementCodeDiffs(workspace, target) {
17
+ const targetElements = new Map((target?.elements || []).map((element) => [element.key, element]));
18
+ const workspaceElements = new Map((workspace.elements || []).map((element) => [element.key, element]));
19
+ return [...new Set([...targetElements.keys(), ...workspaceElements.keys()])]
20
+ .sort((left, right) => left.localeCompare(right))
21
+ .flatMap((element) => {
22
+ const before = String(targetElements.get(element)?.details ?? '');
23
+ const after = String(workspaceElements.get(element)?.details ?? '');
24
+ const lines = unifiedLineDiff(before, after);
25
+ return lines.length > 0 ? [{ element, lines }] : [];
26
+ });
27
+ }
28
+ function componentElementFieldChanges(workspace, target) {
29
+ const targetElements = new Map((target.elements || []).map((element) => [element.key, element]));
30
+ const workspaceElements = new Map((workspace.elements || []).map((element) => [element.key, element]));
31
+ const fields = ['desc', 'hidden', 'order'];
32
+ return [...new Set([...targetElements.keys(), ...workspaceElements.keys()])]
33
+ .sort((left, right) => left.localeCompare(right))
34
+ .flatMap((key) => {
35
+ const beforeElement = targetElements.get(key);
36
+ const afterElement = workspaceElements.get(key);
37
+ if (!beforeElement || !afterElement) {
38
+ return [{
39
+ field: `elements.${key}`,
40
+ target: beforeElement ? 'present' : '<absent>',
41
+ workspace: afterElement ? 'present' : '<absent>',
42
+ }];
43
+ }
44
+ return fields.flatMap((field) => {
45
+ const before = beforeElement[field];
46
+ const after = afterElement[field];
47
+ if (hashStable({ value: before }) === hashStable({ value: after })) {
48
+ return [];
49
+ }
50
+ return [{
51
+ field: `elements.${key}.${field}`,
52
+ target: formatDiffValue(before, field),
53
+ workspace: formatDiffValue(after, field),
54
+ }];
55
+ });
56
+ });
57
+ }
15
58
  const NULL_CATEGORY_FOLDER = '__no_category__';
16
59
  function rethrowComponentAccessError(error, action) {
17
60
  if (error instanceof PermissionDeniedError) {
@@ -110,6 +153,32 @@ function normalizeComponentType(component) {
110
153
  }
111
154
  return 'CODE_JS';
112
155
  }
156
+ function componentTypeTransitionBlocker(desired, current) {
157
+ const desiredType = normalizeComponentType(desired).trim().toUpperCase();
158
+ const currentType = normalizeComponentType(current).trim().toUpperCase();
159
+ const languagePairs = new Map([
160
+ ['CODE_JS', 'component'],
161
+ ['CODE_TS', 'component'],
162
+ ['CODE_JS_LIB', 'library'],
163
+ ['CODE_TS_LIB', 'library'],
164
+ ]);
165
+ if (desiredType === currentType
166
+ || !languagePairs.has(desiredType)
167
+ || languagePairs.get(desiredType) !== languagePairs.get(currentType)) {
168
+ return null;
169
+ }
170
+ return `The target API cannot change Component type from ${currentType} to ${desiredType}; resolve this transition manually before syncing.`;
171
+ }
172
+ function componentDeploymentRank(type) {
173
+ const normalized = type.trim().toUpperCase();
174
+ if (normalized === 'CODE_TS_LIB' || normalized === 'CODE_JS_LIB') {
175
+ return 0;
176
+ }
177
+ if (normalized === 'JSON_VALIDATOR') {
178
+ return 1;
179
+ }
180
+ return 2;
181
+ }
113
182
  function getWorkspaceRoot(cwd) {
114
183
  const projectWorkspace = resolveProjectWorkspace(cwd);
115
184
  return path.join(projectWorkspace || cwd, 'Components');
@@ -444,10 +513,10 @@ function createComponentCatalog(identity) {
444
513
  unmanaged: [],
445
514
  };
446
515
  }
447
- function buildLocalComponentCatalog(cwd, identity) {
516
+ function buildLocalComponentCatalog(cwd, identity, strict = false) {
448
517
  const catalog = createComponentCatalog(identity);
449
518
  for (const manifestPath of getComponentManifestPaths(getWorkspaceRoot(cwd))) {
450
- const component = readWorkspaceComponentSafe(manifestPath);
519
+ const component = strict ? readWorkspaceComponent(manifestPath) : readWorkspaceComponentSafe(manifestPath);
451
520
  if (!component) {
452
521
  continue;
453
522
  }
@@ -459,15 +528,25 @@ function buildLocalComponentCatalog(cwd, identity) {
459
528
  }
460
529
  return catalog;
461
530
  }
531
+ function componentPruneBlocker(localCatalog, remote) {
532
+ const remoteComponentId = componentIdOf(remote.component);
533
+ if (!remoteComponentId) {
534
+ return 'target component has no ID';
535
+ }
536
+ if (localCatalog.byComponentId.has(remoteComponentId)) {
537
+ return 'a local component still has the target component ID';
538
+ }
539
+ return null;
540
+ }
462
541
  async function buildRemoteComponentCatalog(context, identity, summaries) {
463
542
  const catalog = createComponentCatalog(identity);
464
543
  const source = summaries || (await fetchAllComponentSummaries(context)).components;
465
- for (const summary of source) {
544
+ const filtered = source.filter((summary) => Boolean(String(summary.componentId || summary.id || '')));
545
+ const components = await mapWithConcurrency(filtered, async (summary) => {
466
546
  const componentId = String(summary.componentId || summary.id || '');
467
- if (!componentId) {
468
- continue;
469
- }
470
- const component = unwrapComponent(await context.client.getComponent(componentId));
547
+ return unwrapComponent(await context.client.getComponent(componentId));
548
+ });
549
+ for (const component of components) {
471
550
  addCatalogEntry(catalog, {
472
551
  component,
473
552
  hash: componentSourceHash(component, identity),
@@ -930,16 +1009,16 @@ async function fetchAllComponentSummaries(context) {
930
1009
  rethrowComponentAccessError(error, 'list');
931
1010
  }
932
1011
  }
933
- async function pullAllComponents(context, options) {
1012
+ export async function pullAllComponents(context, options) {
934
1013
  const { components, discoveredTotal } = await fetchAllComponentSummaries(context);
935
- if (components.length === 0) {
1014
+ if (components.length === 0 && options.pruneOrphans !== true) {
936
1015
  context.println('No components found.');
937
1016
  return [];
938
1017
  }
939
1018
  const identity = resolveComponentIdentity(context.cwd);
940
1019
  const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
941
1020
  const managedCount = remoteCatalog.byIdentity.size;
942
- if (managedCount === 0) {
1021
+ if (managedCount === 0 && options.pruneOrphans !== true) {
943
1022
  context.println(`No components managed by ${identityDescription(identity)} were found.`);
944
1023
  return [];
945
1024
  }
@@ -948,6 +1027,7 @@ async function pullAllComponents(context, options) {
948
1027
  : managedCount, options.force || options.yes);
949
1028
  const startedAt = Date.now();
950
1029
  const results = [];
1030
+ const root = getWorkspaceRoot(context.cwd);
951
1031
  const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
952
1032
  migrateComponentLockIdentity(context.cwd, identity, localCatalog, remoteCatalog);
953
1033
  for (const entry of remoteCatalog.byComponentId.values()) {
@@ -960,6 +1040,31 @@ async function pullAllComponents(context, options) {
960
1040
  results.push(result);
961
1041
  }
962
1042
  }
1043
+ if (options.pruneOrphans === true) {
1044
+ for (const [identityKey, entry] of localCatalog.byIdentity) {
1045
+ if (remoteCatalog.byIdentity.has(identityKey) || !entry.manifestPath) {
1046
+ continue;
1047
+ }
1048
+ const componentDirectory = path.dirname(entry.manifestPath);
1049
+ if (!isRelativeInside(root, componentDirectory) || componentDirectory === root) {
1050
+ throw new Error(`Refusing to prune Component outside the workspace root: ${componentDirectory}`);
1051
+ }
1052
+ const targetPath = componentWorkspacePath(context.cwd, entry.manifestPath);
1053
+ fs.rmSync(componentDirectory, { recursive: true, force: true });
1054
+ const result = {
1055
+ status: 'pruned',
1056
+ targetPath,
1057
+ reason: `not present in source environment ${context.componentEnvironment || 'default'}`,
1058
+ };
1059
+ results.push(result);
1060
+ printSyncStatus(context.println, {
1061
+ status: 'Pruned',
1062
+ direction: 'pull',
1063
+ targetPath,
1064
+ reason: result.reason,
1065
+ });
1066
+ }
1067
+ }
963
1068
  printSyncSummary(context.println, 'Pulled', results, Date.now() - startedAt);
964
1069
  return results;
965
1070
  }
@@ -1056,7 +1161,7 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1056
1161
  try {
1057
1162
  const remote = await resolveRemoteComponentForLocal(context, component, identity, resolvedRemoteCatalog);
1058
1163
  if (!remote) {
1059
- if (context.componentEnvironment) {
1164
+ if (identity.mode === 'stableKey') {
1060
1165
  const created = unwrapComponent(await client.createComponent(buildComponentCreatePayload(component, identity)));
1061
1166
  const createdComponentId = componentIdOf(created);
1062
1167
  if (!createdComponentId) {
@@ -1097,6 +1202,10 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1097
1202
  if (!remoteComponentId) {
1098
1203
  throw new Error(`Remote component matched by ${identityDescription(identity)} "${identityKey}" has no componentId.`);
1099
1204
  }
1205
+ const typeTransitionBlocker = componentTypeTransitionBlocker(component, remote);
1206
+ if (typeTransitionBlocker) {
1207
+ throw new Error(`Cannot push ${targetPath}: ${typeTransitionBlocker}`);
1208
+ }
1100
1209
  if (!readBoolFlag(context.args, ['force', 'f'])) {
1101
1210
  const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(context.cwd)), identity, component, context.componentEnvironment);
1102
1211
  if (!lockEntry) {
@@ -1193,6 +1302,16 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1193
1302
  if (!isNotModifiedError(error)) {
1194
1303
  throw error;
1195
1304
  }
1305
+ if (hasLiveRemote) {
1306
+ const refreshedAfterNotModified = unwrapComponent(await client.getComponent(remoteComponentId));
1307
+ const remainingConfigurationFields = diffPortableComponentSource(component, refreshedAfterNotModified).configurationFields.filter((field) => portableDiff.configurationFields.includes(field));
1308
+ if (remainingConfigurationFields.length > 0) {
1309
+ const typeTransition = remainingConfigurationFields.includes('type')
1310
+ ? `type change from ${String(refreshedAfterNotModified.type)} to ${String(component.type)}`
1311
+ : `configuration changes (${remainingConfigurationFields.join(', ')})`;
1312
+ throw new Error(`Cannot push ${targetPath}: ${typeTransition} was not applied by the target API.`);
1313
+ }
1314
+ }
1196
1315
  }
1197
1316
  }
1198
1317
  let elementsChanged = false;
@@ -1303,13 +1422,27 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1303
1422
  throw error;
1304
1423
  }
1305
1424
  }
1306
- async function pushAllComponents(context, options) {
1425
+ export async function pushAllComponents(context, options) {
1307
1426
  const { cwd, println } = context;
1308
1427
  const root = getWorkspaceRoot(cwd);
1309
1428
  const identity = resolveComponentIdentity(cwd);
1429
+ const prunePlan = options.prune ? await buildComponentPlan(context, undefined, false, true) : null;
1430
+ const pruneCandidates = prunePlan?.items.filter((item) => item.status === 'delete') || [];
1431
+ const pruneBlockers = prunePlan?.items.filter((item) => item.blocked && item.localHash === null) || [];
1432
+ if (pruneBlockers.length > 0) {
1433
+ throw new Error(`Component prune blocked: ${pruneBlockers.map((item) => `${item.identityKey}: ${item.reason}`).join('; ')}.`);
1434
+ }
1310
1435
  let manifests = getComponentManifestPaths(root);
1311
- if (manifests.length === 0) {
1312
- println(`No component.json files found in ${path.relative(cwd, root) || 'Components'}.`);
1436
+ manifests.sort((leftPath, rightPath) => {
1437
+ const left = readWorkspaceComponent(leftPath);
1438
+ const right = readWorkspaceComponent(rightPath);
1439
+ return componentDeploymentRank(normalizeComponentType(left)) - componentDeploymentRank(normalizeComponentType(right))
1440
+ || String(readComponentIdentityValue(left, identity) || leftPath).localeCompare(String(readComponentIdentityValue(right, identity) || rightPath));
1441
+ });
1442
+ if (manifests.length === 0 && pruneCandidates.length === 0) {
1443
+ println(options.prune
1444
+ ? 'No managed target-only components are eligible for prune.'
1445
+ : `No component.json files found in ${path.relative(cwd, root) || 'Components'}.`);
1313
1446
  return [];
1314
1447
  }
1315
1448
  if (options.scope?.enabled) {
@@ -1323,13 +1456,20 @@ async function pushAllComponents(context, options) {
1323
1456
  return [];
1324
1457
  }
1325
1458
  }
1326
- await confirmBulkAction(context, 'push', manifests.length, options.force || options.yes);
1327
1459
  const remoteCatalog = identity.mode === 'stableKey'
1328
1460
  ? await buildRemoteComponentCatalog(context, identity)
1329
1461
  : undefined;
1330
1462
  if (remoteCatalog) {
1331
1463
  migrateComponentLockIdentity(cwd, identity, buildLocalComponentCatalog(cwd, identity), remoteCatalog);
1332
1464
  }
1465
+ await assertNoComponentTypeTransitionBlockers(context, manifests, identity, remoteCatalog);
1466
+ await confirmBulkAction(context, 'push', manifests.length + pruneCandidates.length, options.force || options.yes);
1467
+ if (pruneCandidates.length > 0) {
1468
+ printSyncNotice(println, `Pruning ${pruneCandidates.length} managed component(s) absent from the repository.`);
1469
+ for (const item of pruneCandidates) {
1470
+ println(` - ${item.identityKey || item.componentId} (${item.remoteComponentId})`);
1471
+ }
1472
+ }
1333
1473
  const startedAt = Date.now();
1334
1474
  const results = [];
1335
1475
  for (const manifestPath of manifests) {
@@ -1338,15 +1478,90 @@ async function pushAllComponents(context, options) {
1338
1478
  results.push(result);
1339
1479
  }
1340
1480
  }
1481
+ for (const item of pruneCandidates) {
1482
+ const identityKey = item.identityKey || '';
1483
+ const remoteComponentId = item.remoteComponentId || '';
1484
+ let deleteAccepted = false;
1485
+ try {
1486
+ const lockEntry = getComponentLockEntries(readComponentLock(getProjectRoot(cwd)), identity, context.componentEnvironment)[identityKey];
1487
+ if ((item.lockRemoteComponentId || undefined) !== lockEntry?.remoteComponentId
1488
+ || (item.lockHash || undefined) !== lockEntry?.remoteHash) {
1489
+ throw new Error('selected environment lock baseline changed after prune planning');
1490
+ }
1491
+ const localCatalog = buildLocalComponentCatalog(cwd, identity, true);
1492
+ if (localCatalog.byIdentity.has(identityKey)) {
1493
+ throw new Error('local component reappeared after prune planning');
1494
+ }
1495
+ const live = unwrapComponent(await context.client.getComponent(remoteComponentId));
1496
+ if (componentIdOf(live) !== remoteComponentId
1497
+ || readComponentIdentityValue(live, identity) !== identityKey
1498
+ || componentSourceHash(live, identity) !== item.remoteHash) {
1499
+ throw new Error('target component changed after prune planning');
1500
+ }
1501
+ const blocker = componentPruneBlocker(localCatalog, {
1502
+ component: live,
1503
+ hash: componentSourceHash(live, identity),
1504
+ });
1505
+ if (blocker) {
1506
+ throw new Error(blocker);
1507
+ }
1508
+ await context.client.deleteComponent(remoteComponentId);
1509
+ deleteAccepted = true;
1510
+ const active = await fetchAllComponentSummaries(context);
1511
+ if (active.components.some((summary) => String(summary.componentId || summary.id || '') === remoteComponentId)) {
1512
+ throw new Error('deleted component still appears in the active target catalog');
1513
+ }
1514
+ if (lockEntry) {
1515
+ removeComponentLockBaseline(getProjectRoot(cwd), identity, identityKey, lockEntry.remoteComponentId, context.componentEnvironment);
1516
+ }
1517
+ results.push({ status: 'pruned', targetPath: item.path });
1518
+ printSyncStatus(println, { status: 'Pruned', direction: 'push', targetPath: item.path });
1519
+ }
1520
+ catch (error) {
1521
+ const reason = error instanceof Error ? error.message : String(error);
1522
+ const status = deleteAccepted ? 'write-unverified' : 'failed';
1523
+ results.push({ status, targetPath: item.path, reason });
1524
+ printSyncStatus(println, {
1525
+ status: deleteAccepted ? 'Unverified' : 'Failed',
1526
+ direction: 'push',
1527
+ targetPath: item.path,
1528
+ reason,
1529
+ });
1530
+ }
1531
+ }
1341
1532
  printSyncSummary(context.println, 'Deployed', results, Date.now() - startedAt);
1533
+ if (results.some((result) => result.status === 'failed' || result.status === 'write-unverified')) {
1534
+ throw new Error('Component push finished with failed or unverified prune operations.');
1535
+ }
1342
1536
  return results;
1343
1537
  }
1344
- async function buildComponentPlan(context, scope = { enabled: false, base: '', componentIds: new Set() }) {
1538
+ async function assertNoComponentTypeTransitionBlockers(context, manifests, identity, remoteCatalog) {
1539
+ const blockers = [];
1540
+ for (const manifestPath of manifests) {
1541
+ const component = readWorkspaceComponent(manifestPath);
1542
+ const identityKey = readComponentIdentityValue(component, identity);
1543
+ if (!identityKey) {
1544
+ continue;
1545
+ }
1546
+ const remote = await resolveRemoteComponentForLocal(context, component, identity, remoteCatalog);
1547
+ if (!remote) {
1548
+ continue;
1549
+ }
1550
+ const blocker = componentTypeTransitionBlocker(component, remote);
1551
+ if (blocker) {
1552
+ blockers.push(`${componentWorkspacePath(context.cwd, manifestPath)}: ${blocker}`);
1553
+ }
1554
+ }
1555
+ if (blockers.length > 0) {
1556
+ throw new Error(`Component push is blocked:\n${blockers.map((blocker) => `- ${blocker}`).join('\n')}`);
1557
+ }
1558
+ }
1559
+ export async function buildComponentPlan(context, scope = { enabled: false, base: '', componentIds: new Set() }, includeDiffDetails = false, prune = false) {
1345
1560
  const projectRoot = getProjectRoot(context.cwd);
1346
1561
  const lock = readComponentLock(projectRoot);
1347
1562
  const root = getWorkspaceRoot(context.cwd);
1348
1563
  const identity = resolveComponentIdentity(context.cwd);
1349
- const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
1564
+ const localCatalog = buildLocalComponentCatalog(context.cwd, identity, prune);
1350
1565
  const { components } = await fetchAllComponentSummaries(context);
1351
1566
  const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
1352
1567
  const lockEntries = getComponentLockEntries(lock, identity, context.componentEnvironment);
@@ -1364,6 +1579,7 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1364
1579
  const remoteComponentId = remote ? componentIdOf(remote.component) : lockEntry?.remoteComponentId || '';
1365
1580
  const componentId = localComponentId || remoteComponentId || lockEntry?.componentId || identityKey;
1366
1581
  const componentName = component?.name || lockEntry?.componentName || identityKey;
1582
+ const componentType = component ? normalizeComponentType(component) : '';
1367
1583
  const category = normalizeValue(component?.category, lockEntry?.category ?? null);
1368
1584
  const targetPath = local?.manifestPath
1369
1585
  ? componentWorkspacePath(context.cwd, local.manifestPath)
@@ -1376,14 +1592,30 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1376
1592
  const changedFields = local && remote
1377
1593
  ? diffPortableComponentSource(local.component, remote.component).changedFields
1378
1594
  : [];
1595
+ const fieldChanges = includeDiffDetails && local && remote
1596
+ ? [...describeFieldChanges(normalizePortableComponentSource(local.component), normalizePortableComponentSource(remote.component), changedFields.filter((field) => field !== 'elements')), ...componentElementFieldChanges(local.component, remote.component)]
1597
+ : [];
1598
+ const codeDiffs = includeDiffDetails && local
1599
+ ? componentElementCodeDiffs(local.component, remote?.component)
1600
+ : [];
1379
1601
  let status = 'clean';
1380
1602
  let reason = 'local, lock, and remote match';
1603
+ let pruneBlocker = null;
1381
1604
  if (!local && !remote) {
1382
1605
  reason = 'lock entry has no matching local or remote component';
1383
1606
  }
1384
1607
  else if (!local && remote) {
1385
- status = 'safe-update';
1386
- reason = 'remote component is missing locally';
1608
+ if (prune) {
1609
+ pruneBlocker = componentPruneBlocker(localCatalog, remote);
1610
+ status = pruneBlocker ? 'blocked' : 'delete';
1611
+ reason = pruneBlocker || 'target component is absent from the repository';
1612
+ }
1613
+ else {
1614
+ status = 'safe-update';
1615
+ reason = lockEntry
1616
+ ? 'remote component is missing locally'
1617
+ : 'unmanaged remote component is missing locally';
1618
+ }
1387
1619
  }
1388
1620
  else if (local && !remote) {
1389
1621
  status = 'create';
@@ -1412,6 +1644,13 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1412
1644
  status = 'conflict';
1413
1645
  reason = 'local and remote changed since lock';
1414
1646
  }
1647
+ const typeTransitionBlocker = local && remote
1648
+ ? componentTypeTransitionBlocker(local.component, remote.component)
1649
+ : null;
1650
+ if (typeTransitionBlocker) {
1651
+ status = 'blocked';
1652
+ reason = typeTransitionBlocker;
1653
+ }
1415
1654
  const inScope = !scope.enabled
1416
1655
  || scope.componentIds.has(localComponentId)
1417
1656
  || scope.componentIds.has(remoteComponentId);
@@ -1420,7 +1659,9 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1420
1659
  identityKey,
1421
1660
  ...(identity.mode === 'stableKey' ? { stableKey: identityKey } : {}),
1422
1661
  ...(remoteComponentId ? { remoteComponentId } : {}),
1662
+ ...(lockEntry ? { lockRemoteComponentId: lockEntry.remoteComponentId } : {}),
1423
1663
  componentName,
1664
+ componentType,
1424
1665
  category,
1425
1666
  path: targetPath,
1426
1667
  status,
@@ -1430,10 +1671,15 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1430
1671
  remoteVersion: remote ? componentVersion(remote.component) : lockEntry?.remoteVersion ?? null,
1431
1672
  reason,
1432
1673
  ...(changedFields.length > 0 ? { changedFields } : {}),
1674
+ ...(fieldChanges.length > 0 ? { fieldChanges } : {}),
1675
+ ...(codeDiffs.length > 0 ? { codeDiffs } : {}),
1676
+ ...(typeTransitionBlocker || pruneBlocker ? { blocked: true } : {}),
1433
1677
  ...(scope.enabled ? { inScope } : {}),
1434
1678
  };
1435
1679
  });
1436
- const scopedItems = scope.enabled ? items.filter((item) => item.inScope) : items;
1680
+ const scopedItems = (scope.enabled ? items.filter((item) => item.inScope) : items)
1681
+ .sort((left, right) => (componentDeploymentRank(left.componentType) - componentDeploymentRank(right.componentType)
1682
+ || String(left.identityKey || left.componentId).localeCompare(String(right.identityKey || right.componentId))));
1437
1683
  return {
1438
1684
  schemaVersion: 1,
1439
1685
  generatedAt: new Date().toISOString(),
@@ -1460,9 +1706,14 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1460
1706
  'safe-update': 0,
1461
1707
  conflict: 0,
1462
1708
  create: 0,
1709
+ delete: 0,
1463
1710
  'missing-lock': 0,
1711
+ blocked: 0,
1464
1712
  }),
1465
1713
  items: scopedItems,
1714
+ blockers: scopedItems
1715
+ .filter((item) => item.blocked === true)
1716
+ .map((item) => `Component "${item.stableKey || item.componentName}" is blocked: ${item.reason}`),
1466
1717
  };
1467
1718
  }
1468
1719
  function parseTargets(args, names) {
@@ -1787,9 +2038,16 @@ export async function handleComponentCommand(context) {
1787
2038
  const force = readBoolFlag(args, ['force', 'f']);
1788
2039
  const yes = readBoolFlag(args, ['yes', 'y']);
1789
2040
  const stale = readBoolFlag(args, ['stale', 's']);
2041
+ const prune = readBoolFlag(args, ['prune']);
1790
2042
  const json = readBoolFlag(args, ['json']);
1791
2043
  const strict = readBoolFlag(args, ['strict']);
1792
2044
  const changedScope = resolveChangedComponentScope(context);
2045
+ if (prune && (!['plan', 'push'].includes(subcommand) || !all || changedScope.enabled)) {
2046
+ throw new Error('Component --prune requires plan --all or push --all without --changed.');
2047
+ }
2048
+ if (prune && subcommand === 'push' && (!yes || !force)) {
2049
+ throw new Error('Component push --prune requires --yes --force.');
2050
+ }
1793
2051
  if (context.componentEnvironment && ['pull', 'plan', 'push'].includes(subcommand)) {
1794
2052
  const identity = resolveComponentIdentity(context.cwd);
1795
2053
  if (identity.mode !== 'stableKey') {
@@ -1805,7 +2063,7 @@ export async function handleComponentCommand(context) {
1805
2063
  return;
1806
2064
  }
1807
2065
  if (subcommand === 'plan') {
1808
- const plan = await buildComponentPlan(context, changedScope);
2066
+ const plan = await buildComponentPlan(context, changedScope, true, prune);
1809
2067
  if (json) {
1810
2068
  context.print(plan);
1811
2069
  }
@@ -1814,12 +2072,18 @@ export async function handleComponentCommand(context) {
1814
2072
  title: 'Component',
1815
2073
  environment: context.componentEnvironment || 'default',
1816
2074
  counts: plan.counts,
2075
+ showHints: readBoolFlag(context.args, ['hints']),
1817
2076
  items: plan.items.map((item) => ({
1818
2077
  status: item.status,
1819
2078
  target: item.path,
1820
2079
  reason: item.reason,
1821
- changedFields: item.changedFields,
2080
+ changedFields: item.status === 'create' ? undefined : item.changedFields,
2081
+ fieldChanges: item.status === 'create' ? undefined : item.fieldChanges,
2082
+ details: item.status === 'create' ? undefined : [
2083
+ ...(item.codeDiffs || []).map((code) => ({ label: `element ${code.element}`, lines: code.lines })),
2084
+ ],
1822
2085
  })),
2086
+ blockers: plan.blockers,
1823
2087
  });
1824
2088
  }
1825
2089
  if (strict) {
@@ -1827,7 +2091,9 @@ export async function handleComponentCommand(context) {
1827
2091
  && (item.status === 'conflict'
1828
2092
  || item.status === 'missing-lock'
1829
2093
  || item.status === 'remote-changed'
1830
- || item.status === 'safe-update')));
2094
+ || item.status === 'safe-update'
2095
+ || item.status === 'delete'
2096
+ || item.status === 'blocked')));
1831
2097
  if (blocking.length > 0) {
1832
2098
  throw new Error(`Component plan is not safe: ${blocking.length} blocking item(s).`);
1833
2099
  }
@@ -1860,15 +2126,21 @@ export async function handleComponentCommand(context) {
1860
2126
  throw new Error('Provide --id <componentId> or --all.');
1861
2127
  }
1862
2128
  if (all) {
1863
- await pushAllComponents(context, { force, yes, scope: changedScope });
2129
+ await pushAllComponents(context, { force, yes, prune, scope: changedScope });
1864
2130
  return;
1865
2131
  }
1866
2132
  const manifests = targets.flatMap((target) => findComponentManifestsByTarget(context.cwd, target));
1867
2133
  if (manifests.length === 0) {
1868
2134
  throw new Error(`Unable to find local component for ${targets.join(', ')}.`);
1869
2135
  }
2136
+ const identity = resolveComponentIdentity(context.cwd);
2137
+ const hasManagedManifest = manifests.some((manifestPath) => (Boolean(readComponentIdentityValue(readWorkspaceComponent(manifestPath), identity))));
2138
+ const remoteCatalog = identity.mode === 'stableKey' && hasManagedManifest
2139
+ ? await buildRemoteComponentCatalog(context, identity)
2140
+ : undefined;
2141
+ await assertNoComponentTypeTransitionBlockers(context, manifests, identity, remoteCatalog);
1870
2142
  for (const manifestPath of manifests) {
1871
- await pushSingleComponent(context, manifestPath);
2143
+ await pushSingleComponent(context, manifestPath, remoteCatalog);
1872
2144
  }
1873
2145
  return;
1874
2146
  }
@@ -0,0 +1,2 @@
1
+ import type { CommandContext } from '../types.ts';
2
+ export declare function handleDatabaseTablesCommand(context: CommandContext): Promise<void>;