@revoengine/cli 1.0.20 → 1.0.22

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 (44) hide show
  1. package/README.md +48 -10
  2. package/dist/src/cli.js +5 -1
  3. package/dist/src/client.d.ts +37 -8
  4. package/dist/src/client.js +58 -0
  5. package/dist/src/commands/agents.d.ts +2 -0
  6. package/dist/src/commands/agents.js +56 -0
  7. package/dist/src/commands/component.js +19 -0
  8. package/dist/src/commands/env.js +8 -5
  9. package/dist/src/commands/index.d.ts +1 -0
  10. package/dist/src/commands/index.js +1 -0
  11. package/dist/src/commands/migrate.js +19 -3
  12. package/dist/src/commands/schedules.js +11 -9
  13. package/dist/src/component-contract.d.ts +8 -0
  14. package/dist/src/component-contract.js +68 -0
  15. package/dist/src/component-lock.d.ts +6 -2
  16. package/dist/src/component-lock.js +42 -2
  17. package/dist/src/database-indexes.d.ts +14 -0
  18. package/dist/src/database-indexes.js +124 -0
  19. package/dist/src/env-sync.d.ts +2 -0
  20. package/dist/src/env-sync.js +18 -2
  21. package/dist/src/metadata-backfill.js +39 -1
  22. package/dist/src/migration-actions.js +1 -1
  23. package/dist/src/migration.d.ts +9 -2
  24. package/dist/src/migration.js +61 -2
  25. package/dist/src/resource-inventory.d.ts +4 -2
  26. package/dist/src/resource-inventory.js +11 -1
  27. package/dist/src/resource-syncs/agent-sync.d.ts +98 -0
  28. package/dist/src/resource-syncs/agent-sync.js +612 -0
  29. package/dist/src/resource-syncs/database-table-sync.d.ts +3 -0
  30. package/dist/src/resource-syncs/database-table-sync.js +10 -6
  31. package/dist/src/resource-syncs/database-view-sync.d.ts +2 -4
  32. package/dist/src/resource-syncs/database-view-sync.js +16 -38
  33. package/dist/src/resource-syncs/endpoint-sync.js +53 -26
  34. package/dist/src/resource-syncs/job-template-sync.d.ts +1 -0
  35. package/dist/src/resource-syncs/job-template-sync.js +31 -10
  36. package/dist/src/resource-syncs/schedule-sync.d.ts +7 -3
  37. package/dist/src/resource-syncs/schedule-sync.js +85 -16
  38. package/dist/src/tracked-resources.d.ts +1 -1
  39. package/dist/src/tracked-resources.js +4 -2
  40. package/dist/src/types.d.ts +14 -0
  41. package/dist/src/ui.js +6 -2
  42. package/dist/src/workspace-diff.js +2 -0
  43. package/dist/src/workspace-prune.js +38 -2
  44. package/package.json +2 -2
@@ -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
+ }
@@ -119,6 +119,8 @@ export type RevoLockFile = {
119
119
  groups: Record<string, GroupLockEntry>;
120
120
  roleGroups: Record<string, RoleGroupLockEntry>;
121
121
  serviceAccounts: Record<string, RoleGroupLockEntry>;
122
+ agents: Record<string, RoleGroupLockEntry>;
123
+ agentPlugins: Record<string, RoleGroupLockEntry>;
122
124
  jobTemplates: Record<string, JobTemplateLockEntry>;
123
125
  schedules: Record<string, ScheduleLockEntry>;
124
126
  events: Record<string, EventLockEntry>;
@@ -136,6 +138,7 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
136
138
  active: boolean;
137
139
  type: string;
138
140
  async: boolean;
141
+ metadata: Record<string, unknown>;
139
142
  elements: {
140
143
  key: string;
141
144
  desc: string | null;
@@ -152,6 +155,7 @@ export declare function normalizePortableComponentSource(component: ComponentRec
152
155
  active: boolean;
153
156
  type: string;
154
157
  async: boolean;
158
+ metadata: Record<string, unknown>;
155
159
  elements: {
156
160
  key: string;
157
161
  desc: string | null;
@@ -161,10 +165,10 @@ export declare function normalizePortableComponentSource(component: ComponentRec
161
165
  }[];
162
166
  };
163
167
  export declare function hashPortableComponentSource(component: ComponentRecord): string;
164
- 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"];
165
169
  export type PortableComponentConfigField = (typeof PORTABLE_COMPONENT_CONFIG_FIELDS)[number];
166
170
  export declare function diffPortableComponentSource(source: ComponentRecord, target: ComponentRecord): {
167
- configurationFields: ("desc" | "name" | "category" | "type" | "active" | "async")[];
171
+ configurationFields: ("metadata" | "desc" | "name" | "category" | "type" | "active" | "async")[];
168
172
  elementsChanged: boolean;
169
173
  changedFields: string[];
170
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,
@@ -156,6 +158,8 @@ export function readComponentLock(projectRoot) {
156
158
  groups: {},
157
159
  roleGroups: {},
158
160
  serviceAccounts: {},
161
+ agents: {},
162
+ agentPlugins: {},
159
163
  jobTemplates: {},
160
164
  schedules: {},
161
165
  events: {},
@@ -229,6 +233,40 @@ export function readComponentLock(projectRoot) {
229
233
  syncedAt: String(baseline.syncedAt),
230
234
  }])),
231
235
  }])),
