@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
@@ -6,10 +6,11 @@ import { describeFieldChanges } from "../diff-details.js";
6
6
  import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
7
7
  import { normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
8
8
  import { readJsonFile, sanitizeSegment } from "../utils.js";
9
+ import { canonicalJobRuntimeOptionDefaults, jobTemplateDefinitionErrors } from "./runtime-definition-validation.js";
10
+ import { requestContractDefaults } from "../request-contract.js";
9
11
  import { findManifestFiles, isRecord, localTargetPath, mapWithConcurrency, removeRelocatedManifest, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
10
12
  export const JOB_TEMPLATES_DIRECTORY = 'JobTemplates';
11
13
  export const JOB_TEMPLATE_MANIFEST_FILE = 'job-template.json';
12
- const DEFAULT_JOB_TEMPLATE_MEMORY_MB = 256;
13
14
  function canonicalValue(value) {
14
15
  if (Array.isArray(value))
15
16
  return value.map((item) => canonicalValue(item));
@@ -26,15 +27,13 @@ function canonicalJobTemplateInputs(value) {
26
27
  return {};
27
28
  return canonicalValue(value);
28
29
  }
29
- function canonicalJobTemplateOptions(value, inputs) {
30
+ function canonicalJobTemplateOptions(value, inputs, normalizeDefaults = true) {
30
31
  const canonical = canonicalValue(value);
31
32
  if (!isRecord(canonical))
32
- return canonical;
33
- const normalized = { ...canonical };
34
- // The Automation API materializes these defaults after create even when the
35
- // source omitted them. They are semantically equivalent in portable state.
36
- if (normalized.memory === DEFAULT_JOB_TEMPLATE_MEMORY_MB)
37
- delete normalized.memory;
33
+ return normalizeDefaults && canonical === null ? undefined : canonical;
34
+ const normalized = normalizeDefaults ? canonicalJobRuntimeOptionDefaults(canonical) : { ...canonical };
35
+ // Historical hashes that stripped explicit memory cannot prove the same live
36
+ // definition: missing memory follows input overlays, then the isolate default.
38
37
  const canonicalInputs = canonicalJobTemplateInputs(inputs);
39
38
  const inputIsEmpty = isRecord(normalized.input) && Object.keys(normalized.input).length === 0;
40
39
  const inputDuplicatesLegacyInputs = inputs !== undefined
@@ -109,9 +108,6 @@ function isOptionalString(value, { nullable = false } = {}) {
109
108
  function isOptionalRecord(value, { nullable = false } = {}) {
110
109
  return value === undefined || (nullable && value === null) || isRecord(value);
111
110
  }
112
- function isOptionalFiniteNumber(value) {
113
- return value === undefined || (typeof value === 'number' && Number.isFinite(value));
114
- }
115
111
  function hasValidJobTemplateComponent(value) {
116
112
  return isRecord(value)
117
113
  && hasOnlyKeys(value, new Set(['stableKey', 'pinnedDigest']))
@@ -143,9 +139,8 @@ function validateManifest(manifest, stableKeyName) {
143
139
  if (!isOptionalString(manifest.description)) {
144
140
  return false;
145
141
  }
146
- if (!isOptionalFiniteNumber(manifest.timeout)) {
142
+ if (manifest.timeout !== undefined && (typeof manifest.timeout !== 'number' || !Number.isFinite(manifest.timeout)))
147
143
  return false;
148
- }
149
144
  if (!isOptionalRecord(manifest.options, { nullable: true })) {
150
145
  return false;
151
146
  }
@@ -161,6 +156,8 @@ function validateManifest(manifest, stableKeyName) {
161
156
  if (!hasValidJobTemplateMigration(manifest.migration)) {
162
157
  return false;
163
158
  }
159
+ if (jobTemplateDefinitionErrors(manifest).length > 0)
160
+ return false;
164
161
  return readConfiguredResourceMetadataStableKey(manifest, stableKeyName) === manifest.stableKey;
165
162
  }
166
163
  async function componentStableKey(input) {
@@ -174,7 +171,7 @@ async function componentStableKey(input) {
174
171
  return readConfiguredResourceMetadataStableKey(component || {}, input.stableKeyName);
175
172
  }
176
173
  function manifestFromRecord(record, stableKey, componentKey, stableKeyName) {
177
- return {
174
+ const manifest = {
178
175
  kind: 'job-template',
179
176
  stableKey,
180
177
  name: String(record.name || ''),
@@ -186,6 +183,10 @@ function manifestFromRecord(record, stableKey, componentKey, stableKeyName) {
186
183
  ...(record.options === undefined ? {} : { options: canonicalValue(record.options) }),
187
184
  ...(record.inputs === undefined ? {} : { inputs: canonicalValue(record.inputs) }),
188
185
  };
186
+ const errors = jobTemplateDefinitionErrors(manifest);
187
+ if (errors.length > 0)
188
+ throw new Error(`Job template "${stableKey}" has invalid backend definition: ${errors.join('; ')}.`);
189
+ return manifest;
189
190
  }
190
191
  async function withRecordPrincipal(client, record, manifest, stableKeyName, compare, preferLegacy = false) {
191
192
  if (!compare) {
@@ -211,6 +212,11 @@ async function targetPrincipalId(client, manifest, stableKeyName, target) {
211
212
  ...(target?.executionPolicy && target.executionPolicy.mode !== 'INHERIT' ? { executionPolicy: { mode: 'INHERIT' } } : {}) };
212
213
  }
213
214
  function buildCreatePayload(manifest, componentId) {
215
+ const hasLegacyInput = isRecord(manifest.inputs) && Object.keys(manifest.inputs).length > 0;
216
+ // An absent/null options envelope is expanded before the backend legacy alias
217
+ // is applied. Make that alias explicit so the requested template input survives creation.
218
+ const options = manifest.options == null && hasLegacyInput
219
+ ? { input: canonicalValue(manifest.inputs) } : canonicalValue(manifest.options);
214
220
  return {
215
221
  name: manifest.name,
216
222
  ...(manifest.category === undefined ? {} : { category: manifest.category }),
@@ -219,7 +225,7 @@ function buildCreatePayload(manifest, componentId) {
219
225
  componentId,
220
226
  ...(manifest.component.pinnedDigest ? { componentDigest: manifest.component.pinnedDigest } : {}),
221
227
  ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
222
- ...(manifest.options === undefined ? {} : { options: canonicalValue(manifest.options) }),
228
+ ...(options === undefined ? {} : { options }),
223
229
  ...(manifest.inputs === undefined ? {} : { inputs: canonicalValue(manifest.inputs) }),
224
230
  };
225
231
  }
@@ -233,13 +239,18 @@ function buildUpdatePayload(manifest, componentId, version) {
233
239
  componentDigest: manifest.component.pinnedDigest ?? null,
234
240
  componentVersion: null,
235
241
  ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
236
- ...(manifest.options === undefined ? {} : { options: canonicalValue(manifest.options) }),
242
+ options: isRecord(manifest.options) ? canonicalValue(manifest.options) : {},
237
243
  ...(manifest.inputs === undefined ? {} : { inputs: canonicalValue(manifest.inputs) }),
238
244
  version,
239
245
  };
240
246
  }
241
247
  export function hashPortableJobTemplate(manifest) {
242
- const options = canonicalJobTemplateOptions(manifest.options, manifest.inputs);
248
+ return jobTemplateDefinitionHash(manifest, true);
249
+ }
250
+ function jobTemplateDefinitionHash(manifest, normalizeDefaults) {
251
+ const options = canonicalJobTemplateOptions(manifest.options, manifest.inputs, normalizeDefaults);
252
+ const rawInputs = canonicalJobTemplateInputs(manifest.inputs);
253
+ const inputs = normalizeDefaults && isRecord(rawInputs) && Object.keys(rawInputs).length === 0 ? undefined : rawInputs;
243
254
  return hashStable({
244
255
  kind: 'job-template',
245
256
  stableKey: manifest.stableKey,
@@ -250,9 +261,10 @@ export function hashPortableJobTemplate(manifest) {
250
261
  component: { ...manifest.component },
251
262
  ...(manifest.executionPrincipal ? { executionPrincipal: manifest.executionPrincipal } : {}),
252
263
  ...(manifest.executionPolicy ? { executionPolicy: manifest.executionPolicy } : {}),
253
- ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
264
+ ...(normalizeDefaults ? { timeout: manifest.timeout ?? requestContractDefaults.job.timeout }
265
+ : manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
254
266
  ...(options === undefined ? {} : { options }),
255
- ...(manifest.inputs === undefined ? {} : { inputs: canonicalJobTemplateInputs(manifest.inputs) }),
267
+ ...(inputs === undefined ? {} : { inputs }),
256
268
  });
257
269
  }
258
270
  function diffJobTemplates(desired, target) {
@@ -265,13 +277,13 @@ function diffJobTemplates(desired, target) {
265
277
  ['component.pinnedDigest', desired.component.pinnedDigest, target.component.pinnedDigest],
266
278
  ...(desired.executionPrincipal ? [['executionPrincipal', desired.executionPrincipal, target.executionPrincipal]] : []),
267
279
  ...(desired.executionPolicy ? [['executionPolicy', desired.executionPolicy, target.executionPolicy]] : []),
268
- ['timeout', desired.timeout, target.timeout],
280
+ ['timeout', desired.timeout ?? requestContractDefaults.job.timeout, target.timeout ?? requestContractDefaults.job.timeout],
269
281
  [
270
282
  'options',
271
283
  canonicalJobTemplateOptions(desired.options, desired.inputs),
272
284
  canonicalJobTemplateOptions(target.options, target.inputs),
273
285
  ],
274
- ['inputs', canonicalJobTemplateInputs(desired.inputs), canonicalJobTemplateInputs(target.inputs)],
286
+ ['inputs', canonicalJobTemplateInputs(desired.inputs) ?? {}, canonicalJobTemplateInputs(target.inputs) ?? {}],
275
287
  ];
276
288
  return fields
277
289
  .filter(([, desiredValue, targetValue]) => (hashStable({ value: desiredValue }) !== hashStable({ value: targetValue })))
@@ -333,8 +345,10 @@ export async function buildJobTemplatesPlan(input) {
333
345
  const localByKey = new Map();
334
346
  for (const entry of localEntries) {
335
347
  if (!validateManifest(entry.manifest, input.stableKeyName)) {
336
- blockers.push(`Invalid job-template manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
337
- items.push({ status: 'conflict', name: path.basename(path.dirname(entry.manifestPath)), reason: 'invalid job-template manifest' });
348
+ const errors = isRecord(entry.manifest) ? jobTemplateDefinitionErrors(entry.manifest) : [];
349
+ const reason = errors.length > 0 ? errors.join('; ') : 'invalid job-template manifest';
350
+ blockers.push(`Invalid job-template manifest ${path.relative(projectRoot, entry.manifestPath)}: ${reason}.`);
351
+ items.push({ status: 'conflict', name: path.basename(path.dirname(entry.manifestPath)), reason });
338
352
  continue;
339
353
  }
340
354
  localByKey.set(entry.manifest.stableKey, [...(localByKey.get(entry.manifest.stableKey) || []), entry]);
@@ -514,10 +528,10 @@ export async function buildJobTemplatesPlan(input) {
514
528
  else if (desiredHash === target.hash) {
515
529
  items.push({ status: 'clean', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, ...dependencyDetails });
516
530
  }
517
- else if (target.hash === baseline) {
531
+ else if (target.hash === baseline || jobTemplateDefinitionHash(target.manifest, false) === baseline) {
518
532
  items.push({ status: 'safe-update', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, baselineHash: baseline, reason: 'local manifest changed; target matches lock baseline', ...dependencyDetails, ...changeDetails });
519
533
  }
520
- else if (desiredHash === baseline) {
534
+ else if (desiredHash === baseline || jobTemplateDefinitionHash(desired, false) === baseline) {
521
535
  items.push({ status: 'remote-changed', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, baselineHash: baseline, reason: 'target changed; local manifest matches lock baseline', ...dependencyDetails, ...changeDetails });
522
536
  }
523
537
  else {
@@ -630,7 +644,8 @@ export async function pullJobTemplatesToWorkspace(input) {
630
644
  if (existing && !input.force) {
631
645
  const localHash = hashPortableJobTemplate(existing.manifest);
632
646
  const baseline = lock.jobTemplates[manifest.stableKey];
633
- if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash)) {
647
+ if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash
648
+ && jobTemplateDefinitionHash(existing.manifest, false) !== baseline.sourceHash)) {
634
649
  throw new Error(`Cannot pull job-template "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
635
650
  }
636
651
  }
@@ -790,7 +805,9 @@ export async function pushJobTemplates(input) {
790
805
  const createdId = jobTemplateIdOf(created);
791
806
  if (!createdId)
792
807
  throw new Error('create response did not include jobTemplateId');
793
- const verified = unwrapData(await input.client.getJobTemplate(createdId));
808
+ let verified = unwrapData(await input.client.getJobTemplate(createdId));
809
+ if (jobTemplateIdOf(verified) !== createdId)
810
+ throw new Error('created job template identity changed before verification');
794
811
  const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, input.stableKeyName);
795
812
  if (!verifiedStableKey)
796
813
  throw new Error(`created job template is missing ${input.stableKeyName}`);
@@ -799,7 +816,37 @@ export async function pushJobTemplates(input) {
799
816
  const verifiedComponentKey = await componentStableKey({ client: input.client, record: verified, stableKeyName: input.stableKeyName });
800
817
  if (!verifiedComponentKey)
801
818
  throw new Error(`created job template references a component without ${input.stableKeyName}`);
802
- const verifiedManifest = await withRecordPrincipal(input.client, verified, manifestFromRecord(verified, verifiedStableKey, verifiedComponentKey, input.stableKeyName), input.stableKeyName, Boolean(prepared.manifest.executionPrincipal || prepared.manifest.executionPolicy), Boolean(prepared.manifest.executionPrincipal));
819
+ let verifiedManifest = await withRecordPrincipal(input.client, verified, manifestFromRecord(verified, verifiedStableKey, verifiedComponentKey, input.stableKeyName), input.stableKeyName, Boolean(prepared.manifest.executionPrincipal || prepared.manifest.executionPolicy), Boolean(prepared.manifest.executionPrincipal));
820
+ const desiredMemory = isRecord(prepared.manifest.options) ? prepared.manifest.options.memory : undefined;
821
+ if (hashPortableJobTemplate(verifiedManifest) !== prepared.desiredHash
822
+ && (desiredMemory === undefined || desiredMemory === null || desiredMemory === 0)) {
823
+ // Create coerces missing/null/0 memory to 256. The existing update API
824
+ // preserves it, so restore the complete desired options before accepting
825
+ // the new target. Concurrent changes must fail even under --force.
826
+ if (typeof created.version !== 'number' || verified.version !== created.version)
827
+ throw new Error('created job template changed before restoring desired options');
828
+ const createdComponentKey = await componentStableKey({ client: input.client, record: created, stableKeyName: input.stableKeyName });
829
+ if (!createdComponentKey)
830
+ throw new Error(`create response dependency is missing ${input.stableKeyName}`);
831
+ const createdManifest = await withRecordPrincipal(input.client, created, manifestFromRecord(created, stableKey, createdComponentKey, input.stableKeyName), input.stableKeyName, Boolean(prepared.manifest.executionPrincipal || prepared.manifest.executionPolicy), Boolean(prepared.manifest.executionPrincipal));
832
+ if (hashPortableJobTemplate(createdManifest) !== hashPortableJobTemplate(verifiedManifest))
833
+ throw new Error('created job template changed before restoring desired options');
834
+ const latestLocal = readWorkspaceJobTemplates(input.cwd).find(entry => entry.manifest.stableKey === stableKey);
835
+ if (!latestLocal || hashPortableJobTemplate(latestLocal.manifest) !== prepared.desiredHash)
836
+ throw new Error('desired manifest changed before restoring created job template options');
837
+ await input.client.updateJobTemplate(createdId, {
838
+ ...buildUpdatePayload(prepared.manifest, prepared.componentId, created.version),
839
+ ...await targetPrincipalId(input.client, prepared.manifest, input.stableKeyName, verified),
840
+ });
841
+ verified = unwrapData(await input.client.getJobTemplate(createdId));
842
+ const restoredStableKey = readConfiguredResourceMetadataStableKey(verified, input.stableKeyName);
843
+ if (restoredStableKey !== stableKey)
844
+ throw new Error(`restored target is missing or changed ${input.stableKeyName}`);
845
+ const restoredComponentKey = await componentStableKey({ client: input.client, record: verified, stableKeyName: input.stableKeyName });
846
+ if (!restoredComponentKey)
847
+ throw new Error(`restored target dependency is missing ${input.stableKeyName}`);
848
+ verifiedManifest = await withRecordPrincipal(input.client, verified, manifestFromRecord(verified, restoredStableKey, restoredComponentKey, input.stableKeyName), input.stableKeyName, Boolean(prepared.manifest.executionPrincipal || prepared.manifest.executionPolicy), Boolean(prepared.manifest.executionPrincipal));
849
+ }
803
850
  if (hashPortableJobTemplate(verifiedManifest) !== prepared.desiredHash) {
804
851
  throw new Error('created job template did not match desired portable hash');
805
852
  }
@@ -2,10 +2,12 @@ import path from 'node:path';
2
2
  import { describeFieldChanges } from "../diff-details.js";
3
3
  import { hashStable, readComponentLock, writeComponentLock, } from "../component-lock.js";
4
4
  import { normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "../resource-metadata.js";
5
+ import { validateUserMetadata } from "../request-contract.js";
5
6
  import { readJsonFile, sanitizeSegment } from "../utils.js";
6
7
  import { findManifestFiles, isRecord, localTargetPath, mapWithConcurrency, removeRelocatedManifest, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
7
8
  export const ROLE_GROUPS_DIRECTORY = 'RoleGroups';
8
9
  export const ROLE_GROUP_MANIFEST_FILE = 'role-group.json';
10
+ const ROLE_GROUP_MANIFEST_FIELDS = new Set(['kind', 'stableKey', 'name', 'category', 'description', 'metadata', 'roles']);
9
11
  function roleGroupIdOf(record) {
10
12
  return String(record.roleGroupId || record.id || '');
11
13
  }
@@ -98,6 +100,10 @@ function validateManifest(manifest, stableKeyName) {
98
100
  if (!isRecord(manifest)) {
99
101
  return ['manifest must be a JSON object'];
100
102
  }
103
+ const unsupportedFields = Object.keys(manifest).filter((key) => !ROLE_GROUP_MANIFEST_FIELDS.has(key)).sort();
104
+ if (unsupportedFields.length > 0) {
105
+ errors.push(`unsupported manifest fields: ${unsupportedFields.join(', ')}`);
106
+ }
101
107
  if (manifest.kind !== 'role-group'
102
108
  || typeof manifest.stableKey !== 'string'
103
109
  || !manifest.stableKey.trim()
@@ -112,6 +118,8 @@ function validateManifest(manifest, stableKeyName) {
112
118
  if (manifest.description !== undefined && typeof manifest.description !== 'string') {
113
119
  errors.push('description must be a string or omitted');
114
120
  }
121
+ if (isRecord(manifest.metadata))
122
+ errors.push(...validateUserMetadata(manifest.metadata));
115
123
  const metadataStableKey = isRecord(manifest.metadata)
116
124
  ? readConfiguredResourceMetadataStableKey(manifest, stableKeyName)
117
125
  : null;
@@ -0,0 +1,14 @@
1
+ /** Matches the Endpoint DTO transform, so accepted normalized routes also verify on readback. */
2
+ export declare function normalizeEndpointPath(value: string): string;
3
+ /** Endpoint create and update normalize nullable/zero memory and result references. */
4
+ export declare function canonicalEndpointOptionDefaults(value: Record<string, unknown> | undefined): {
5
+ [x: string]: unknown;
6
+ } | undefined;
7
+ /** Job create/update materialize nullable concurrency fields and the complete retry policy. */
8
+ export declare function canonicalJobRuntimeOptionDefaults(value: Record<string, unknown>): {
9
+ [x: string]: unknown;
10
+ };
11
+ /** Request DTO constraints plus the API's local static guard and schema-binding policy. */
12
+ export declare function endpointDefinitionErrors(manifest: Record<string, unknown>): string[];
13
+ /** The runtime normalizes nullable option containers, then validates effective retry backoff. */
14
+ export declare function jobTemplateDefinitionErrors(manifest: Record<string, unknown>): string[];
@@ -0,0 +1,153 @@
1
+ import { requestContractDefaults, validateRequestContract } from "../request-contract.js";
2
+ import { isRecord } from "./util.js";
3
+ /** Matches the Endpoint DTO transform, so accepted normalized routes also verify on readback. */
4
+ export function normalizeEndpointPath(value) {
5
+ const normalized = value.replace(/\/{2,}/g, '/');
6
+ return normalized.length > 1 && normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
7
+ }
8
+ /** Endpoint create and update normalize nullable/zero memory and result references. */
9
+ export function canonicalEndpointOptionDefaults(value) {
10
+ if (value === undefined)
11
+ return undefined;
12
+ const normalized = { ...value };
13
+ if (normalized.input === null)
14
+ normalized.input = {};
15
+ if (normalized.memory === null || normalized.memory === 0)
16
+ normalized.memory = requestContractDefaults.endpoint.optionDefaults.memory;
17
+ if (typeof normalized.popResult === 'string')
18
+ normalized.popResult = `${normalized.popResult.charAt(0).toUpperCase()}${normalized.popResult.slice(1)}`;
19
+ for (const [key, defaultValue] of Object.entries(requestContractDefaults.endpoint.optionDefaults)) {
20
+ if (JSON.stringify(normalized[key]) === JSON.stringify(defaultValue))
21
+ delete normalized[key];
22
+ }
23
+ return Object.keys(normalized).length > 0 ? normalized : undefined;
24
+ }
25
+ /** Job create/update materialize nullable concurrency fields and the complete retry policy. */
26
+ export function canonicalJobRuntimeOptionDefaults(value) {
27
+ const normalized = { ...value };
28
+ if (normalized.input === null)
29
+ normalized.input = {};
30
+ for (const [key, defaultValue] of Object.entries(requestContractDefaults.job.optionDefaults)) {
31
+ // Input/legacy-input precedence is handled by the owning portable hash.
32
+ // Missing memory falls back to runtime inputs (then 128), while every explicit
33
+ // value overrides those inputs. Even 256 is not a portable default.
34
+ if (key === 'memory')
35
+ continue;
36
+ if (!['input', 'concurrency'].includes(key) && normalized[key] === defaultValue)
37
+ delete normalized[key];
38
+ }
39
+ if (normalized.concurrency === null)
40
+ delete normalized.concurrency;
41
+ if (isRecord(normalized.concurrency)) {
42
+ const concurrency = { ...normalized.concurrency };
43
+ for (const key of ['key', 'limit', 'ttl'])
44
+ if (concurrency[key] === null || concurrency[key] === '')
45
+ delete concurrency[key];
46
+ if (Object.keys(concurrency).length === 0)
47
+ delete normalized.concurrency;
48
+ else
49
+ normalized.concurrency = concurrency;
50
+ }
51
+ if (normalized.retry === null)
52
+ delete normalized.retry;
53
+ if (isRecord(normalized.retry)) {
54
+ const retry = { ...normalized.retry };
55
+ if (retry.enabled === null)
56
+ retry.enabled = false;
57
+ if (retry.bypassConcurrencyOnRetry === null)
58
+ retry.bypassConcurrencyOnRetry = false;
59
+ if (retry.maxDoublings === null)
60
+ retry.maxDoublings = 0;
61
+ for (const [key, defaultValue] of Object.entries(requestContractDefaults.retry))
62
+ if (retry[key] === defaultValue)
63
+ delete retry[key];
64
+ if (Object.keys(retry).length === 0)
65
+ delete normalized.retry;
66
+ else
67
+ normalized.retry = retry;
68
+ }
69
+ return normalized;
70
+ }
71
+ function requestFields(manifest) {
72
+ return Object.fromEntries(['name', 'category', 'metadata', 'timeout', 'options', 'inputs']
73
+ .filter(field => manifest[field] !== undefined).map(field => [field, manifest[field]]));
74
+ }
75
+ /** Request DTO constraints plus the API's local static guard and schema-binding policy. */
76
+ export function endpointDefinitionErrors(manifest) {
77
+ const route = isRecord(manifest.route) ? manifest.route : {};
78
+ const body = { ...requestFields(manifest),
79
+ ...(manifest.description === undefined ? {} : { desc: manifest.description }),
80
+ method: route.method, path: typeof route.path === 'string' ? normalizeEndpointPath(route.path) : route.path };
81
+ const errors = validateRequestContract('EndpointRequestDto', body, { partial: true, path: 'Endpoint' });
82
+ if (typeof body.path === 'string' && body.path.split('/').filter(Boolean).length > requestContractDefaults.endpoint.maxPathSegments) {
83
+ errors.push(`Endpoint.path must contain at most ${requestContractDefaults.endpoint.maxPathSegments} segments`);
84
+ }
85
+ if (isRecord(manifest.schema) && manifest.schema.element !== undefined) {
86
+ errors.push(...validateRequestContract('EndpointOptionsDto', { componentSchemaElement: manifest.schema.element }, { path: 'Endpoint.options' }));
87
+ }
88
+ const options = isRecord(manifest.options) ? manifest.options : {};
89
+ if (options.guard && manifest.schema)
90
+ errors.push('Endpoint static guard and schema component cannot be configured together');
91
+ // Full schema compilation remains owned by Sandbox; these are the API's root envelope semantics.
92
+ if (isRecord(options.guard)) {
93
+ const schema = isRecord(options.guard.schema) ? options.guard.schema : undefined;
94
+ if (schema?.type !== 'object' || !Array.isArray(schema.objectSchema))
95
+ errors.push('Endpoint.options.guard.schema must be an object with objectSchema entries');
96
+ else {
97
+ if (schema.objectSchema.length > requestContractDefaults.guard.maxNodes)
98
+ errors.push('Endpoint.options.guard.schema exceeds its structural budget');
99
+ const seen = new Set();
100
+ const rootTypes = { query: 'object', headers: 'object', parameters: 'object', body: null };
101
+ for (const entry of schema.objectSchema) {
102
+ if (!isRecord(entry) || typeof entry.property !== 'string') {
103
+ errors.push('Endpoint.options.guard root entries must declare a string property');
104
+ continue;
105
+ }
106
+ if (!Object.hasOwn(rootTypes, entry.property))
107
+ errors.push(`Endpoint.options.guard property "${entry.property}" must be query, headers, parameters or body`);
108
+ else if (rootTypes[entry.property] && (!isRecord(entry.schema) || ![rootTypes[entry.property], 'any'].includes(String(entry.schema.type))))
109
+ errors.push(`Endpoint.options.guard property "${entry.property}" must use type object or any`);
110
+ if (seen.has(entry.property))
111
+ errors.push(`Endpoint.options.guard property "${entry.property}" is duplicated`);
112
+ seen.add(entry.property);
113
+ }
114
+ const pending = [{ value: schema, depth: 0 }];
115
+ let visited = 0;
116
+ while (pending.length) {
117
+ const item = pending.pop();
118
+ if (++visited > requestContractDefaults.guard.maxNodes || item.depth > requestContractDefaults.guard.maxDepth) {
119
+ errors.push('Endpoint.options.guard.schema exceeds its structural budget');
120
+ break;
121
+ }
122
+ if (item.value.regex !== undefined && typeof item.value.regex !== 'string')
123
+ errors.push('Endpoint.options.guard.schema regex must be a string');
124
+ if (Array.isArray(item.value.objectSchema))
125
+ for (const entry of item.value.objectSchema) {
126
+ if (isRecord(entry) && isRecord(entry.schema))
127
+ pending.push({ value: entry.schema, depth: item.depth + 1 });
128
+ }
129
+ if (isRecord(item.value.arraySchema))
130
+ pending.push({ value: item.value.arraySchema, depth: item.depth + 1 });
131
+ }
132
+ }
133
+ }
134
+ return errors;
135
+ }
136
+ /** The runtime normalizes nullable option containers, then validates effective retry backoff. */
137
+ export function jobTemplateDefinitionErrors(manifest) {
138
+ const body = { ...requestFields(manifest), ...(manifest.description === undefined ? {} : { desc: manifest.description }) };
139
+ const errors = validateRequestContract('JobTemplateRequestDto', body, { partial: true, path: 'JobTemplate' });
140
+ const options = isRecord(manifest.options) ? manifest.options : {};
141
+ if (isRecord(options.retry)) {
142
+ const effective = { ...requestContractDefaults.retry, ...options.retry };
143
+ // The runtime uses Number(null)=0 for these fields: null is not an omitted/default backoff.
144
+ if (effective.minBackoffSeconds === null)
145
+ errors.push('JobTemplate.options.retry.minBackoffSeconds must be at least 1');
146
+ if (effective.maxBackoffSeconds === null)
147
+ errors.push('JobTemplate.options.retry.maxBackoffSeconds must be at least 60');
148
+ if (typeof effective.minBackoffSeconds === 'number' && typeof effective.maxBackoffSeconds === 'number'
149
+ && effective.minBackoffSeconds > effective.maxBackoffSeconds)
150
+ errors.push('JobTemplate.options.retry.minBackoffSeconds must be less than or equal to maxBackoffSeconds');
151
+ }
152
+ return errors;
153
+ }
@@ -0,0 +1,33 @@
1
+ export type NativeTestSource = {
2
+ name: string;
3
+ type: string;
4
+ active: boolean;
5
+ category?: string | null;
6
+ desc?: string | null;
7
+ metadata?: Record<string, unknown>;
8
+ testConfig?: Record<string, unknown> | null;
9
+ elements: Array<{
10
+ key: string;
11
+ details: string;
12
+ order: number;
13
+ desc?: string | null;
14
+ hidden?: boolean;
15
+ metadata?: Record<string, unknown>;
16
+ }>;
17
+ };
18
+ export type WorkspaceNativeTest = {
19
+ name: string;
20
+ type: string;
21
+ mode: 'fixture' | 'integration';
22
+ targets: string[];
23
+ category: string | null;
24
+ path: string;
25
+ };
26
+ /** Reads the pulled worktree without writing locks, resolving instance IDs or publishing source. */
27
+ export declare function readNativeTestWorkspace(cwd: string, selectedWorkspace?: string, options?: {
28
+ includeSource?: boolean;
29
+ }): Promise<{
30
+ workspaceRoot: string;
31
+ tests: WorkspaceNativeTest[];
32
+ components: NativeTestSource[];
33
+ }>;
@@ -0,0 +1,156 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { resolveProjectWorkspace } from "./project.js";
4
+ import { sanitizeUserMetadata } from "./resource-metadata.js";
5
+ import { normalizeCustomNodeElementPath } from "./automation-contract.generated.js";
6
+ const CODE_TYPES = new Set([
7
+ 'CODE_JS', 'CODE_TS', 'CODE_JS_LIB', 'CODE_TS_LIB',
8
+ 'CODE_JS_TEST', 'CODE_TS_TEST', 'JSON_VALIDATOR', 'CUSTOM_NODEJS',
9
+ ]);
10
+ const EXCLUDED_DIRECTORIES = new Set(['node_modules', '.git', '.idea', 'dist', 'build']);
11
+ const MAX_WORKSPACE_BYTES = 8 * 1024 * 1024;
12
+ function isRecord(value) {
13
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
14
+ }
15
+ function assertInside(root, target) {
16
+ const relative = path.relative(root, target);
17
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
18
+ throw new Error('Native test source files must stay inside the selected workspace.');
19
+ }
20
+ }
21
+ async function readSourceFile(root, target) {
22
+ const resolved = await fs.realpath(target);
23
+ assertInside(root, resolved);
24
+ const stat = await fs.stat(resolved);
25
+ if (!stat.isFile() || stat.size > MAX_WORKSPACE_BYTES) {
26
+ throw new Error('Native test source must be a file of at most 8 MiB.');
27
+ }
28
+ return fs.readFile(resolved, 'utf8');
29
+ }
30
+ async function manifestPaths(directory) {
31
+ const entries = await fs.readdir(directory, { withFileTypes: true });
32
+ const paths = [];
33
+ for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
34
+ const fullPath = path.join(directory, entry.name);
35
+ if (entry.isDirectory() && !EXCLUDED_DIRECTORIES.has(entry.name)) {
36
+ paths.push(...await manifestPaths(fullPath));
37
+ }
38
+ else if (entry.isFile() && entry.name === 'component.json') {
39
+ paths.push(fullPath);
40
+ }
41
+ }
42
+ return paths;
43
+ }
44
+ async function elementDetails(root, directory, key, order, type, inline) {
45
+ const extension = type.includes('_TS') ? 'ts' : type === 'JSON_VALIDATOR' ? 'json' : 'js';
46
+ const prefix = `${order}_${key}.`;
47
+ if (type === 'CUSTOM_NODEJS' && !normalizeCustomNodeElementPath(key)) {
48
+ throw new Error('Component element has an unsafe Custom Node file path.');
49
+ }
50
+ if (type !== 'CUSTOM_NODEJS' && (key.includes('/') || key.includes('\\') || key.includes('\0'))) {
51
+ throw new Error('Component element keys cannot contain path separators.');
52
+ }
53
+ for (const folder of ['elements', 'details']) {
54
+ const target = path.join(directory, folder, path.dirname(prefix));
55
+ let entries;
56
+ try {
57
+ entries = await fs.readdir(target, { withFileTypes: true });
58
+ }
59
+ catch (error) {
60
+ if (error.code === 'ENOENT')
61
+ continue;
62
+ throw error;
63
+ }
64
+ const filePrefix = path.basename(prefix);
65
+ const preferred = `${filePrefix}${extension}`;
66
+ const matched = entries.find(entry => entry.name === preferred)
67
+ || entries.sort((left, right) => left.name.localeCompare(right.name)).find(entry => entry.name.startsWith(filePrefix));
68
+ if (matched)
69
+ return readSourceFile(root, path.join(target, matched.name));
70
+ }
71
+ return typeof inline === 'string' ? inline : '';
72
+ }
73
+ function names(value, field) {
74
+ if (value === undefined)
75
+ return [];
76
+ if (!Array.isArray(value) || value.some(name => typeof name !== 'string' || !name.trim())) {
77
+ throw new Error(`Native test ${field} must contain non-empty names.`);
78
+ }
79
+ return [...new Set(value)];
80
+ }
81
+ /** Reads the pulled worktree without writing locks, resolving instance IDs or publishing source. */
82
+ export async function readNativeTestWorkspace(cwd, selectedWorkspace, options = {}) {
83
+ const workspaceRoot = await fs.realpath(path.resolve(cwd, selectedWorkspace || resolveProjectWorkspace(cwd) || '.'));
84
+ const directory = path.join(workspaceRoot, 'Components');
85
+ let manifests;
86
+ try {
87
+ assertInside(workspaceRoot, await fs.realpath(directory));
88
+ manifests = await manifestPaths(directory);
89
+ }
90
+ catch (error) {
91
+ if (error.code === 'ENOENT')
92
+ return { workspaceRoot, tests: [], components: [] };
93
+ throw error;
94
+ }
95
+ const components = [];
96
+ const tests = [];
97
+ const seenNames = new Map();
98
+ let sourceBytes = 0;
99
+ for (const manifestPath of manifests) {
100
+ const manifest = JSON.parse(await readSourceFile(workspaceRoot, manifestPath));
101
+ if (!isRecord(manifest))
102
+ throw new Error(`Invalid component manifest: ${path.relative(workspaceRoot, manifestPath)}.`);
103
+ const type = typeof manifest.type === 'string' ? manifest.type : '';
104
+ if (!CODE_TYPES.has(type))
105
+ continue;
106
+ if (typeof manifest.name !== 'string' || !manifest.name.trim())
107
+ throw new Error('Native test workspace components require a name.');
108
+ const duplicate = seenNames.get(manifest.name);
109
+ if (duplicate)
110
+ throw new Error(`Duplicate Component name "${manifest.name}" in ${duplicate} and ${path.relative(workspaceRoot, manifestPath)}. Native source names must be unique.`);
111
+ seenNames.set(manifest.name, path.relative(workspaceRoot, manifestPath));
112
+ if (!Array.isArray(manifest.elements))
113
+ throw new Error(`Component ${manifest.name} requires elements.`);
114
+ const elements = [];
115
+ for (const element of manifest.elements) {
116
+ if (!isRecord(element) || typeof element.key !== 'string' || !Number.isSafeInteger(element.order)) {
117
+ throw new Error(`Component ${manifest.name} has an invalid element.`);
118
+ }
119
+ elements.push({
120
+ key: element.key,
121
+ order: element.order,
122
+ details: options.includeSource === false ? '' : await elementDetails(workspaceRoot, path.dirname(manifestPath), element.key, element.order, type, element.details),
123
+ ...(typeof element.desc === 'string' || element.desc === null ? { desc: element.desc } : {}),
124
+ ...(typeof element.hidden === 'boolean' ? { hidden: element.hidden } : {}),
125
+ ...(isRecord(element.metadata) ? { metadata: sanitizeUserMetadata(element.metadata) } : {}),
126
+ });
127
+ }
128
+ const testConfig = manifest.testConfig === null || isRecord(manifest.testConfig) ? manifest.testConfig : undefined;
129
+ if (type.endsWith('_TEST') && !isRecord(testConfig))
130
+ throw new Error(`Test ${manifest.name} requires testConfig.`);
131
+ const source = {
132
+ name: manifest.name,
133
+ type,
134
+ active: typeof manifest.active === 'boolean' ? manifest.active : true,
135
+ elements,
136
+ ...(typeof manifest.category === 'string' || manifest.category === null ? { category: manifest.category } : {}),
137
+ ...(typeof manifest.desc === 'string' || manifest.desc === null ? { desc: manifest.desc } : {}),
138
+ ...(isRecord(manifest.metadata) ? { metadata: sanitizeUserMetadata(manifest.metadata) } : {}),
139
+ ...(testConfig !== undefined ? { testConfig } : {}),
140
+ };
141
+ if (options.includeSource !== false) {
142
+ sourceBytes += Buffer.byteLength(JSON.stringify(source));
143
+ if (sourceBytes > MAX_WORKSPACE_BYTES)
144
+ throw new Error('Native test workspace source exceeds 8 MiB.');
145
+ components.push(source);
146
+ if (components.length > 100)
147
+ throw new Error('A native test source overlay supports at most 100 Components.');
148
+ }
149
+ if (type.endsWith('_TEST') && isRecord(testConfig)) {
150
+ if (testConfig.mode !== 'fixture' && testConfig.mode !== 'integration')
151
+ throw new Error(`Test ${manifest.name} has an invalid mode.`);
152
+ tests.push({ name: manifest.name, type, mode: testConfig.mode, targets: names(testConfig.targets, 'targets'), category: source.category || null, path: path.relative(workspaceRoot, path.dirname(manifestPath)) });
153
+ }
154
+ }
155
+ return { workspaceRoot, tests, components };
156
+ }
@@ -57,6 +57,7 @@ export type ComponentRecord = {
57
57
  metadata?: Record<string, unknown>;
58
58
  metaData?: Record<string, unknown>;
59
59
  resourceMetadata?: Record<string, unknown>;
60
+ testConfig?: Record<string, unknown> | null;
60
61
  elements?: ComponentElementRecord[];
61
62
  [key: string]: unknown;
62
63
  };