@revoengine/cli 1.0.10 → 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 (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,50 +1,61 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { execFileSync } from 'node:child_process';
4
+ import { randomUUID } from 'node:crypto';
4
5
  import { ApiError, COMPONENT_LIST_PAGE_SIZE, PermissionDeniedError } from "../client.js";
5
- import { REVO_LOCK_FILE, componentLockMatchesIdentity, getComponentLockEntry, hashComponentSource, hashPortableComponentSource, hashStable, readComponentLock, sanitizeComponentSource, upsertComponentLockEntry, writeComponentLock, } from "../component-lock.js";
6
+ import { getConfigDir } from "../config.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";
6
9
  import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, readProjectComponentIdentity, readProjectMetadata, resolveProjectRoot, resolveProjectWorkspace, } from "../project.js";
7
10
  import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
8
- import { readComponentIdentityValue, } from "../resource-metadata.js";
9
- import { deepClone, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
10
- const NULL_CATEGORY_FOLDER = '__no_category__';
11
- const ANSI = {
12
- reset: '\u001b[0m',
13
- bold: '\u001b[1m',
14
- dim: '\u001b[2m',
15
- green: '\u001b[32m',
16
- yellow: '\u001b[33m',
17
- cyan: '\u001b[36m',
18
- blue: '\u001b[34m',
19
- magenta: '\u001b[35m',
20
- };
21
- function supportsColor() {
22
- return Boolean(process.stdout.isTTY || process.env.FORCE_COLOR);
23
- }
24
- function paint(text, code) {
25
- return supportsColor() ? `${code}${text}${ANSI.reset}` : text;
26
- }
27
- function paintStatus(status) {
28
- if (status === 'Skipped') {
29
- return paint(status.padEnd(9), ANSI.bold + ANSI.yellow);
30
- }
31
- if (status === 'Notice') {
32
- return paint(status.padEnd(9), ANSI.bold + ANSI.magenta);
33
- }
34
- return paint(status.padEnd(9), ANSI.bold + ANSI.green);
35
- }
36
- function paintPath(targetPath) {
37
- return paint(targetPath, ANSI.cyan);
38
- }
39
- function paintEngine() {
40
- return paint('RevoEngine', ANSI.bold + ANSI.blue);
41
- }
42
- function paintArrow(direction) {
43
- return paint(direction === 'pull' ? '->' : '<-', ANSI.bold + ANSI.magenta);
11
+ import { readComponentIdentityValue, sanitizeUserMetadata, } from "../resource-metadata.js";
12
+ import { printSyncPlan, printSyncNotice, printSyncStatus, printSyncSummary, } from "../sync-output.js";
13
+ import { deepClone, mapWithConcurrency, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
14
+ import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
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
+ });
44
27
  }
45
- function paintReason(reason) {
46
- return paint(`(${reason})`, ANSI.dim + ANSI.yellow);
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
+ });
47
57
  }