236
+ agents: Object.fromEntries(Object.entries(raw.agents && typeof raw.agents === 'object' ? raw.agents : {})
237
+ .filter(([, entry]) => (typeof entry.stableKey === 'string'
238
+ && typeof entry.path === 'string'
239
+ && typeof entry.sourceHash === 'string'
240
+ && entry.environments
241
+ && typeof entry.environments === 'object'))
242
+ .map(([key, entry]) => [key, {
243
+ stableKey: String(entry.stableKey),
244
+ path: String(entry.path),
245
+ sourceHash: String(entry.sourceHash),
246
+ environments: Object.fromEntries(Object.entries(entry.environments)
247
+ .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
248
+ .map(([envName, baseline]) => [envName, {
249
+ remoteHash: String(baseline.remoteHash),
250
+ syncedAt: String(baseline.syncedAt),
251
+ }])),
252
+ }])),
253
+ agentPlugins: Object.fromEntries(Object.entries(raw.agentPlugins && typeof raw.agentPlugins === 'object' ? raw.agentPlugins : {})
254
+ .filter(([, entry]) => (typeof entry.stableKey === 'string'
255
+ && typeof entry.path === 'string'
256
+ && typeof entry.sourceHash === 'string'
257
+ && entry.environments
258
+ && typeof entry.environments === 'object'))
259
+ .map(([key, entry]) => [key, {
260
+ stableKey: String(entry.stableKey),
261
+ path: String(entry.path),
262
+ sourceHash: String(entry.sourceHash),
263
+ environments: Object.fromEntries(Object.entries(entry.environments)
264
+ .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
265
+ .map(([envName, baseline]) => [envName, {
266
+ remoteHash: String(baseline.remoteHash),
267
+ syncedAt: String(baseline.syncedAt),
268
+ }])),
269
+ }])),
232
270
  serviceAccounts: Object.fromEntries(Object.entries(raw.serviceAccounts && typeof raw.serviceAccounts === 'object' ? raw.serviceAccounts : {})
233
271
  .filter(([, entry]) => (typeof entry.stableKey === 'string'
234
272
  && typeof entry.path === 'string'
@@ -399,6 +437,8 @@ export function writeComponentLock(projectRoot, lock) {
399
437
  components: sortedComponents,
400
438
  ...(Object.keys(sortedGroups).length > 0 ? { groups: sortedGroups } : {}),
401
439
  roleGroups: sortedRoleGroups,
440
+ ...(Object.keys(lock.agents || {}).length ? { agents: lock.agents } : {}),
441
+ ...(Object.keys(lock.agentPlugins || {}).length ? { agentPlugins: lock.agentPlugins } : {}),
402
442
  ...(Object.keys(lock.serviceAccounts || {}).length ? { serviceAccounts: lock.serviceAccounts } : {}),
403
443
  jobTemplates: sortedJobTemplates,
404
444
  ...(Object.keys(sortedSchedules).length > 0 ? { schedules: sortedSchedules } : {}),
@@ -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.`);
@@ -582,6 +582,21 @@ export async function buildMetadataBackfillPlan(input) {
582
582
  });
583
583
  }
584
584
  }
585
+ for (const [family, method] of [['agent', 'listAllAgents'], ['agent-plugin', 'listAllAgentPlugins']]) {
586
+ if (!shouldTrackResource(trackedResources, family) || typeof client[method] !== 'function')
587
+ continue;
588
+ for await (const { resource } of readResourceInventory(client, family)) {
589
+ if (resource.deletedAt || resource.deletedBy)
590
+ continue;
591
+ const raw = rawConfiguredStableKey(resource, stableKeyName);
592
+ const invalid = raw.present && (typeof raw.value !== 'string' || !raw.value.trim());
593
+ const existing = readConfiguredResourceMetadataStableKey(resource, stableKeyName);
594
+ items.push({ resourceType: family, resourceId: resourceIdOf(resource), name: String(resource.name || ''), category: resource.category || null,
595
+ action: invalid ? 'blocked' : existing && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
596
+ stableKey: existing && !force ? existing : buildNamedResourceGeneratedStableKey(resource),
597
+ reason: invalid ? 'Invalid Stable Key; refusing to overwrite.' : existing && !force ? 'stable key already exists' : 'assign-stable-key' });
598
+ }
599
+ }
585
600
  if (shouldTrackResource(trackedResources, 'job-template') && typeof client.listAllJobTemplates === 'function') {
586
601
  for await (const { listedId, resource: jobTemplate } of readResourceInventory(client, 'job-template')) {
587
602
  if (!listedId) {
@@ -747,7 +762,7 @@ export async function applyMetadataBackfillPlan(input) {
747
762
  const resourceTypes = new Set(plan.items.map((item) => item.resourceType));
748
763
  const readOrder = [
749
764
  'component', 'database-table', 'database-view', 'endpoint',
750
- 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event',
765
+ 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event', 'agent-plugin', 'agent',
751
766
  ];
752
767
  for (const resourceType of readOrder) {
753
768
  if (!resourceTypes.has(resourceType)) {
@@ -833,6 +848,29 @@ export async function applyMetadataBackfillPlan(input) {
833
848
  throw new Error(`Unsupported metadata plan action: ${item.action}.`);
834
849
  }
835
850
  try {
851
+ if (item.resourceType === 'agent' || item.resourceType === 'agent-plugin') {
852
+ const live = unwrapResource(item.resourceType === 'agent' ? await client.getAgent(item.resourceId) : await client.getAgentPlugin(item.resourceId));
853
+ if (live.deletedAt || live.deletedBy || !Number.isInteger(live.version))
854
+ throw new Error('Active target and current version are required.');
855
+ const raw = rawConfiguredStableKey(live, plan.stableKeyName);
856
+ if (raw.present && (typeof raw.value !== 'string' || !raw.value.trim()))
857
+ throw new Error('Invalid current Stable Key.');
858
+ const existing = readConfiguredResourceMetadataStableKey(live, plan.stableKeyName);
859
+ if (existing && !plan.force) {
860
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: existing, action: 'skip' });
861
+ continue;
862
+ }
863
+ const metadata = { ...sanitizeUserMetadata(live.metadata), [plan.stableKeyName]: item.stableKey };
864
+ if (item.resourceType === 'agent')
865
+ await client.updateAgent(item.resourceId, { metadata, version: live.version });
866
+ else
867
+ await client.updateAgentPlugin(item.resourceId, { metadata, version: live.version });
868
+ const verified = unwrapResource(item.resourceType === 'agent' ? await client.getAgent(item.resourceId) : await client.getAgentPlugin(item.resourceId));
869
+ if (readConfiguredResourceMetadataStableKey(verified, plan.stableKeyName) !== item.stableKey)
870
+ throw new Error('Agent metadata readback differs; write unverified.');
871
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: item.stableKey, action: 'update' });
872
+ continue;
873
+ }
836
874
  if (item.resourceType === 'component') {
837
875
  const component = currentResources.get(`component:${item.resourceId}`);
838
876
  if (!component)
@@ -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';
@@ -1,3 +1,4 @@
1
+ import { type AgentSyncPlan, type AgentSyncPull, type AgentSyncResult } from './resource-syncs/agent-sync.ts';
1
2
  import { type MigrationResourcePlan } from './migration-actions.ts';
2
3
  import { type WorkspacePrunePlan } from './workspace-prune.ts';
3
4
  import { type ServiceAccountsPlan, type ServiceAccountPullResult, type ServiceAccountPushResult } from './resource-syncs/service-account-sync.ts';
@@ -11,12 +12,12 @@ import { type GroupPullResult, type GroupPushResult, type GroupsPlan } from './r
11
12
  import { type JobTemplatePullResult, type JobTemplatePushResult, type JobTemplatesPlan } from './resource-syncs/job-template-sync.ts';
12
13
  import { type SchedulePullResult, type SchedulePushResult, type SchedulesPlan } from './resource-syncs/schedule-sync.ts';
13
14
  import { type RoleGroupPullResult, type RoleGroupPushResult, type RoleGroupsPlan } from './resource-syncs/role-group-sync.ts';
14
- export type MigrationResource = 'database-table' | 'database-view' | 'component' | 'job-template' | 'endpoint' | 'schedule' | 'event' | 'group' | 'role-group' | 'service-account';
15
+ export type MigrationResource = 'database-table' | 'database-view' | 'component' | 'job-template' | 'endpoint' | 'schedule' | 'event' | 'group' | 'role-group' | 'service-account' | 'agent-plugin' | 'agent';
15
16
  export type MigrationVerdict = 'ready' | 'ready-with-warnings' | 'blocked';
16
17
  export type MigrationOperations = Record<'noop' | 'create' | 'update' | 'adopt' | 'excluded' | 'blocked', number> & {
17
18
  delete?: number;
18
19
  };
19
- type MigrationPushResult = DatabaseSchemaPushResult | DatabaseViewPushResult | ComponentSyncResult | JobTemplatePushResult | EndpointPushResult | SchedulePushResult | EventPushResult | GroupPushResult | RoleGroupPushResult | ServiceAccountPushResult;
20
+ type MigrationPushResult = DatabaseSchemaPushResult | DatabaseViewPushResult | ComponentSyncResult | JobTemplatePushResult | EndpointPushResult | SchedulePushResult | EventPushResult | GroupPushResult | RoleGroupPushResult | ServiceAccountPushResult | AgentSyncResult;
20
21
  export type MigrationPhasePlan = {
21
22
  order: number;
22
23
  resource: MigrationResource;
@@ -69,6 +70,8 @@ export type MigrationPlan = {
69
70
  groups?: MigrationResourcePlan<GroupsPlan>;
70
71
  roleGroups?: MigrationResourcePlan<RoleGroupsPlan>;
71
72
  serviceAccounts?: MigrationResourcePlan<ServiceAccountsPlan>;
73
+ agentPlugins?: MigrationResourcePlan<AgentSyncPlan>;
74
+ agents?: MigrationResourcePlan<AgentSyncPlan>;
72
75
  warnings: string[];
73
76
  blockers: string[];
74
77
  };
@@ -93,6 +96,8 @@ export type MigrationRun = {
93
96
  groups?: GroupPullResult;
94
97
  roleGroups?: RoleGroupPullResult;
95
98
  serviceAccounts?: ServiceAccountPullResult;
99
+ agentPlugins?: AgentSyncPull;
100
+ agents?: AgentSyncPull;
96
101
  };
97
102
  plan: MigrationPlan;
98
103
  results: MigrationPushResult[];
@@ -132,6 +137,8 @@ export type ResourcePullResults = {
132
137
  groups?: GroupPullResult;
133
138
  roleGroups?: RoleGroupPullResult;
134
139
  serviceAccounts?: ServiceAccountPullResult;
140
+ agentPlugins?: AgentSyncPull;
141
+ agents?: AgentSyncPull;
135
142
  };
136
143
  export type ResourcePullInput = {
137
144
  cwd: string;