@revoengine/cli 1.0.8 → 1.0.10

package/dist/src/env-sync.js

@@ -0,0 +1,331 @@
+import { 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,
+    };
+}
+const PORTABLE_METADATA_FIELDS = ['name', 'category', 'desc', 'active', 'type', 'async'];
+function diffMetadataFields(source, target) {
+    return PORTABLE_METADATA_FIELDS.filter((field) => source[field] !== target[field]);
+}
+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 = diffMetadataFields(sourceEntry.portable, targetEntry.portable);
+        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),
+    };
+}
+function buildMetadataPayload(source, target, changedFields) {
+    if (!Number.isInteger(target.version)) {
+        throw new Error('target component version is required to update component metadata');
+    }
+    const payload = { version: target.version };
+    for (const field of PORTABLE_METADATA_FIELDS) {
+        if (changedFields.includes(field)) {
+            payload[field] = source[field];
+        }
+    }
+    return payload;
+}
+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, buildMetadataPayload(sourceEntry.portable, 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,46 @@
+import type { RevoClient } from './client.ts';
+import { type TrackedResource } from './tracked-resources.ts';
+import type { ComponentRecord } from './types.ts';
+export type MetadataBackfillAction = 'update' | 'skip' | 'failed';
+export type MetadataBackfillPlanItem = {
+    resourceType: 'component';
+    resourceId: string;
+    name: string;
+    category: string | null;
+    action: Exclude<MetadataBackfillAction, 'failed'>;
+    metadataField: 'metadata';
+    stableKeyName: string;
+    stableKey?: string;
+    reason: string;
+};
+export type MetadataBackfillPlan = {
+    schemaVersion: 1;
+    generatedAt: string;
+    env: string;
+    baseUrl: string;
+    instance: string;
+    stableKeyName: string;
+    trackedResources: TrackedResource[];
+    counts: Record<Exclude<MetadataBackfillAction, 'failed'>, number>;
+    items: MetadataBackfillPlanItem[];
+};
+export type MetadataBackfillResult = {
+    resourceType: 'component';
+    resourceId: string;
+    stableKey?: string;
+    action: MetadataBackfillAction;
+    error?: string;
+};
+export declare function generateStableKeySuffix(bytes?: number): string;
+export declare function buildGeneratedStableKey(component: ComponentRecord): string;
+export declare function buildMetadataBackfillPlan(input: {
+    client: RevoClient;
+    envName: string;
+    stableKeyName: string;
+    trackedResources: TrackedResource[];
+    force?: boolean;
+}): Promise<MetadataBackfillPlan>;
+export declare function applyMetadataBackfillPlan(input: {
+    client: RevoClient;
+    plan: MetadataBackfillPlan;
+}): Promise<MetadataBackfillResult[]>;

package/dist/src/metadata-backfill.js

@@ -0,0 +1,125 @@
+import { randomBytes } from 'node:crypto';
+import { buildStableKey, buildResourceIdentityStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "./resource-metadata.js";
+import { shouldTrackResource } from "./tracked-resources.js";
+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 || '');
+}
+function normalizeValue(value, fallback = null) {
+    return value ?? fallback;
+}
+export function generateStableKeySuffix(bytes = 4) {
+    return randomBytes(bytes).toString('hex');
+}
+export function buildGeneratedStableKey(component) {
+    return `${buildResourceIdentityStableKeyValue(component)}#${generateStableKeySuffix()}`;
+}
+function buildComponentMetadataUpdatePayload(component, stableKeyName, stableKey) {
+    if (!Number.isInteger(component.version)) {
+        throw new Error('component version is required to update metadata');
+    }
+    return {
+        version: component.version,
+        metadata: {
+            ...sanitizeUserMetadata(component.metadata),
+            [stableKeyName]: stableKey,
+        },
+    };
+}
+export async function buildMetadataBackfillPlan(input) {
+    const { client, envName, stableKeyName, trackedResources, force = false } = input;
+    const items = [];
+    if (shouldTrackResource(trackedResources, 'component')) {
+        const { components } = await client.listAllComponents();
+        for (const summary of components) {
+            const summaryId = componentIdOf(summary);
+            if (!summaryId) {
+                continue;
+            }
+            const component = unwrapComponent(await client.getComponent(summaryId));
+            const resourceId = componentIdOf(component) || summaryId;
+            const existingStableKey = readConfiguredResourceMetadataStableKey(component, stableKeyName);
+            const stableKey = existingStableKey && !force
+                ? undefined
+                : buildGeneratedStableKey(component);
+            items.push({
+                resourceType: 'component',
+                resourceId,
+                name: String(component.name || ''),
+                category: normalizeValue(component.category),
+                action: existingStableKey && !force ? 'skip' : 'update',
+                metadataField: 'metadata',
+                stableKeyName,
+                ...(stableKey ? { stableKey } : {}),
+                reason: existingStableKey
+                    ? (force ? 'stable key will be regenerated' : 'stable key already exists')
+                    : 'stable key missing',
+            });
+        }
+    }
+    items.sort((left, right) => left.resourceType.localeCompare(right.resourceType)
+        || buildStableKey({ name: left.name, category: left.category }).localeCompare(buildStableKey({ name: right.name, category: right.category }))
+        || left.resourceId.localeCompare(right.resourceId));
+    const counts = {
+        update: items.filter((item) => item.action === 'update').length,
+        skip: items.filter((item) => item.action === 'skip').length,
+    };
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        env: envName,
+        baseUrl: client.baseUrl,
+        instance: client.instance,
+        stableKeyName,
+        trackedResources,
+        counts,
+        items,
+    };
+}
+export async function applyMetadataBackfillPlan(input) {
+    const { client, plan } = input;
+    const results = [];
+    for (const item of plan.items) {
+        if (item.action === 'skip') {
+            results.push({
+                resourceType: item.resourceType,
+                resourceId: item.resourceId,
+                action: 'skip',
+            });
+            continue;
+        }
+        try {
+            if (item.resourceType === 'component') {
+                const component = unwrapComponent(await client.getComponent(item.resourceId));
+                const stableKey = item.stableKey || buildGeneratedStableKey(component);
+                await client.updateComponent(item.resourceId, buildComponentMetadataUpdatePayload(component, plan.stableKeyName, stableKey));
+                results.push({
+                    resourceType: item.resourceType,
+                    resourceId: item.resourceId,
+                    stableKey,
+                    action: 'update',
+                });
+                continue;
+            }
+            throw new Error(`unsupported resource type: ${item.resourceType}`);
+        }
+        catch (error) {
+            results.push({
+                resourceType: item.resourceType,
+                resourceId: item.resourceId,
+                stableKey: item.stableKey,
+                action: 'failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return results;
+}

package/dist/src/project.d.ts

@@ -1,4 +1,6 @@
 import type { ParsedArgs } from './types.ts';
+import { type ComponentIdentityConfig, type ComponentIdentityMode } from './resource-metadata.ts';
+import { type TrackedResource } from './tracked-resources.ts';
 export declare const REVO_PROJECT_DIR = ".revoengine";
 export declare const REVO_TYPES_DIR: string;
 export declare const REVO_TYPES_FILE: string;
@@ -15,6 +17,9 @@ export type ProjectInvocation = {
     action: 'init' | 'update';
     targetArg?: string;
     extraArgs: string[];
+    identityMode?: ComponentIdentityMode;
+    stableKeyName?: string;
+    trackedResources?: TrackedResource[];
 };
 export type EditorTypesBundle = {
     code: string;
@@ -34,6 +39,10 @@ export type RevoProjectMetadata = {
     hash: string;
     lastSyncAt: string;
     workspace?: string;
+    componentIdentity?: ComponentIdentityConfig;
+    /** Legacy project metadata field. Read for migration, but no longer written. */
+    stableKeyName?: string;
+    trackedResources?: TrackedResource[];
 };
 export type ProjectSyncInput = {
     endpoint: string;
@@ -43,6 +52,8 @@ export type ProjectSyncInput = {
     libVersion: string;
     hash: string;
     lastSyncAt: string;
+    componentIdentity?: ComponentIdentityConfig;
+    trackedResources?: TrackedResource[];
 };
 export type ProjectConfigResult = {
     filePath: string;
@@ -80,21 +91,16 @@ export declare function buildProjectMetadata(input: {
 };
 export declare function findProjectMetadataFile(startDir?: string): string;
 export declare function readProjectMetadata(startDir?: string): RevoProjectMetadata | null;
+export declare function readProjectStableKeyName(startDir?: string): string;
+export declare function readProjectComponentIdentity(startDir?: string): ComponentIdentityConfig;
+export declare function readProjectTrackedResources(startDir?: string): TrackedResource[];
 export declare function resolveProjectRoot(startDir?: string): string;
 export declare function resolveProjectWorkspace(startDir?: string): string;
 export declare function buildProjectSyncState(input: {
     fallbackEndpoint: string;
     bundle: EditorTypesBundle;
     now?: Date;
-}): {
-    endpoint: string;
-    code: string;
-    definitions: unknown[];
-    apiVersion: string;
-    libVersion: string;
-    hash: string;
-    lastSyncAt: string;
-};
+}): ProjectSyncInput;
 export declare function syncProjectFiles(layoutOrTargetDir: ProjectTargetLayout | string, input: ProjectSyncInput): {
     projectDir: string;
     typesFile: string;