@revoengine/cli 1.0.29 → 1.0.31

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 +156 -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 +56 -23
  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 +57 -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 +67 -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
@@ -0,0 +1,236 @@
1
+ import { createHash, randomUUID } from 'node:crypto';
2
+ import { setTimeout as wait } from 'node:timers/promises';
3
+ import { nativeTestCollection, nativeTestRunPassed, nativeTestRunPending } from "../native-tests.js";
4
+ import { readNativeTestWorkspace } from "../test-workspace.js";
5
+ import { readBoolFlag, readFlag, readValues } from "../utils.js";
6
+ function integerOption(context, name, fallback, maximum) {
7
+ const raw = readFlag(context.args, [name]);
8
+ if (!raw && context.args[name] !== undefined)
9
+ throw new Error(`--${name} requires a number.`);
10
+ const value = raw ? Number(raw) : fallback;
11
+ if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
12
+ throw new Error(`--${name} must be an integer from 1 to ${maximum}.`);
13
+ }
14
+ return value;
15
+ }
16
+ async function remoteCatalog(context) {
17
+ const data = [];
18
+ const search = readFlag(context.args, ['search']);
19
+ let skip = 0;
20
+ while (true) {
21
+ const page = await context.client.listNativeTests({ take: 50, skip, ...(search ? { search } : {}) });
22
+ if (!page || !Array.isArray(page.data) || typeof page.next !== 'boolean') {
23
+ throw new Error('Native test catalog returned an invalid page.');
24
+ }
25
+ data.push(...page.data);
26
+ if (!page.next)
27
+ return data;
28
+ if (!page.data.length)
29
+ throw new Error('Native test catalog pagination made no progress.');
30
+ skip += page.data.length;
31
+ if (skip > 10_000)
32
+ throw new Error('Native test catalog exceeds 10,000 suites; narrow --search.');
33
+ }
34
+ }
35
+ function renderResult(context, run) {
36
+ if (readBoolFlag(context.args, ['json'])) {
37
+ context.print(run);
38
+ return;
39
+ }
40
+ context.println(`Native tests: ${run.status} · run ${run.runId}`);
41
+ for (const suite of run.runs) {
42
+ const marker = suite.status === 'PASSED' ? '✓' : ['QUEUED', 'RUNNING'].includes(suite.status) ? '…' : '✗';
43
+ context.println(`${marker} ${suite.testComponentName} · ${suite.status} · ${suite.cases?.length || 0} cases · ${suite.assertions?.length || 0} assertions${suite.durationMs === undefined ? '' : ` · ${suite.durationMs} ms`}`);
44
+ for (const item of suite.cases || []) {
45
+ context.println(` ${item.status === 'PASSED' ? '✓' : '✗'} ${item.name || 'Unnamed case'}`);
46
+ }
47
+ if (suite.error)
48
+ context.println(` ${typeof suite.error === 'string' ? suite.error : JSON.stringify(suite.error)}`);
49
+ }
50
+ }
51
+ class RunCollectionError extends Error {
52
+ run;
53
+ constructor(cause, run) {
54
+ super(cause instanceof Error ? cause.message : String(cause), { cause });
55
+ this.run = run;
56
+ }
57
+ }
58
+ function noWait(context) {
59
+ return context.args.wait === false || readBoolFlag(context.args, ['no-wait']);
60
+ }
61
+ async function collectRun(context, initial, deadline = Date.now() + integerOption(context, 'wait-timeout', 600, 3600) * 1000) {
62
+ let run = initial;
63
+ if (!noWait(context)) {
64
+ try {
65
+ while (nativeTestRunPending(run) && Date.now() < deadline) {
66
+ if (!run.runs.some(suite => suite.status === 'RUNNING') && run.runs.some(suite => suite.status === 'QUEUED')) {
67
+ run = await context.client.executeNativeTestRun(run.runId);
68
+ }
69
+ else {
70
+ await wait(Math.min(1000, Math.max(1, deadline - Date.now())));
71
+ run = await context.client.getNativeTestRun(run.runId);
72
+ }
73
+ }
74
+ }
75
+ catch (error) {
76
+ throw new RunCollectionError(error, run);
77
+ }
78
+ }
79
+ return run;
80
+ }
81
+ function setResultExitCode(context, run) {
82
+ if (nativeTestRunPending(run)) {
83
+ if (!noWait(context)) {
84
+ process.exitCode = 1;
85
+ context.warn?.(`Run remains ${run.status}. Resume with revo tests resume ${run.runId}.`);
86
+ }
87
+ }
88
+ else if (!nativeTestRunPassed(run))
89
+ process.exitCode = 1;
90
+ }
91
+ async function finishRun(context, initial) {
92
+ let run;
93
+ try {
94
+ run = await collectRun(context, initial);
95
+ }
96
+ catch (error) {
97
+ if (error instanceof RunCollectionError) {
98
+ renderResult(context, error.run);
99
+ context.warn?.(`Result collection stopped. Resume with revo tests resume ${error.run.runId}.`);
100
+ }
101
+ throw error;
102
+ }
103
+ renderResult(context, run);
104
+ setResultExitCode(context, run);
105
+ }
106
+ function batchOperationId(operationId, index) {
107
+ if (index === 0)
108
+ return operationId;
109
+ const bytes = createHash('sha256').update(`revo-native-test-batch-v1:${operationId}:${index}`).digest().subarray(0, 16);
110
+ bytes[6] = (bytes[6] & 0x0f) | 0x50;
111
+ bytes[8] = (bytes[8] & 0x3f) | 0x80;
112
+ const value = bytes.toString('hex');
113
+ return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
114
+ }
115
+ /** Native execution captures portable source; it never saves Components or creates an approval. */
116
+ export async function handleTestsCommand(context) {
117
+ for (const name of ['workspace', 'search', 'operation-id', 'suite']) {
118
+ if (context.args[name] !== undefined && !readFlag(context.args, [name]))
119
+ throw new Error(`--${name} requires a value.`);
120
+ }
121
+ const action = context.args._[1] || 'list';
122
+ const remote = readBoolFlag(context.args, ['remote']);
123
+ const workspace = readFlag(context.args, ['workspace']);
124
+ if (remote && workspace)
125
+ throw new Error('Choose --remote or a local --workspace.');
126
+ if (action === 'resume' || action === 'cancel') {
127
+ const runId = context.args._[2];
128
+ if (!runId || context.args._.length > 3)
129
+ throw new Error(`tests ${action} requires one run ID.`);
130
+ if (action === 'cancel') {
131
+ renderResult(context, await context.client.cancelNativeTestRun(runId));
132
+ return;
133
+ }
134
+ await finishRun(context, await context.client.getNativeTestRun(runId));
135
+ return;
136
+ }
137
+ if (action !== 'list' && action !== 'run')
138
+ throw new Error(`Unknown tests action: ${action}. Use list, run, resume or cancel.`);
139
+ const local = remote ? undefined : await readNativeTestWorkspace(context.cwd, workspace || undefined, { includeSource: action === 'run' });
140
+ const search = readFlag(context.args, ['search']).toLowerCase();
141
+ const catalog = local ? local.tests.filter(test => !search || test.name.toLowerCase().includes(search)) : await remoteCatalog(context);
142
+ if (action === 'list') {
143
+ if (context.args._.length > 2)
144
+ throw new Error('tests list does not accept suite names; use --search.');
145
+ const result = { source: remote ? 'stored' : 'worktree', ...(local ? { workspaceRoot: local.workspaceRoot } : {}), tests: catalog };
146
+ if (readBoolFlag(context.args, ['json']))
147
+ context.print(result);
148
+ else {
149
+ context.println(`${catalog.length} native test suites · ${remote ? 'stored Components' : local.workspaceRoot}`);
150
+ for (const suite of catalog) {
151
+ const config = 'testConfig' in suite ? suite.testConfig : suite;
152
+ context.println(`${suite.name} · ${config?.mode || 'unconfigured'}${suite.category ? ` · ${suite.category}` : ''}${config?.targets?.length ? ` · targets: ${config.targets.join(', ')}` : ''}`);
153
+ }
154
+ }
155
+ return;
156
+ }
157
+ const all = readBoolFlag(context.args, ['all']);
158
+ const selected = [...new Set([...context.args._.slice(2), ...readValues(context.args, ['suite'])])];
159
+ if (all && selected.length)
160
+ throw new Error('Choose suite names or --all.');
161
+ if (!all && !selected.length)
162
+ throw new Error('tests run requires suite names or --all.');
163
+ const suiteNames = all ? [...new Set(catalog.filter(suite => ('testConfig' in suite ? suite.testConfig?.mode : suite.mode) === 'fixture').map(suite => suite.name))] : selected;
164
+ if (!suiteNames.length)
165
+ throw new Error('No fixture test suites found in the selected workspace.');
166
+ const batchCount = Math.ceil(suiteNames.length / 20);
167
+ if (batchCount > (noWait(context) ? 10 : 100))
168
+ throw new Error(`This collection exceeds ${noWait(context) ? '10 queued' : '100 sequential'} batches. Select fewer suites or narrow --search.`);
169
+ for (const name of suiteNames) {
170
+ const suite = catalog.find(item => item.name === name);
171
+ if (!suite)
172
+ throw new Error(`Native test suite not found: ${name}.`);
173
+ const mode = 'testConfig' in suite ? suite.testConfig?.mode : suite.mode;
174
+ if (mode === 'integration') {
175
+ throw new Error(`Integration suite ${name} requires an approved Studio candidate. Standalone runs support fixtures.`);
176
+ }
177
+ if (mode !== 'fixture')
178
+ throw new Error(`Native test suite ${name} requires fixture testConfig.`);
179
+ }
180
+ const operationId = readFlag(context.args, ['operation-id']) || randomUUID();
181
+ if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(operationId))
182
+ throw new Error('--operation-id must be a UUID.');
183
+ const timeout = integerOption(context, 'timeout', 10, 60);
184
+ // Validate the client wait budget before creating a durable remote run.
185
+ integerOption(context, 'wait-timeout', 600, 3600);
186
+ const input = { ...(local ? { components: local.components } : {}), timeout };
187
+ if (batchCount === 1) {
188
+ const run = await context.client.createNativeTestRun({ operationId, testComponentNames: suiteNames, ...input });
189
+ if (!readBoolFlag(context.args, ['json']))
190
+ context.println(`Created native test run ${run.runId}.`);
191
+ await finishRun(context, run);
192
+ return;
193
+ }
194
+ const executions = [];
195
+ const deadline = Date.now() + integerOption(context, 'wait-timeout', 600, 3600) * 1000;
196
+ let failure;
197
+ for (let index = 0; index < batchCount; index++) {
198
+ try {
199
+ const captured = await context.client.createNativeTestRun({
200
+ operationId: batchOperationId(operationId, index), testComponentNames: suiteNames.slice(index * 20, (index + 1) * 20), ...input,
201
+ });
202
+ executions.push(captured);
203
+ if (!readBoolFlag(context.args, ['json']))
204
+ context.println(`Created native test run ${captured.runId} · batch ${index + 1}/${batchCount}.`);
205
+ try {
206
+ executions[index] = await collectRun(context, captured, deadline);
207
+ }
208
+ catch (error) {
209
+ if (error instanceof RunCollectionError)
210
+ executions[index] = error.run;
211
+ throw error;
212
+ }
213
+ setResultExitCode(context, executions[index]);
214
+ // Do not fill the host's pending quota when collection has timed out.
215
+ if (!noWait(context) && nativeTestRunPending(executions[index]))
216
+ break;
217
+ }
218
+ catch (error) {
219
+ failure = error;
220
+ break;
221
+ }
222
+ }
223
+ const result = nativeTestCollection(executions, Boolean(failure) || executions.length < batchCount);
224
+ if (readBoolFlag(context.args, ['json']))
225
+ context.print(result);
226
+ else {
227
+ context.println(`Native test collection: ${result.status} · ${executions.length}/${batchCount} runs`);
228
+ for (const run of executions)
229
+ renderResult(context, run);
230
+ }
231
+ if (failure) {
232
+ process.exitCode = 1;
233
+ context.warn?.(`Collection stopped. Retained runs: ${result.runIds.join(', ') || 'none'}. Retry the same selection with --operation-id ${operationId}.`);
234
+ throw failure;
235
+ }
236
+ }
@@ -0,0 +1,8 @@
1
+ import type { ComponentRecord } from './types.ts';
2
+ /** Validate raw authoring fields before hashing or payload normalization can hide malformed values.
3
+ * Local ids, derived compilation state and unwritten element metadata are outside the wire projection.
4
+ * Source compilation and JSON-schema analysis remain owned by the backend.
5
+ */
6
+ export declare function componentElementValidationErrors(component: ComponentRecord, options?: {
7
+ mode?: 'create' | 'save';
8
+ }): string[];
@@ -0,0 +1,79 @@
1
+ import { normalizeCustomNodeElementPath, requestContractDefaults } from "./automation-contract.generated.js";
2
+ import { requestContracts, validateRequestContract } from "./request-contract.js";
3
+ const policy = requestContractDefaults.componentElements;
4
+ const lowCodeTypes = new Set(policy.lowCodeTypes);
5
+ const libraryTypes = new Set(policy.libraryTypes);
6
+ const reservedKeys = new Set(policy.reservedKeys);
7
+ const identifier = new RegExp(policy.identifierPattern.pattern, policy.identifierPattern.patternFlags);
8
+ const nativeTestTypes = new Set(policy.nativeTestPolicy.types);
9
+ const nativeTestReservedKeys = new Set(policy.nativeTestPolicy.reservedKeys);
10
+ const nativeTestIdentifier = new RegExp(policy.nativeTestPolicy.identifierPattern.pattern, policy.nativeTestPolicy.identifierPattern.patternFlags);
11
+ const fields = Object.keys(requestContracts.ComponentElementsDto.properties || {})
12
+ .filter(field => field !== 'componentElementId' && field !== 'metadata');
13
+ /** Validate raw authoring fields before hashing or payload normalization can hide malformed values.
14
+ * Local ids, derived compilation state and unwritten element metadata are outside the wire projection.
15
+ * Source compilation and JSON-schema analysis remain owned by the backend.
16
+ */
17
+ export function componentElementValidationErrors(component, options = {}) {
18
+ const elements = component.elements;
19
+ if ((elements === undefined || elements === null || Array.isArray(elements) && elements.length === 0) && options.mode === 'create')
20
+ return [];
21
+ if (!Array.isArray(elements) || elements.length === 0)
22
+ return ['Component elements must be a nonempty array for save.'];
23
+ const type = component.type;
24
+ const errors = [];
25
+ const keys = new Set();
26
+ const orders = new Set();
27
+ const paths = new Set();
28
+ let detailsBytes = 0;
29
+ elements.forEach((value, index) => {
30
+ const label = `Component elements[${index}]`;
31
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
32
+ errors.push(`${label} must be a JSON object.`);
33
+ return;
34
+ }
35
+ const element = value;
36
+ const payload = Object.fromEntries(fields.filter(field => Object.hasOwn(element, field)).map(field => [field, element[field]]));
37
+ errors.push(...validateRequestContract('ComponentElementsDto', payload, { path: label }));
38
+ if (typeof element.details === 'string')
39
+ detailsBytes += Buffer.byteLength(element.details, 'utf8');
40
+ if (type && lowCodeTypes.has(type)) {
41
+ if (typeof element.key === 'string') {
42
+ const applicableReservedKeys = nativeTestTypes.has(type) ? nativeTestReservedKeys : reservedKeys;
43
+ const applicableIdentifier = nativeTestTypes.has(type) ? nativeTestIdentifier : identifier;
44
+ if (applicableReservedKeys.has(element.key))
45
+ errors.push(`${label}.key is reserved by the backend.`);
46
+ if (!(libraryTypes.has(type) && element.key === policy.defaultLibraryKey) && !applicableIdentifier.test(element.key)) {
47
+ errors.push(`${label}.key must be a JavaScript identifier.`);
48
+ }
49
+ if (keys.has(element.key))
50
+ errors.push(`${label} has a duplicate key "${element.key}".`);
51
+ keys.add(element.key);
52
+ }
53
+ if (typeof element.order === 'number' && Number.isInteger(element.order)) {
54
+ if (orders.has(element.order))
55
+ errors.push(`${label} has a duplicate order ${element.order}.`);
56
+ orders.add(element.order);
57
+ }
58
+ }
59
+ else if (type === 'CUSTOM_NODEJS') {
60
+ const normalized = normalizeCustomNodeElementPath(element.key);
61
+ if (!normalized)
62
+ errors.push(`${label} has an unsafe Custom Node file path.`);
63
+ else {
64
+ if (paths.has(normalized))
65
+ errors.push(`${label} has a duplicate Custom Node file path "${normalized}".`);
66
+ paths.add(normalized);
67
+ }
68
+ }
69
+ });
70
+ if (type === 'CUSTOM_NODEJS') {
71
+ for (const file of policy.customRequiredFiles) {
72
+ if (!paths.has(file))
73
+ errors.push(`Component elements are missing the required Custom Node file "${file}".`);
74
+ }
75
+ }
76
+ if (detailsBytes > policy.maxDetailsBytes)
77
+ errors.push(`Component elements source exceeds the backend save limit of ${policy.maxDetailsBytes} UTF-8 bytes.`);
78
+ return errors;
79
+ }
@@ -0,0 +1,3 @@
1
+ import type { RevoClient } from './client.ts';
2
+ /** Lifecycle writes use an exact-version review instead of unsupported PUT fields. */
3
+ export declare function changeComponentActivation(client: RevoClient, componentId: string, active: boolean, expectedVersion: number | null): Promise<number>;
@@ -0,0 +1,17 @@
1
+ /** Lifecycle writes use an exact-version review instead of unsupported PUT fields. */
2
+ export async function changeComponentActivation(client, componentId, active, expectedVersion) {
3
+ if (!Number.isSafeInteger(expectedVersion))
4
+ throw new Error('Component activation requires an observed integer version.');
5
+ const action = active ? 'activate' : 'disable';
6
+ const response = await client.reviewComponentLifecycle(componentId, action);
7
+ const outer = response;
8
+ const review = outer?.data && typeof outer.data === 'object' ? outer.data : outer;
9
+ const target = review?.target;
10
+ if (review?.kind !== 'mutation_review' || review.schemaVersion !== 1 || review.baseVersion !== expectedVersion
11
+ || review.operationId !== `ComponentController_${action}` || target?.refType !== 'COMPONENTS' || target.refId !== componentId
12
+ || typeof review.token !== 'string' || !review.token) {
13
+ throw new Error('Component activation review does not match the observed target/version; run plan again.');
14
+ }
15
+ await client.setComponentActive(componentId, active, review.token);
16
+ return expectedVersion + 1;
17
+ }
@@ -136,6 +136,14 @@ export type RevoLockFile = {
136
136
  export declare function hashStable(value: unknown): string;
137
137
  export declare function sanitizeComponentSource<T extends ComponentRecord>(component: T): T;
138
138
  export declare function normalizeComponentSource(component: ComponentRecord): {
139
+ elements: {
140
+ key: string;
141
+ desc: string | null;
142
+ hidden: boolean;
143
+ order: number;
144
+ details: string;
145
+ }[];
146
+ testConfig?: Record<string, unknown> | undefined;
139
147
  componentId: string;
140
148
  name: string;
141
149
  category: string | null;
@@ -144,6 +152,9 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
144
152
  type: string;
145
153
  async: boolean;
146
154
  metadata: Record<string, unknown>;
155
+ };
156
+ export declare function hashComponentSource(component: ComponentRecord): string;
157
+ export declare function normalizePortableComponentSource(component: ComponentRecord): {
147
158
  elements: {
148
159
  key: string;
149
160
  desc: string | null;
@@ -151,9 +162,7 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
151
162
  order: number;
152
163
  details: string;
153
164
  }[];
154
- };
155
- export declare function hashComponentSource(component: ComponentRecord): string;
156
- export declare function normalizePortableComponentSource(component: ComponentRecord): {
165
+ testConfig?: Record<string, unknown> | undefined;
157
166
  name: string;
158
167
  category: string | null;
159
168
  desc: string | null;
@@ -161,23 +170,19 @@ export declare function normalizePortableComponentSource(component: ComponentRec
161
170
  type: string;
162
171
  async: boolean;
163
172
  metadata: Record<string, unknown>;
164
- elements: {
165
- key: string;
166
- desc: string | null;
167
- hidden: boolean;
168
- order: number;
169
- details: string;
170
- }[];
171
173
  };
172
174
  export declare function hashPortableComponentSource(component: ComponentRecord): string;
173
- export declare const PORTABLE_COMPONENT_CONFIG_FIELDS: readonly ["name", "category", "desc", "active", "type", "async", "metadata"];
175
+ export declare const PORTABLE_COMPONENT_CONFIG_FIELDS: readonly ["name", "category", "desc", "active", "type", "metadata", "testConfig"];
174
176
  export type PortableComponentConfigField = (typeof PORTABLE_COMPONENT_CONFIG_FIELDS)[number];
177
+ export declare function componentActivationValidationError(source: ComponentRecord): "Component active must be a boolean." | null;
178
+ export declare function componentTypeTransitionReason(desired: string, current: string): string | null;
175
179
  export declare function diffPortableComponentSource(source: ComponentRecord, target: ComponentRecord): {
176
- configurationFields: ("metadata" | "desc" | "name" | "category" | "type" | "active" | "async")[];
180
+ configurationFields: ("name" | "type" | "metadata" | "desc" | "category" | "active" | "testConfig")[];
177
181
  elementsChanged: boolean;
178
182
  changedFields: string[];
179
183
  };
180
184
  export declare function buildPortableComponentUpdatePayload(source: ComponentRecord, target: ComponentRecord, changedFields: ReadonlyArray<string>): Record<string, unknown>;
185
+ export declare function componentUpdateValidationError(source: ComponentRecord, target: ComponentRecord): string | null;
181
186
  export declare function getLockPath(projectRoot: string): string;
182
187
  export declare function readComponentLock(projectRoot: string): RevoLockFile;
183
188
  export declare function writeComponentLock(projectRoot: string, lock: RevoLockFile): void;
@@ -4,6 +4,8 @@ import path from 'node:path';
4
4
  import { REVO_PROJECT_DIR } from "./project.js";
5
5
  import { COMPONENT_IDENTITY_BY_ID, normalizeComponentIdentityConfig, readComponentIdentityValue, sameComponentIdentityConfig, sanitizeUserMetadata, } from "./resource-metadata.js";
6
6
  import { readJsonFile, writeJsonFile } from "./utils.js";
7
+ import { requestContracts, validateRequestContract } from "./request-contract.js";
8
+ import { componentSourceConfigurationErrors } from "./component-source-validation.js";
7
9
  export const REVO_LOCK_FILE = path.join(REVO_PROJECT_DIR, 'revo.lock.json');
8
10
  const VOLATILE_COMPONENT_FIELDS = new Set([
9
11
  'version',
@@ -54,7 +56,7 @@ function stableObject(value) {
54
56
  if (!value || typeof value !== 'object') {
55
57
  return value;
56
58
  }
57
- const output = {};
59
+ const output = Object.create(null);
58
60
  for (const key of Object.keys(value).sort()) {
59
61
  output[key] = stableObject(value[key]);
60
62
  }
@@ -83,8 +85,11 @@ export function normalizeComponentSource(component) {
83
85
  desc: normalizeValue(source.desc),
84
86
  active: source.active ?? true,
85
87
  type: source.type || '',
86
- async: Boolean(source.async),
88
+ // Creation transport policy is not persisted. Keep the historical default hash shape.
89
+ async: false,
87
90
  metadata: sanitizeUserMetadata(source.metadata),
91
+ // Empty config is equivalent to omission; keep existing ordinary baselines.
92
+ ...(source.testConfig != null ? { testConfig: source.testConfig } : {}),
88
93
  elements: [...(source.elements || [])]
89
94
  .map((element) => ({
90
95
  key: typeof element.key === 'string' ? element.key : '',
@@ -115,13 +120,23 @@ export const PORTABLE_COMPONENT_CONFIG_FIELDS = [
115
120
  'desc',
116
121
  'active',
117
122
  'type',
118
- 'async',
119
123
  'metadata',
124
+ 'testConfig',
120
125
  ];
126
+ const COMPONENT_UPDATE_FIELDS = new Set(Object.keys(requestContracts.UpdateComponentDto.properties || {}).filter(field => field !== 'version'));
127
+ export function componentActivationValidationError(source) {
128
+ return source.active !== undefined && typeof source.active !== 'boolean' ? 'Component active must be a boolean.' : null;
129
+ }
130
+ export function componentTypeTransitionReason(desired, current) {
131
+ const desiredType = desired.trim().toUpperCase();
132
+ const currentType = current.trim().toUpperCase();
133
+ return desiredType === currentType ? null
134
+ : `The target API cannot change Component type from ${currentType} to ${desiredType}; resolve this transition manually before syncing.`;
135
+ }
121
136
  export function diffPortableComponentSource(source, target) {
122
137
  const sourcePortable = normalizePortableComponentSource(source);
123
138
  const targetPortable = normalizePortableComponentSource(target);
124
- const configurationFields = PORTABLE_COMPONENT_CONFIG_FIELDS.filter((field) => hashStable(sourcePortable[field]) !== hashStable(targetPortable[field]));
139
+ const configurationFields = PORTABLE_COMPONENT_CONFIG_FIELDS.filter((field) => hashStable(sourcePortable[field] ?? null) !== hashStable(targetPortable[field] ?? null));
125
140
  const elementsChanged = hashStable(sourcePortable.elements) !== hashStable(targetPortable.elements);
126
141
  return {
127
142
  configurationFields,
@@ -136,15 +151,51 @@ export function buildPortableComponentUpdatePayload(source, target, changedField
136
151
  if (!Number.isInteger(target.version)) {
137
152
  throw new Error('target component version is required to update component configuration');
138
153
  }
154
+ const configurationErrors = componentSourceConfigurationErrors(source);
155
+ if (configurationErrors.length)
156
+ throw new Error(configurationErrors.join('; '));
139
157
  const sourcePortable = normalizePortableComponentSource(source);
158
+ const activationError = componentActivationValidationError(source);
159
+ if (activationError)
160
+ throw new Error(activationError);
161
+ const transition = componentTypeTransitionReason(sourcePortable.type, normalizePortableComponentSource(target).type);
162
+ if (transition)
163
+ throw new Error(transition);
140
164
  const payload = { version: target.version };
141
165
  for (const field of PORTABLE_COMPONENT_CONFIG_FIELDS) {
142
- if (changedFields.includes(field)) {
143
- payload[field] = sourcePortable[field];
166
+ if (COMPONENT_UPDATE_FIELDS.has(field) && changedFields.includes(field)) {
167
+ payload[field] = field === 'testConfig' ? sourcePortable.testConfig ?? null : sourcePortable[field];
144
168
  }
145
169
  }
170
+ const errors = validateRequestContract('UpdateComponentDto', payload);
171
+ if (errors.length)
172
+ throw new Error(`Invalid Component update: ${errors.join('; ')}`);
146
173
  return payload;
147
174
  }
175
+ export function componentUpdateValidationError(source, target) {
176
+ const targetType = String(target.type || '').toUpperCase();
177
+ if (['CODE_JS_LIB', 'CODE_TS_LIB'].includes(targetType)
178
+ && target.elements?.some(element => element.key === '@default')
179
+ && !source.elements?.some(element => element.key === '@default')) {
180
+ return 'The target library has a permanent @default element that is missing from the local source. Pull and reconcile the migrated library, including its explicit exports, before deploying; @default cannot be deleted.';
181
+ }
182
+ const configurationErrors = componentSourceConfigurationErrors(source);
183
+ if (configurationErrors.length)
184
+ return configurationErrors.join('; ');
185
+ const activationError = componentActivationValidationError(source);
186
+ if (activationError)
187
+ return activationError;
188
+ const diff = diffPortableComponentSource(source, target);
189
+ if (diff.configurationFields.length === 0)
190
+ return null;
191
+ try {
192
+ buildPortableComponentUpdatePayload(source, target, diff.configurationFields);
193
+ return null;
194
+ }
195
+ catch (error) {
196
+ return error instanceof Error ? error.message : String(error);
197
+ }
198
+ }
148
199
  export function getLockPath(projectRoot) {
149
200
  return path.join(projectRoot, REVO_LOCK_FILE);
150
201
  }
@@ -19,6 +19,9 @@ export async function listComponentManifests(client) {
19
19
  export function hydrateComponentManifest(summary, local) {
20
20
  if (!local || !Array.isArray(summary.elements) || !isComponentDigest(summary.metadata?.__digest))
21
21
  return null;
22
+ if ((summary.type === 'CODE_JS_TEST' || summary.type === 'CODE_TS_TEST')
23
+ && !Object.prototype.hasOwnProperty.call(summary, 'testConfig'))
24
+ return null;
22
25
  if (summary.elements.length !== (local.elements || []).length)
23
26
  return null;
24
27
  const byKey = new Map((local.elements || []).map(element => [element.key, element]));
@@ -0,0 +1,5 @@
1
+ import type { ComponentRecord } from './types.ts';
2
+ /** Validate raw source configuration before normalization or lifecycle writes.
3
+ * Fixtures remain arbitrary input data; omitted/null configurations retain backend clearing semantics.
4
+ */
5
+ export declare function componentSourceConfigurationErrors(component: ComponentRecord): string[];
@@ -0,0 +1,27 @@
1
+ import { requestContractDefaults } from "./automation-contract.generated.js";
2
+ import { validateRequestContract } from "./request-contract.js";
3
+ const policy = requestContractDefaults.componentTestConfig;
4
+ const nativeTestTypes = new Set(policy.nativeTestTypes);
5
+ /** Validate raw source configuration before normalization or lifecycle writes.
6
+ * Fixtures remain arbitrary input data; omitted/null configurations retain backend clearing semantics.
7
+ */
8
+ export function componentSourceConfigurationErrors(component) {
9
+ const config = component.testConfig;
10
+ if (config === undefined || config === null)
11
+ return [];
12
+ const errors = validateRequestContract('ComponentTestConfigDto', config, { path: 'Component testConfig' });
13
+ const type = String(component.type || 'CODE_JS').trim().toUpperCase();
14
+ if (!nativeTestTypes.has(type))
15
+ errors.push('Component testConfig is only accepted on native test Components.');
16
+ try {
17
+ const serialized = JSON.stringify(config);
18
+ if (serialized === undefined)
19
+ errors.push('Component testConfig must be serializable JSON.');
20
+ else if (Buffer.byteLength(serialized, 'utf8') > policy.maxBytes)
21
+ errors.push(`Component testConfig exceeds the backend limit of ${policy.maxBytes} UTF-8 JSON bytes.`);
22
+ }
23
+ catch {
24
+ errors.push('Component testConfig must be serializable JSON.');
25
+ }
26
+ return errors;
27
+ }