@revoengine/cli 1.0.9 → 1.0.10

package/dist/src/component-lock.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { REVO_PROJECT_DIR } from "./project.js";
+import { COMPONENT_IDENTITY_BY_ID, normalizeComponentIdentityConfig, readComponentIdentityValue, sameComponentIdentityConfig, } from "./resource-metadata.js";
 import { readJsonFile, writeJsonFile } from "./utils.js";
 export const REVO_LOCK_FILE = path.join(REVO_PROJECT_DIR, 'revo.lock.json');
 const VOLATILE_COMPONENT_FIELDS = new Set([
@@ -63,10 +64,10 @@ export function normalizeComponentSource(component) {
         async: Boolean(source.async),
         elements: [...(source.elements || [])]
             .map((element) => ({
-            key: element.key,
+            key: typeof element.key === 'string' ? element.key : '',
             desc: normalizeValue(element.desc),
             hidden: Boolean(element.hidden),
-            order: element.order,
+            order: Number.isFinite(Number(element.order)) ? Number(element.order) : 0,
             details: element.details ?? '',
         }))
             .sort((left, right) => left.order - right.order || left.key.localeCompare(right.key)),
@@ -75,6 +76,16 @@ export function normalizeComponentSource(component) {
 export function hashComponentSource(component) {
     return hashStable(normalizeComponentSource(component));
 }
+// componentId is instance-local, so comparing components across two RevoEngine
+// environments must project it away; element componentElementIds are already
+// excluded by normalizeComponentSource.
+export function normalizePortableComponentSource(component) {
+    const { componentId, ...portable } = normalizeComponentSource(component);
+    return portable;
+}
+export function hashPortableComponentSource(component) {
+    return hashStable(normalizePortableComponentSource(component));
+}
 export function getLockPath(projectRoot) {
     return path.join(projectRoot, REVO_LOCK_FILE);
 }
@@ -82,35 +93,98 @@ export function readComponentLock(projectRoot) {
     const lockPath = getLockPath(projectRoot);
     if (!fs.existsSync(lockPath)) {
         return {
-            schemaVersion: 1,
+            schemaVersion: 2,
+            componentIdentity: COMPONENT_IDENTITY_BY_ID,
             components: {},
         };
     }
     const raw = readJsonFile(lockPath);
+    const componentIdentity = normalizeComponentIdentityConfig(raw.componentIdentity, COMPONENT_IDENTITY_BY_ID);
+    const components = Object.fromEntries(Object.entries(raw.components && typeof raw.components === 'object' ? raw.components : {})
+        .map(([key, entry]) => {
+        const remoteComponentId = String(entry.remoteComponentId || entry.componentId || key);
+        const identityMode = entry.identityMode || componentIdentity.mode;
+        return [key, {
+                ...entry,
+                identityMode,
+                ...(identityMode === 'stableKey'
+                    ? {
+                        metadataProperty: entry.metadataProperty || componentIdentity.metadataProperty,
+                        stableKey: entry.stableKey || key,
+                    }
+                    : {}),
+                componentId: String(entry.componentId || remoteComponentId),
+                remoteComponentId,
+            }];
+    }));
     return {
-        schemaVersion: 1,
-        components: raw.components && typeof raw.components === 'object' ? raw.components : {},
+        schemaVersion: 2,
+        componentIdentity,
+        components,
     };
 }
 export function writeComponentLock(projectRoot, lock) {
     const sortedComponents = Object.fromEntries(Object.entries(lock.components).sort(([left], [right]) => left.localeCompare(right)));
     writeJsonFile(getLockPath(projectRoot), {
-        schemaVersion: 1,
+        schemaVersion: 2,
+        componentIdentity: normalizeComponentIdentityConfig(lock.componentIdentity),
         components: sortedComponents,
     });
 }
-export function upsertComponentLockEntry(projectRoot, entry) {
+export function componentLockKey(identity, component) {
+    return readComponentIdentityValue(component, identity);
+}
+export function componentLockMatchesIdentity(lock, identity) {
+    return sameComponentIdentityConfig(lock.componentIdentity, identity);
+}
+export function getComponentLockEntry(lock, identity, component) {
+    if (!componentLockMatchesIdentity(lock, identity)) {
+        return null;
+    }
+    const key = componentLockKey(identity, component);
+    return key ? lock.components[key] || null : null;
+}
+export function upsertComponentLockEntry(projectRoot, entry, identity = COMPONENT_IDENTITY_BY_ID) {
+    const normalizedIdentity = normalizeComponentIdentityConfig(identity);
     const lock = readComponentLock(projectRoot);
-    const existing = lock.components[entry.componentId];
+    if (!componentLockMatchesIdentity(lock, normalizedIdentity)) {
+        lock.componentIdentity = normalizedIdentity;
+        lock.components = {};
+    }
+    const remoteComponentId = entry.remoteComponentId || entry.componentId;
+    const key = normalizedIdentity.mode === 'stableKey'
+        ? entry.stableKey
+        : remoteComponentId;
+    if (!key) {
+        throw new Error(`Cannot write component lock entry without ${normalizedIdentity.mode === 'stableKey' ? normalizedIdentity.metadataProperty : 'componentId'}.`);
+    }
+    const normalizedEntry = {
+        ...entry,
+        identityMode: normalizedIdentity.mode,
+        remoteComponentId,
+        ...(normalizedIdentity.mode === 'stableKey'
+            ? {
+                metadataProperty: normalizedIdentity.metadataProperty,
+                stableKey: key,
+            }
+            : {}),
+    };
+    const existing = lock.components[key];
     if (existing
-        && existing.componentName === entry.componentName
-        && existing.category === entry.category
-        && existing.path === entry.path
-        && existing.remoteVersion === entry.remoteVersion
-        && existing.remoteHash === entry.remoteHash
-        && existing.sourceHash === entry.sourceHash) {
+        && existing.identityMode === normalizedEntry.identityMode
+        && existing.metadataProperty === normalizedEntry.metadataProperty
+        && existing.stableKey === normalizedEntry.stableKey
+        && existing.componentId === normalizedEntry.componentId
+        && existing.remoteComponentId === normalizedEntry.remoteComponentId
+        && existing.componentName === normalizedEntry.componentName
+        && existing.category === normalizedEntry.category
+        && existing.path === normalizedEntry.path
+        && existing.remoteVersion === normalizedEntry.remoteVersion
+        && existing.remoteHash === normalizedEntry.remoteHash
+        && existing.sourceHash === normalizedEntry.sourceHash) {
         return;
     }
-    lock.components[entry.componentId] = entry;
+    lock.componentIdentity = normalizedIdentity;
+    lock.components[key] = normalizedEntry;
     writeComponentLock(projectRoot, lock);
 }

package/dist/src/config.d.ts

@@ -9,9 +9,16 @@ export type RuntimeConfigOptions = {
     baseUrl?: string;
     instance?: string;
     token?: string;
+    envName?: string;
+};
+export type StoredEnvironmentProfile = {
+    baseUrl: string;
+    token: string;
+    instance?: string;
 };
 type StoredConfig = Omit<RuntimeConfig, 'instance'> & {
     instance?: string;
+    environments?: Record<string, StoredEnvironmentProfile>;
 };
 export type AuthValidationState = {
     key: string;
@@ -45,10 +52,15 @@ export declare function loadStoredConfigIndex(): {
 export declare function loadStoredConfig(options?: {
     allowLegacy?: boolean;
 }): StoredConfig;
+export declare function listEnvironmentProfiles(): Record<string, StoredEnvironmentProfile>;
+export declare function getEnvironmentProfile(name: string): StoredEnvironmentProfile | null;
+export declare function saveEnvironmentProfile(name: string, profile: StoredEnvironmentProfile): void;
+export declare function removeEnvironmentProfile(name: string): boolean;
 export declare function buildAuthValidationKey(runtime: RuntimeConfigOptions): string;
 export declare function readAuthValidationState(key?: string): AuthValidationState;
 export declare function saveAuthValidationState(state: AuthValidationState): void;
 export declare function clearAuthValidationState(key?: string): void;
+export declare const DEFAULT_ENV_NAME = "default";
 export declare function resolveRuntimeConfig(options?: RuntimeConfigOptions): {
     baseUrl: string;
     instance: string;

package/dist/src/config.js

@@ -74,16 +74,40 @@ export function saveStoredConfig(nextConfig) {
     ensureDirectory(dir);
     const current = readStoredConfigFile();
     const instance = nextConfig.instance || current.instance || '';
+    const environments = nextConfig.environments ?? current.environments;
     const config = {
         baseUrl: nextConfig.baseUrl || current.baseUrl || DEFAULT_BASE_URL,
         token: nextConfig.token || current.token || '',
         ...(instance ? { instance } : {}),
+        ...(environments && Object.keys(environments).length > 0 ? { environments } : {}),
     };
     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 environments = readStoredConfigFile().environments;
+    if (environments && Object.keys(environments).length > 0) {
+        ensureDirectory(dir);
+        writeJsonFile(configFile, {
+            baseUrl: DEFAULT_BASE_URL,
+            token: '',
+            environments,
+        });
+        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 +168,23 @@ 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 } : {}),
+        };
+    }
+    return Object.keys(environments).length > 0 ? environments : null;
+}
 function parseFlatConfig(raw, credentials) {
     if (!isRecord(raw) || isRecord(raw.instances)) {
         return null;
@@ -153,6 +194,7 @@ function parseFlatConfig(raw, credentials) {
         : isRecord(credentials) && typeof credentials.token === 'string'
             ? credentials.token
             : '';
+    const environments = parseEnvironmentProfiles(raw.environments);
     return {
         baseUrl: typeof raw.baseUrl === 'string'
             ? raw.baseUrl
@@ -160,6 +202,7 @@ function parseFlatConfig(raw, credentials) {
                 ? raw.url
                 : DEFAULT_BASE_URL,
         ...(typeof raw.instance === 'string' && isUuid(raw.instance) ? { instance: raw.instance } : {}),
+        ...(environments ? { environments } : {}),
         token,
     };
 }
@@ -181,14 +224,16 @@ function parseMappedConfig(raw) {
     const defaultInstance = isUuid(configuredDefault) && instances[configuredDefault]
         ? configuredDefault
         : Object.keys(instances)[0] || '';
+    const environments = parseEnvironmentProfiles(raw.environments);
     const selected = defaultInstance ? instances[defaultInstance] : undefined;
-    return selected
+    const base = selected
         ? {
             baseUrl: selected.baseUrl,
             instance: defaultInstance,
             token: selected.token,
         }
         : emptyStoredConfigFile();
+    return environments ? { ...base, environments } : base;
 }
 function parseLegacyConfig(config, credentials) {
     const baseUrl = isRecord(config) && typeof config.baseUrl === 'string'
@@ -256,6 +301,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 +313,25 @@ 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 function saveEnvironmentProfile(name, profile) {
+    const environments = { ...listEnvironmentProfiles(), [name]: profile };
+    saveStoredConfig({ environments });
+}
+export function removeEnvironmentProfile(name) {
+    const environments = listEnvironmentProfiles();
+    if (!(name in environments)) {
+        return false;
+    }
+    delete environments[name];
+    saveStoredConfig({ environments });
+    return true;
+}
 export function buildAuthValidationKey(runtime) {
     return createHash('sha256')
         .update(JSON.stringify({
@@ -357,6 +422,7 @@ export function clearAuthValidationState(key) {
         }
     }
 }
+export const DEFAULT_ENV_NAME = 'default';
 export function resolveRuntimeConfig(options = {}) {
     const env = {
         baseUrl: resolveEnvValue(['REVO_URL', 'REVO_BASE_URL', 'REVOENGINE_URL', 'REVOENGINE_BASE_URL']),
@@ -364,6 +430,20 @@ export function resolveRuntimeConfig(options = {}) {
         token: resolveEnvValue(['REVO_TOKEN', 'REVO_API_KEY', 'REVOENGINE_TOKEN', 'REVOENGINE_API_KEY']),
     };
     const stored = loadStoredConfig();
+    // 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.
+    if (options.envName && options.envName !== DEFAULT_ENV_NAME) {
+        const profile = getEnvironmentProfile(options.envName);
+        if (!profile) {
+            throw new Error(`Unknown environment "${options.envName}". Run 'revo env list' to see saved environments.`);
+        }
+        return {
+            baseUrl: options.baseUrl || profile.baseUrl || DEFAULT_BASE_URL,
+            instance: options.instance || profile.instance || '',
+            token: options.token || profile.token || '',
+        };
+    }
     return {
         baseUrl: options.baseUrl || env.baseUrl || stored.baseUrl || DEFAULT_BASE_URL,
         instance: options.instance || env.instance || stored.instance || '',

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

@@ -0,0 +1,86 @@
+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>;
+declare const PORTABLE_METADATA_FIELDS: readonly ["name", "category", "desc", "active", "type", "async"];
+export type PortableMetadataField = (typeof PORTABLE_METADATA_FIELDS)[number];
+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[]>;
+export {};