@revoengine/cli 1.0.21 → 1.0.23

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.
@@ -0,0 +1,68 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { setTimeout as delay } from 'node:timers/promises';
3
+ import { hashPortableComponentSource } from "./component-lock.js";
4
+ import { unwrapData, isRecord } from "./resource-syncs/util.js";
5
+ export function isComponentDigest(value) {
6
+ return typeof value === 'string' && /^v1:sha256:[a-f0-9]{64}$/.test(value);
7
+ }
8
+ /** Canonical API content identity, separate from portable configuration hashes. */
9
+ export function componentContentDigest(component) {
10
+ const digest = (value) => `v1:sha256:${createHash('sha256').update(value).digest('hex')}`;
11
+ const type = String(component.type || '');
12
+ const elements = [...(component.elements || [])]
13
+ .sort((a, b) => Number(a.order) - Number(b.order) || String(a.key).localeCompare(String(b.key)))
14
+ .map(element => [element.key, Number(element.order), Boolean(element.hidden),
15
+ digest(typeof element.details === 'string' ? element.details : '')]);
16
+ return digest(JSON.stringify([1, type, type.endsWith('_LIB') ? component.name || '' : null, elements]));
17
+ }
18
+ export async function componentRevisionByDigest(client, componentId, digest) {
19
+ if (!isComponentDigest(digest))
20
+ throw new Error('Expected canonical v1 component digest.');
21
+ const current = unwrapData(await client.getComponent(componentId));
22
+ if (!current || current.active === false || current.deletedAt || current.deletedBy)
23
+ throw new Error('Pinned component is missing or deleted.');
24
+ if (componentContentDigest(current) === digest)
25
+ return current;
26
+ const matches = await client.resolveComponentDigest(digest);
27
+ const rows = matches.filter(row => row.componentId === componentId && row.digest === digest && Number.isInteger(row.version));
28
+ if (!rows.length)
29
+ throw new Error(`Component digest ${digest} does not exist for the target component.`);
30
+ const revision = rows.sort((a, b) => b.version - a.version)[0];
31
+ const snapshot = unwrapData(await client.getComponentSnapshotVersion(componentId, revision.version));
32
+ if (!snapshot || componentContentDigest(snapshot) !== digest)
33
+ throw new Error('Component digest readback differs from the selected revision.');
34
+ return snapshot;
35
+ }
36
+ export function componentRuntimeBlocker(runtime, active = true) {
37
+ const value = unwrapData(runtime);
38
+ if (!isRecord(value) || value.availability !== (active ? 'READY' : 'DISABLED') || value.hasPendingRevision !== false
39
+ || !value.activeRevisionId || value.activeRevisionId !== value.desiredRevisionId) {
40
+ return `Custom component runtime is not converged: availability=${String(value?.availability)}, activationMode=${String(value?.activationMode)}, pending=${String(value?.hasPendingRevision)}.`;
41
+ }
42
+ return null;
43
+ }
44
+ export async function verifyComponentRuntime(client, component, waitMs = 0) {
45
+ if (component.type !== 'CUSTOM_NODEJS')
46
+ return;
47
+ const id = String(component.componentId || component.id || '');
48
+ if (!id)
49
+ throw new Error('Custom component runtime requires its target component id.');
50
+ const deadline = Date.now() + waitMs;
51
+ while (true) {
52
+ const runtime = unwrapData(await client.getComponentRuntime(id));
53
+ const blocker = componentRuntimeBlocker(runtime, component.active !== false);
54
+ if (!blocker) {
55
+ if (waitMs > 0) {
56
+ const current = unwrapData(await client.getComponent(id));
57
+ if (hashPortableComponentSource(current) !== hashPortableComponentSource(component))
58
+ throw new Error('Custom component source changed while waiting for deployment.');
59
+ }
60
+ return;
61
+ }
62
+ const deployment = isRecord(runtime?.latestDeployment) ? runtime.latestDeployment : {};
63
+ if (Date.now() >= deadline || runtime?.activationMode === 'MANUAL' || deployment.status === 'FAILED') {
64
+ throw new Error(blocker + ' Review runtime deployment/activation and rerun; saved source alone is not a successful deployment.');
65
+ }
66
+ await delay(Math.min(1000, Math.max(1, deadline - Date.now())));
67
+ }
68
+ }
@@ -138,6 +138,7 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
138
138
  active: boolean;
139
139
  type: string;
140
140
  async: boolean;
