@revoengine/cli 1.0.31 → 1.0.34

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 (113) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +152 -24
  3. package/dist/src/argument-contract.d.ts +17 -0
  4. package/dist/src/argument-contract.js +359 -0
  5. package/dist/src/automation-contract.generated.d.ts +56 -22
  6. package/dist/src/automation-contract.generated.js +68 -26
  7. package/dist/src/cli.js +15 -13
  8. package/dist/src/client.d.ts +34 -2
  9. package/dist/src/client.js +76 -13
  10. package/dist/src/commands/agents.js +5 -1
  11. package/dist/src/commands/auth.js +2 -0
  12. package/dist/src/commands/component.js +34 -17
  13. package/dist/src/commands/database-tables.js +15 -4
  14. package/dist/src/commands/database-views.js +5 -1
  15. package/dist/src/commands/endpoints.js +5 -1
  16. package/dist/src/commands/env.js +5 -1
  17. package/dist/src/commands/events.js +5 -1
  18. package/dist/src/commands/groups.js +5 -1
  19. package/dist/src/commands/info.js +2 -0
  20. package/dist/src/commands/job-templates.js +5 -1
  21. package/dist/src/commands/metadata.js +2 -0
  22. package/dist/src/commands/migrate.d.ts +2 -2
  23. package/dist/src/commands/migrate.js +33 -7
  24. package/dist/src/commands/project.js +19 -14
  25. package/dist/src/commands/request.js +2 -0
  26. package/dist/src/commands/role-groups.js +5 -1
  27. package/dist/src/commands/schedules.js +5 -1
  28. package/dist/src/commands/search.js +2 -0
  29. package/dist/src/commands/service-accounts.js +5 -1
  30. package/dist/src/commands/studio.js +2 -0
  31. package/dist/src/commands/terminal-browser-central-profile.d.ts +65 -0
  32. package/dist/src/commands/terminal-browser-central-profile.js +203 -0
  33. package/dist/src/commands/terminal-browser-human-input.d.ts +3 -1
  34. package/dist/src/commands/terminal-browser-human-input.js +3 -1
  35. package/dist/src/commands/terminal-browser-interaction.js +1 -1
  36. package/dist/src/commands/terminal-browser-live-protocol.d.ts +34 -2
  37. package/dist/src/commands/terminal-browser-live-protocol.js +28 -12
  38. package/dist/src/commands/terminal-browser-live-transport.d.ts +1 -0
  39. package/dist/src/commands/terminal-browser-live-transport.js +9 -5
  40. package/dist/src/commands/terminal-browser-live.d.ts +24 -3
  41. package/dist/src/commands/terminal-browser-live.js +199 -30
  42. package/dist/src/commands/terminal-browser-page-input.d.ts +4 -1
  43. package/dist/src/commands/terminal-browser-page-input.js +46 -1
  44. package/dist/src/commands/terminal-browser-profile-crypto.d.ts +30 -0
  45. package/dist/src/commands/terminal-browser-profile-crypto.js +101 -0
  46. package/dist/src/commands/terminal-browser-profile-import-runner.d.ts +31 -0
  47. package/dist/src/commands/terminal-browser-profile-import-runner.js +112 -0
  48. package/dist/src/commands/terminal-browser-profile-import.d.ts +28 -0
  49. package/dist/src/commands/terminal-browser-profile-import.js +125 -0
  50. package/dist/src/commands/terminal-browser-profile-import.protocol.d.ts +50 -0
  51. package/dist/src/commands/terminal-browser-profile-import.protocol.js +52 -0
  52. package/dist/src/commands/terminal-browser-profile-preferences.d.ts +1 -0
  53. package/dist/src/commands/terminal-browser-profile-preferences.js +16 -0
  54. package/dist/src/commands/terminal-browser-profile-sync.d.ts +14 -0
  55. package/dist/src/commands/terminal-browser-profile-sync.js +169 -0
  56. package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +50 -0
  57. package/dist/src/commands/terminal-browser-profile-sync.protocol.js +19 -0
  58. package/dist/src/commands/terminal-browser-profile.d.ts +10 -1
  59. package/dist/src/commands/terminal-browser-profile.js +30 -4
  60. package/dist/src/commands/terminal-browser-recording.d.ts +39 -0
  61. package/dist/src/commands/terminal-browser-recording.js +74 -0
  62. package/dist/src/commands/terminal-browser-recording.protocol.d.ts +49 -0
  63. package/dist/src/commands/terminal-browser-recording.protocol.js +16 -0
  64. package/dist/src/commands/terminal-browser.d.ts +14 -1
  65. package/dist/src/commands/terminal-browser.js +98 -33
  66. package/dist/src/commands/terminal-file-descriptor.d.ts +9 -0
  67. package/dist/src/commands/terminal-file-descriptor.js +39 -0
  68. package/dist/src/commands/terminal-file.js +41 -6
  69. package/dist/src/commands/terminal-image.js +3 -31
  70. package/dist/src/commands/terminal-output-buffer.d.ts +18 -1
  71. package/dist/src/commands/terminal-output-buffer.js +95 -8
  72. package/dist/src/commands/terminal-process-group.d.ts +25 -0
  73. package/dist/src/commands/terminal-process-group.js +144 -0
  74. package/dist/src/commands/terminal.d.ts +3 -1
  75. package/dist/src/commands/terminal.js +366 -80
  76. package/dist/src/commands/tests.js +2 -0
  77. package/dist/src/component-lock.d.ts +15 -1
  78. package/dist/src/component-lock.js +96 -10
  79. package/dist/src/env-sync.js +12 -6
  80. package/dist/src/migration.d.ts +7 -0
  81. package/dist/src/migration.js +39 -21
  82. package/dist/src/planning-snapshot.d.ts +3 -0
  83. package/dist/src/planning-snapshot.js +60 -2
  84. package/dist/src/project.d.ts +1 -0
  85. package/dist/src/project.js +7 -8
  86. package/dist/src/resource-syncs/agent-sync.js +76 -24
  87. package/dist/src/resource-syncs/database-table-sync.d.ts +8 -1
  88. package/dist/src/resource-syncs/database-table-sync.js +66 -32
  89. package/dist/src/resource-syncs/database-view-sync.js +41 -28
  90. package/dist/src/resource-syncs/endpoint-sync.js +90 -18
  91. package/dist/src/resource-syncs/event-sync.js +33 -14
  92. package/dist/src/resource-syncs/group-sync.js +21 -11
  93. package/dist/src/resource-syncs/job-template-sync.js +98 -37
  94. package/dist/src/resource-syncs/role-group-sync.js +22 -11
  95. package/dist/src/resource-syncs/schedule-sync.js +26 -11
  96. package/dist/src/resource-syncs/service-account-sync.js +22 -11
  97. package/dist/src/reviewed-plan.js +3 -0
  98. package/dist/src/runtime-view.js +2 -18
  99. package/dist/src/sync-omit-command.d.ts +6 -0
  100. package/dist/src/sync-omit-command.js +49 -0
  101. package/dist/src/sync-omit-write-fence.d.ts +10 -0
  102. package/dist/src/sync-omit-write-fence.js +134 -0
  103. package/dist/src/sync-omit.d.ts +59 -0
  104. package/dist/src/sync-omit.js +469 -0
  105. package/dist/src/sync-output.d.ts +3 -3
  106. package/dist/src/ui.js +11 -5
  107. package/dist/src/update-notifier.d.ts +1 -1
  108. package/dist/src/update-notifier.js +2 -1
  109. package/dist/src/utils.js +46 -17
  110. package/dist/src/workspace-prune.js +11 -3
  111. package/dist/src/workspace-write-lock.d.ts +7 -0
  112. package/dist/src/workspace-write-lock.js +144 -0
  113. package/package.json +6 -5