58
+ const NULL_CATEGORY_FOLDER = '__no_category__';
48
59
  function rethrowComponentAccessError(error, action) {
49
60
  if (error instanceof PermissionDeniedError) {
50
61
  throw new Error(`Access denied (403). You are authenticated, but you do not have permission to ${action} components.`);
@@ -54,32 +65,6 @@ function rethrowComponentAccessError(error, action) {
54
65
  function componentWorkspacePath(cwd, manifestPath) {
55
66
  return path.relative(cwd, path.dirname(manifestPath)) || '.';
56
67
  }
57
- function printSyncStatus(println, input) {
58
- const suffix = input.reason ? ` ${paintReason(input.reason)}` : '';
59
- println(`${paintStatus(input.status)} ${paintEngine()} ${paintArrow(input.direction)} ${paintPath(input.targetPath)}${suffix}`);
60
- }
61
- function printNotice(println, message) {
62
- println(`${paintStatus('Notice')} ${message}`);
63
- }
64
- function formatDuration(durationMs) {
65
- if (durationMs < 1_000) {
66
- return `${durationMs}ms`;
67
- }
68
- const seconds = durationMs / 1_000;
69
- if (seconds < 10) {
70
- return `${seconds.toFixed(1)}s`;
71
- }
72
- return `${Math.round(seconds)}s`;
73
- }
74
- function printSummary(println, label, results, durationMs) {
75
- const primary = results.filter((result) => result.status === label.toLowerCase()).length;
76
- const skipped = results.filter((result) => result.status === 'skipped').length;
77
- const total = results.length;
78
- const summary = skipped > 0
79
- ? `${label} ${primary}/${total}, Skipped ${skipped}/${total} in ${formatDuration(durationMs)}`
80
- : `${label} ${primary}/${total} in ${formatDuration(durationMs)}`;
81
- println(summary);
82
- }
83
68
  function formatBulkCount(direction, count) {
84
69
  if (typeof count === 'number') {
85
70
  return direction === 'pull'
@@ -99,7 +84,7 @@ async function confirmBulkAction(context, direction, count, force) {
99
84
  if (!isInteractiveTerminal()) {
100
85
  throw new Error(`Bulk ${action} requires confirmation. Re-run with --force or use an interactive terminal.`);
101
86
  }
102
- printNotice(context.println, `About to ${action} ${subject}.`);
87
+ printSyncNotice(context.println, `About to ${action} ${subject}.`);
103
88
  const confirmed = await promptConfirm('Continue?', false);
104
89
  if (!confirmed) {
105
90
  throw new Error('Cancelled.');
@@ -168,6 +153,32 @@ function normalizeComponentType(component) {
168
153
  }
169
154
  return 'CODE_JS';
170
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
+ }
171
182
  function getWorkspaceRoot(cwd) {
172
183
  const projectWorkspace = resolveProjectWorkspace(cwd);
173
184
  return path.join(projectWorkspace || cwd, 'Components');
@@ -243,36 +254,9 @@ function getComponentManifestPaths(root) {
243
254
  return walkFiles(root).filter((filePath) => filePath.endsWith('component.json'));
244
255
  }
245
256
  function readWorkspaceComponent(manifestPath) {
246
- const componentDir = path.dirname(manifestPath);
247
257
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
248
- const detailDirs = [
249
- path.join(componentDir, 'elements'),
250
- path.join(componentDir, 'details'),
251
- ].filter((dir, index, list) => list.indexOf(dir) === index);
252
258
  const extension = componentTypeToExtension(normalizeComponentType(manifest));
253
- manifest.elements = (manifest.elements || []).map((element) => {
254
- const fileName = `${element.order}_${element.key}.${extension}`;
255
- let details = '';
256
- for (const detailDir of detailDirs) {
257
- const preferredPath = path.join(detailDir, fileName);
258
- if (fs.existsSync(preferredPath)) {
259
- details = fs.readFileSync(preferredPath, 'utf8');
260
- break;
261
- }
262
- if (fs.existsSync(detailDir)) {
263
- const match = fs.readdirSync(detailDir).find((entry) => entry.startsWith(`${element.order}_${element.key}.`));
264
- if (match) {
265
- details = fs.readFileSync(path.join(detailDir, match), 'utf8');
266
- break;
267
- }
268
- }
269
- }
270
- return {
271
- ...element,
272
- details,
273
- };
274
- });
275
- return manifest;
259
+ return hydrateWorkspaceComponentElementDetails(manifestPath, manifest, extension);
276
260
  }
277
261
  function getComponentIdFromPath(componentPath) {
278
262
  const basename = path.basename(componentPath);
@@ -449,6 +433,50 @@ function componentSourceHash(component, identity) {
449
433
  ? hashPortableComponentSource(component)
450
434
  : hashComponentSource(component);
451
435
  }
436
+ function writeComponentPushVerificationLog(input) {
437
+ const outputDir = path.join(input.cwd, '.revoengine', 'logs', 'component-push');
438
+ const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
439
+ const identityKey = readComponentIdentityValue(input.desired, input.identity) || componentIdOf(input.desired);
440
+ const outputFile = path.join(outputDir, `${timestamp}-${sanitizeSegment(identityKey)}.json`);
441
+ const desiredHash = componentSourceHash(input.desired, input.identity);
442
+ const actualHash = componentSourceHash(input.actual, input.identity);
443
+ const portableDiff = diffPortableComponentSource(input.desired, input.actual);
444
+ writeJsonFile(outputFile, {
445
+ schemaVersion: 1,
446
+ kind: 'component-push-verification-failure',
447
+ generatedAt: new Date().toISOString(),
448
+ targetPath: input.targetPath,
449
+ ...(input.environment ? { environment: input.environment } : {}),
450
+ identity: input.identity,
451
+ hashes: { desired: desiredHash, actual: actualHash },
452
+ difference: portableDiff,
453
+ ...(input.operations ? { operations: input.operations } : {}),
454
+ ...(input.errorOperationId ? { errorOperationId: input.errorOperationId } : {}),
455
+ desired: input.desired,
456
+ actual: input.actual,
457
+ });
458
+ return path.relative(input.cwd, outputFile);
459
+ }
460
+ function describeComponentPushOperationError(error) {
461
+ if (error instanceof ApiError) {
462
+ return {
463
+ outcome: 'rejected',
464
+ name: error.name,
465
+ message: error.message,
466
+ status: error.status,
467
+ response: error.data,
468
+ };
469
+ }
470
+ return {
471
+ outcome: 'failed',
472
+ name: error instanceof Error ? error.name : 'Error',
473
+ message: error instanceof Error ? error.message : String(error),
474
+ };
475
+ }
476
+ function readRevoOperationId(headers) {
477
+ const value = headers?.get('x-revo-oid')?.trim();
478
+ return value || undefined;
479
+ }
452
480
  function identityDescription(identity) {
453
481
  return identity.mode === 'stableKey'
454
482
  ? `metadata.${identity.metadataProperty}`
@@ -485,10 +513,10 @@ function createComponentCatalog(identity) {
485
513
  unmanaged: [],
486
514
  };
487
515
  }
488
- function buildLocalComponentCatalog(cwd, identity) {
516
+ function buildLocalComponentCatalog(cwd, identity, strict = false) {
489
517
  const catalog = createComponentCatalog(identity);
490
518
  for (const manifestPath of getComponentManifestPaths(getWorkspaceRoot(cwd))) {
491
- const component = readWorkspaceComponentSafe(manifestPath);
519
+ const component = strict ? readWorkspaceComponent(manifestPath) : readWorkspaceComponentSafe(manifestPath);
492
520
  if (!component) {
493
521
  continue;
494
522
  }
@@ -500,15 +528,25 @@ function buildLocalComponentCatalog(cwd, identity) {
500
528
  }
501
529
  return catalog;
502
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
+ }
503
541
  async function buildRemoteComponentCatalog(context, identity, summaries) {
504
542
  const catalog = createComponentCatalog(identity);
505
543
  const source = summaries || (await fetchAllComponentSummaries(context)).components;
506
- 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) => {
507
546
  const componentId = String(summary.componentId || summary.id || '');
508
- if (!componentId) {
509
- continue;
510
- }
511
- const component = unwrapComponent(await context.client.getComponent(componentId));
547
+ return unwrapComponent(await context.client.getComponent(componentId));
548
+ });
549
+ for (const component of components) {
512
550
  addCatalogEntry(catalog, {
513
551
  component,
514
552
  hash: componentSourceHash(component, identity),
@@ -573,6 +611,14 @@ function migrateComponentLockIdentity(cwd, identity, localCatalog, remoteCatalog
573
611
  schemaVersion: 2,
574
612
  componentIdentity: identity,
575
613
  components: migratedComponents,
614
+ groups: lock.groups,
615
+ roleGroups: lock.roleGroups,
616
+ jobTemplates: lock.jobTemplates,
617
+ schedules: lock.schedules,
618
+ events: lock.events,
619
+ endpoints: lock.endpoints,
620
+ databaseSchemas: lock.databaseSchemas,
621
+ databaseViews: lock.databaseViews,
576
622
  };
577
623
  writeComponentLock(projectRoot, migrated);
578
624
  return migrated;
@@ -602,7 +648,7 @@ function findLocalEntryForRemote(remote, localCatalog) {
602
648
  }
603
649
  return idMatch;
604
650
  }
605
- function upsertLockFromRemote(cwd, remote, targetPath, local) {
651
+ function upsertLockFromRemote(cwd, remote, targetPath, local, environmentName) {
606
652
  const identity = resolveComponentIdentity(cwd);
607
653
  const remoteComponentId = componentIdOf(remote);
608
654
  const localComponentId = componentIdOf(local || remote);
@@ -628,9 +674,9 @@ function upsertLockFromRemote(cwd, remote, targetPath, local) {
628
674
  remoteHash,
629
675
  sourceHash: local ? componentSourceHash(local, identity) : remoteHash,
630
676
  pulledAt: new Date().toISOString(),
631
- }, identity);
677
+ }, identity, environmentName);
632
678
  }
633
- function buildPullDecision(cwd, remote, localCatalog = buildLocalComponentCatalog(cwd, resolveComponentIdentity(cwd))) {
679
+ function buildPullDecision(cwd, remote, localCatalog = buildLocalComponentCatalog(cwd, resolveComponentIdentity(cwd)), environmentName) {
634
680
  const identity = localCatalog.identity;
635
681
  const remoteTargetPath = componentTargetPath(cwd, remote);
636
682
  const identityKey = readComponentIdentityValue(remote, identity);
@@ -649,7 +695,7 @@ function buildPullDecision(cwd, remote, localCatalog = buildLocalComponentCatalo
649
695
  };
650
696
  }
651
697
  const targetPath = componentWorkspacePath(cwd, local.manifestPath);
652
- const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(cwd)), identity, remote);
698
+ const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(cwd)), identity, remote, environmentName);
653
699
  const localHash = local.hash;
654
700
  const remoteHash = componentSourceHash(remote, identity);
655
701
  const base = {
@@ -759,7 +805,7 @@ async function confirmSingleStalePull(context, targetPath) {
759
805
  if (!isInteractiveTerminal()) {
760
806
  throw new Error(`Local component is stale at ${targetPath}. Re-run with --stale or --force, or use an interactive terminal to confirm overwrite.`);
761
807
  }
762
- printNotice(context.println, `Local component is stale at ${targetPath}.`);
808
+ printSyncNotice(context.println, `Local component is stale at ${targetPath}.`);
763
809
  return promptConfirm('Overwrite local component with the remote version?', false);
764
810
  }
765
811
  async function resolveRemoteComponentForTarget(context, target, identity, remoteCatalog) {
@@ -810,7 +856,7 @@ async function pullResolvedComponent(context, component, mode, localCatalog) {
810
856
  const { cwd, println } = context;
811
857
  const identity = resolveComponentIdentity(cwd);
812
858
  const componentId = componentIdOf(component);
813
- const decision = buildPullDecision(cwd, component, localCatalog || buildLocalComponentCatalog(cwd, identity));
859
+ const decision = buildPullDecision(cwd, component, localCatalog || buildLocalComponentCatalog(cwd, identity), context.componentEnvironment);
814
860
  if (decision.kind === 'skip' && decision.reason.includes('; unmanaged')) {
815
861
  const result = {
816
862
  status: 'skipped',
@@ -872,7 +918,7 @@ async function pullResolvedComponent(context, component, mode, localCatalog) {
872
918
  const localComponent = decision.manifestPath
873
919
  ? readWorkspaceComponentSafe(decision.manifestPath) || decision.localComponent
874
920
  : decision.localComponent;
875
- upsertLockFromRemote(cwd, component, decision.targetPath, localComponent);
921
+ upsertLockFromRemote(cwd, component, decision.targetPath, localComponent, context.componentEnvironment);
876
922
  }
877
923
  const result = {
878
924
  status: metadataUpdated ? 'pulled' : 'skipped',
@@ -893,18 +939,26 @@ async function pullResolvedComponent(context, component, mode, localCatalog) {
893
939
  ? path.dirname(decision.manifestPath)
894
940
  : path.join(root, getComponentFolder(component));
895
941
  const targetPath = path.relative(cwd, folder);
896
- const elementsDir = path.join(folder, 'elements');
897
- fs.mkdirSync(elementsDir, { recursive: true });
898
- const extension = getDetailsExtension(component);
899
- for (const element of component.elements || []) {
900
- const content = element.details ?? element.logic ?? '';
901
- const filePath = path.join(elementsDir, `${element.order}_${element.key}.${extension}`);
902
- fs.writeFileSync(filePath, content);
942
+ const populate = (directory) => {
943
+ const elementsDir = path.join(directory, 'elements');
944
+ fs.mkdirSync(elementsDir, { recursive: true });
945
+ const extension = getDetailsExtension(component);
946
+ for (const element of component.elements || []) {
947
+ const content = element.details ?? element.logic ?? '';
948
+ const filePath = path.join(elementsDir, `${element.order}_${element.key}.${extension}`);
949
+ fs.writeFileSync(filePath, content);
950
+ }
951
+ writeJsonFile(path.join(directory, 'component.json'), buildPulledManifest(component, decision.localComponent, identity));
952
+ };
953
+ if (mode.force) {
954
+ replaceWorkspaceResourceDirectory(root, folder, populate);
955
+ }
956
+ else {
957
+ populate(folder);
903
958
  }
904
959
  const manifestPath = path.join(folder, 'component.json');
905
- writeJsonFile(manifestPath, buildPulledManifest(component, decision.localComponent, identity));
906
960
  const localComponent = readWorkspaceComponentSafe(manifestPath) || decision.localComponent;
907
- upsertLockFromRemote(cwd, component, targetPath, localComponent);
961
+ upsertLockFromRemote(cwd, component, targetPath, localComponent, context.componentEnvironment);
908
962
  const result = {
909
963
  status: 'pulled',
910
964
  targetPath,
@@ -955,16 +1009,16 @@ async function fetchAllComponentSummaries(context) {
955
1009
  rethrowComponentAccessError(error, 'list');
956
1010
  }
957
1011
  }
958
- async function pullAllComponents(context, options) {
1012
+ export async function pullAllComponents(context, options) {
959
1013
  const { components, discoveredTotal } = await fetchAllComponentSummaries(context);
960
- if (components.length === 0) {
1014
+ if (components.length === 0 && options.pruneOrphans !== true) {
961
1015
  context.println('No components found.');
962
1016
  return [];
963
1017
  }
964
1018
  const identity = resolveComponentIdentity(context.cwd);
965
1019
  const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
966
1020
  const managedCount = remoteCatalog.byIdentity.size;
967
- if (managedCount === 0) {
1021
+ if (managedCount === 0 && options.pruneOrphans !== true) {
968
1022
  context.println(`No components managed by ${identityDescription(identity)} were found.`);
969
1023
  return [];
970
1024
  }
@@ -973,6 +1027,7 @@ async function pullAllComponents(context, options) {
973
1027
  : managedCount, options.force || options.yes);
974
1028
  const startedAt = Date.now();
975
1029
  const results = [];
1030
+ const root = getWorkspaceRoot(context.cwd);
976
1031
  const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
977
1032
  migrateComponentLockIdentity(context.cwd, identity, localCatalog, remoteCatalog);
978
1033
  for (const entry of remoteCatalog.byComponentId.values()) {
@@ -985,7 +1040,32 @@ async function pullAllComponents(context, options) {
985
1040
  results.push(result);
986
1041
  }
987
1042
  }
988
- printSummary(context.println, 'Pulled', results, Date.now() - startedAt);
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
+ }
1068
+ printSyncSummary(context.println, 'Pulled', results, Date.now() - startedAt);
989
1069
  return results;
990
1070
  }
991
1071
  async function resolveRemoteComponentForLocal(context, component, identity, remoteCatalog) {
@@ -1032,6 +1112,19 @@ function buildPushElements(component, remote, identity) {
1032
1112
  };
1033
1113
  });
1034
1114
  }
1115
+ function buildComponentCreatePayload(component, identity) {
1116
+ return {
1117
+ name: component.name || '',
1118
+ category: component.category ?? null,
1119
+ desc: component.desc ?? null,
1120
+ type: normalizeComponentType(component),
1121
+ compiler: compilerFromType(component.type, component.compiler),
1122
+ active: component.active ?? true,
1123
+ async: Boolean(component.async),
1124
+ metadata: sanitizeUserMetadata(component.metadata),
1125
+ elements: buildPushElements(component, { elements: [] }, identity),
1126
+ };
1127
+ }
1035
1128
  async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1036
1129
  const { client, println } = context;
1037
1130
  const component = readWorkspaceComponent(manifestPath);
@@ -1068,6 +1161,30 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1068
1161
  try {
1069
1162
  const remote = await resolveRemoteComponentForLocal(context, component, identity, resolvedRemoteCatalog);
1070
1163
  if (!remote) {
1164
+ if (identity.mode === 'stableKey') {
1165
+ const created = unwrapComponent(await client.createComponent(buildComponentCreatePayload(component, identity)));
1166
+ const createdComponentId = componentIdOf(created);
1167
+ if (!createdComponentId) {
1168
+ throw new Error(`Cannot push ${targetPath}: create response did not include componentId.`);
1169
+ }
1170
+ await client.saveComponentElements(createdComponentId, buildPushElements(component, { elements: [] }, identity));
1171
+ const refreshedRemote = unwrapComponent(await client.getComponent(createdComponentId));
1172
+ if (componentSourceHash(refreshedRemote, identity) !== componentSourceHash(component, identity)) {
1173
+ const logPath = writeComponentPushVerificationLog({
1174
+ cwd: context.cwd,
1175
+ targetPath,
1176
+ environment: context.componentEnvironment,
1177
+ identity,
1178
+ desired: component,
1179
+ actual: refreshedRemote,
1180
+ });
1181
+ throw new Error(`Cannot push ${targetPath}: created component did not verify against local source. Diagnostic: ${logPath}`);
1182
+ }
1183
+ upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component, context.componentEnvironment);
1184
+ const result = { status: 'deployed', targetPath };
1185
+ printSyncStatus(println, { status: 'Deployed', direction: 'push', targetPath });
1186
+ return result;
1187
+ }
1071
1188
  const result = {
1072
1189
  status: 'skipped',
1073
1190
  targetPath,
@@ -1085,9 +1202,30 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1085
1202
  if (!remoteComponentId) {
1086
1203
  throw new Error(`Remote component matched by ${identityDescription(identity)} "${identityKey}" has no componentId.`);
1087
1204
  }
1205
+ const typeTransitionBlocker = componentTypeTransitionBlocker(component, remote);
1206
+ if (typeTransitionBlocker) {
1207
+ throw new Error(`Cannot push ${targetPath}: ${typeTransitionBlocker}`);
1208
+ }
1088
1209
  if (!readBoolFlag(context.args, ['force', 'f'])) {
1089
- const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(context.cwd)), identity, component);
1210
+ const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(context.cwd)), identity, component, context.componentEnvironment);
1090
1211
  if (!lockEntry) {
1212
+ const remoteHash = componentSourceHash(remote, identity);
1213
+ const localHash = componentSourceHash(component, identity);
1214
+ if (context.componentEnvironment && localHash === remoteHash) {
1215
+ upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
1216
+ const result = {
1217
+ status: 'skipped',
1218
+ targetPath,
1219
+ reason: 'local matches remote; target baseline adopted',
1220
+ };
1221
+ printSyncStatus(println, {
1222
+ status: 'Skipped',
1223
+ direction: 'push',
1224
+ targetPath: result.targetPath,
1225
+ reason: result.reason,
1226
+ });
1227
+ return result;
1228
+ }
1091
1229
  throw new Error(`Cannot push ${targetPath}: missing lock entry. Run \`revo component pull ${identityKey} --force\` to establish a remote baseline.`);
1092
1230
  }
1093
1231
  if (lockEntry.remoteComponentId !== remoteComponentId) {
@@ -1097,7 +1235,7 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1097
1235
  const localHash = componentSourceHash(component, identity);
1098
1236
  if (remoteHash !== lockEntry.remoteHash) {
1099
1237
  if (localHash === remoteHash) {
1100
- upsertLockFromRemote(context.cwd, remote, targetPath, component);
1238
+ upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
1101
1239
  const result = {
1102
1240
  status: 'skipped',
1103
1241
  targetPath,
@@ -1128,21 +1266,108 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1128
1266
  return result;
1129
1267
  }
1130
1268
  }
1131
- const elements = buildPushElements(component, remote, identity);
1132
- const response = await client.saveComponentElements(remoteComponentId, elements);
1133
- if (response.status === 304) {
1269
+ const hasLiveRemote = typeof client.getComponent === 'function';
1270
+ const portableDiff = hasLiveRemote
1271
+ ? diffPortableComponentSource(component, remote)
1272
+ : { configurationFields: [], elementsChanged: true, changedFields: ['elements'] };
1273
+ if (portableDiff.changedFields.length === 0) {
1134
1274
  const result = {
1135
1275
  status: 'skipped',
1136
1276
  targetPath,
1137
1277
  reason: 'no changes',
1138
1278
  };
1279
+ upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
1280
+ printSyncStatus(println, {
1281
+ status: 'Skipped',
1282
+ direction: 'push',
1283
+ targetPath,
1284
+ reason: result.reason,
1285
+ });
1286
+ return result;
1287
+ }
1288
+ let configurationChanged = false;
1289
+ const operations = {};
1290
+ let errorOperationId;
1291
+ if (portableDiff.configurationFields.length > 0) {
1139
1292
  try {
1140
- const refreshedRemote = unwrapComponent(await client.getComponent(remoteComponentId));
1141
- upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component);
1293
+ await client.updateComponent(remoteComponentId, buildPortableComponentUpdatePayload(component, remote, portableDiff.configurationFields));
1294
+ configurationChanged = true;
1295
+ operations.configurationUpdate = { outcome: 'accepted' };
1296
+ }
1297
+ catch (error) {
1298
+ operations.configurationUpdate = describeComponentPushOperationError(error);
1299
+ if (error instanceof ApiError) {
1300
+ errorOperationId = readRevoOperationId(error.headers) || errorOperationId;
1301
+ }
1302
+ if (!isNotModifiedError(error)) {
1303
+ throw error;
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
+ }
1142
1315
  }
1143
- catch {
1144
- upsertLockFromRemote(context.cwd, remote, targetPath, component);
1316
+ }
1317
+ let elementsChanged = false;
1318
+ if (portableDiff.elementsChanged) {
1319
+ try {
1320
+ const elements = buildPushElements(component, remote, identity);
1321
+ const response = await client.saveComponentElements(remoteComponentId, elements);
1322
+ elementsChanged = response.status !== 304;
1323
+ const operationId = readRevoOperationId(response.headers);
1324
+ errorOperationId = operationId || errorOperationId;
1325
+ operations.elementsSave = {
1326
+ outcome: 'accepted',
1327
+ status: response.status,
1328
+ ok: response.ok,
1329
+ response: response.data,
1330
+ ...(operationId ? { errorOperationId: operationId } : {}),
1331
+ };
1145
1332
  }
1333
+ catch (error) {
1334
+ operations.elementsSave = describeComponentPushOperationError(error);
1335
+ if (error instanceof ApiError) {
1336
+ errorOperationId = readRevoOperationId(error.headers) || errorOperationId;
1337
+ }
1338
+ if (!isNotModifiedError(error)) {
1339
+ throw error;
1340
+ }
1341
+ }
1342
+ }
1343
+ const refreshedRemote = hasLiveRemote
1344
+ ? unwrapComponent(await client.getComponent(remoteComponentId))
1345
+ : {
1346
+ ...component,
1347
+ componentId: remoteComponentId,
1348
+ ...(componentVersion(remote) != null ? { version: componentVersion(remote) } : {}),
1349
+ };
1350
+ if (hasLiveRemote
1351
+ && componentSourceHash(refreshedRemote, identity) !== componentSourceHash(component, identity)) {
1352
+ const logPath = writeComponentPushVerificationLog({
1353
+ cwd: context.cwd,
1354
+ targetPath,
1355
+ environment: context.componentEnvironment,
1356
+ identity,
1357
+ desired: component,
1358
+ actual: refreshedRemote,
1359
+ operations,
1360
+ errorOperationId,
1361
+ });
1362
+ throw new Error(`Cannot push ${targetPath}: updated component did not verify against local source. Diagnostic: ${logPath}`);
1363
+ }
1364
+ upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component, context.componentEnvironment);
1365
+ if (!configurationChanged && !elementsChanged) {
1366
+ const result = {
1367
+ status: 'skipped',
1368
+ targetPath,
1369
+ reason: 'no changes',
1370
+ };
1146
1371
  printSyncStatus(println, {
1147
1372
  status: 'Skipped',
1148
1373
  direction: 'push',
@@ -1155,17 +1380,6 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1155
1380
  status: 'deployed',
1156
1381
  targetPath,
1157
1382
  };
1158
- try {
1159
- const refreshedRemote = unwrapComponent(await client.getComponent(remoteComponentId));
1160
- upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component);
1161
- }
1162
- catch {
1163
- upsertLockFromRemote(context.cwd, {
1164
- ...component,
1165
- componentId: remoteComponentId,
1166
- ...(componentVersion(remote) != null ? { version: componentVersion(remote) } : {}),
1167
- }, targetPath, component);
1168
- }
1169
1383
  printSyncStatus(println, {
1170
1384
  status: 'Deployed',
1171
1385
  direction: 'push',
@@ -1208,13 +1422,27 @@ async function pushSingleComponent(context, manifestPath, remoteCatalog) {
1208
1422
  throw error;
1209
1423
  }
1210
1424
  }
1211
- async function pushAllComponents(context, options) {
1425
+ export async function pushAllComponents(context, options) {
1212
1426
  const { cwd, println } = context;
1213
1427
  const root = getWorkspaceRoot(cwd);
1214
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
+ }
1215
1435
  let manifests = getComponentManifestPaths(root);
1216
- if (manifests.length === 0) {
1217
- 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'}.`);
1218
1446
  return [];
1219
1447
  }
1220
1448
  if (options.scope?.enabled) {
@@ -1228,13 +1456,20 @@ async function pushAllComponents(context, options) {
1228
1456
  return [];
1229
1457
  }
1230
1458
  }
1231
- await confirmBulkAction(context, 'push', manifests.length, options.force || options.yes);
1232
1459
  const remoteCatalog = identity.mode === 'stableKey'
1233
1460
  ? await buildRemoteComponentCatalog(context, identity)
1234
1461
  : undefined;
1235
1462
  if (remoteCatalog) {
1236
1463
  migrateComponentLockIdentity(cwd, identity, buildLocalComponentCatalog(cwd, identity), remoteCatalog);
1237
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
+ }
1238
1473
  const startedAt = Date.now();
1239
1474
  const results = [];
1240
1475
  for (const manifestPath of manifests) {
@@ -1243,18 +1478,93 @@ async function pushAllComponents(context, options) {
1243
1478
  results.push(result);
1244
1479
  }
1245
1480
  }
1246
- printSummary(context.println, 'Deployed', results, Date.now() - startedAt);
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
+ }
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
+ }
1247
1536
  return results;
1248
1537
  }
1249
- 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) {
1250
1560
  const projectRoot = getProjectRoot(context.cwd);
1251
1561
  const lock = readComponentLock(projectRoot);
1252
1562
  const root = getWorkspaceRoot(context.cwd);
1253
1563
  const identity = resolveComponentIdentity(context.cwd);
1254
- const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
1564
+ const localCatalog = buildLocalComponentCatalog(context.cwd, identity, prune);
1255
1565
  const { components } = await fetchAllComponentSummaries(context);
1256
1566
  const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
1257
- const lockEntries = componentLockMatchesIdentity(lock, identity) ? lock.components : {};
1567
+ const lockEntries = getComponentLockEntries(lock, identity, context.componentEnvironment);
1258
1568
  const allIdentityKeys = [...new Set([
1259
1569
  ...localCatalog.byIdentity.keys(),
1260
1570
  ...remoteCatalog.byIdentity.keys(),
@@ -1269,6 +1579,7 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1269
1579
  const remoteComponentId = remote ? componentIdOf(remote.component) : lockEntry?.remoteComponentId || '';
1270
1580
  const componentId = localComponentId || remoteComponentId || lockEntry?.componentId || identityKey;
1271
1581
  const componentName = component?.name || lockEntry?.componentName || identityKey;
1582
+ const componentType = component ? normalizeComponentType(component) : '';
1272
1583
  const category = normalizeValue(component?.category, lockEntry?.category ?? null);
1273
1584
  const targetPath = local?.manifestPath
1274
1585
  ? componentWorkspacePath(context.cwd, local.manifestPath)
@@ -1278,14 +1589,33 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1278
1589
  const localHash = local?.hash || null;
1279
1590
  const remoteHash = remote?.hash || null;
1280
1591
  const lockHash = lockEntry?.remoteHash || null;
1592
+ const changedFields = local && remote
1593
+ ? diffPortableComponentSource(local.component, remote.component).changedFields
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
+ : [];
1281
1601
  let status = 'clean';
1282
1602
  let reason = 'local, lock, and remote match';
1603
+ let pruneBlocker = null;
1283
1604
  if (!local && !remote) {
1284
1605
  reason = 'lock entry has no matching local or remote component';
1285
1606
  }
1286
1607
  else if (!local && remote) {
1287
- status = 'safe-update';
1288
- 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
+ }
1289
1619
  }
1290
1620
  else if (local && !remote) {
1291
1621
  status = 'create';
@@ -1314,6 +1644,13 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1314
1644
  status = 'conflict';
1315
1645
  reason = 'local and remote changed since lock';
1316
1646
  }
1647
+ const typeTransitionBlocker = local && remote
1648
+ ? componentTypeTransitionBlocker(local.component, remote.component)
1649
+ : null;
1650
+ if (typeTransitionBlocker) {
1651
+ status = 'blocked';
1652
+ reason = typeTransitionBlocker;
1653
+ }
1317
1654
  const inScope = !scope.enabled
1318
1655
  || scope.componentIds.has(localComponentId)
1319
1656
  || scope.componentIds.has(remoteComponentId);
@@ -1322,7 +1659,9 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1322
1659
  identityKey,
1323
1660
  ...(identity.mode === 'stableKey' ? { stableKey: identityKey } : {}),
1324
1661
  ...(remoteComponentId ? { remoteComponentId } : {}),
1662
+ ...(lockEntry ? { lockRemoteComponentId: lockEntry.remoteComponentId } : {}),
1325
1663
  componentName,
1664
+ componentType,
1326
1665
  category,
1327
1666
  path: targetPath,
1328
1667
  status,
@@ -1331,10 +1670,16 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1331
1670
  remoteHash,
1332
1671
  remoteVersion: remote ? componentVersion(remote.component) : lockEntry?.remoteVersion ?? null,
1333
1672
  reason,
1673
+ ...(changedFields.length > 0 ? { changedFields } : {}),
1674
+ ...(fieldChanges.length > 0 ? { fieldChanges } : {}),
1675
+ ...(codeDiffs.length > 0 ? { codeDiffs } : {}),
1676
+ ...(typeTransitionBlocker || pruneBlocker ? { blocked: true } : {}),
1334
1677
  ...(scope.enabled ? { inScope } : {}),
1335
1678
  };
1336
1679
  });
1337
- 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))));
1338
1683
  return {
1339
1684
  schemaVersion: 1,
1340
1685
  generatedAt: new Date().toISOString(),
@@ -1361,17 +1706,16 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
1361
1706
  'safe-update': 0,
1362
1707
  conflict: 0,
1363
1708
  create: 0,
1709
+ delete: 0,
1364
1710
  'missing-lock': 0,
1711
+ blocked: 0,
1365
1712
  }),
1366
1713
  items: scopedItems,
1714
+ blockers: scopedItems
1715
+ .filter((item) => item.blocked === true)
1716
+ .map((item) => `Component "${item.stableKey || item.componentName}" is blocked: ${item.reason}`),
1367
1717
  };
1368
1718
  }
1369
- function printPlan(context, plan) {
1370
- for (const item of plan.items) {
1371
- context.println(`${item.status.padEnd(14)} ${item.path} ${item.reason ? `(${item.reason})` : ''}`.trimEnd());
1372
- }
1373
- context.println(`Plan: ${plan.items.length} components, ${plan.counts.conflict} conflicts, ${plan.counts['local-changed']} local changes, ${plan.counts['remote-changed']} remote changes.`);
1374
- }
1375
1719
  function parseTargets(args, names) {
1376
1720
  const values = readValues(args, names);
1377
1721
  if (values.length > 0) {
@@ -1562,7 +1906,17 @@ function collectDebugExtraLibs(cwd, currentComponentId) {
1562
1906
  }));
1563
1907
  }
1564
1908
  function writeRawDebugRequestDump(options) {
1565
- process.stderr.write(`[debug-request] ${JSON.stringify(options, null, 2)}\n`);
1909
+ const directory = path.join(getConfigDir(), 'debug-requests');
1910
+ fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
1911
+ try {
1912
+ fs.chmodSync(directory, 0o700);
1913
+ }
1914
+ catch {
1915
+ // Some platforms do not support Unix-style permissions.
1916
+ }
1917
+ const filePath = path.join(directory, `debug-request-${randomUUID()}.json`);
1918
+ writeJsonFile(filePath, options);
1919
+ process.stderr.write(`[debug-request] Saved private payload to ${filePath}\n`);
1566
1920
  }
1567
1921
  function formatProcessLog(log) {
1568
1922
  if (!log || typeof log !== 'object' || Array.isArray(log)) {
@@ -1684,9 +2038,22 @@ export async function handleComponentCommand(context) {
1684
2038
  const force = readBoolFlag(args, ['force', 'f']);
1685
2039
  const yes = readBoolFlag(args, ['yes', 'y']);
1686
2040
  const stale = readBoolFlag(args, ['stale', 's']);
2041
+ const prune = readBoolFlag(args, ['prune']);
1687
2042
  const json = readBoolFlag(args, ['json']);
1688
2043
  const strict = readBoolFlag(args, ['strict']);
1689
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
+ }
2051
+ if (context.componentEnvironment && ['pull', 'plan', 'push'].includes(subcommand)) {
2052
+ const identity = resolveComponentIdentity(context.cwd);
2053
+ if (identity.mode !== 'stableKey') {
2054
+ throw new Error('Component sync with a named project requires componentIdentity.mode "stableKey". Configure it in .revoengine/revo.json before pulling from a named project.');
2055
+ }
2056
+ }
1690
2057
  if (subcommand === 'pull-all') {
1691
2058
  await pullAllComponents(context, { force, stale, yes });
1692
2059
  return;
@@ -1696,19 +2063,37 @@ export async function handleComponentCommand(context) {
1696
2063
  return;
1697
2064
  }
1698
2065
  if (subcommand === 'plan') {
1699
- const plan = await buildComponentPlan(context, changedScope);
2066
+ const plan = await buildComponentPlan(context, changedScope, true, prune);
1700
2067
  if (json) {
1701
2068
  context.print(plan);
1702
2069
  }
1703
2070
  else {
1704
- printPlan(context, plan);
2071
+ printSyncPlan(context.println, {
2072
+ title: 'Component',
2073
+ environment: context.componentEnvironment || 'default',
2074
+ counts: plan.counts,
2075
+ showHints: readBoolFlag(context.args, ['hints']),
2076
+ items: plan.items.map((item) => ({
2077
+ status: item.status,
2078
+ target: item.path,
2079
+ reason: item.reason,
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
+ ],
2085
+ })),
2086
+ blockers: plan.blockers,
2087
+ });
1705
2088
  }
1706
2089
  if (strict) {
1707
2090
  const blocking = plan.items.filter((item) => ((!changedScope.enabled || item.inScope)
1708
2091
  && (item.status === 'conflict'
1709
2092
  || item.status === 'missing-lock'
1710
2093
  || item.status === 'remote-changed'
1711
- || item.status === 'safe-update')));
2094
+ || item.status === 'safe-update'
2095
+ || item.status === 'delete'
2096
+ || item.status === 'blocked')));
1712
2097
  if (blocking.length > 0) {
1713
2098
  throw new Error(`Component plan is not safe: ${blocking.length} blocking item(s).`);
1714
2099
  }
@@ -1741,15 +2126,21 @@ export async function handleComponentCommand(context) {
1741
2126
  throw new Error('Provide --id <componentId> or --all.');
1742
2127
  }
1743
2128
  if (all) {
1744
- await pushAllComponents(context, { force, yes, scope: changedScope });
2129
+ await pushAllComponents(context, { force, yes, prune, scope: changedScope });
1745
2130
  return;
1746
2131
  }
1747
2132
  const manifests = targets.flatMap((target) => findComponentManifestsByTarget(context.cwd, target));
1748
2133
  if (manifests.length === 0) {
1749
2134
  throw new Error(`Unable to find local component for ${targets.join(', ')}.`);
1750
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);
1751
2142
  for (const manifestPath of manifests) {
1752
- await pushSingleComponent(context, manifestPath);
2143
+ await pushSingleComponent(context, manifestPath, remoteCatalog);
1753
2144
  }
1754
2145
  return;
1755
2146
  }