141
+ metadata: Record<string, unknown>;
141
142
  elements: {
142
143
  key: string;
143
144
  desc: string | null;
@@ -154,6 +155,7 @@ export declare function normalizePortableComponentSource(component: ComponentRec
154
155
  active: boolean;
155
156
  type: string;
156
157
  async: boolean;
158
+ metadata: Record<string, unknown>;
157
159
  elements: {
158
160
  key: string;
159
161
  desc: string | null;
@@ -163,10 +165,10 @@ export declare function normalizePortableComponentSource(component: ComponentRec
163
165
  }[];
164
166
  };
165
167
  export declare function hashPortableComponentSource(component: ComponentRecord): string;
166
- export declare const PORTABLE_COMPONENT_CONFIG_FIELDS: readonly ["name", "category", "desc", "active", "type", "async"];
168
+ export declare const PORTABLE_COMPONENT_CONFIG_FIELDS: readonly ["name", "category", "desc", "active", "type", "async", "metadata"];
167
169
  export type PortableComponentConfigField = (typeof PORTABLE_COMPONENT_CONFIG_FIELDS)[number];
168
170
  export declare function diffPortableComponentSource(source: ComponentRecord, target: ComponentRecord): {
169
- configurationFields: ("desc" | "name" | "category" | "type" | "active" | "async")[];
171
+ configurationFields: ("metadata" | "desc" | "name" | "category" | "type" | "active" | "async")[];
170
172
  elementsChanged: boolean;
171
173
  changedFields: string[];
172
174
  };
@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { REVO_PROJECT_DIR } from "./project.js";
5
- import { COMPONENT_IDENTITY_BY_ID, normalizeComponentIdentityConfig, readComponentIdentityValue, sameComponentIdentityConfig, } from "./resource-metadata.js";
5
+ import { COMPONENT_IDENTITY_BY_ID, normalizeComponentIdentityConfig, readComponentIdentityValue, sameComponentIdentityConfig, sanitizeUserMetadata, } from "./resource-metadata.js";
6
6
  import { readJsonFile, writeJsonFile } from "./utils.js";
7
7
  export const REVO_LOCK_FILE = path.join(REVO_PROJECT_DIR, 'revo.lock.json');
8
8
  const VOLATILE_COMPONENT_FIELDS = new Set([
@@ -84,6 +84,7 @@ export function normalizeComponentSource(component) {
84
84
  active: source.active ?? true,
85
85
  type: source.type || '',
86
86
  async: Boolean(source.async),
87
+ metadata: sanitizeUserMetadata(source.metadata),
87
88
  elements: [...(source.elements || [])]
88
89
  .map((element) => ({
89
90
  key: typeof element.key === 'string' ? element.key : '',
@@ -115,11 +116,12 @@ export const PORTABLE_COMPONENT_CONFIG_FIELDS = [
115
116
  'active',
116
117
  'type',
117
118
  'async',
119
+ 'metadata',
118
120
  ];
119
121
  export function diffPortableComponentSource(source, target) {
120
122
  const sourcePortable = normalizePortableComponentSource(source);
121
123
  const targetPortable = normalizePortableComponentSource(target);
122
- const configurationFields = PORTABLE_COMPONENT_CONFIG_FIELDS.filter((field) => sourcePortable[field] !== targetPortable[field]);
124
+ const configurationFields = PORTABLE_COMPONENT_CONFIG_FIELDS.filter((field) => hashStable(sourcePortable[field]) !== hashStable(targetPortable[field]));
123
125
  const elementsChanged = hashStable(sourcePortable.elements) !== hashStable(targetPortable.elements);
124
126
  return {
125
127
  configurationFields,
@@ -0,0 +1,14 @@
1
+ export type DatabaseIndex = {
2
+ columns: Array<string | Record<string, unknown>>;
3
+ name?: string;
4
+ using?: string;
5
+ unique?: boolean;
6
+ where?: Record<string, unknown>;
7
+ include?: string[];
8
+ };
9
+ /** Preserve structured PostgreSQL semantics and normalize only confirmed defaults. */
10
+ export declare function normalizeDatabaseIndexes(value: unknown): DatabaseIndex[];
11
+ export declare function databaseIndexPayload(value: unknown): Array<DatabaseIndex & {
12
+ columns: Record<string, unknown>[];
13
+ }>;
14
+ export declare function databaseIndexReferences(index: DatabaseIndex): string[];
@@ -0,0 +1,124 @@
1
+ import { hashStable } from "./component-lock.js";
2
+ import { isRecord } from "./resource-syncs/util.js";
3
+ function keys(value, allowed) {
4
+ if (Object.keys(value).some(key => !allowed.includes(key)))
5
+ throw new Error('Unsupported index field; refusing to discard it.');
6
+ }
7
+ function expression(value, depth = 0) {
8
+ if (!isRecord(value) || depth > 16)
9
+ throw new Error('Invalid index expression.');
10
+ keys(value, ['column', 'fn', 'args', 'cast', 'literal']);
11
+ for (const field of ['column', 'fn', 'cast'])
12
+ if (value[field] !== undefined && typeof value[field] !== 'string')
13
+ throw new Error('Invalid index expression field.');
14
+ if (value.args !== undefined) {
15
+ if (!Array.isArray(value.args))
16
+ throw new Error('Invalid index expression arguments.');
17
+ value.args.forEach(child => expression(child, depth + 1));
18
+ }
19
+ }
20
+ function predicate(value, depth = 0) {
21
+ if (!isRecord(value) || depth > 16)
22
+ throw new Error('Invalid index predicate.');
23
+ keys(value, ['and', 'or', 'not', 'column', 'op', 'value', 'values']);
24
+ for (const field of ['and', 'or'])
25
+ if (value[field] !== undefined) {
26
+ if (!Array.isArray(value[field]) || !value[field].length)
27
+ throw new Error('Invalid index predicate group.');
28
+ value[field].forEach(child => predicate(child, depth + 1));
29
+ }
30
+ if (value.not !== undefined)
31
+ predicate(value.not, depth + 1);
32
+ if (value.column !== undefined && typeof value.column !== 'string')
33
+ throw new Error('Invalid index predicate column.');
34
+ if (value.op !== undefined && !['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike', 'in', 'between', 'isnull', 'notnull'].includes(String(value.op)))
35
+ throw new Error('Invalid index predicate operator.');
36
+ if (value.values !== undefined && !Array.isArray(value.values))
37
+ throw new Error('Invalid index predicate values.');
38
+ }
39
+ /** Preserve structured PostgreSQL semantics and normalize only confirmed defaults. */
40
+ export function normalizeDatabaseIndexes(value) {
41
+ if (value == null)
42
+ return [];
43
+ if (!Array.isArray(value))
44
+ throw new Error('indexes must be an array.');
45
+ return value.map((raw, position) => {
46
+ if (!isRecord(raw))
47
+ throw new Error('Invalid index.');
48
+ keys(raw, ['name', 'using', 'columns', 'where', 'include', 'unique']);
49
+ if (!Array.isArray(raw.columns) || !raw.columns.length)
50
+ throw new Error('Index requires columns.');
51
+ if (raw.name !== undefined && (typeof raw.name !== 'string' || !raw.name.trim()))
52
+ throw new Error('Invalid index name.');
53
+ if (raw.using !== undefined && !['btree', 'hash', 'gist', 'spgist', 'gin', 'brin'].includes(String(raw.using)))
54
+ throw new Error('Invalid index method.');
55
+ if (raw.unique !== undefined && typeof raw.unique !== 'boolean')
56
+ throw new Error('Invalid index unique flag.');
57
+ if (raw.include !== undefined && (!Array.isArray(raw.include) || !raw.include.every(c => typeof c === 'string' && c.trim())))
58
+ throw new Error('Invalid index include columns.');
59
+ if (raw.where !== undefined)
60
+ predicate(raw.where);
61
+ const columns = raw.columns.map(column => {
62
+ if (typeof column === 'string' && column.trim())
63
+ return column;
64
+ if (!isRecord(column))
65
+ throw new Error('Invalid index column.');
66
+ keys(column, ['name', 'expression', 'order', 'nulls', 'collation', 'opclass']);
67
+ if (column.name !== undefined && (typeof column.name !== 'string' || !column.name.trim()))
68
+ throw new Error('Invalid index column name.');
69
+ if (!column.name && !column.expression)
70
+ throw new Error('Index column requires name or expression.');
71
+ if (column.expression !== undefined)
72
+ expression(column.expression);
73
+ if (column.order !== undefined && !['ASC', 'DESC'].includes(String(column.order)))
74
+ throw new Error('Invalid index order.');
75
+ if (column.nulls !== undefined && !['FIRST', 'LAST'].includes(String(column.nulls)))
76
+ throw new Error('Invalid index null placement.');
77
+ for (const field of ['collation', 'opclass'])
78
+ if (column[field] !== undefined && typeof column[field] !== 'string')
79
+ throw new Error('Invalid index column field.');
80
+ const normalized = structuredClone(column);
81
+ if (normalized.nulls === (normalized.order === 'DESC' ? 'FIRST' : 'LAST'))
82
+ delete normalized.nulls;
83
+ if (normalized.order === 'ASC')
84
+ delete normalized.order;
85
+ return Object.keys(normalized).length === 1 && typeof normalized.name === 'string' ? normalized.name : normalized;
86
+ });
87
+ return {
88
+ columns,
89
+ name: raw.name || `index_${position + 1}`,
90
+ ...(raw.using && raw.using !== 'btree' ? { using: raw.using } : {}),
91
+ ...(raw.unique === true ? { unique: true } : {}),
92
+ ...(raw.where !== undefined ? { where: structuredClone(raw.where) } : {}),
93
+ ...(Array.isArray(raw.include) && raw.include.length ? { include: [...raw.include] } : {}),
94
+ };
95
+ }).sort((a, b) => hashStable(a).localeCompare(hashStable(b)));
96
+ }
97
+ export function databaseIndexPayload(value) {
98
+ return normalizeDatabaseIndexes(value).map(index => ({ ...index, columns: index.columns.map(c => typeof c === 'string' ? { name: c } : c) }));
99
+ }
100
+ export function databaseIndexReferences(index) {
101
+ const refs = [...(index.include || [])];
102
+ const visit = (value) => {
103
+ if (!isRecord(value))
104
+ return;
105
+ if (typeof value.column === 'string')
106
+ refs.push(value.column);
107
+ for (const field of ['args', 'and', 'or'])
108
+ if (Array.isArray(value[field]))
109
+ value[field].forEach(visit);
110
+ if (value.not)
111
+ visit(value.not);
112
+ };
113
+ index.columns.forEach(c => {
114
+ if (typeof c === 'string')
115
+ refs.push(c);
116
+ else {
117
+ if (typeof c.name === 'string')
118
+ refs.push(c.name);
119
+ visit(c.expression);
120
+ }
121
+ });
122
+ visit(index.where);
123
+ return refs;
124
+ }
@@ -13,6 +13,7 @@ export type EnvComponentEntry = {
13
13
  component: ComponentRecord;
14
14
  portable: PortableComponentSource;
15
15
  portableHash: string;
16
+ runtimeBlocker?: string;
16
17
  };
17
18
  export type EnvCollision = {
18
19
  stableKey: string;
@@ -37,6 +38,7 @@ export type EnvSyncPlanItem = {
37
38
  targetComponentId: string | null;
38
39
  sourceHash: string | null;
39
40
  targetHash: string | null;
41
+ blocked?: boolean;
40
42
  changedFields?: string[];
41
43
  addedElementKeys?: string[];
42
44
  removedElementKeys?: string[];
@@ -1,3 +1,4 @@
1
+ import { verifyComponentRuntime } from "./component-contract.js";
1
2
  import { buildPortableComponentUpdatePayload, diffPortableComponentSource, hashPortableComponentSource, normalizePortableComponentSource, sanitizeComponentSource, } from "./component-lock.js";
2
3
  import { buildStableKey as buildComponentStableKey, DEFAULT_STABLE_KEY_NAME, NULL_CATEGORY_KEY, sanitizeUserMetadata, } from "./resource-metadata.js";
3
4
  import { mapWithConcurrency } from "./utils.js";
@@ -34,6 +35,14 @@ export async function captureEnvSnapshot(client, envName, options = {}) {
34
35
  portable: normalizePortableComponentSource(component),
35
36
  portableHash: hashPortableComponentSource(component),
36
37
  };
38
+ if (component.type === 'CUSTOM_NODEJS') {
39
+ try {
40
+ await verifyComponentRuntime(client, component);
41
+ }
42
+ catch (error) {
43
+ entry.runtimeBlocker = error instanceof Error ? error.message : String(error);
44
+ }
45
+ }
37
46
  return entry;
38
47
  });
39
48
  for (const entry of entries) {
@@ -169,7 +178,8 @@ export function buildEnvSyncPlan(source, target, options) {
169
178
  continue;
170
179
  }
171
180
  if (sourceEntry.portableHash === targetEntry.portableHash) {
172
- items.push({ ...base, action: 'noop', reason: 'up to date' });
181
+ items.push({ ...base, action: 'noop', reason: targetEntry.runtimeBlocker || 'up to date',
182
+ ...(targetEntry.runtimeBlocker ? { blocked: true } : {}) });
173
183
  continue;
174
184
  }
175
185
  const changedFields = diffPortableComponentSource(sourceEntry.component, targetEntry.component).configurationFields;
@@ -240,10 +250,16 @@ function buildCreatePayload(component) {
240
250
  }
241
251
  async function verifyAppliedComponent(targetClient, componentId, expectedHash) {
242
252
  const component = unwrapComponent(await targetClient.getComponent(componentId));
243
- return hashPortableComponentSource(component) === expectedHash;
253
+ if (hashPortableComponentSource(component) !== expectedHash)
254
+ return false;
255
+ await verifyComponentRuntime(targetClient, component, 120_000);
256
+ return true;
244
257
  }
245
258
  export async function applyEnvSyncPlan(input) {
246
259
  const { targetClient, plan, source, target, stableKeyName, onItem } = input;
260
+ const blocked = plan.items.filter(item => item.blocked);
261
+ if (blocked.length)
262
+ throw new Error(`Cannot apply: ${blocked.length} component runtime(s) are not ready. ${blocked.map(item => item.reason).join(' ')}`);
247
263
  const collisions = plan.items.filter((item) => item.action === 'collision');
248
264
  if (collisions.length > 0) {
249
265
  throw new Error(`Cannot apply: ${collisions.length} stable-key collision(s) in scope. Resolve duplicates or narrow the scope with --key/--category.`);
@@ -125,7 +125,7 @@ export function scheduleItemAction(item) {
125
125
  if (item.status === 'missing-lock') {
126
126
  return item.desiredHash === item.currentHash ? 'adopt' : 'update';
127
127
  }
128
- if (item.status === 'orphan' || item.status === 'skipped') {
128
+ if (item.status === 'orphan' || item.status === 'skipped' || item.status === 'activation-drift') {
129
129
  return 'excluded';
130
130
  }
131
131
  return 'noop';
@@ -261,7 +261,7 @@ function summarizeSchedulePhase(plan) {
261
261
  return {
262
262
  order: 6,
263
263
  resource: 'schedule',
264
- needsChanges: operations.create + operations.update > 0,
264
+ needsChanges: operations.create + operations.update > 0 || plan.items.some((item) => item.status === 'activation-drift'),
265
265
  readyToMigrate: blockers.length === 0,
266
266
  verdict: phaseVerdict(blockers, warnings),
267
267
  operations,
@@ -291,7 +291,7 @@ function summarizeEventPhase(plan) {
291
291
  return {
292
292
  order: 7,
293
293
  resource: 'event',
294
- needsChanges: operations.create + operations.update > 0,
294
+ needsChanges: operations.create + operations.update > 0 || plan.items.some(item => item.status === 'activation-drift'),
295
295
  readyToMigrate: blockers.length === 0,
296
296
  verdict: phaseVerdict(blockers, warnings),
297
297
  operations,
@@ -1089,7 +1089,7 @@ async function planWorkspace(input) {
1089
1089
  if (serviceAccounts && identities) {
1090
1090
  serviceAccounts.blockers.push(...identities.blockers);
1091
1091
  }
1092
- const projected = { component: input.projectDependencies && components ? components.items.filter(item => !item.blocked).flatMap(item => item.stableKey ? [item.stableKey] : []) : [],
1092
+ const projected = { component: input.projectDependencies && components ? components.items.filter(item => !item.blocked && ['create', 'update'].includes(componentItemAction(item))).flatMap(item => item.stableKey ? [item.stableKey] : []) : [],
1093
1093
  'service-account': identities?.projection.serviceAccounts || [], group: identities?.projection.groups || [] };
1094
1094
  const agentPlugins = resources.includes('agent-plugin') ? await runMigrationStage('target plan', 'agent-plugin', environmentLabel, () => buildAgentsPlan({ client, cwd: input.cwd, envName: environmentKey, stableKeyName, family: 'agent-plugin', projected })) : undefined;
1095
1095
  const agents = resources.includes('agent') ? await runMigrationStage('target plan', 'agent', environmentLabel, () => buildAgentsPlan({ client, cwd: input.cwd, envName: environmentKey, stableKeyName, family: 'agent', projected: { ...projected,
@@ -1,3 +1,4 @@
1
+ import { componentRevisionByDigest, verifyComponentRuntime } from "../component-contract.js";
1
2
  import fs from 'node:fs';
2
3
  import path from 'node:path';
3
4
  import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
@@ -327,6 +328,8 @@ async function resolveKey(input, family, key, cache = new Map()) {
327
328
  const matches = values.filter(value => active(value) && readConfiguredResourceMetadataStableKey(value, input.stableKeyName) === key);
328
329
  if (matches.length !== 1)
329
330
  throw new Error(`${family} "${key}" must resolve to exactly one active target resource.`);
331
+ if (family === 'component' && matches[0].active !== true)
332
+ throw new Error('Backing component must be active.');
330
333
  if (family === 'service-account' && (matches[0].serviceAccount !== true || ![0, 'ACTIVE'].includes(matches[0].status)))
331
334
  throw new Error('Agent execution Service Account must be active.');
332
335
  return resourceIdOf(matches[0]);
@@ -364,7 +367,7 @@ async function pluginPayload(input, definition, current, cache = new Map()) {
364
367
  async function writePayload(input, manifest, current) {
365
368
  const cache = new Map();
366
369
  if (manifest.kind === 'agent-plugin')
367
- return { ...await pluginPayload(input, manifest.definition, isRecord(current?.config) ? current.config : undefined, cache), metadata: manifest.metadata };
370
+ return { ...await pluginPayload(input, manifest.definition, isRecord(current?.config) ? current.config : undefined, cache), category: manifest.definition.category ?? null, metadata: manifest.metadata };
368
371
  if (manifest.executionPrincipal?.kind === 'service-account') {
369
372
  const id = await resolveKey(input, 'service-account', manifest.executionPrincipal.stableKey, cache);
370
373
  if ((await input.client.getServiceAccount(id)).platformAccess !== true)
@@ -394,6 +397,27 @@ async function writePayload(input, manifest, current) {
394
397
  }
395
398
  return result;
396
399
  }
400
+ async function verifyPluginComponents(input, manifest, cache, projected) {
401
+ const definitions = manifest.kind === 'agent-plugin' ? [manifest.definition]
402
+ : ['config', 'policy'].flatMap(field => {
403
+ const section = manifest.definition[field];
404
+ return isRecord(section) && Array.isArray(section.plugins) ? section.plugins.map(record) : [];
405
+ });
406
+ for (const definition of definitions) {
407
+ if (!definition.componentStableKey)
408
+ continue;
409
+ const key = String(definition.componentStableKey);
410
+ if (projected?.component?.includes(key))
411
+ continue;
412
+ const id = await resolveKey(input, 'component', key, cache);
413
+ const component = unwrapData(await input.client.getComponent(id));
414
+ if (component.active !== true || component.deletedAt || component.deletedBy)
415
+ throw new Error('Backing component must be active and not deleted.');
416
+ await verifyComponentRuntime(input.client, component);
417
+ if (definition.componentDigest)
418
+ await componentRevisionByDigest(input.client, id, String(definition.componentDigest));
419
+ }
420
+ }
397
421
  export async function buildAgentsPlan(input) {
398
422
  const plan = { resourceType: input.family, env: input.envName, items: [], counts: { clean: 0, create: 0, 'safe-update': 0, 'remote-changed': 0, conflict: 0, 'missing-lock': 0, orphan: 0, skipped: 0, collision: 0 }, blockers: [], warnings: [], exclusions: ['Agent memory, sessions, workspace files, terminals, automation recipients, avatars and MCP secrets remain target-local.'] };
399
423
  const locals = readWorkspaceAgents(input.cwd, input.family);
@@ -468,10 +492,11 @@ export async function buildAgentsPlan(input) {
468
492
  // A projected create can fill an absent dependency, never hide duplicate target identities.
469
493
  const candidates = await dependencyRecords(input, family, cache);
470
494
  const matches = candidates.filter(value => active(value) && readConfiguredResourceMetadataStableKey(value, input.stableKeyName) === key);
471
- if (matches.length === 0 && input.projected?.[family]?.includes(key))
495
+ if (matches.length <= 1 && input.projected?.[family]?.includes(key) && (family === 'component' || matches.length === 0))
472
496
  continue;
473
497
  await resolveKey(input, family, key, cache);
474
498
  }
499
+ await verifyPluginComponents(input, manifest, cache, input.projected);
475
500
  if (manifest.owner?.type === 'system' && !await ownerIsAvailable(input.client, manifest.owner, input.stableKeyName))
476
501
  throw new Error('System owner unavailable.');
477
502
  if (manifest.executionPrincipal?.kind === 'service-account' && !input.projected?.['service-account']?.includes(manifest.executionPrincipal.stableKey)) {
@@ -549,6 +574,7 @@ export async function pushAgents(input) {
549
574
  const current = target ? await agentManifestFromRecord(input, target) : null;
550
575
  if ((current ? hashPortableAgent(comparableAgent(manifest, current)) : undefined) !== item.currentHash)
551
576
  throw new Error('Target definition changed after planning.');
577
+ await verifyPluginComponents(input, manifest, new Map());
552
578
  let written = target;
553
579
  if (item.desiredHash !== item.currentHash) {
554
580
  const payload = await writePayload(input, manifest, target);
@@ -11,6 +11,9 @@ export type DatabaseSchemaManifest = {
11
11
  metadata: Record<string, unknown>;
12
12
  type?: string;
13
13
  definition?: PortableDefinition[];
14
+ options?: {
15
+ indexes: Record<string, unknown>[];
16
+ };
14
17
  partition?: Record<string, unknown>;
15
18
  parentStableKey?: string;
16
19
  migration?: {
@@ -1,3 +1,4 @@
1
+ import { databaseIndexPayload } from "../database-indexes.js";
1
2
  import fs from 'node:fs';
2
3
  import path from 'node:path';
3
4
  import { ApiError } from "../client.js";
@@ -134,6 +135,7 @@ function manifestFromEntry(entry, stableKeyName) {
134
135
  ...common,
135
136
  ...(typeof record.type === 'string' ? { type: record.type } : {}),
136
137
  definition,
138
+ options: { indexes: databaseIndexPayload(isRecord(record.options) ? record.options.indexes : undefined) },
137
139
  ...(partition ? { partition } : {}),
138
140
  ...(hasForeignReferences(definition) ? { migration: { foreignReferences: 'manual' } } : {}),
139
141
  };
@@ -163,6 +165,7 @@ function portableDatabaseSchemaManifest(manifest) {
163
165
  kind: manifest.kind,
164
166
  ...common,
165
167
  ...(manifest.type === undefined ? {} : { type: manifest.type }),
168
+ options: { indexes: databaseIndexPayload(manifest.options?.indexes) },
166
169
  ...(manifest.definition === undefined
167
170
  ? {}
168
171
  : { definition: portableDefinitions(manifest.definition) }),
@@ -604,19 +607,18 @@ function diffDatabaseSchemas(desired, current, stableKeyName) {
604
607
  hint: 'Changing the physical table kind can rebuild storage and dependencies; use a replacement table with a new Stable Key and an explicit data migration.',
605
608
  });
606
609
  }
607
- for (const field of ['category', 'description', 'metadata']) {
610
+ for (const field of ['category', 'description', 'metadata', 'options']) {
608
611
  if (valuesEqual(desired[field], current[field])) {
609
612
  continue;
610
613
  }
611
- const cannotClearCategory = field === 'category' && (desired.category === undefined || desired.category === null);
612
614
  changes.push({
613
615
  kind: 'field-changed',
614
616
  field,
615
- risk: cannotClearCategory ? 'manual' : 'safe',
617
+ risk: field === 'options' ? 'operational' : 'safe',
616
618
  before: current[field],
617
619
  after: desired[field],
618
- hint: cannotClearCategory
619
- ? 'The current Database API accepts a category value but cannot clear one. Clear it through the target UI or a reviewed backend migration, then reconcile the manifest.'
620
+ hint: field === 'options'
621
+ ? 'Index changes may scan data and hold schema locks; review target size and deployment timing before applying.'
620
622
  : safeFieldHint(field),
621
623
  });
622
624
  }
@@ -1538,6 +1540,7 @@ function createPayloadForDatabaseSchema(input) {
1538
1540
  return {
1539
1541
  ...common,
1540
1542
  definition: portableDefinitions(input.manifest.definition),
1543
+ options: { indexes: databaseIndexPayload(input.manifest.options?.indexes) },
1541
1544
  ...(input.manifest.partition === undefined
1542
1545
  ? {}
1543
1546
  : { partition: canonicalValue(input.manifest.partition, true) }),
@@ -1725,7 +1728,7 @@ function buildDatabaseSchemaUpdatePayload(input) {
1725
1728
  ...(input.sourceWins === true && input.desired.name !== input.target.name
1726
1729
  ? { name: input.desired.name }
1727
1730
  : {}),
1728
- ...(typeof input.desired.category === 'string' ? { category: input.desired.category } : {}),
1731
+ category: input.desired.category ?? null,
1729
1732
  ...(input.desired.description === undefined
1730
1733
  ? (typeof input.target.desc === 'string' && input.target.desc ? { desc: '' } : {})
1731
1734
  : { desc: input.desired.description }),
@@ -1756,6 +1759,7 @@ function buildDatabaseSchemaUpdatePayload(input) {
1756
1759
  desiredStableKeyOwners.set(stableKey, [...(desiredStableKeyOwners.get(stableKey) || []), definition]);
1757
1760
  }
1758
1761
  }
1762
+ payload.options = { indexes: databaseIndexPayload(input.desired.options?.indexes) };
1759
1763
  payload.definition = (input.desired.definition || []).map((definition) => {
1760
1764
  const value = portableDefinition(definition);
1761
1765
  const stableKey = columnStableKey(value, stableKeyName);
@@ -1,3 +1,4 @@
1
+ import { type DatabaseIndex } from '../database-indexes.ts';
1
2
  import { type FieldChange } from '../diff-details.ts';
2
3
  import type { RevoClient } from '../client.ts';
3
4
  import type { DatabaseSchemaRecord } from '../types.ts';
@@ -23,10 +24,7 @@ export type DatabaseViewOutputField = {
23
24
  type: string;
24
25
  isArray: boolean;
25
26
  };
26
- export type DatabaseViewIndex = {
27
- columns: string[];
28
- unique?: boolean;
29
- };
27
+ export type DatabaseViewIndex = DatabaseIndex;
30
28
  type DatabaseViewManifestBase = {
31
29
  kind: 'database-view';
32
30
  stableKey: string;
@@ -1,3 +1,4 @@
1
+ import { normalizeDatabaseIndexes, databaseIndexPayload, databaseIndexReferences } from "../database-indexes.js";
1
2
  import path from 'node:path';
2
3
  import { describeFieldChanges, unifiedLineDiff } from "../diff-details.js";
3
4
  import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
@@ -119,13 +120,10 @@ function validManifest(value, stableKeyName) {
119
120
  || !value.uniqueKey.every(isNonEmptyString)) {
120
121
  return false;
121
122
  }
122
- if (value.indexes !== undefined && (!Array.isArray(value.indexes)
123
- || !value.indexes.every((index) => (isRecord(index)
124
- && Array.isArray(index.columns)
125
- && index.columns.length > 0
126
- && index.columns.every(isNonEmptyString)
127
- && (index.unique === undefined || typeof index.unique === 'boolean')
128
- && Object.keys(index).every((key) => key === 'columns' || key === 'unique'))))) {
123
+ try {
124
+ normalizeDatabaseIndexes(value.indexes);
125
+ }
126
+ catch {
129
127
  return false;
130
128
  }
131
129
  }
@@ -134,6 +132,7 @@ function validManifest(value, stableKeyName) {
134
132
  export function hashPortableDatabaseView(manifest) {
135
133
  return hashStable(canonicalValue({
136
134
  ...manifest,
135
+ ...(manifest.type === 'MATERIALIZED_VIEW' ? { indexes: normalizeDatabaseIndexes(manifest.indexes) } : {}),
137
136
  sources: [...manifest.sources].sort((left, right) => (left.databaseStableKey.localeCompare(right.databaseStableKey)
138
137
  || left.name.localeCompare(right.name))),
139
138
  }));
@@ -235,33 +234,15 @@ function materializedConfiguration(record, output) {
235
234
  if (record.uniqueKey.some((column) => !outputNames.has(column))) {
236
235
  return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" uniqueKey references an unknown output column`;
237
236
  }
238
- const indexes = [];
239
- if (record.indexes !== undefined && !Array.isArray(record.indexes)) {
240
- return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
241
- }
242
- for (const index of record.indexes || []) {
243
- if (!isRecord(index) || !Array.isArray(index.columns) || index.columns.length === 0) {
244
- return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
245
- }
246
- const columns = [];
247
- for (const column of index.columns) {
248
- const name = isNonEmptyString(column)
249
- ? column
250
- : isRecord(column) && isNonEmptyString(column.name)
251
- ? column.name
252
- : undefined;
253
- if (!name) {
254
- return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index`;
255
- }
256
- columns.push(name);
257
- }
258
- if (columns.some((column) => !outputNames.has(column))) {
259
- return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" index references an unknown output column`;
260
- }
261
- if (index.unique !== undefined && typeof index.unique !== 'boolean') {
262
- return `Database View "${String(record.name || viewIdOf(record) || 'unknown')}" has an invalid materialized index unique flag`;
263
- }
264
- indexes.push({ columns, ...(index.unique === true ? { unique: true } : {}) });
237
+ let indexes;
238
+ try {
239
+ indexes = normalizeDatabaseIndexes(record.indexes);
240
+ }
241
+ catch (error) {
242
+ return `Database View "${String(record.name || viewIdOf(record))}" has an invalid materialized index: ${String(error)}`;
243
+ }
244
+ if (indexes.some(index => databaseIndexReferences(index).some(column => !outputNames.has(column)))) {
245
+ return `Database View "${String(record.name || viewIdOf(record))}" index references an unknown output column`;
265
246
  }
266
247
  return {
267
248
  uniqueKey: [...record.uniqueKey],
@@ -809,10 +790,7 @@ function createDatabaseViewPayload(manifest) {
809
790
  };
810
791
  }
811
792
  function databaseViewWriteIndexes(indexes) {
812
- return indexes?.map((index) => ({
813
- columns: index.columns.map((name) => ({ name })),
814
- ...(index.unique === true ? { unique: true } : {}),
815
- }));
793
+ return databaseIndexPayload(indexes);
816
794
  }
817
795
  function assertTargetPreviewMatchesManifest(manifest, preview) {
818
796
  const output = previewOutput(preview);