@@ -0,0 +1,469 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ import { createHash } from 'node:crypto';
3
+ import { requestContracts } from "./request-contract.js";
4
+ export const SYNC_RESOURCE_FAMILIES = ['database-table', 'database-view', 'component', 'service-account', 'agent-plugin', 'agent', 'job-template', 'endpoint', 'schedule', 'event', 'group', 'role-group'];
5
+ const context = new AsyncLocalStorage();
6
+ const MAX_DIGEST_NODES = 50_000;
7
+ const MAX_DIGEST_DEPTH = 100;
8
+ const unsafeSegments = new Set(['__proto__', 'prototype', 'constructor']);
9
+ const families = new Set(SYNC_RESOURCE_FAMILIES);
10
+ function isObject(value) {
11
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
12
+ }
13
+ function stableValue(value) {
14
+ if (Array.isArray(value))
15
+ return value.map(stableValue);
16
+ if (!isObject(value))
17
+ return value;
18
+ return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]));
19
+ }
20
+ function hash(value) {
21
+ return createHash('sha256').update(JSON.stringify(stableValue(value))).digest('hex');
22
+ }
23
+ const EMPTY_POLICY = Object.freeze({ schemaVersion: 1, rules: Object.freeze([]), fingerprint: hash({ schemaVersion: 1, rules: [] }) });
24
+ export function normalizeSyncResourceFamily(value) {
25
+ const normalized = value === 'database-schema' || value === 'database-partition' ? 'database-table' : value;
26
+ if (!families.has(normalized))
27
+ throw new Error(`Unknown --omit resource family "${value}".`);
28
+ return normalized;
29
+ }
30
+ function parsePath(value) {
31
+ let parts;
32
+ if (value.startsWith('/')) {
33
+ if (/~(?![01])/u.test(value))
34
+ throw new Error(`Invalid JSON Pointer in --omit: "${value}".`);
35
+ parts = value.slice(1).split('/').map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'));
36
+ }
37
+ else {
38
+ if (/[\[\]*\\]/u.test(value))
39
+ throw new Error('--omit uses object paths; use JSON Pointer for literal keys. Array indexes and wildcards are not supported.');
40
+ parts = value.split('.');
41
+ }
42
+ if (parts.some(part => !part || unsafeSegments.has(part)))
43
+ throw new Error(`Unsafe or empty property in --omit path "${value}".`);
44
+ return parts;
45
+ }
46
+ function pathString(parts) {
47
+ return `/${parts.map(part => part.replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}`;
48
+ }
49
+ function schemaAllows(schema, parts) {
50
+ if (parts.length === 0)
51
+ return true;
52
+ if (schema.$ref) {
53
+ const referenced = requestContracts[schema.$ref.split('/').at(-1)];
54
+ return Boolean(referenced && schemaAllows(referenced, parts));
55
+ }
56
+ if (schema.allOf?.length)
57
+ return schema.allOf.some(child => schemaAllows(child, parts));
58
+ if (schema.type === 'array' || schema.items)
59
+ return false;
60
+ const child = schema.properties?.[parts[0]];
61
+ if (child)
62
+ return schemaAllows(child, parts.slice(1));
63
+ return schema.additionalProperties === true || (!schema.properties && schema.additionalProperties !== false && (!schema.type || schema.type === 'object'));
64
+ }
65
+ const runtimeOptionRoots = { endpoint: 'EndpointOptionsDto', 'job-template': 'JobOptionsDto' };
66
+ const ordinaryRoots = {
67
+ 'database-table': ['name', 'category', 'description'],
68
+ 'database-view': ['name', 'category', 'description'],
69
+ component: ['name', 'category', 'desc', 'active', 'testConfig'],
70
+ 'service-account': ['name'],
71
+ 'agent-plugin': ['name'],
72
+ agent: ['name'],
73
+ 'job-template': ['name', 'category', 'description', 'timeout', 'inputs'],
74
+ endpoint: ['name', 'category', 'description', 'active', 'timeout'],
75
+ schedule: ['name', 'category', 'description', 'cron', 'timezone', 'input', 'inputMode'],
76
+ event: ['name', 'category', 'description', 'filter', 'input', 'inputMode', 'extensions'],
77
+ group: ['name', 'category', 'description'],
78
+ 'role-group': ['name', 'category', 'description'],
79
+ };
80
+ const agentConfig = new Set(['model', 'reasoningEffort', 'executionMode', 'planningPolicy', 'workMode', 'persona', 'systemInstructions', 'definition', 'memoryPolicy', 'cheapTurn', 'toolNames', 'maxActiveRootRuns', 'maxChildRuns', 'maxConcurrentChildRuns', 'maxTicks', 'childFailureMode']);
81
+ const agentPolicy = new Set(['defaultToolPermission', 'toolPermissions', 'toolNames', 'maxActiveRootRuns', 'maxChildRuns', 'maxConcurrentChildRuns', 'maxTicks', 'childFailureMode']);
82
+ const pluginSettings = new Set(['name', 'description', 'category', 'active', 'routing', 'executionMode', 'inputSchema', 'outputSchema', 'approvalPolicy', 'mutationIntent', 'reversibility', 'targetScope', 'sideEffectSummary', 'sideEffectCategories', 'timeoutMs', 'resultMaxBytes', 'autoDiscovery']);
83
+ function familyPath(family, parts) {
84
+ if (family === 'component' && parts[0] === 'description')
85
+ return ['desc', ...parts.slice(1)];
86
+ if (family === 'agent' && (parts[0] === 'description' || parts[0] === 'desc'))
87
+ return ['definition', 'desc', ...parts.slice(1)];
88
+ if (family === 'agent-plugin' && ['category', 'description', 'active'].includes(parts[0]))
89
+ return ['definition', ...parts];
90
+ return [...parts];
91
+ }
92
+ function allowedPath(family, parts, stableKeyName = 'stableKey') {
93
+ const [root, second, third] = parts;
94
+ if (root === 'metadata')
95
+ return parts.length > 1 && second !== stableKeyName && second !== 'stableKey' && !second.startsWith('__')
96
+ && !(second === 'details' && (parts.length === 2 || third === stableKeyName || third === 'stableKey'));
97
+ if (family === 'event' && root === 'extensions' && second === 'inputMode' && parts.length > 2)
98
+ return false;
99
+ if (root === 'options' && runtimeOptionRoots[family]) {
100
+ if (parts.length === 1)
101
+ return true;
102
+ if (/^componentSchema/.test(second))
103
+ return false;
104
+ return schemaAllows(requestContracts[runtimeOptionRoots[family]], parts.slice(1));
105
+ }
106
+ if (ordinaryRoots[family].includes(root))
107
+ return parts.length === 1 || ['testConfig', 'inputs', 'input', 'filter', 'extensions'].includes(root);
108
+ if (root !== 'definition')
109
+ return false;
110
+ if (family === 'agent-plugin')
111
+ return pluginSettings.has(second) && (parts.length === 2 || ['routing', 'inputSchema', 'outputSchema', 'approvalPolicy'].includes(second));
112
+ if (family !== 'agent')
113
+ return false;
114
+ if (second === 'desc')
115
+ return parts.length === 2;
116
+ if (second === 'config')
117
+ return parts.length >= 3 && agentConfig.has(third);
118
+ if (second === 'policy')
119
+ return parts.length >= 3 && agentPolicy.has(third);
120
+ return false;
121
+ }
122
+ /** Flags are invocation-local; resource metadata never changes this policy. */
123
+ export function parseOmitPolicy(args, options = {}) {
124
+ const value = args.omit;
125
+ if (value === undefined || value === false)
126
+ return emptySyncOmitPolicy();
127
+ const values = Array.isArray(value) ? value : [value];
128
+ if (values.some(item => typeof item !== 'string' || !item.trim()))
129
+ throw new Error('--omit requires a comma-separated property list.');
130
+ const rules = new Map();
131
+ for (const item of values) {
132
+ for (const raw of item.split(',')) {
133
+ const spec = raw.trim();
134
+ if (!spec)
135
+ throw new Error('--omit contains an empty property path.');
136
+ const separator = spec.startsWith('/') ? -1 : spec.indexOf(':');
137
+ const resource = separator < 0 ? undefined : normalizeSyncResourceFamily(spec.slice(0, separator));
138
+ const parts = parsePath(separator < 0 ? spec : spec.slice(separator + 1));
139
+ const applicable = (resource ? [resource] : SYNC_RESOURCE_FAMILIES).filter(family => allowedPath(family, familyPath(family, parts), options.stableKeyName));
140
+ if (applicable.length === 0)
141
+ throw new Error(`--omit cannot ignore "${spec}": unknown, protected, structural, or dependency property. Use a configurable property path for the selected resource.`);
142
+ const rule = { ...(resource ? { resource } : {}), path: pathString(parts) };
143
+ rules.set(`${resource || '*'}:${rule.path}`, rule);
144
+ }
145
+ }
146
+ const normalized = [...rules.values()].sort((a, b) => `${a.resource || '*'}:${a.path}`.localeCompare(`${b.resource || '*'}:${b.path}`));
147
+ return { schemaVersion: 1, rules: normalized, fingerprint: hash({ schemaVersion: 1, rules: normalized }) };
148
+ }
149
+ export function emptySyncOmitPolicy() {
150
+ return EMPTY_POLICY;
151
+ }
152
+ /** Unqualified paths must be meaningful for every selected family. Mixed workspaces can qualify individual rules. */
153
+ export function validateSyncOmitFamilies(policy, resources) {
154
+ const selected = [...new Set(resources.map(normalizeSyncResourceFamily))];
155
+ for (const rule of policy.rules) {
156
+ if (rule.resource && !selected.includes(rule.resource))
157
+ throw new Error(`--omit resource "${rule.resource}" is outside the selected resource families.`);
158
+ for (const family of rule.resource ? [rule.resource] : selected) {
159
+ if (!allowedPath(family, familyPath(family, parsePath(rule.path)))) {
160
+ throw new Error(`--omit path "${rule.path}" is not configurable for ${family}; qualify the path with its resource family.`);
161
+ }
162
+ }
163
+ }
164
+ }
165
+ export function currentSyncOmitPolicy() {
166
+ return context.getStore()?.policy || emptySyncOmitPolicy();
167
+ }
168
+ export function withSyncOmitPolicy(policy, operation) {
169
+ return context.run({ policy, captures: new Map() }, operation);
170
+ }
171
+ /** Integrity checks and source manifests always retain the complete definition. */
172
+ export function withoutSyncOmit(operation) {
173
+ return context.run({ policy: emptySyncOmitPolicy(), captures: context.getStore()?.captures || new Map() }, operation);
174
+ }
175
+ export function omitPaths(resource, policy = currentSyncOmitPolicy()) {
176
+ const family = normalizeSyncResourceFamily(resource);
177
+ const paths = policy.rules.flatMap(rule => {
178
+ if (rule.resource && rule.resource !== family)
179
+ return [];
180
+ const parts = familyPath(family, parsePath(rule.path));
181
+ if (!allowedPath(family, parts))
182
+ return [];
183
+ if (family === 'agent-plugin' && parts.length === 1 && parts[0] === 'name')
184
+ return [parts, ['definition', 'name']];
185
+ if (family === 'agent-plugin' && parts.length === 2 && parts[0] === 'definition' && parts[1] === 'name')
186
+ return [parts, ['name']];
187
+ if (family === 'job-template' && parts.length === 1 && parts[0] === 'options')
188
+ return [parts, ['inputs']];
189
+ if (family === 'job-template' && parts[0] === 'inputs')
190
+ return [parts, ['options', 'input', ...parts.slice(1)]];
191
+ if (family === 'job-template' && parts[0] === 'options' && parts[1] === 'input')
192
+ return [parts, ['inputs', ...parts.slice(2)]];
193
+ if (family === 'event') {
194
+ if (parts.length === 1 && parts[0] === 'extensions')
195
+ return [parts, ['input'], ['inputMode']];
196
+ if (parts[0] === 'input' || parts[0] === 'inputMode')
197
+ return [parts, ['extensions', ...parts]];
198
+ if (parts[0] === 'extensions' && (parts[1] === 'input' || parts[1] === 'inputMode'))
199
+ return [parts, parts.slice(1)];
200
+ }
201
+ return [parts];
202
+ });
203
+ const sorted = [...new Map(paths.map(parts => [pathString(parts), parts])).values()].sort((a, b) => a.length - b.length || pathString(a).localeCompare(pathString(b)));
204
+ return sorted.filter((parts, index) => !sorted.slice(0, index).some(parent => parent.length <= parts.length && parent.every((part, at) => part === parts[at])));
205
+ }
206
+ function readPath(value, parts) {
207
+ let current = value;
208
+ for (const part of parts) {
209
+ if (Array.isArray(current))
210
+ throw new Error('--omit cannot traverse arrays; omit the complete array property instead.');
211
+ if (!isObject(current) || !Object.hasOwn(current, part))
212
+ return { exists: false };
213
+ current = current[part];
214
+ }
215
+ return { exists: true, value: current };
216
+ }
217
+ function removePath(value, parts) {
218
+ if (Array.isArray(value))
219
+ throw new Error('--omit cannot traverse arrays; omit the complete array property instead.');
220
+ if (!isObject(value))
221
+ return;
222
+ const [part, ...rest] = parts;
223
+ if (!Object.hasOwn(value, part))
224
+ return;
225
+ if (!rest.length) {
226
+ delete value[part];
227
+ return;
228
+ }
229
+ if (Array.isArray(value[part]))
230
+ throw new Error('--omit cannot traverse arrays; omit the complete array property instead.');
231
+ if (!isObject(value[part]))
232
+ return;
233
+ removePath(value[part], rest);
234
+ if (Object.keys(value[part]).length === 0)
235
+ delete value[part];
236
+ }
237
+ function writePath(value, parts, entry) {
238
+ if (!isObject(value))
239
+ return;
240
+ let current = value;
241
+ for (const part of parts.slice(0, -1)) {
242
+ if (Object.hasOwn(current, part) && !isObject(current[part]))
243
+ throw new Error('--omit cannot preserve a nested property through an existing array, null, or scalar ancestor; omit the complete ancestor property instead.');
244
+ if (!Object.hasOwn(current, part))
245
+ current[part] = {};
246
+ current = current[part];
247
+ }
248
+ current[parts.at(-1)] = structuredClone(entry);
249
+ }
250
+ export function projectSyncDefinition(family, shape, policy = currentSyncOmitPolicy()) {
251
+ const paths = omitPaths(family, policy);
252
+ if (!paths.length)
253
+ return shape;
254
+ const result = structuredClone(shape);
255
+ for (const parts of paths)
256
+ removePath(result, parts);
257
+ return result;
258
+ }
259
+ /** Updates retain target ownership, including the difference between missing and null. Creates use the complete desired definition. */
260
+ export function preserveOmittedProperties(family, desired, target, policy = currentSyncOmitPolicy()) {
261
+ const paths = omitPaths(family, policy);
262
+ if (!paths.length || target === undefined || target === null)
263
+ return desired;
264
+ const result = structuredClone(desired);
265
+ if (normalizeSyncResourceFamily(family) === 'event') {
266
+ for (const field of ['input', 'inputMode']) {
267
+ if (!paths.some(parts => parts[0] === field || parts[0] === 'extensions' && (parts.length === 1 || parts[1] === field)))
268
+ continue;
269
+ const canonicalTarget = readPath(target, [field]);
270
+ const legacyTarget = readPath(target, ['extensions', field]);
271
+ const canonicalDesired = readPath(result, [field]);
272
+ const legacyDesired = readPath(result, ['extensions', field]);
273
+ // Nested ownership must merge siblings into one runtime envelope. Merely
274
+ // copying both aliases would let canonical input hide a preserved legacy key.
275
+ if (canonicalTarget.exists) {
276
+ if (!canonicalDesired.exists && legacyDesired.exists)
277
+ writePath(result, [field], legacyDesired.value);
278
+ if (!legacyTarget.exists)
279
+ removePath(result, ['extensions', field]);
280
+ }
281
+ else if (legacyTarget.exists) {
282
+ if (canonicalDesired.exists)
283
+ writePath(result, ['extensions', field], canonicalDesired.value);
284
+ removePath(result, [field]);
285
+ }
286
+ }
287
+ }
288
+ for (const parts of paths) {
289
+ const current = readPath(target, parts);
290
+ if (current.exists)
291
+ writePath(result, parts, current.value);
292
+ else
293
+ removePath(result, parts);
294
+ }
295
+ return result;
296
+ }
297
+ /** Verify target-owned values separately from the deliberately masked convergence hash. */
298
+ export function assertOmittedPropertiesPreserved(family, expectedTargetManifest, actualManifest) {
299
+ const paths = omitPaths(family);
300
+ if (!paths.length)
301
+ return;
302
+ const expectedShape = normalizeSyncResourceFamily(family) === 'event' ? normalizedEventRuntimeAliases(expectedTargetManifest) : expectedTargetManifest;
303
+ const actualShape = normalizeSyncResourceFamily(family) === 'event' ? normalizedEventRuntimeAliases(actualManifest) : actualManifest;
304
+ for (const parts of paths) {
305
+ const expected = readPath(expectedShape, parts);
306
+ const actual = readPath(actualShape, parts);
307
+ if (expected.exists !== actual.exists || expected.exists && hash({ defined: expected.value !== undefined, value: expected.value }) !== hash({ defined: actual.value !== undefined, value: actual.value })) {
308
+ throw new Error(`Ignored ${family} property "${pathString(parts)}" was not preserved by the write.`);
309
+ }
310
+ }
311
+ }
312
+ function normalizedEventRuntimeAliases(shape) {
313
+ const value = structuredClone(shape);
314
+ if (!isObject(value) || !isObject(value.extensions))
315
+ return value;
316
+ for (const field of ['input', 'inputMode']) {
317
+ if (!Object.hasOwn(value, field) && Object.hasOwn(value.extensions, field))
318
+ value[field] = value.extensions[field];
319
+ delete value.extensions[field];
320
+ }
321
+ if (!Object.keys(value.extensions).length)
322
+ delete value.extensions;
323
+ return value;
324
+ }
325
+ export function createSyncDefinitionDigest(shape) {
326
+ let nodes = 0;
327
+ function visit(value, depth) {
328
+ if (++nodes > MAX_DIGEST_NODES || depth > MAX_DIGEST_DEPTH)
329
+ throw new Error('Definition is too large or deeply nested for a safe --omit baseline.');
330
+ if (!isObject(value))
331
+ return { kind: 'value', hash: hash(value === undefined ? null : value), ...(Array.isArray(value) ? { array: true } : {}) };
332
+ return { kind: 'object', properties: Object.fromEntries(Object.keys(value).filter(key => value[key] !== undefined).sort().map(key => [key, visit(value[key], depth + 1)])) };
333
+ }
334
+ return visit(shape, 0);
335
+ }
336
+ function removeDigestPath(tree, parts) {
337
+ if (tree.kind !== 'object')
338
+ return;
339
+ const [part, ...rest] = parts;
340
+ if (!Object.hasOwn(tree.properties, part))
341
+ return;
342
+ if (!rest.length) {
343
+ delete tree.properties[part];
344
+ return;
345
+ }
346
+ const child = tree.properties[part];
347
+ if (child.kind === 'value' && child.array)
348
+ throw new Error('--omit cannot traverse arrays; omit the complete array property instead.');
349
+ if (child.kind !== 'object')
350
+ return;
351
+ removeDigestPath(child, rest);
352
+ if (Object.keys(child.properties).length === 0)
353
+ delete tree.properties[part];
354
+ }
355
+ function normalizeProjectedDigest(family, tree) {
356
+ if (tree.kind !== 'object')
357
+ return;
358
+ if (family === 'event') {
359
+ const extensions = tree.properties.extensions;
360
+ if (extensions?.kind === 'object') {
361
+ for (const field of ['input', 'inputMode']) {
362
+ const legacy = extensions.properties[field];
363
+ if (legacy && !Object.hasOwn(tree.properties, field))
364
+ tree.properties[field] = legacy;
365
+ delete extensions.properties[field];
366
+ }
367
+ if (!Object.keys(extensions.properties).length)
368
+ delete tree.properties.extensions;
369
+ }
370
+ return;
371
+ }
372
+ if (family !== 'job-template')
373
+ return;
374
+ const inputs = tree.properties.inputs;
375
+ const options = tree.properties.options;
376
+ const input = options?.kind === 'object' ? options.properties.input : undefined;
377
+ // The owning Job hash removes the legacy alias once the effective values are
378
+ // equal. A previously full baseline can become equal only after projection.
379
+ if (inputs && input && hashSyncDefinitionDigest(inputs) === hashSyncDefinitionDigest(input))
380
+ removeDigestPath(tree, ['options', 'input']);
381
+ }
382
+ export function projectSyncDefinitionDigest(resource, tree, policy = currentSyncOmitPolicy()) {
383
+ const family = normalizeSyncResourceFamily(resource);
384
+ const result = structuredClone(tree);
385
+ for (const parts of omitPaths(family, policy))
386
+ removeDigestPath(result, parts);
387
+ normalizeProjectedDigest(family, result);
388
+ return result;
389
+ }
390
+ export function hashSyncDefinitionDigest(tree) {
391
+ return hash({ syncDefinitionDigestVersion: 1, tree });
392
+ }
393
+ export function hashSyncDefinition(resource, shape, legacyHash) {
394
+ const family = normalizeSyncResourceFamily(resource);
395
+ const rawHash = legacyHash || hash(shape);
396
+ const paths = omitPaths(family);
397
+ const active = paths.length > 0;
398
+ // Validate against the actual definition as well as its atomic digest tree.
399
+ // Missing dynamic object keys are valid; traversing a runtime array is not.
400
+ for (const parts of paths)
401
+ readPath(shape, parts);
402
+ const store = context.getStore();
403
+ if (!active && !store)
404
+ return rawHash;
405
+ // Ordinary raw hashes identify the exact canonical shape. Custom legacy
406
+ // envelope hashes can normalize aliases differently, so do not cache those.
407
+ const tree = (!legacyHash ? store?.captures.get(`${family}:${rawHash}`)?.tree : undefined) || createSyncDefinitionDigest(shape);
408
+ const result = active ? hashSyncDefinitionDigest(projectSyncDefinitionDigest(family, tree)) : rawHash;
409
+ if (store) {
410
+ const capture = { schemaVersion: 1, family, rawHash, tree, paths: paths.map(pathString), policyFingerprint: currentSyncOmitPolicy().fingerprint };
411
+ // A full historical hash proves all fields, even when observed while a mask
412
+ // is active. Only the projected hash represents previously unmanaged paths.
413
+ // An active custom legacy hash can describe a fuller canonical alias shape
414
+ // than the projected shape supplied here. Only an unmasked observation can
415
+ // establish its full source proof, and a later projection must not replace it.
416
+ if (!legacyHash || !active)
417
+ store.captures.set(`${family}:${rawHash}`, { ...capture, paths: [], policyFingerprint: emptySyncOmitPolicy().fingerprint });
418
+ store.captures.set(`${family}:${result}`, capture);
419
+ }
420
+ return result;
421
+ }
422
+ export function syncBaselineData(resource, value) {
423
+ const capture = context.getStore()?.captures.get(`${normalizeSyncResourceFamily(resource)}:${value}`);
424
+ return capture ? { schemaVersion: 1, rawHash: capture.rawHash, tree: structuredClone(capture.tree), paths: [...capture.paths], policyFingerprint: capture.policyFingerprint } : undefined;
425
+ }
426
+ function baselineDataMatchesHash(family, data, value) {
427
+ if (!data || data.schemaVersion !== 1 || !Array.isArray(data.paths))
428
+ return false;
429
+ if (!data.paths.length)
430
+ return data.rawHash === value;
431
+ try {
432
+ const projected = structuredClone(data.tree);
433
+ for (const previous of data.paths)
434
+ removeDigestPath(projected, parsePath(previous));
435
+ normalizeProjectedDigest(family, projected);
436
+ return hashSyncDefinitionDigest(projected) === value;
437
+ }
438
+ catch {
439
+ return false;
440
+ }
441
+ }
442
+ export function syncBaselineHash(resource, baseline) {
443
+ if (!baseline?.remoteHash)
444
+ return undefined;
445
+ const family = normalizeSyncResourceFamily(resource);
446
+ const captured = syncBaselineData(family, baseline.remoteHash);
447
+ // Metadata is useful only for the precise baseline it accompanies. A stale
448
+ // digest must never turn an independently changed remoteHash into convergence.
449
+ const data = baselineDataMatchesHash(family, baseline.omitBaseline, baseline.remoteHash) ? baseline.omitBaseline
450
+ : captured?.rawHash === baseline.remoteHash && baselineDataMatchesHash(family, captured, baseline.remoteHash) ? captured : undefined;
451
+ if (data) {
452
+ const activePaths = omitPaths(family);
453
+ if (!Array.isArray(data.paths) || data.paths.some(previous => {
454
+ const parts = parsePath(previous);
455
+ return !activePaths.some(current => current.length <= parts.length && current.every((part, index) => parts[index] === part));
456
+ }))
457
+ return `omit-policy-rebaseline-required:${currentSyncOmitPolicy().fingerprint}:${baseline.remoteHash}`;
458
+ if (!omitPaths(family).length)
459
+ return data.rawHash;
460
+ return hashSyncDefinitionDigest(projectSyncDefinitionDigest(family, data.tree));
461
+ }
462
+ if (!omitPaths(family).length)
463
+ return baseline.remoteHash;
464
+ return `omit-baseline-unavailable:${currentSyncOmitPolicy().fingerprint}:${baseline.remoteHash}`;
465
+ }
466
+ /** Local pull ownership has its own complete proof; target-environment baselines never prove local edit safety. */
467
+ export function syncSourceBaselineHash(resource, entry) {
468
+ return syncBaselineHash(resource, entry?.sourceHash ? { remoteHash: entry.sourceHash, omitBaseline: entry.sourceBaseline } : undefined);
469
+ }
@@ -1,13 +1,13 @@
1
1
  import type { CommandContext } from './types.ts';
