@revoengine/cli 1.0.29 → 1.0.30

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 (69) hide show
  1. package/README.md +154 -3
  2. package/dist/src/automation-contract.generated.d.ts +742 -0
  3. package/dist/src/automation-contract.generated.js +1021 -0
  4. package/dist/src/cli.js +9 -1
  5. package/dist/src/client.d.ts +24 -0
  6. package/dist/src/client.js +60 -0
  7. package/dist/src/commands/component.js +52 -22
  8. package/dist/src/commands/env.js +1 -1
  9. package/dist/src/commands/index.d.ts +2 -0
  10. package/dist/src/commands/index.js +2 -0
  11. package/dist/src/commands/studio.d.ts +3 -0
  12. package/dist/src/commands/studio.js +114 -0
  13. package/dist/src/commands/terminal-browser-human-input.d.ts +11 -0
  14. package/dist/src/commands/terminal-browser-human-input.js +44 -0
  15. package/dist/src/commands/terminal-browser-interaction.d.ts +25 -0
  16. package/dist/src/commands/terminal-browser-interaction.js +56 -0
  17. package/dist/src/commands/terminal-browser-live-protocol.d.ts +151 -0
  18. package/dist/src/commands/terminal-browser-live-protocol.js +177 -0
  19. package/dist/src/commands/terminal-browser-live-transport.d.ts +41 -0
  20. package/dist/src/commands/terminal-browser-live-transport.js +206 -0
  21. package/dist/src/commands/terminal-browser-live.d.ts +114 -0
  22. package/dist/src/commands/terminal-browser-live.js +455 -0
  23. package/dist/src/commands/terminal-browser-observation.d.ts +10 -0
  24. package/dist/src/commands/terminal-browser-observation.js +27 -0
  25. package/dist/src/commands/terminal-browser-page-input.d.ts +8 -0
  26. package/dist/src/commands/terminal-browser-page-input.js +94 -0
  27. package/dist/src/commands/terminal-browser-profile-preferences.d.ts +37 -0
  28. package/dist/src/commands/terminal-browser-profile-preferences.js +136 -0
  29. package/dist/src/commands/terminal-browser-profile.d.ts +52 -0
  30. package/dist/src/commands/terminal-browser-profile.js +447 -0
  31. package/dist/src/commands/terminal-browser.d.ts +28 -1
  32. package/dist/src/commands/terminal-browser.js +401 -55
  33. package/dist/src/commands/terminal-policy.js +2 -0
  34. package/dist/src/commands/terminal-public-web-proxy.d.ts +14 -0
  35. package/dist/src/commands/terminal-public-web-proxy.js +141 -0
  36. package/dist/src/commands/terminal-public-web.d.ts +11 -0
  37. package/dist/src/commands/terminal-public-web.js +99 -0
  38. package/dist/src/commands/terminal.d.ts +1 -0
  39. package/dist/src/commands/terminal.js +92 -9
  40. package/dist/src/commands/tests.d.ts +3 -0
  41. package/dist/src/commands/tests.js +236 -0
  42. package/dist/src/component-element-validation.d.ts +8 -0
  43. package/dist/src/component-element-validation.js +79 -0
  44. package/dist/src/component-lifecycle.d.ts +3 -0
  45. package/dist/src/component-lifecycle.js +17 -0
  46. package/dist/src/component-lock.d.ts +17 -12
  47. package/dist/src/component-lock.js +51 -6
  48. package/dist/src/component-manifests.js +3 -0
  49. package/dist/src/component-source-validation.d.ts +5 -0
  50. package/dist/src/component-source-validation.js +27 -0
  51. package/dist/src/env-sync.js +64 -9
  52. package/dist/src/native-tests.d.ts +61 -0
  53. package/dist/src/native-tests.js +20 -0
  54. package/dist/src/request-contract.d.ts +39 -0
  55. package/dist/src/request-contract.js +138 -0
  56. package/dist/src/resource-syncs/agent-sync.js +47 -7
  57. package/dist/src/resource-syncs/database-table-sync.js +8 -8
  58. package/dist/src/resource-syncs/endpoint-sync.js +20 -14
  59. package/dist/src/resource-syncs/group-sync.js +8 -3
  60. package/dist/src/resource-syncs/job-template-sync.js +75 -28
  61. package/dist/src/resource-syncs/role-group-sync.js +8 -0
  62. package/dist/src/resource-syncs/runtime-definition-validation.d.ts +14 -0
  63. package/dist/src/resource-syncs/runtime-definition-validation.js +153 -0
  64. package/dist/src/test-workspace.d.ts +33 -0
  65. package/dist/src/test-workspace.js +156 -0
  66. package/dist/src/types.d.ts +1 -0
  67. package/dist/src/ui.js +12 -0
  68. package/dist/src/update-notifier.d.ts +1 -1
  69. package/package.json +5 -3
@@ -1,5 +1,8 @@
1
1
  import { verifyComponentRuntime } from "./component-contract.js";
