@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/config.js

@@ -74,16 +74,44 @@ export function saveStoredConfig(nextConfig) {
     ensureDirectory(dir);
     const current = readStoredConfigFile();
     const instance = nextConfig.instance || current.instance || '';
+    const environments = nextConfig.environments ?? current.environments;
+    const activeEnvironment = nextConfig.activeEnvironment ?? current.activeEnvironment;
     const config = {
         baseUrl: nextConfig.baseUrl || current.baseUrl || DEFAULT_BASE_URL,
         token: nextConfig.token || current.token || '',
         ...(instance ? { instance } : {}),
+        ...(environments && Object.keys(environments).length > 0 ? { environments } : {}),
+        ...(activeEnvironment && activeEnvironment !== DEFAULT_ENV_NAME ? { activeEnvironment } : {}),
     };
     writeJsonFile(configFile, config);
     removeFileIfExists(credentialsFile);
 }
 export function clearStoredConfig() {
-    const { configFile, credentialsFile, authStateFile } = getConfigPaths();
+    const { dir, configFile, credentialsFile, authStateFile } = getConfigPaths();
+    // Logout clears the default login but must not destroy named environment
+    // profiles stored alongside it.
+    const stored = readStoredConfigFile();
+    const environments = stored.environments;
+    if (environments && Object.keys(environments).length > 0) {
+        ensureDirectory(dir);
+        writeJsonFile(configFile, {
+            baseUrl: DEFAULT_BASE_URL,
+            token: '',
+            environments,
+            ...(stored.activeEnvironment ? { activeEnvironment: stored.activeEnvironment } : {}),
+        });
+        for (const filePath of [credentialsFile, authStateFile]) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch (error) {
+                if (!error || error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+        }
+        return;
+    }
     for (const filePath of [configFile, credentialsFile, authStateFile]) {
         try {
             fs.unlinkSync(filePath);
@@ -144,6 +172,24 @@ function normalizeInstanceConfig(value) {
         token: typeof value.token === 'string' ? value.token : '',
     };
 }
+function parseEnvironmentProfiles(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const environments = {};
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isRecord(entry) || typeof entry.baseUrl !== 'string' || typeof entry.token !== 'string') {
+            continue;
+        }
+        environments[name] = {
+            baseUrl: entry.baseUrl,
+            token: entry.token,
+            ...(typeof entry.instance === 'string' && isUuid(entry.instance) ? { instance: entry.instance } : {}),
+            ...(entry.production === true ? { production: true } : {}),
+        };
+    }
+    return Object.keys(environments).length > 0 ? environments : null;
+}
 function parseFlatConfig(raw, credentials) {
     if (!isRecord(raw) || isRecord(raw.instances)) {
         return null;
@@ -153,6 +199,12 @@ function parseFlatConfig(raw, credentials) {
         : isRecord(credentials) && typeof credentials.token === 'string'
             ? credentials.token
             : '';
+    const environments = parseEnvironmentProfiles(raw.environments);
+    const activeEnvironment = typeof raw.activeEnvironment === 'string'
+        && raw.activeEnvironment !== DEFAULT_ENV_NAME
+        && environments?.[raw.activeEnvironment]
+        ? raw.activeEnvironment
+        : undefined;
     return {
         baseUrl: typeof raw.baseUrl === 'string'
             ? raw.baseUrl
@@ -160,6 +212,8 @@ function parseFlatConfig(raw, credentials) {
                 ? raw.url
                 : DEFAULT_BASE_URL,
         ...(typeof raw.instance === 'string' && isUuid(raw.instance) ? { instance: raw.instance } : {}),
+        ...(environments ? { environments } : {}),
+        ...(activeEnvironment ? { activeEnvironment } : {}),
         token,
     };
 }
@@ -181,14 +235,25 @@ function parseMappedConfig(raw) {
     const defaultInstance = isUuid(configuredDefault) && instances[configuredDefault]
         ? configuredDefault
         : Object.keys(instances)[0] || '';
+    const environments = parseEnvironmentProfiles(raw.environments);
+    const activeEnvironment = typeof raw.activeEnvironment === 'string'
+        && raw.activeEnvironment !== DEFAULT_ENV_NAME
+        && environments?.[raw.activeEnvironment]
+        ? raw.activeEnvironment
+        : undefined;
     const selected = defaultInstance ? instances[defaultInstance] : undefined;
-    return selected
+    const base = selected
         ? {
             baseUrl: selected.baseUrl,
             instance: defaultInstance,
             token: selected.token,
         }
         : emptyStoredConfigFile();
+    return {
+        ...base,
+        ...(environments ? { environments } : {}),
+        ...(activeEnvironment ? { activeEnvironment } : {}),
+    };
 }
 function parseLegacyConfig(config, credentials) {
     const baseUrl = isRecord(config) && typeof config.baseUrl === 'string'
@@ -256,6 +321,7 @@ function mergeWithLegacy(stored, options = {}) {
         return stored;
     }
     const merged = {
+        ...stored,
         baseUrl: stored.baseUrl || legacy.baseUrl || DEFAULT_BASE_URL,
         token: stored.token || legacy.token || '',
     };
@@ -267,6 +333,38 @@ function mergeWithLegacy(stored, options = {}) {
 export function loadStoredConfig(options = {}) {
     return mergeWithLegacy(readStoredConfig(), options);
 }
+export function listEnvironmentProfiles() {
+    return readStoredConfigFile().environments || {};
+}
+export function getEnvironmentProfile(name) {
+    return listEnvironmentProfiles()[name] || null;
+}
+export const DEFAULT_ENV_NAME = 'default';
+export function getActiveEnvironmentName() {
+    return readStoredConfigFile().activeEnvironment || DEFAULT_ENV_NAME;
+}
+export function setActiveEnvironmentName(name) {
+    if (name !== DEFAULT_ENV_NAME && !getEnvironmentProfile(name)) {
+        throw new Error(`Unknown project "${name}". Run 'revo projects list' to see saved projects.`);
+    }
+    saveStoredConfig({ activeEnvironment: name });
+}
+export function saveEnvironmentProfile(name, profile, options = {}) {
+    const environments = { ...listEnvironmentProfiles(), [name]: profile };
+    saveStoredConfig({ environments, ...(options.activate ? { activeEnvironment: name } : {}) });
+}
+export function removeEnvironmentProfile(name) {
+    const environments = listEnvironmentProfiles();
+    if (!(name in environments)) {
+        return false;
+    }
+    delete environments[name];
+    saveStoredConfig({
+        environments,
+        ...(getActiveEnvironmentName() === name ? { activeEnvironment: DEFAULT_ENV_NAME } : {}),
+    });
+    return true;
+}
 export function buildAuthValidationKey(runtime) {
     return createHash('sha256')
         .update(JSON.stringify({
@@ -363,10 +461,27 @@ export function resolveRuntimeConfig(options = {}) {
         instance: resolveEnvValue(['REVO_INSTANCE', 'REVOENGINE_INSTANCE']),
         token: resolveEnvValue(['REVO_TOKEN', 'REVO_API_KEY', 'REVOENGINE_TOKEN', 'REVOENGINE_API_KEY']),
     };
-    const stored = loadStoredConfig();
+    const stored = readStoredConfigFile();
+    // A named profile is an explicit selection and resolves exclusively: no
+    // fallback to env vars or the stored default, or --from/--to could silently
+    // mix one environment's URL with another environment's token or instance.
+    const envName = options.envName || stored.activeEnvironment || DEFAULT_ENV_NAME;
+    if (envName !== DEFAULT_ENV_NAME) {
+        const profile = stored.environments?.[envName];
+        if (!profile) {
+            throw new Error(`Unknown project "${envName}". Run 'revo projects list' to see saved projects.`);
+        }
+        return {
+            baseUrl: options.baseUrl || profile.baseUrl || DEFAULT_BASE_URL,
+            instance: options.instance ?? (profile.instance || ''),
+            token: options.token || profile.token || '',
+            ...(profile.production ? { production: true } : {}),
+        };
+    }
+    const defaultStored = mergeWithLegacy(stored);
     return {
-        baseUrl: options.baseUrl || env.baseUrl || stored.baseUrl || DEFAULT_BASE_URL,
-        instance: options.instance || env.instance || stored.instance || '',
-        token: options.token || env.token || stored.token || '',
+        baseUrl: options.baseUrl || env.baseUrl || defaultStored.baseUrl || DEFAULT_BASE_URL,
+        instance: options.instance ?? (env.instance || defaultStored.instance || ''),
+        token: options.token || env.token || defaultStored.token || '',
     };
 }

package/dist/src/database-schema-artifacts.d.ts

@@ -0,0 +1,7 @@
+export declare const DATABASE_BACKUP_CATEGORY = "Database Backup";
+export declare function isDatabaseBackupArtifact(value: {
+    category?: unknown;
+}): boolean;
+export declare function excludeDatabaseBackupArtifacts<T extends {
+    category?: unknown;
+}>(records: readonly T[]): T[];

package/dist/src/database-schema-artifacts.js

@@ -0,0 +1,8 @@
+export const DATABASE_BACKUP_CATEGORY = 'Database Backup';
+export function isDatabaseBackupArtifact(value) {
+    return typeof value.category === 'string'
+        && value.category.trim() === DATABASE_BACKUP_CATEGORY;
+}
+export function excludeDatabaseBackupArtifacts(records) {
+    return records.filter((record) => !isDatabaseBackupArtifact(record));
+}

package/dist/src/env-sync.d.ts

@@ -0,0 +1,83 @@
+import type { RevoClient } from './client.ts';
+import { normalizePortableComponentSource } from './component-lock.ts';
+import type { ComponentRecord } from './types.ts';
+export type EnvRef = {
+    env: string;
+    baseUrl: string;
+    instance: string;
+};
+export type PortableComponentSource = ReturnType<typeof normalizePortableComponentSource>;
+export type EnvComponentEntry = {
+    stableKey: string;
+    componentId: string;
+    component: ComponentRecord;
+    portable: PortableComponentSource;
+    portableHash: string;
+};
+export type EnvCollision = {
+    stableKey: string;
+    components: Array<{
+        componentId: string;
+        name: string;
+    }>;
+};
+export type EnvSnapshot = {
+    ref: EnvRef;
+    components: Map<string, EnvComponentEntry>;
+    collisions: EnvCollision[];
+};
+export type EnvSyncAction = 'create' | 'update' | 'delete' | 'orphan' | 'noop' | 'collision';
+export type EnvSyncPlanItem = {
+    resourceType: 'component';
+    stableKey: string;
+    action: EnvSyncAction;
+    name: string;
+    category: string | null;
+    sourceComponentId: string | null;
+    targetComponentId: string | null;
+    sourceHash: string | null;
+    targetHash: string | null;
+    changedFields?: string[];
+    addedElementKeys?: string[];
+    removedElementKeys?: string[];
+    changedElementKeys?: string[];
+    reason: string;
+};
+export type EnvSyncScope = {
+    keys?: string[];
+    categories?: string[];
+};
+export type EnvSyncPlan = {
+    schemaVersion: 1;
+    generatedAt: string;
+    from: EnvRef;
+    to: EnvRef;
+    prune: boolean;
+    scope?: EnvSyncScope;
+    counts: Record<EnvSyncAction, number>;
+    items: EnvSyncPlanItem[];
+};
+export type EnvApplyItemResult = {
+    stableKey: string;
+    action: EnvSyncAction;
+    status: 'applied' | 'failed';
+    verified?: boolean;
+    error?: string;
+};
+export declare function normalizeKeyPart(value: string | null | undefined): string;
+export declare function buildStableKey(component: ComponentRecord, stableKeyName?: string): string;
+export declare function captureEnvSnapshot(client: RevoClient, envName: string, options?: {
+    stableKeyName?: string;
+}): Promise<EnvSnapshot>;
+export declare function buildEnvSyncPlan(source: EnvSnapshot, target: EnvSnapshot, options: {
+    prune: boolean;
+    scope?: EnvSyncScope;
+}): EnvSyncPlan;
+export declare function applyEnvSyncPlan(input: {
+    targetClient: RevoClient;
+    plan: EnvSyncPlan;
+    source: EnvSnapshot;
+    target: EnvSnapshot;
+    stableKeyName?: string;
+    onItem?: (result: EnvApplyItemResult) => void;
+}): Promise<EnvApplyItemResult[]>;

package/dist/src/env-sync.js

@@ -0,0 +1,315 @@
+import { buildPortableComponentUpdatePayload, diffPortableComponentSource, hashPortableComponentSource, normalizePortableComponentSource, sanitizeComponentSource, } from "./component-lock.js";
+import { buildStableKey as buildComponentStableKey, DEFAULT_STABLE_KEY_NAME, NULL_CATEGORY_KEY, sanitizeUserMetadata, } from "./resource-metadata.js";
+export function normalizeKeyPart(value) {
+    return (value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+export function buildStableKey(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    return buildComponentStableKey(component, stableKeyName);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapComponent(value) {
+    if (isRecord(value) && isRecord(value.data)) {
+        return value.data;
+    }
+    return value;
+}
+function componentIdOf(component) {
+    return String(component.componentId || component.id || '');
+}
+export async function captureEnvSnapshot(client, envName, options = {}) {
+    const { components: summaries } = await client.listAllComponents();
+    const byStableKey = new Map();
+    for (const summary of summaries) {
+        const componentId = componentIdOf(summary);
+        if (!componentId) {
+            continue;
+        }
+        const component = unwrapComponent(await client.getComponent(componentId));
+        const stableKey = buildStableKey(component, options.stableKeyName);
+        const entry = {
+            stableKey,
+            componentId,
+            component,
+            portable: normalizePortableComponentSource(component),
+            portableHash: hashPortableComponentSource(component),
+        };
+        const bucket = byStableKey.get(stableKey);
+        if (bucket) {
+            bucket.push(entry);
+        }
+        else {
+            byStableKey.set(stableKey, [entry]);
+        }
+    }
+    const components = new Map();
+    const collisions = [];
+    for (const [stableKey, entries] of byStableKey) {
+        if (entries.length === 1) {
+            components.set(stableKey, entries[0]);
+            continue;
+        }
+        collisions.push({
+            stableKey,
+            components: entries.map((entry) => ({
+                componentId: entry.componentId,
+                name: String(entry.component.name || ''),
+            })),
+        });
+    }
+    collisions.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    return {
+        ref: {
+            env: envName,
+            baseUrl: client.baseUrl,
+            instance: client.instance,
+        },
+        components,
+        collisions,
+    };
+}
+function diffElementKeys(source, target) {
+    const sourceByKey = new Map(source.elements.map((element) => [element.key, element]));
+    const targetByKey = new Map(target.elements.map((element) => [element.key, element]));
+    const addedElementKeys = [];
+    const changedElementKeys = [];
+    for (const [key, element] of sourceByKey) {
+        const other = targetByKey.get(key);
+        if (!other) {
+            addedElementKeys.push(key);
+        }
+        else if (JSON.stringify(element) !== JSON.stringify(other)) {
+            changedElementKeys.push(key);
+        }
+    }
+    const removedElementKeys = [...targetByKey.keys()].filter((key) => !sourceByKey.has(key));
+    return { addedElementKeys, removedElementKeys, changedElementKeys };
+}
+function buildScopeFilter(scope) {
+    const keys = scope?.keys?.map((key) => normalizeKeyPart(key)).filter(Boolean);
+    const categories = scope?.categories?.map((category) => normalizeKeyPart(category) || NULL_CATEGORY_KEY);
+    if ((!keys || keys.length === 0) && (!categories || categories.length === 0)) {
+        return () => true;
+    }
+    return (stableKey) => {
+        if (keys && keys.length > 0 && keys.includes(stableKey)) {
+            return true;
+        }
+        if (categories && categories.length > 0) {
+            const categoryPart = stableKey.slice(0, stableKey.lastIndexOf('/'));
+            return categories.includes(categoryPart);
+        }
+        return false;
+    };
+}
+function emptyCounts() {
+    return {
+        create: 0,
+        update: 0,
+        delete: 0,
+        orphan: 0,
+        noop: 0,
+        collision: 0,
+    };
+}
+export function buildEnvSyncPlan(source, target, options) {
+    const inScope = buildScopeFilter(options.scope);
+    const items = [];
+    const collisionKeys = new Set();
+    for (const [envLabel, snapshot] of [['source', source], ['target', target]]) {
+        for (const collision of snapshot.collisions) {
+            if (!inScope(collision.stableKey) || collisionKeys.has(`${envLabel}:${collision.stableKey}`)) {
+                continue;
+            }
+            collisionKeys.add(`${envLabel}:${collision.stableKey}`);
+            items.push({
+                resourceType: 'component',
+                stableKey: collision.stableKey,
+                action: 'collision',
+                name: collision.components[0]?.name || '',
+                category: null,
+                sourceComponentId: null,
+                targetComponentId: null,
+                sourceHash: null,
+                targetHash: null,
+                reason: `${collision.components.length} components share this key in ${envLabel} (${snapshot.ref.env}): ${collision.components.map((component) => component.componentId).join(', ')}`,
+            });
+        }
+    }
+    const blockedKeys = new Set([...source.collisions, ...target.collisions].map((collision) => collision.stableKey));
+    const allKeys = new Set([...source.components.keys(), ...target.components.keys()]);
+    for (const stableKey of allKeys) {
+        if (!inScope(stableKey) || blockedKeys.has(stableKey)) {
+            continue;
+        }
+        const sourceEntry = source.components.get(stableKey);
+        const targetEntry = target.components.get(stableKey);
+        const reference = (sourceEntry || targetEntry);
+        const base = {
+            resourceType: 'component',
+            stableKey,
+            name: String(reference.component.name || ''),
+            category: reference.portable.category,
+            sourceComponentId: sourceEntry?.componentId ?? null,
+            targetComponentId: targetEntry?.componentId ?? null,
+            sourceHash: sourceEntry?.portableHash ?? null,
+            targetHash: targetEntry?.portableHash ?? null,
+        };
+        if (sourceEntry && !targetEntry) {
+            items.push({ ...base, action: 'create', reason: 'missing in target' });
+            continue;
+        }
+        if (!sourceEntry && targetEntry) {
+            items.push(options.prune
+                ? { ...base, action: 'delete', reason: 'missing in source' }
+                : { ...base, action: 'orphan', reason: 'missing in source; use --prune to delete' });
+            continue;
+        }
+        if (sourceEntry.portableHash === targetEntry.portableHash) {
+            items.push({ ...base, action: 'noop', reason: 'up to date' });
+            continue;
+        }
+        const changedFields = diffPortableComponentSource(sourceEntry.component, targetEntry.component).configurationFields;
+        const elementDiff = diffElementKeys(sourceEntry.portable, targetEntry.portable);
+        items.push({
+            ...base,
+            action: 'update',
+            changedFields,
+            ...elementDiff,
+            reason: 'source and target content differ',
+        });
+    }
+    items.sort((left, right) => left.stableKey.localeCompare(right.stableKey)
+        || left.action.localeCompare(right.action));
+    const counts = emptyCounts();
+    for (const item of items) {
+        counts[item.action] += 1;
+    }
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        from: source.ref,
+        to: target.ref,
+        prune: options.prune,
+        ...(options.scope && (options.scope.keys?.length || options.scope.categories?.length)
+            ? { scope: options.scope }
+            : {}),
+        counts,
+        items,
+    };
+}
+// Mirrors the push payload shape, but componentElementIds never cross
+// environments: they are only set when they belong to the target component.
+function buildPortableElementPayload(component, targetElementsByKey) {
+    return [...(component.elements || [])].map((element) => {
+        const targetElementId = targetElementsByKey?.get(element.key)?.componentElementId;
+        return {
+            ...(typeof targetElementId === 'string' && targetElementId
+                ? { componentElementId: targetElementId }
+                : {}),
+            key: element.key,
+            desc: element.desc,
+            details: element.details || '',
+            hidden: Boolean(element.hidden),
+            order: element.order,
+        };
+    });
+}
+function compilerFromType(type, compiler) {
+    if (compiler) {
+        return compiler;
+    }
+    return (type || '').toLowerCase().includes('ts') ? 'typescript' : 'javascript';
+}
+function buildCreatePayload(component) {
+    const sanitized = sanitizeComponentSource(component);
+    return {
+        name: sanitized.name || '',
+        category: sanitized.category ?? null,
+        desc: sanitized.desc ?? null,
+        type: sanitized.type || '',
+        compiler: compilerFromType(sanitized.type, sanitized.compiler),
+        active: sanitized.active ?? true,
+        async: Boolean(sanitized.async),
+        metadata: sanitizeUserMetadata(component.metadata),
+        elements: buildPortableElementPayload(component),
+    };
+}
+async function verifyAppliedComponent(targetClient, componentId, expectedHash) {
+    const component = unwrapComponent(await targetClient.getComponent(componentId));
+    return hashPortableComponentSource(component) === expectedHash;
+}
+export async function applyEnvSyncPlan(input) {
+    const { targetClient, plan, source, target, stableKeyName, onItem } = input;
+    const collisions = plan.items.filter((item) => item.action === 'collision');
+    if (collisions.length > 0) {
+        throw new Error(`Cannot apply: ${collisions.length} stable-key collision(s) in scope. Resolve duplicates or narrow the scope with --key/--category.`);
+    }
+    const ordered = [
+        ...plan.items.filter((item) => item.action === 'create'),
+        ...plan.items.filter((item) => item.action === 'update'),
+        ...plan.items.filter((item) => item.action === 'delete'),
+    ];
+    const results = [];
+    for (const item of ordered) {
+        const result = await applyPlanItem(targetClient, item, source, target, stableKeyName);
+        results.push(result);
+        onItem?.(result);
+    }
+    return results;
+}
+async function applyPlanItem(targetClient, item, source, target, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    try {
+        if (item.action === 'create') {
+            const sourceEntry = source.components.get(item.stableKey);
+            if (!sourceEntry) {
+                throw new Error('source component disappeared from the snapshot');
+            }
+            const created = unwrapComponent(await targetClient.createComponent(buildCreatePayload(sourceEntry.component)));
+            const newComponentId = componentIdOf(created);
+            if (!newComponentId) {
+                throw new Error('create response did not include a componentId');
+            }
+            // The save endpoint is the authoritative element write; re-sending the
+            // elements guards against create endpoints that ignore inline elements.
+            await targetClient.saveComponentElements(newComponentId, buildPortableElementPayload(sourceEntry.component));
+            const verified = await verifyAppliedComponent(targetClient, newComponentId, sourceEntry.portableHash);
+            return { stableKey: item.stableKey, action: item.action, status: 'applied', verified };
+        }
+        if (item.action === 'update') {
+            const sourceEntry = source.components.get(item.stableKey);
+            const targetEntry = target.components.get(item.stableKey);
+            if (!sourceEntry || !targetEntry) {
+                throw new Error('component disappeared from the snapshot');
+            }
+            if (item.changedFields && item.changedFields.length > 0) {
+                await targetClient.updateComponent(targetEntry.componentId, buildPortableComponentUpdatePayload(sourceEntry.component, targetEntry.component, item.changedFields));
+            }
+            const hasElementChanges = Boolean(item.addedElementKeys?.length || item.removedElementKeys?.length || item.changedElementKeys?.length);
+            if (hasElementChanges) {
+                const targetElementsByKey = new Map((targetEntry.component.elements || []).map((element) => [element.key, element]));
+                await targetClient.saveComponentElements(targetEntry.componentId, buildPortableElementPayload(sourceEntry.component, targetElementsByKey));
+            }
+            const verified = await verifyAppliedComponent(targetClient, targetEntry.componentId, sourceEntry.portableHash);
+            return { stableKey: item.stableKey, action: item.action, status: 'applied', verified };
+        }
+        if (item.action === 'delete') {
+            const targetEntry = target.components.get(item.stableKey);
+            if (!targetEntry) {
+                throw new Error('target component disappeared from the snapshot');
+            }
+            await targetClient.deleteComponent(targetEntry.componentId);
+            return { stableKey: item.stableKey, action: item.action, status: 'applied' };
+        }
+        throw new Error(`unexpected plan action: ${item.action}`);
+    }
+    catch (error) {
+        return {
+            stableKey: item.stableKey,
+            action: item.action,
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/src/metadata-backfill.d.ts

@@ -0,0 +1,56 @@
+import type { RevoClient } from './client.ts';
+import { type TrackedResource } from './tracked-resources.ts';
+import type { ComponentRecord, DatabaseSchemaRecord, DatabaseViewRecord, EndpointRecord, EventRecord, GroupRecord, JobTemplateRecord, RoleGroupRecord, ScheduleRecord } from './types.ts';
+export type MetadataBackfillAction = 'update' | 'skip' | 'blocked' | 'failed';
+type MetadataBackfillResourceType = 'component' | 'endpoint' | 'group' | 'role-group' | 'job-template' | 'schedule' | 'event' | 'database-schema' | 'database-view';
+type MetadataResourceRecord = ComponentRecord | DatabaseSchemaRecord | DatabaseViewRecord | EndpointRecord | GroupRecord | RoleGroupRecord | JobTemplateRecord | ScheduleRecord | EventRecord;
+export type MetadataBackfillPlanItem = {
+    resourceType: MetadataBackfillResourceType;
+    resourceId: string;
+    name: string;
+    category: string | null;
+    action: Exclude<MetadataBackfillAction, 'failed'>;
+    metadataField: 'metadata' | 'definition[].metadata';
+    stableKeyName: string;
+    stableKey?: string;
+    columnName?: string;
+    columnDefinitionId?: string;
+    reason: string;
+};
+export type MetadataBackfillPlan = {
+    schemaVersion: 1;
+    generatedAt: string;
+    env: string;
+    baseUrl: string;
+    instance: string;
+    stableKeyName: string;
+    trackedResources: TrackedResource[];
+    force: boolean;
+    skipPartitions?: boolean;
+    counts: Record<Exclude<MetadataBackfillAction, 'failed'>, number>;
+    blockers: string[];
+    items: MetadataBackfillPlanItem[];
+};
+export type MetadataBackfillResult = {
+    resourceType: MetadataBackfillResourceType;
+    resourceId: string;
+    stableKey?: string;
+    columnName?: string;
+    action: MetadataBackfillAction;
+    error?: string;
+};
+export declare function generateStableKeySuffix(bytes?: number): string;
+export declare function buildGeneratedStableKey(resource: MetadataResourceRecord): string;
+export declare function buildMetadataBackfillPlan(input: {
+    client: RevoClient;
+    envName: string;
+    stableKeyName: string;
+    trackedResources: TrackedResource[];
+    force?: boolean;
+    skipPartitions?: boolean;
+}): Promise<MetadataBackfillPlan>;
+export declare function applyMetadataBackfillPlan(input: {
+    client: RevoClient;
+    plan: MetadataBackfillPlan;
+}): Promise<MetadataBackfillResult[]>;
+export {};