2
2
  import type { FieldChange } from './diff-details.ts';
3
3
  import type { WorkspaceDiff } from './workspace-diff.ts';
4
- export type WorkspaceSyncStatus = 'pulled' | 'pruned' | 'deployed' | 'skipped' | 'failed' | 'write-unverified';
4
+ export type WorkspaceSyncStatus = 'pulled' | 'pruned' | 'deployed' | 'accepted' | 'skipped' | 'failed' | 'write-unverified';
5
5
  export type WorkspaceSyncResult = {
6
6
  status: WorkspaceSyncStatus;
7
7
  targetPath: string;
8
8
  reason?: string;
9
9
  };
10
- export type SyncOutputStatus = 'Pulled' | 'Pruned' | 'Skipped' | 'Deployed' | 'Activated' | 'Deactivated' | 'Failed' | 'Unverified';
10
+ export type SyncOutputStatus = 'Pulled' | 'Pruned' | 'Skipped' | 'Deployed' | 'Accepted' | 'Activated' | 'Deactivated' | 'Failed' | 'Unverified';
11
11
  export type SyncPlanDetail = {
12
12
  label: string;
13
13
  values?: string | ReadonlyArray<string>;
@@ -63,4 +63,4 @@ export declare function printSyncStatus(println: CommandContext['println'], inpu
63
63
  reason?: string;
64
64
  }): void;