2
- import { buildPortableComponentUpdatePayload, diffPortableComponentSource, hashPortableComponentSource, normalizePortableComponentSource, sanitizeComponentSource, } from "./component-lock.js";
2
+ import { changeComponentActivation } from "./component-lifecycle.js";
3
+ import { componentElementValidationErrors } from "./component-element-validation.js";
4
+ import { componentSourceConfigurationErrors } from "./component-source-validation.js";
5
+ import { buildPortableComponentUpdatePayload, componentTypeTransitionReason, componentActivationValidationError, componentUpdateValidationError, diffPortableComponentSource, hashPortableComponentSource, normalizePortableComponentSource, sanitizeComponentSource, } from "./component-lock.js";
3
6
  import { buildStableKey as buildComponentStableKey, DEFAULT_STABLE_KEY_NAME, NULL_CATEGORY_KEY, sanitizeUserMetadata, } from "./resource-metadata.js";
4
7
  import { mapWithConcurrency } from "./utils.js";
5
8
  export function normalizeKeyPart(value) {
@@ -167,6 +170,15 @@ export function buildEnvSyncPlan(source, target, options) {
167
170
  sourceHash: sourceEntry?.portableHash ?? null,
168
171
  targetHash: targetEntry?.portableHash ?? null,
169
172
  };
173
+ const elementErrors = sourceEntry ? componentElementValidationErrors(sourceEntry.component, {
174
+ mode: !targetEntry || diffPortableComponentSource(sourceEntry.component, targetEntry.component).elementsChanged ? 'save' : 'create',
175
+ }) : [];
176
+ const activationError = sourceEntry ? componentActivationValidationError(sourceEntry.component) : null;
177
+ const configurationErrors = sourceEntry ? componentSourceConfigurationErrors(sourceEntry.component) : [];
178
+ if (elementErrors.length || activationError || configurationErrors.length) {
179
+ items.push({ ...base, action: targetEntry ? 'update' : 'create', blocked: true, reason: activationError || [...configurationErrors, ...elementErrors].join('; ') });
180
+ continue;
181
+ }
170
182
  if (sourceEntry && !targetEntry) {
171
183
  items.push({ ...base, action: 'create', reason: 'missing in target' });
172
184
  continue;
@@ -184,12 +196,15 @@ export function buildEnvSyncPlan(source, target, options) {
184
196
  }
185
197
  const changedFields = diffPortableComponentSource(sourceEntry.component, targetEntry.component).configurationFields;
186
198
  const elementDiff = diffElementKeys(sourceEntry.portable, targetEntry.portable);
199
+ const transition = componentTypeTransitionReason(sourceEntry.portable.type, targetEntry.portable.type)
200
+ || componentUpdateValidationError(sourceEntry.component, targetEntry.component);
187
201
  items.push({
188
202
  ...base,
189
203
  action: 'update',
190
204
  changedFields,
191
205
  ...elementDiff,
192
- reason: 'source and target content differ',
206
+ ...(transition ? { blocked: true } : {}),
207
+ reason: transition || 'source and target content differ',
193
208
  });
194
209
  }
195
210
  items.sort((left, right) => left.stableKey.localeCompare(right.stableKey)
@@ -214,6 +229,9 @@ export function buildEnvSyncPlan(source, target, options) {
214
229
  // Mirrors the push payload shape, but componentElementIds never cross
215
230
  // environments: they are only set when they belong to the target component.
216
231
  function buildPortableElementPayload(component, targetElementsByKey) {
232
+ const errors = componentElementValidationErrors(component, { mode: 'save' });
233
+ if (errors.length)
234
+ throw new Error(errors.join('; '));
217
235
  return [...(component.elements || [])].map((element) => {
218
236
  const targetElementId = targetElementsByKey?.get(element.key)?.componentElementId;
219
237
  return {
@@ -245,6 +263,7 @@ function buildCreatePayload(component) {
245
263
  active: sanitized.active ?? true,
246
264
  async: Boolean(sanitized.async),
247
265
  metadata: sanitizeUserMetadata(component.metadata),
266
+ ...(sanitized.testConfig !== undefined ? { testConfig: sanitized.testConfig } : {}),
248
267
  elements: buildPortableElementPayload(component),
249
268
  };
250
269
  }
@@ -259,7 +278,7 @@ export async function applyEnvSyncPlan(input) {
259
278
  const { targetClient, plan, source, target, stableKeyName, onItem } = input;
260
279
  const blocked = plan.items.filter(item => item.blocked);
261
280
  if (blocked.length)
262
- throw new Error(`Cannot apply: ${blocked.length} component runtime(s) are not ready. ${blocked.map(item => item.reason).join(' ')}`);
281
+ throw new Error(`Cannot apply: ${blocked.length} component(s) are blocked. ${blocked.map(item => item.reason).join(' ')}`);
263
282
  const collisions = plan.items.filter((item) => item.action === 'collision');
264
283
  if (collisions.length > 0) {
265
284
  throw new Error(`Cannot apply: ${collisions.length} stable-key collision(s) in scope. Resolve duplicates or narrow the scope with --key/--category.`);
@@ -284,6 +303,12 @@ async function applyPlanItem(targetClient, item, source, target, stableKeyName =
284
303
  if (!sourceEntry) {
285
304
  throw new Error('source component disappeared from the snapshot');
286
305
  }
306
+ const configurationErrors = componentSourceConfigurationErrors(sourceEntry.component);
307
+ if (configurationErrors.length)
308
+ throw new Error(configurationErrors.join('; '));
309
+ const activationError = componentActivationValidationError(sourceEntry.component);
310
+ if (activationError)
311
+ throw new Error(activationError);
287
312
  const created = unwrapComponent(await targetClient.createComponent(buildCreatePayload(sourceEntry.component)));
288
313
  const newComponentId = componentIdOf(created);
289
314
  if (!newComponentId) {
@@ -291,7 +316,8 @@ async function applyPlanItem(targetClient, item, source, target, stableKeyName =
291
316
  }
292
317
  // The save endpoint is the authoritative element write; re-sending the
293
318
  // elements guards against create endpoints that ignore inline elements.
294
- await targetClient.saveComponentElements(newComponentId, buildPortableElementPayload(sourceEntry.component));
319
+ if (sourceEntry.component.elements?.length)
320
+ await targetClient.saveComponentElements(newComponentId, buildPortableElementPayload(sourceEntry.component));
295
321
  const verified = await verifyAppliedComponent(targetClient, newComponentId, sourceEntry.portableHash);
296
322
  return { stableKey: item.stableKey, action: item.action, status: 'applied', verified };
297
323
  }
@@ -301,13 +327,42 @@ async function applyPlanItem(targetClient, item, source, target, stableKeyName =
301
327
  if (!sourceEntry || !targetEntry) {
302
328
  throw new Error('component disappeared from the snapshot');
303
329
  }
304
- if (item.changedFields && item.changedFields.length > 0) {
305
- await targetClient.updateComponent(targetEntry.componentId, buildPortableComponentUpdatePayload(sourceEntry.component, targetEntry.component, item.changedFields));
306
- }
330
+ const configurationErrors = componentSourceConfigurationErrors(sourceEntry.component);
331
+ if (configurationErrors.length)
332
+ throw new Error(configurationErrors.join('; '));
333
+ const elementErrors = componentElementValidationErrors(sourceEntry.component, { mode: 'create' });
334
+ if (elementErrors.length)
335
+ throw new Error(elementErrors.join('; '));
336
+ const transition = componentTypeTransitionReason(sourceEntry.portable.type, targetEntry.portable.type);
337
+ if (transition)
338
+ throw new Error(transition);
339
+ let expectedVersion = Number.isSafeInteger(targetEntry.component.version) ? targetEntry.component.version : null;
340
+ const activationChanged = sourceEntry.portable.active !== targetEntry.portable.active;
341
+ const updateFields = (item.changedFields || []).filter(field => field !== 'active' && field !== 'type');
342
+ const updatePayload = updateFields.length || activationChanged
343
+ ? buildPortableComponentUpdatePayload(sourceEntry.component, targetEntry.component, updateFields) : undefined;
307
344
  const hasElementChanges = Boolean(item.addedElementKeys?.length || item.removedElementKeys?.length || item.changedElementKeys?.length);
345
+ const targetElementsByKey = new Map((targetEntry.component.elements || []).map(element => [element.key, element]));
346
+ const elementPayload = hasElementChanges ? buildPortableElementPayload(sourceEntry.component, targetElementsByKey) : undefined;
347
+ if (activationChanged && !sourceEntry.portable.active) {
348
+ expectedVersion = await changeComponentActivation(targetClient, targetEntry.componentId, false, expectedVersion);
349
+ }
350
+ if (updateFields.length > 0) {
351
+ await targetClient.updateComponent(targetEntry.componentId, { ...updatePayload, version: expectedVersion });
352
+ if (expectedVersion !== null)
353
+ expectedVersion += 1;
354
+ }
308
355
  if (hasElementChanges) {
309
- const targetElementsByKey = new Map((targetEntry.component.elements || []).map((element) => [element.key, element]));
310
- await targetClient.saveComponentElements(targetEntry.componentId, buildPortableElementPayload(sourceEntry.component, targetElementsByKey));
356
+ const result = await targetClient.saveComponentElements(targetEntry.componentId, elementPayload);
357
+ if (result.status !== 304 && expectedVersion !== null)
358
+ expectedVersion += 1;
359
+ }
360
+ if (activationChanged && sourceEntry.portable.active) {
361
+ const beforeActivation = unwrapComponent(await targetClient.getComponent(targetEntry.componentId));
362
+ if (hashPortableComponentSource(beforeActivation) !== hashPortableComponentSource({ ...sourceEntry.component, active: false })) {
363
+ throw new Error('component source did not verify before activation');
364
+ }
365
+ await changeComponentActivation(targetClient, targetEntry.componentId, true, expectedVersion);
311
366
  }
312
367
  const verified = await verifyAppliedComponent(targetClient, targetEntry.componentId, sourceEntry.portableHash);
313
368
  return { stableKey: item.stableKey, action: item.action, status: 'applied', verified };
@@ -0,0 +1,61 @@
1
+ import type { NativeTestSource } from './test-workspace.ts';
2
+ export type NativeTestCatalogItem = {
3
+ name: string;
4
+ type: string;
5
+ version?: number;
6
+ active: boolean;
7
+ category?: string | null;
8
+ testConfig: {
9
+ mode?: 'fixture' | 'integration';
10
+ targets?: string[];
11
+ [key: string]: unknown;
12
+ } | null;
13
+ };
14
+ export type NativeTestCatalog = {
15
+ data: NativeTestCatalogItem[];
16
+ next: boolean;
17
+ total: number;
18
+ capabilities: {
19
+ canRun: boolean;
20
+ };
21
+ };
22
+ export type NativeTestRun = {
23
+ runId: string;
24
+ status: string;
25
+ createdAt: string;
26
+ completedAt: string | null;
27
+ snapshotDigest: string;
28
+ runs: Array<{
29
+ testRunId: string;
30
+ testComponentName: string;
31
+ status: string;
32
+ cases?: Array<{
33
+ name?: string;
34
+ status?: string;
35
+ assertions?: number;
36
+ }>;
37
+ assertions?: Array<{
38
+ name: string;
39
+ passed: boolean;
40
+ [key: string]: unknown;
41
+ }>;
42
+ error?: unknown;
43
+ durationMs?: number;
44
+ [key: string]: unknown;
45
+ }>;
46
+ };
47
+ export type NativeTestRunInput = {
48
+ operationId: string;
49
+ testComponentNames: string[];
50
+ components?: NativeTestSource[];
51
+ timeout?: number;
52
+ };
53
+ export type NativeTestCollection = {
54
+ status: string;
55
+ runIds: string[];
56
+ executions: NativeTestRun[];
57
+ };
58
+ export declare function nativeTestCollection(executions: NativeTestRun[], incomplete?: boolean): NativeTestCollection;
59
+ export declare function nativeTestRunPending(run: NativeTestRun): boolean;
60
+ /** A server PASS still needs host cases and assertions; an empty run never makes CI green. */
61
+ export declare function nativeTestRunPassed(run: NativeTestRun): boolean;
@@ -0,0 +1,20 @@
1
+ export function nativeTestCollection(executions, incomplete = false) {
2
+ const terminalOrder = ['CANCELLED', 'ABORTED', 'UNAVAILABLE', 'INCOMPLETE', 'STALE', 'FAILED'];
3
+ const status = incomplete ? 'INCOMPLETE'
4
+ : executions.some(run => run.status === 'RUNNING') ? 'RUNNING'
5
+ : executions.some(run => run.status === 'QUEUED') ? 'QUEUED'
6
+ : terminalOrder.find(value => executions.some(run => run.status === value))
7
+ || (executions.length && executions.every(nativeTestRunPassed) ? 'PASSED' : 'INCOMPLETE');
8
+ return { status, runIds: executions.map(run => run.runId), executions };
9
+ }
10
+ export function nativeTestRunPending(run) {
11
+ return ['QUEUED', 'RUNNING'].includes(run.status);
12
+ }
13
+ /** A server PASS still needs host cases and assertions; an empty run never makes CI green. */
14
+ export function nativeTestRunPassed(run) {
15
+ return run.status === 'PASSED' && run.runs.length > 0 && run.runs.every(suite => (suite.status === 'PASSED'
16
+ && Array.isArray(suite.cases) && suite.cases.length > 0
17
+ && suite.cases.every(item => item.status === 'PASSED')
18
+ && Array.isArray(suite.assertions) && suite.assertions.length > 0
19
+ && suite.assertions.every(item => item.passed === true)));
20
+ }
@@ -0,0 +1,39 @@
1
+ import { requestContractDefaults } from './automation-contract.generated.ts';
2
+ export type RequestContractSchema = {
3
+ type?: string;
4
+ $ref?: string;
5
+ allOf?: readonly RequestContractSchema[];
6
+ properties?: Readonly<Record<string, RequestContractSchema>>;
7
+ required?: readonly string[];
8
+ additionalProperties?: boolean;
9
+ nullable?: boolean;
10
+ items?: RequestContractSchema;
11
+ enum?: readonly unknown[];
12
+ minimum?: number;
13
+ maximum?: number;
14
+ minLength?: number;
15
+ maxLength?: number;
16
+ maxItems?: number;
17
+ nonBlank?: boolean;
18
+ pattern?: string;
19
+ patternFlags?: string;
20
+ format?: string;
21
+ userMetadata?: boolean;
22
+ whenEquals?: {
23
+ field: string;
24
+ value: unknown;
25
+ };
26
+ requiredWhen?: {
27
+ field: string;
28
+ value: unknown;
29
+ };
30
+ };
31
+ export declare const requestContracts: Readonly<Record<string, RequestContractSchema>>;
32
+ export { requestContractDefaults };
33
+ /** Shared metadata namespace and serialized-size policy; nested JSON keys remain unrestricted. */
34
+ export declare function validateUserMetadata(value: unknown, label?: string): string[];
35
+ /** Validate published request fields without coercing, stripping or changing their values. */
36
+ export declare function validateRequestContract(name: string, value: unknown, options?: {
37
+ partial?: boolean;
38
+ path?: string;
39
+ }): string[];
@@ -0,0 +1,138 @@
1
+ import { requestContracts as generatedContracts, requestContractDefaults } from "./automation-contract.generated.js";
2
+ export const requestContracts = generatedContracts;
3
+ export { requestContractDefaults };
4
+ // Matches the backend class-validator default UUID mode (validator.js 13.15.35):
5
+ // RFC versions 1-8 with variants 8-B, plus the nil and max UUIDs.
6
+ const BACKEND_UUID_PATTERN = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
7
+ function isObject(value) {
8
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
9
+ && [Object.prototype, null].includes(Object.getPrototypeOf(value));
10
+ }
11
+ /** Shared metadata namespace and serialized-size policy; nested JSON keys remain unrestricted. */
12
+ export function validateUserMetadata(value, label = 'metadata') {
13
+ if (value === undefined || value === null)
14
+ return [];
15
+ if (!isObject(value))
16
+ return [`${label} must be a JSON object`];
17
+ const errors = [];
18
+ const keys = Object.keys(value);
19
+ if (keys.some(key => key.startsWith(requestContractDefaults.metadata.reservedPrefix)))
20
+ errors.push(`${label} must not contain backend-reserved keys starting with "${requestContractDefaults.metadata.reservedPrefix}"`);
21
+ if (keys.length > requestContractDefaults.metadata.maxTopLevelKeys)
22
+ errors.push(`${label} must contain at most ${requestContractDefaults.metadata.maxTopLevelKeys} top-level keys`);
23
+ const ancestors = new Set();
24
+ const pending = [{ value, path: '$' }];
25
+ while (pending.length) {
26
+ const item = pending.pop();
27
+ if (item.exit) {
28
+ ancestors.delete(item.value);
29
+ continue;
30
+ }
31
+ if (item.value === null || ['string', 'boolean'].includes(typeof item.value))
32
+ continue;
33
+ if (typeof item.value === 'number' && Number.isFinite(item.value))
34
+ continue;
35
+ if (typeof item.value !== 'object' || item.value === null || !Array.isArray(item.value) && !isObject(item.value)) {
36
+ errors.push(`${label} value at ${item.path} must use a finite JSON-compatible value`);
37
+ break;
38
+ }
39
+ if (ancestors.has(item.value)) {
40
+ errors.push(`${label} must not contain circular references`);
41
+ break;
42
+ }
43
+ ancestors.add(item.value);
44
+ pending.push({ ...item, exit: true });
45
+ const entries = Array.isArray(item.value) ? item.value.flatMap((child, index) => [[String(index), child]]) : Object.entries(item.value);
46
+ for (const [key, child] of entries)
47
+ pending.push({ value: child, path: `${item.path}.${key}` });
48
+ }
49
+ try {
50
+ const serialized = JSON.stringify(value);
51
+ if (Buffer.byteLength(serialized, 'utf8') > requestContractDefaults.metadata.maxBytes)
52
+ errors.push(`${label} must not exceed ${requestContractDefaults.metadata.maxBytes} UTF-8 JSON bytes`);
53
+ }
54
+ catch {
55
+ errors.push(`${label} must be serializable JSON`);
56
+ }
57
+ return errors;
58
+ }
59
+ /** Validate published request fields without coercing, stripping or changing their values. */
60
+ export function validateRequestContract(name, value, options = {}) {
61
+ const schema = requestContracts[name];
62
+ if (!schema)
63
+ return [`Unknown request contract "${name}"`];
64
+ const errors = [];
65
+ function visit(rule, input, label, parent, partial = false) {
66
+ if (rule.whenEquals && parent?.[rule.whenEquals.field] !== rule.whenEquals.value)
67
+ return;
68
+ if (input === null && rule.nullable)
69
+ return;
70
+ if (rule.$ref) {
71
+ const reference = rule.$ref.replace('#/components/schemas/', '');
72
+ const target = requestContracts[reference];
73
+ if (!target) {
74
+ errors.push(`${label} has an unresolved request contract ${reference}`);
75
+ return;
76
+ }
77
+ visit(target, input, label, parent, partial);
78
+ return;
79
+ }
80
+ for (const nested of rule.allOf || [])
81
+ visit(nested, input, label, parent, partial);
82
+ const typeValid = rule.type === undefined || rule.type === 'object' && isObject(input)
83
+ || rule.type === 'array' && Array.isArray(input) || rule.type === 'string' && typeof input === 'string'
84
+ || rule.type === 'boolean' && typeof input === 'boolean'
85
+ || rule.type === 'number' && typeof input === 'number' && Number.isFinite(input)
86
+ || rule.type === 'integer' && typeof input === 'number' && Number.isInteger(input);
87
+ if (!typeValid) {
88
+ errors.push(`${label} must be ${rule.type === 'object' ? 'a JSON object' : `of type ${rule.type}`}`);
89
+ return;
90
+ }
91
+ if (rule.enum && !rule.enum.includes(input))
92
+ errors.push(`${label} must be one of ${rule.enum.join(', ')}`);
93
+ if (typeof input === 'number') {
94
+ if (rule.minimum !== undefined && input < rule.minimum)
95
+ errors.push(`${label} must be at least ${rule.minimum}`);
96
+ if (rule.maximum !== undefined && input > rule.maximum)
97
+ errors.push(`${label} must be at most ${rule.maximum}`);
98
+ }
99
+ if (typeof input === 'string') {
100
+ if (rule.minLength !== undefined && input.length < rule.minLength)
101
+ errors.push(`${label} must contain at least ${rule.minLength} characters`);
102
+ if (rule.maxLength !== undefined && input.length > rule.maxLength)
103
+ errors.push(`${label} must contain at most ${rule.maxLength} characters`);
104
+ if (rule.pattern && !new RegExp(rule.pattern, rule.patternFlags).test(input))
105
+ errors.push(`${label} does not match the backend format`);
106
+ if (rule.format === 'uuid' && !BACKEND_UUID_PATTERN.test(input))
107
+ errors.push(`${label} must be a UUID`);
108
+ if (rule.nonBlank && input.trim().length === 0)
109
+ errors.push(`${label} must be a non-empty component name`);
110
+ }
111
+ if (rule.userMetadata)
112
+ errors.push(...validateUserMetadata(input, label));
113
+ if (Array.isArray(input)) {
114
+ if (rule.maxItems !== undefined && input.length > rule.maxItems)
115
+ errors.push(`${label} must contain at most ${rule.maxItems} items`);
116
+ if (rule.items)
117
+ input.forEach((item, index) => visit(rule.items, item, `${label}[${index}]`));
118
+ }
119
+ if (isObject(input) && rule.properties) {
120
+ if (!partial)
121
+ for (const key of rule.required || [])
122
+ if (input[key] === undefined)
123
+ errors.push(`${label}.${key} is required`);
124
+ for (const [key, child] of Object.entries(rule.properties)) {
125
+ if (input[key] !== undefined)
126
+ visit(child, input[key], `${label}.${key}`, input);
127
+ else if (child.requiredWhen && input[child.requiredWhen.field] === child.requiredWhen.value)
128
+ errors.push(`${label}.${key} is required for ${child.requiredWhen.field}=${String(child.requiredWhen.value)}`);
129
+ }
130
+ if (rule.additionalProperties === false)
131
+ for (const key of Object.keys(input))
132
+ if (!Object.hasOwn(rule.properties, key))
133
+ errors.push(`${label}.${key} is not supported by the backend request contract`);
134
+ }
135
+ }
136
+ visit(schema, value, options.path || name, undefined, options.partial);
137
+ return errors;
138
+ }
@@ -37,15 +37,55 @@ async function dependencyKey(client, family, id, keyName) {
37
37
  throw new Error(`${family} dependency has no active Stable Key.`);
38
38
  return key;
39
39
  }
40
- function portableToolContracts(value) {
41
- if (Array.isArray(value))
42
- return value.map(portableToolContracts);
40
+ function assertPortableBindings(value) {
41
+ if (Array.isArray(value)) {
42
+ value.forEach(assertPortableBindings);
43
+ return;
44
+ }
43
45
  if (!isRecord(value))
44
- return value;
45
- if (value.$vault || value.vault || value.rollbackToSnapshotId)
46
+ return;
47
+ // The backend detects bound values by this own tag and then validates their
48
+ // shape. Ordinary keys named vault/$vault are user data, including wrappers.
49
+ if (Object.hasOwn(value, '__revoBoundValue'))
46
50
  throw new Error('Tool input Vault bindings and rollout snapshots require target-local configuration; cannot export instance IDs.');
47
- return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, key === 'approvalPolicy' && isRecord(child)
48
- ? pick(child, ['mode', 'safetyTier', 'condition']) : portableToolContracts(child)]));
51
+ Object.values(value).forEach(assertPortableBindings);
52
+ }
53
+ function portableToolset(value, collection) {
54
+ if (!isRecord(value)) {
55
+ assertPortableBindings(value);
56
+ return structuredClone(value);
57
+ }
58
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => {
59
+ if (key === 'defaultConfig')
60
+ return [key, portableToolContracts(child)];
61
+ if (key === collection && isRecord(child))
62
+ return [key, Object.fromEntries(Object.entries(child)
63
+ .map(([toolName, config]) => [toolName, portableToolContracts(config)]))];
64
+ assertPortableBindings(child);
65
+ return [key, structuredClone(child)];
66
+ }));
67
+ }
68
+ function portableToolContracts(value) {
69
+ if (!isRecord(value)) {
70
+ assertPortableBindings(value);
71
+ return structuredClone(value);
72
+ }
73
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => {
74
+ // JSON Schemas are opaque user contracts. Their property names, examples
75
+ // and defaults are unrelated to plugin credentials and approval governance.
76
+ if (key === 'inputSchema' || key === 'outputSchema')
77
+ return [key, structuredClone(child)];
78
+ if (key === 'approvalPolicy' && isRecord(child))
79
+ return [key, pick(child, ['mode', 'safetyTier', 'condition'])];
80
+ if (key === 'componentToolset')
81
+ return [key, portableToolset(child, 'tools')];
82
+ if (key === 'mcpToolset')
83
+ return [key, portableToolset(child, 'configs')];
84
+ if (key === 'rollout' && isRecord(child) && child.rollbackToSnapshotId)
85
+ throw new Error('Tool input Vault bindings and rollout snapshots require target-local configuration; cannot export instance IDs.');
86
+ assertPortableBindings(child);
87
+ return [key, structuredClone(child)];
88
+ }));
49
89
  }
50
90
  async function portablePlugin(client, config, keyName) {
51
91
  const result = record(portableToolContracts(pick(config, pluginFields)));
@@ -38,19 +38,19 @@ function canonicalValue(value, omitInstanceFields = false) {
38
38
  .map((key) => [key, canonicalValue(value[key], omitInstanceFields)]));
39
39
  }
40
40
  function portableDefinition(value) {
41
+ const source = isRecord(value) ? value : {};
42
+ const { metadata: sourceMetadata, ...fields } = source;
41
43
  const definition = {
42
- ...canonicalValue(value, true),
44
+ ...canonicalValue(fields, true),
43
45
  // The Database Table write API requires this flag explicitly even though
44
46
  // older/source records may omit it to mean the default value.
45
- isIndex: isRecord(value) && value.isIndex === true,
47
+ isIndex: source.isIndex === true,
46
48
  };
47
- if (!Object.hasOwn(definition, 'metadata')) {
48
- return definition;
49
- }
50
- const metadata = sanitizeUserMetadata(definition.metadata);
49
+ // Column metadata is user JSON: only its top-level backend namespace is
50
+ // reserved. Instance field names inside it carry ordinary business values.
51
+ const metadata = sanitizeUserMetadata(sourceMetadata);
51
52
  if (Object.keys(metadata).length === 0) {
52
- const { metadata: _metadata, ...withoutMetadata } = definition;
53
- return withoutMetadata;
53
+ return definition;
54
54
  }
55
55
  return {
56
56
  ...definition,
@@ -9,11 +9,11 @@ import { readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from ".
9
9
  import { HTTP_REQUEST_CONCURRENCY } from "../request-queue.js";
10
10
  import { mapWithConcurrency, readJsonFile, sanitizeSegment } from "../utils.js";
11
11
  import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
12
+ import { canonicalEndpointOptionDefaults, endpointDefinitionErrors, normalizeEndpointPath } from "./runtime-definition-validation.js";
12
13
  import { findManifestFiles, isRecord, localTargetPath, removeRelocatedManifest, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
13
14
  export const ENDPOINTS_DIRECTORY = 'Endpoints';
14
15
  export const ENDPOINT_MANIFEST_FILE = 'endpoint.json';
15
16
  const ENDPOINT_DEFAULT_TIMEOUT_SECONDS = 60;
16
- const ENDPOINT_DEFAULT_MEMORY_MB = 32;
17
17
  const REMOTE_DETAIL_REQUEST_TIMEOUT_MS = 30_000;
18
18
  const ENDPOINT_PLAN_STATUS_ORDER = [
19
19
  'create', 'restore', 'safe-update', 'remote-changed', 'conflict', 'missing-lock',
@@ -75,10 +75,7 @@ function portableOptions(record) {
75
75
  return Object.keys(options).length > 0 ? canonicalValue(options) : undefined;
76
76
  }
77
77
  function canonicalPortableOptions(options) {
78
- if (options === undefined) {
79
- return undefined;
80
- }
81
- return canonicalValue(options);
78
+ return canonicalValue(canonicalEndpointOptionDefaults(options));
82
79
  }
83
80
  function endpointLabel(record, fallback = 'remote-id') {
84
81
  const category = typeof record.category === 'string' && record.category.trim()
@@ -178,9 +175,15 @@ function validateManifest(manifest, stableKeyName) {
178
175
  if (manifest.schema !== undefined && !hasValidSchemaBinding(manifest.schema)) {
179
176
  return false;
180
177
  }
178
+ if (endpointDefinitionErrors(manifest).length > 0)
179
+ return false;
181
180
  return readConfiguredResourceMetadataStableKey(manifest, stableKeyName) === manifest.stableKey;
182
181
  }
183
182
  export function hashPortableEndpoint(manifest) {
183
+ return endpointDefinitionHash(manifest, true);
184
+ }
185
+ function endpointDefinitionHash(manifest, normalizeDefaults) {
186
+ const options = normalizeDefaults ? canonicalPortableOptions(manifest.options) : canonicalValue(manifest.options);
184
187
  return hashStable({
185
188
  kind: manifest.kind,
186
189
  stableKey: manifest.stableKey,
@@ -190,8 +193,8 @@ export function hashPortableEndpoint(manifest) {
190
193
  metadata: canonicalValue(manifest.metadata),
191
194
  active: manifest.active,
192
195
  timeout: manifest.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS,
193
- route: canonicalValue(manifest.route),
194
- ...(manifest.options === undefined ? {} : { options: canonicalPortableOptions(manifest.options) }),
196
+ route: canonicalValue({ ...manifest.route, path: normalizeEndpointPath(manifest.route.path) }),
197
+ ...(options === undefined ? {} : { options }),
195
198
  ...(manifest.execution === undefined ? {} : { execution: canonicalValue(manifest.execution) }),
196
199
  ...(manifest.executionPolicy === undefined ? {} : { executionPolicy: canonicalValue(manifest.executionPolicy) }),
197
200
  ...(manifest.schema === undefined ? {} : { schema: canonicalValue(manifest.schema) }),
@@ -401,7 +404,8 @@ export async function pullEndpointsToWorkspace(input) {
401
404
  if (existing && !input.force) {
402
405
  const localHash = hashPortableEndpoint(existing.manifest);
403
406
  const baseline = lock.endpoints[manifest.stableKey];
404
- if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash)) {
407
+ if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash
408
+ && endpointDefinitionHash(existing.manifest, false) !== baseline.sourceHash)) {
405
409
  throw new Error(`Cannot pull endpoint "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
406
410
  }
407
411
  }
@@ -517,7 +521,7 @@ function diffEndpoints(desired, current) {
517
521
  ['active', desired.active, current.active],
518
522
  ['timeout', desired.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS, current.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS],
519
523
  ['route.method', desired.route.method, current.route.method],
520
- ['route.path', desired.route.path, current.route.path],
524
+ ['route.path', normalizeEndpointPath(desired.route.path), normalizeEndpointPath(current.route.path)],
521
525
  ['options', canonicalPortableOptions(desired.options) ?? null, canonicalPortableOptions(current.options) ?? null],
522
526
  ['execution', canonicalValue(desired.execution ?? null), canonicalValue(current.execution ?? null)],
523
527
  ...(desired.executionPolicy ? [['executionPolicy', canonicalValue(desired.executionPolicy), canonicalValue(current.executionPolicy ?? null)]] : []),
@@ -731,8 +735,10 @@ export async function buildEndpointsPlan(input) {
731
735
  for (const entry of readWorkspaceEndpoints(input.cwd, input.stableKeyName)) {
732
736
  if (!validateManifest(entry.manifest, input.stableKeyName)) {
733
737
  const relativePath = path.relative(projectRoot, entry.manifestPath);
734
- blockers.push(`Invalid Endpoint manifest "${relativePath}".`);
735
- items.push({ status: 'conflict', name: relativePath, reason: 'invalid portable manifest' });
738
+ const errors = isRecord(entry.manifest) ? endpointDefinitionErrors(entry.manifest) : [];
739
+ const reason = errors.length > 0 ? errors.join('; ') : 'invalid portable manifest';
740
+ blockers.push(`Invalid Endpoint manifest "${relativePath}": ${reason}.`);
741
+ items.push({ status: 'conflict', name: relativePath, reason });
736
742
  continue;
737
743
  }
738
744
  localByStableKey.set(entry.manifest.stableKey, [
@@ -1065,10 +1071,10 @@ export async function buildEndpointsPlan(input) {
1065
1071
  reason: `missing ${input.envName} lock baseline`,
1066
1072
  });
1067
1073
  }
1068
- else if (current.hash === baselineHash) {
1074
+ else if (current.hash === baselineHash || endpointDefinitionHash(current.manifest, false) === baselineHash) {
1069
1075
  items.push({ status: 'safe-update', ...common, changedFields: diffEndpoints(desired, current.manifest), reason: 'local manifest changed; target matches lock baseline' });
1070
1076
  }
1071
- else if (desiredHash === baselineHash) {
1077
+ else if (desiredHash === baselineHash || endpointDefinitionHash(desired, false) === baselineHash) {
1072
1078
  items.push({ status: 'remote-changed', ...common, changedFields: diffEndpoints(desired, current.manifest), reason: 'target changed; local manifest matches lock baseline' });
1073
1079
  }
1074
1080
  else {
@@ -1188,7 +1194,7 @@ async function resolveEndpointWritePayload(input) {
1188
1194
  }
1189
1195
  : { componentId: null, componentDigest: null, componentVersion: null }),
1190
1196
  timeout: input.manifest.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS,
1191
- path: input.manifest.route.path,
1197
+ path: normalizeEndpointPath(input.manifest.route.path),
1192
1198
  method: input.manifest.route.method,
1193
1199
  ...(options === undefined ? {} : { options }),
1194
1200
  };
@@ -4,10 +4,12 @@ import { ownerFromPrincipal, resolveSystemAccount } from "./account-principal.js
4
4
  import { describeFieldChanges, formatDiffValue } from "../diff-details.js";
5
5
  import { hashStable, readComponentLock, writeComponentLock, } from "../component-lock.js";
6
6
  import { readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "../resource-metadata.js";
7
+ import { validateUserMetadata } from "../request-contract.js";
7
8
  import { readJsonFile, sanitizeSegment } from "../utils.js";
8
9
  import { findManifestFiles, isRecord, localTargetPath, mapWithConcurrency, removeRelocatedManifest, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
9
10
  export const GROUPS_DIRECTORY = 'Groups';
10
11
  export const GROUP_MANIFEST_FILE = 'group.json';
12
+ const GROUP_MANIFEST_FIELDS = new Set(['kind', 'stableKey', 'name', 'category', 'description', 'metadata', 'owner']);
11
13
  function groupIdOf(record) {
12
14
  return String(record.groupId || record.id || '');
13
15
  }
@@ -115,6 +117,10 @@ function validateManifest(manifest, stableKeyName) {
115
117
  if (!isRecord(manifest)) {
116
118
  return ['manifest must be a JSON object'];
117
119
  }
120
+ const unsupportedFields = Object.keys(manifest).filter((key) => !GROUP_MANIFEST_FIELDS.has(key)).sort();
121
+ if (unsupportedFields.length > 0) {
122
+ errors.push(`unsupported manifest fields: ${unsupportedFields.join(', ')}`);
123
+ }
118
124
  if (manifest.kind !== 'group'
119
125
  || typeof manifest.stableKey !== 'string'
120
126
  || !manifest.stableKey.trim()
@@ -135,9 +141,8 @@ function validateManifest(manifest, stableKeyName) {
135
141
  || manifest.owner.type === 'service-account' && typeof manifest.owner.stableKey === 'string' && !!manifest.owner.stableKey.trim()))) {
136
142
  errors.push('owner must contain a Service Account stableKey or a System reference');
137
143
  }
138
- if (isRecord(manifest.metadata) && Object.keys(manifest.metadata).some((key) => key.startsWith('__'))) {
139
- errors.push('metadata must not contain backend-reserved keys');
140
- }
144
+ if (isRecord(manifest.metadata))
145
+ errors.push(...validateUserMetadata(manifest.metadata));
141
146
  const metadataStableKey = isRecord(manifest.metadata)
142
147
  ? readConfiguredResourceMetadataStableKey(manifest, stableKeyName)
143
148
  : null;