65
65
  export declare function printSyncNotice(println: CommandContext['println'], message: string): void;
66
- export declare function printSyncSummary(println: CommandContext['println'], label: 'Pulled' | 'Deployed' | 'Activated', results: ReadonlyArray<Pick<WorkspaceSyncResult, 'status'>>, durationMs: number): void;
66
+ export declare function printSyncSummary(println: CommandContext['println'], label: 'Pulled' | 'Deployed' | 'Accepted' | 'Activated', results: ReadonlyArray<Pick<WorkspaceSyncResult, 'status'>>, durationMs: number): void;
package/dist/src/ui.js CHANGED
@@ -99,7 +99,11 @@ function renderCommandCatalog() {
99
99
  commandRow('--instance <uuid>', 'Override target instance for tenant-scoped requests'),
100
100
  commandRow('--token <apiKey>', 'Override API key for non-interactive runs'),
101
101
  commandRow('--hints', 'Show per-resource hints in human-readable plans'),
102
+ commandRow('--omit <[family:]path,...>', 'Preserve destination properties; pull keeps local values, push keeps target values'),
102
103
  commandRow('--no-update-notifier', 'Disable npm version update checks for this run'),
104
+ noteRow('Unknown options and unsupported option combinations are rejected before execution.'),
105
+ noteRow('Booleans accept true or false; --no-<option> disables an option. Values such as 0 or no are invalid.'),
106
+ noteRow('--dry-run is available for migrate run and env apply; use plan for push or deploy previews.'),
103
107
  '',
104
108
  paintHeader('Projects'),
105
109
  commandRow('revo -i', 'Show runtime info, config path, and auth state'),
@@ -119,7 +123,7 @@ function renderCommandCatalog() {
119
123
  '',
120
124
  paintHeader('Terminal'),
121
125
  commandRow('revo terminal connect --workspace <path> --name <name>', 'Pair and run a local terminal'),
122
- commandRow('revo terminal connect --browser-profile <name> --workspace <path>', 'Opt in to encrypted browser auth reuse (macOS foreground)'),
126
+ noteRow('Browser profiles: manage website authentication in Revo Vault and assign it to approved workspaces.'),
123
127
  commandRow('revo terminal browser-profile forget --browser-profile <name> --terminal-id <uuid> --workspace <path>', 'Forget a selected local browser auth profile'),
124
128
  commandRow('revo terminal service install --workspace <path>', 'Run an approved terminal in the background on macOS or Linux'),
125
129
  commandRow('revo terminal service uninstall --workspace <path>', 'Stop and remove the background service'),
@@ -147,6 +151,7 @@ function renderCommandCatalog() {
147
151
  commandRow('revo database-tables pull --all [--project <name>] [--force] [--strict]', 'Pull portable Database Tables and partitions'),
148
152
  commandRow('revo database-tables plan --all [--project <name>] [--with-stats] [--json] [--strict] [--hints]', 'Preview schema drift, DDL risks, partitions, and performance hints'),
149
153
  commandRow('revo database-tables push <stableKey>|--all [--project <name>] --yes [--force] [--prune-partitions]', 'Create, safely update, or explicitly prune managed partitions'),
154
+ commandRow('revo database-tables push <stableKey> --yes --async [--idempotency-key <uuid>] [--json]', 'Accept durable schema work; poll Database Operations before dependent writes'),
150
155
  commandRow('revo database-views pull --all [--project <name>] [--force] [--strict]', 'Pull portable STRUCTURED and RAW_SQL Database Views after Database Table convergence'),
151
156
  commandRow('revo database-views plan --all [--project <name>] [--json] [--strict] [--hints]', 'Preview Database View drift, source readiness, and target compilation'),
152
157
  commandRow('revo database-views push <stableKey>|--all [--project <name>] --yes [--force]', 'Create or update Database Views after live preview'),
@@ -188,11 +193,12 @@ function renderCommandCatalog() {
188
193
  commandRow('revo env apply --from <env> --to <env> [--yes] [--prune] [--force]', 'Mirror components from one project into another'),
189
194
  commandRow('revo metadata plan [--project <name>] [--skip-partitions] [--json]', 'Preview stable-key metadata backfill'),
190
195
  commandRow('revo metadata apply [--project <name>] --yes [--skip-partitions]', 'Populate missing stable-key metadata'),
191
- commandRow('revo pull --all|--resources <list> --yes [--skip-groups] [--force] [--json]', 'Build the repository workspace from the configured runtime source'),
192
- commandRow('revo diff [--json]', 'Show only workspace-to-target resource differences without writes'),
193
- commandRow('revo plan [--activate] [--prune] [--out file] [--force] [--strict] [--json] [--hints]', 'Plan tracked definitions; preserve automation activation unless --activate'),
196
+ commandRow('revo pull --all|--resources <list>|<families...> --yes [--skip-groups] [--force] [--json] [--omit <paths>]', 'Pull source definitions and preserve selected local properties'),
197
+ commandRow('revo pull databases --omit=name --yes', 'Pull Database Tables while keeping existing local names'),
198
+ commandRow('revo diff [--json] [--omit <paths>]', 'Show only workspace-to-target resource differences without writes'),
199
+ commandRow('revo plan [--activate] [--prune] [--out file] [--force] [--strict] [--json] [--hints] [--omit <paths>]', 'Plan tracked definitions; preserve automation activation unless --activate'),
194
200
  commandRow('revo plan update [--json]', 'Update the local Stable Key source digest index without contacting the target'),
195
- commandRow('revo deploy [--yes] [--activate] [--prune] [--reviewed-plan file] [--force] [--json]', 'Deploy tracked definitions; preserve automation activation unless --activate'),
201
+ commandRow('revo deploy [--yes] [--activate] [--prune] [--reviewed-plan file] [--force] [--json] [--omit <paths>]', 'Deploy tracked definitions; preserve automation activation unless --activate'),
196
202
  commandRow('revo migrate plan --from <env> --to <env> [--resources <list>] [--skip-groups] [--force] [--json] [--hints]', 'Preview twelve resource families and identity dependencies'),
197
203
  commandRow('revo migrate run --from <env> --to <env> [--resources <list>] [--skip-groups] --yes [--force] [--json]', 'Pull, plan, migrate, and verify resources in dependency order'),
198
204
  commandRow('revo migrate verify --from <env> --to <env> [--resources <list>] [--json]', 'Verify target resources against a fresh temporary source pull'),
@@ -6,7 +6,7 @@ type UpdateNotifierOptions = {
6
6
  now?: number;
7
7
  stream?: NodeJS.WriteStream;
8
8
  };
9
- export declare function compareSemver(left: string, right: string): 1 | 0 | -1;
9
+ export declare function compareSemver(left: string, right: string): 0 | 1 | -1;
10
10
  export declare function renderUpdateNotice(input: {
11
11
  currentVersion: string;
12
12
  latestVersion: string;
@@ -11,7 +11,8 @@ function isTruthyEnv(value) {
11
11
  return value === '1' || value === 'true' || value === 'yes';
12
12
  }
13
13
  function updateNotifierDisabled(args) {
14
- return Boolean(args?.['no-update-notifier'])
14
+ return args?.['update-notifier'] === false || args?.['update-notifier'] === 'false'
15
+ || args?.['no-update-notifier'] === true || args?.['no-update-notifier'] === 'true'
15
16
  || isTruthyEnv(process.env.REVO_NO_UPDATE_NOTIFIER)
16
17
  || isTruthyEnv(process.env.NO_UPDATE_NOTIFIER)
17
18
  || isTruthyEnv(process.env.CI);
package/dist/src/utils.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { fileURLToPath } from 'node:url';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { readBooleanOption } from "./argument-contract.js";
4
6
  export function readFlag(args, names) {
5
7
  for (const name of names) {
6
8
  const value = args[name];
@@ -14,16 +16,7 @@ export function readFlag(args, names) {
14
16
  return '';
15
17
  }
16
18
  export function readBoolFlag(args, names) {
17
- for (const name of names) {
18
- const value = args[name];
19
- if (typeof value === 'boolean') {
20
- return value;
21
- }
22
- if (typeof value === 'string') {
23
- return value !== 'false';
24
- }
25
- }
26
- return false;
19
+ return readBooleanOption(args, names);
27
20
  }
28
21
  export function readValues(args, names) {
29
22
  const values = [];
@@ -120,15 +113,51 @@ export function readJsonFile(filePath) {
120
113
  return raw.trim() ? JSON.parse(raw) : {};
121
114
  }
122
115
  export function writeJsonFile(filePath, data) {
123
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
124
- fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, {
125
- mode: 0o600,
126
- });
116
+ const contents = `${JSON.stringify(data, null, 2)}\n`;
117
+ const directory = path.dirname(filePath);
118
+ fs.mkdirSync(directory, { recursive: true });
127
119
  try {
128
- fs.chmodSync(filePath, 0o600);
120
+ if (fs.lstatSync(filePath).isSymbolicLink())
121
+ throw new Error(`Refusing to replace a symbolic-link JSON file: ${filePath}`);
129
122
  }
130
- catch {
131
- // Best effort on platforms with limited chmod support.
123
+ catch (error) {
124
+ if (error.code !== 'ENOENT')
125
+ throw error;
126
+ }
127
+ const temporary = path.join(directory, `.${path.basename(filePath)}.tmp-${process.pid}-${randomUUID()}`);
128
+ let descriptor;
129
+ try {
130
+ descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW || 0), 0o600);
131
+ fs.writeFileSync(descriptor, contents);
132
+ fs.fsyncSync(descriptor);
133
+ fs.closeSync(descriptor);
134
+ descriptor = undefined;
135
+ fs.renameSync(temporary, filePath);
136
+ // Persist the directory entry as well as the new contents on supported filesystems.
137
+ let parent;
138
+ try {
139
+ parent = fs.openSync(directory, fs.constants.O_RDONLY);
140
+ fs.fsyncSync(parent);
141
+ }
142
+ catch (error) {
143
+ if (!['EINVAL', 'ENOTSUP', 'EPERM', 'EISDIR', 'EBADF'].includes(error.code || ''))
144
+ throw error;
145
+ }
146
+ finally {
147
+ if (parent !== undefined)
148
+ fs.closeSync(parent);
149
+ }
150
+ }
151
+ finally {
152
+ if (descriptor !== undefined)
153
+ fs.closeSync(descriptor);
154
+ try {
155
+ fs.unlinkSync(temporary);
156
+ }
157
+ catch (error) {
158
+ if (error.code !== 'ENOENT')
159
+ throw error;
160
+ }
132
161
  }
133
162
  }
134
163
  export function deepClone(value) {