@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/commands/component.js

@@ -1,54 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { ApiError, PermissionDeniedError } from "../client.js";
-import { hashComponentSource, hashStable, readComponentLock, sanitizeComponentSource, upsertComponentLockEntry, } from "../component-lock.js";
-import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, resolveProjectRoot, resolveProjectWorkspace, } from "../project.js";
+import { randomUUID } from 'node:crypto';
+import { ApiError, COMPONENT_LIST_PAGE_SIZE, PermissionDeniedError } from "../client.js";
+import { getConfigDir } from "../config.js";
+import { REVO_LOCK_FILE, buildPortableComponentUpdatePayload, componentLockMatchesIdentity, diffPortableComponentSource, getComponentLockEntry, getComponentLockEntries, hashComponentSource, hashPortableComponentSource, hashStable, readComponentLock, sanitizeComponentSource, upsertComponentLockEntry, writeComponentLock, } from "../component-lock.js";
+import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, readProjectComponentIdentity, readProjectMetadata, resolveProjectRoot, resolveProjectWorkspace, } from "../project.js";
 import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
+import { readComponentIdentityValue, sanitizeUserMetadata, } from "../resource-metadata.js";
+import { printSyncPlan, printSyncNotice, printSyncStatus, printSyncSummary, } from "../sync-output.js";
 import { deepClone, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
+import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
+import { replaceWorkspaceResourceDirectory } from "../workspace-resource.js";
 const NULL_CATEGORY_FOLDER = '__no_category__';
-const COMPONENT_LIST_PAGE_SIZE = 200;
-const ACTIVE_COMPONENT_LIST_FILTER = {
-    'filter[and][0][field]': 'deletedAt',
-    'filter[and][0][op]': 'isNull',
-};
-const ANSI = {
-    reset: '\u001b[0m',
-    bold: '\u001b[1m',
-    dim: '\u001b[2m',
-    green: '\u001b[32m',
-    yellow: '\u001b[33m',
-    cyan: '\u001b[36m',
-    blue: '\u001b[34m',
-    magenta: '\u001b[35m',
-};
-function supportsColor() {
-    return Boolean(process.stdout.isTTY || process.env.FORCE_COLOR);
-}
-function paint(text, code) {
-    return supportsColor() ? `${code}${text}${ANSI.reset}` : text;
-}
-function paintStatus(status) {
-    if (status === 'Skipped') {
-        return paint(status.padEnd(9), ANSI.bold + ANSI.yellow);
-    }
-    if (status === 'Notice') {
-        return paint(status.padEnd(9), ANSI.bold + ANSI.magenta);
-    }
-    return paint(status.padEnd(9), ANSI.bold + ANSI.green);
-}
-function paintPath(targetPath) {
-    return paint(targetPath, ANSI.cyan);
-}
-function paintEngine() {
-    return paint('RevoEngine', ANSI.bold + ANSI.blue);
-}
-function paintArrow(direction) {
-    return paint(direction === 'pull' ? '->' : '<-', ANSI.bold + ANSI.magenta);
-}
-function paintReason(reason) {
-    return paint(`(${reason})`, ANSI.dim + ANSI.yellow);
-}
 function rethrowComponentAccessError(error, action) {
     if (error instanceof PermissionDeniedError) {
         throw new Error(`Access denied (403). You are authenticated, but you do not have permission to ${action} components.`);
@@ -58,32 +22,6 @@ function rethrowComponentAccessError(error, action) {
 function componentWorkspacePath(cwd, manifestPath) {
     return path.relative(cwd, path.dirname(manifestPath)) || '.';
 }
-function printSyncStatus(println, input) {
-    const suffix = input.reason ? ` ${paintReason(input.reason)}` : '';
-    println(`${paintStatus(input.status)} ${paintEngine()} ${paintArrow(input.direction)} ${paintPath(input.targetPath)}${suffix}`);
-}
-function printNotice(println, message) {
-    println(`${paintStatus('Notice')} ${message}`);
-}
-function formatDuration(durationMs) {
-    if (durationMs < 1_000) {
-        return `${durationMs}ms`;
-    }
-    const seconds = durationMs / 1_000;
-    if (seconds < 10) {
-        return `${seconds.toFixed(1)}s`;
-    }
-    return `${Math.round(seconds)}s`;
-}
-function printSummary(println, label, results, durationMs) {
-    const primary = results.filter((result) => result.status === label.toLowerCase()).length;
-    const skipped = results.filter((result) => result.status === 'skipped').length;
-    const total = results.length;
-    const summary = skipped > 0
-        ? `${label} ${primary}/${total}, Skipped ${skipped}/${total} in ${formatDuration(durationMs)}`
-        : `${label} ${primary}/${total} in ${formatDuration(durationMs)}`;
-    println(summary);
-}
 function formatBulkCount(direction, count) {
     if (typeof count === 'number') {
         return direction === 'pull'
@@ -103,7 +41,7 @@ async function confirmBulkAction(context, direction, count, force) {
     if (!isInteractiveTerminal()) {
         throw new Error(`Bulk ${action} requires confirmation. Re-run with --force or use an interactive terminal.`);
     }
-    printNotice(context.println, `About to ${action} ${subject}.`);
+    printSyncNotice(context.println, `About to ${action} ${subject}.`);
     const confirmed = await promptConfirm('Continue?', false);
     if (!confirmed) {
         throw new Error('Cancelled.');
@@ -120,27 +58,6 @@ function readWorkspaceComponentSafe(manifestPath) {
         return null;
     }
 }
-function findLocalManifestInfo(cwd, componentId) {
-    const manifestPath = findComponentManifestsById(cwd, componentId)[0];
-    if (!manifestPath) {
-        return null;
-    }
-    try {
-        const manifest = readWorkspaceManifest(manifestPath);
-        return {
-            manifestPath,
-            targetPath: componentWorkspacePath(cwd, manifestPath),
-            version: typeof manifest.version === 'number' ? manifest.version : null,
-        };
-    }
-    catch {
-        return {
-            manifestPath,
-            targetPath: componentWorkspacePath(cwd, manifestPath),
-            version: null,
-        };
-    }
-}
 function isNotModifiedError(error) {
     if (!(error instanceof ApiError) || error.status !== 400) {
         return false;
@@ -198,7 +115,28 @@ function getWorkspaceRoot(cwd) {
     return path.join(projectWorkspace || cwd, 'Components');
 }
 function getProjectRoot(cwd) {
-    return resolveProjectRoot(cwd) || cwd;
+    const configuredRoot = resolveProjectRoot(cwd);
+    if (configuredRoot) {
+        return configuredRoot;
+    }
+    let currentDir = path.resolve(cwd);
+    const { root } = path.parse(currentDir);
+    while (true) {
+        if (fs.existsSync(path.join(currentDir, REVO_LOCK_FILE))) {
+            return currentDir;
+        }
+        if (currentDir === root) {
+            return cwd;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+}
+function resolveComponentIdentity(cwd) {
+    const metadata = readProjectMetadata(cwd);
+    if (metadata) {
+        return readProjectComponentIdentity(cwd);
+    }
+    return readComponentLock(getProjectRoot(cwd)).componentIdentity;
 }
 function getCategoryFolder(component) {
     if (component.category == null || component.category === '') {
@@ -247,36 +185,9 @@ function getComponentManifestPaths(root) {
     return walkFiles(root).filter((filePath) => filePath.endsWith('component.json'));
 }
 function readWorkspaceComponent(manifestPath) {
-    const componentDir = path.dirname(manifestPath);
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const detailDirs = [
-        path.join(componentDir, 'elements'),
-        path.join(componentDir, 'details'),
-    ].filter((dir, index, list) => list.indexOf(dir) === index);
     const extension = componentTypeToExtension(normalizeComponentType(manifest));
-    manifest.elements = (manifest.elements || []).map((element) => {
-        const fileName = `${element.order}_${element.key}.${extension}`;
-        let details = '';
-        for (const detailDir of detailDirs) {
-            const preferredPath = path.join(detailDir, fileName);
-            if (fs.existsSync(preferredPath)) {
-                details = fs.readFileSync(preferredPath, 'utf8');
-                break;
-            }
-            if (fs.existsSync(detailDir)) {
-                const match = fs.readdirSync(detailDir).find((entry) => entry.startsWith(`${element.order}_${element.key}.`));
-                if (match) {
-                    details = fs.readFileSync(path.join(detailDir, match), 'utf8');
-                    break;
-                }
-            }
-        }
-        return {
-            ...element,
-            details,
-        };
-    });
-    return manifest;
+    return hydrateWorkspaceComponentElementDetails(manifestPath, manifest, extension);
 }
 function getComponentIdFromPath(componentPath) {
     const basename = path.basename(componentPath);
@@ -298,6 +209,18 @@ function findComponentManifestsById(cwd, componentId) {
         return getComponentIdFromPath(path.dirname(manifestPath)).includes(componentId);
     });
 }
+function findComponentManifestsByTarget(cwd, target) {
+    const identity = resolveComponentIdentity(cwd);
+    const matches = findComponentManifestsById(cwd, target);
+    if (identity.mode !== 'stableKey') {
+        return matches;
+    }
+    const stableMatches = getComponentManifestPaths(getWorkspaceRoot(cwd)).filter((manifestPath) => {
+        const component = readWorkspaceComponentSafe(manifestPath);
+        return component && readComponentIdentityValue(component, identity) === target;
+    });
+    return [...new Set([...stableMatches, ...matches])];
+}
 function isRelativeInside(parent, child) {
     const relative = path.relative(parent, child);
     return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
@@ -392,79 +315,6 @@ function unwrapList(value) {
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
-function readNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : null;
-}
-function resolveNextComponentListRequest(value) {
-    if (typeof value === 'string' && value) {
-        return {
-            path: value,
-        };
-    }
-    if (!isRecord(value)) {
-        return null;
-    }
-    for (const key of ['path', 'url', 'href']) {
-        if (typeof value[key] === 'string' && value[key]) {
-            return {
-                path: value[key],
-            };
-        }
-    }
-    const query = {};
-    for (const key of ['cursor', 'page', 'skip', 'take', 'limit', 'offset']) {
-        const candidate = value[key];
-        if (typeof candidate === 'string' || typeof candidate === 'number') {
-            query[key] = candidate;
-        }
-    }
-    return Object.keys(query).length > 0 ? { query } : null;
-}
-function buildActiveComponentListQuery(skip, take = COMPONENT_LIST_PAGE_SIZE) {
-    return {
-        take,
-        skip,
-        count: true,
-        ...ACTIVE_COMPONENT_LIST_FILTER,
-    };
-}
-function withActiveComponentListFilter(request) {
-    if (!request.query) {
-        return request;
-    }
-    return {
-        ...request,
-        query: {
-            ...request.query,
-            count: request.query.count ?? true,
-            ...ACTIVE_COMPONENT_LIST_FILTER,
-        },
-    };
-}
-function unwrapComponentListPage(value) {
-    const items = unwrapList(value);
-    if (!isRecord(value)) {
-        return {
-            items,
-            total: null,
-            nextRequest: null,
-        };
-    }
-    const meta = isRecord(value.meta) ? value.meta : null;
-    const pagination = isRecord(value.pagination) ? value.pagination : null;
-    const total = readNumber(value.total)
-        ?? readNumber(value.count)
-        ?? (meta ? readNumber(meta.total) ?? readNumber(meta.count) : null)
-        ?? (pagination ? readNumber(pagination.total) ?? readNumber(pagination.count) : null);
-    const nextRequest = resolveNextComponentListRequest(value.next)
-        ?? (meta ? resolveNextComponentListRequest(meta.next) : null)
-        ?? (pagination ? resolveNextComponentListRequest(pagination.next) : null);
-    return {
-        items,
-        total,
-        nextRequest,
-    };
-}
 function unwrapComponent(value) {
     if (value && typeof value === 'object' && !Array.isArray(value)) {
         const candidate = value;
@@ -478,11 +328,12 @@ function normalizeValue(value, fallback = null) {
     return value ?? fallback;
 }
 function normalizeElementContract(element) {
+    const order = Number.isFinite(Number(element.order)) ? Number(element.order) : 0;
     return {
-        key: element.key,
+        key: typeof element.key === 'string' ? element.key : '',
         desc: normalizeValue(element.desc),
         hidden: Boolean(element.hidden),
-        order: element.order,
+        order,
         details: element.details ?? '',
     };
 }
@@ -508,113 +359,430 @@ function componentIdOf(component) {
 function componentTargetPath(cwd, component) {
     return path.relative(cwd, path.join(getWorkspaceRoot(cwd), getComponentFolder(component)));
 }
-function upsertLockFromRemote(cwd, remote, targetPath) {
-    const componentId = componentIdOf(remote);
-    if (!componentId) {
+function componentSourceHash(component, identity) {
+    return identity.mode === 'stableKey'
+        ? hashPortableComponentSource(component)
+        : hashComponentSource(component);
+}
+function writeComponentPushVerificationLog(input) {
+    const outputDir = path.join(input.cwd, '.revoengine', 'logs', 'component-push');
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const identityKey = readComponentIdentityValue(input.desired, input.identity) || componentIdOf(input.desired);
+    const outputFile = path.join(outputDir, `${timestamp}-${sanitizeSegment(identityKey)}.json`);
+    const desiredHash = componentSourceHash(input.desired, input.identity);
+    const actualHash = componentSourceHash(input.actual, input.identity);
+    const portableDiff = diffPortableComponentSource(input.desired, input.actual);
+    writeJsonFile(outputFile, {
+        schemaVersion: 1,
+        kind: 'component-push-verification-failure',
+        generatedAt: new Date().toISOString(),
+        targetPath: input.targetPath,
+        ...(input.environment ? { environment: input.environment } : {}),
+        identity: input.identity,
+        hashes: { desired: desiredHash, actual: actualHash },
+        difference: portableDiff,
+        ...(input.operations ? { operations: input.operations } : {}),
+        ...(input.errorOperationId ? { errorOperationId: input.errorOperationId } : {}),
+        desired: input.desired,
+        actual: input.actual,
+    });
+    return path.relative(input.cwd, outputFile);
+}
+function describeComponentPushOperationError(error) {
+    if (error instanceof ApiError) {
+        return {
+            outcome: 'rejected',
+            name: error.name,
+            message: error.message,
+            status: error.status,
+            response: error.data,
+        };
+    }
+    return {
+        outcome: 'failed',
+        name: error instanceof Error ? error.name : 'Error',
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+function readRevoOperationId(headers) {
+    const value = headers?.get('x-revo-oid')?.trim();
+    return value || undefined;
+}
+function identityDescription(identity) {
+    return identity.mode === 'stableKey'
+        ? `metadata.${identity.metadataProperty}`
+        : 'componentId';
+}
+function addCatalogEntry(catalog, entry, source) {
+    const componentId = componentIdOf(entry.component);
+    if (componentId) {
+        const duplicateId = catalog.byComponentId.get(componentId);
+        if (duplicateId && duplicateId.manifestPath !== entry.manifestPath) {
+            throw new Error(`Duplicate ${source} componentId "${componentId}".`);
+        }
+        catalog.byComponentId.set(componentId, entry);
+    }
+    const identityKey = readComponentIdentityValue(entry.component, catalog.identity);
+    if (!identityKey) {
+        catalog.unmanaged.push(entry);
         return;
     }
-    const remoteHash = hashComponentSource(remote);
+    const duplicate = catalog.byIdentity.get(identityKey);
+    if (duplicate && duplicate.component !== entry.component) {
+        const duplicateIds = [componentIdOf(duplicate.component), componentId]
+            .filter(Boolean)
+            .join(', ');
+        throw new Error(`Duplicate ${source} ${identityDescription(catalog.identity)} "${identityKey}"${duplicateIds ? ` (${duplicateIds})` : ''}.`);
+    }
+    catalog.byIdentity.set(identityKey, entry);
+}
+function createComponentCatalog(identity) {
+    return {
+        identity,
+        byIdentity: new Map(),
+        byComponentId: new Map(),
+        unmanaged: [],
+    };
+}
+function buildLocalComponentCatalog(cwd, identity) {
+    const catalog = createComponentCatalog(identity);
+    for (const manifestPath of getComponentManifestPaths(getWorkspaceRoot(cwd))) {
+        const component = readWorkspaceComponentSafe(manifestPath);
+        if (!component) {
+            continue;
+        }
+        addCatalogEntry(catalog, {
+            component,
+            hash: componentSourceHash(component, identity),
+            manifestPath,
+        }, 'local');
+    }
+    return catalog;
+}
+async function buildRemoteComponentCatalog(context, identity, summaries) {
+    const catalog = createComponentCatalog(identity);
+    const source = summaries || (await fetchAllComponentSummaries(context)).components;
+    for (const summary of source) {
+        const componentId = String(summary.componentId || summary.id || '');
+        if (!componentId) {
+            continue;
+        }
+        const component = unwrapComponent(await context.client.getComponent(componentId));
+        addCatalogEntry(catalog, {
+            component,
+            hash: componentSourceHash(component, identity),
+        }, 'remote');
+    }
+    return catalog;
+}
+function migrateComponentLockIdentity(cwd, identity, localCatalog, remoteCatalog) {
+    const projectRoot = getProjectRoot(cwd);
+    const lock = readComponentLock(projectRoot);
+    if (componentLockMatchesIdentity(lock, identity)) {
+        return lock;
+    }
+    const migratedComponents = {};
+    if (identity.mode === 'stableKey' && lock.componentIdentity.mode === 'componentId') {
+        const legacyEntries = Object.values(lock.components);
+        for (const [stableKey, remote] of remoteCatalog.byIdentity) {
+            const local = findLocalEntryForRemote(remote.component, localCatalog);
+            const localComponentId = local ? componentIdOf(local.component) : '';
+            const remoteComponentId = componentIdOf(remote.component);
+            const legacy = legacyEntries.find((entry) => (entry.componentId === localComponentId
+                || entry.remoteComponentId === localComponentId
+                || entry.componentId === remoteComponentId
+                || entry.remoteComponentId === remoteComponentId));
+            if (!legacy || !remoteComponentId) {
+                continue;
+            }
+            const remoteLegacyHash = hashComponentSource(remote.component);
+            const localLegacyHash = local ? hashComponentSource(local.component) : null;
+            let portableBaselineHash = null;
+            if (legacy.remoteHash === remoteLegacyHash) {
+                portableBaselineHash = remote.hash;
+            }
+            else if (local && legacy.remoteHash === localLegacyHash) {
+                portableBaselineHash = local.hash;
+            }
+            else if (local && local.hash === remote.hash) {
+                portableBaselineHash = remote.hash;
+            }
+            if (!portableBaselineHash) {
+                continue;
+            }
+            migratedComponents[stableKey] = {
+                identityMode: 'stableKey',
+                metadataProperty: identity.metadataProperty,
+                stableKey,
+                componentId: localComponentId || legacy.componentId || remoteComponentId,
+                remoteComponentId,
+                componentName: remote.component.name || local?.component.name || legacy.componentName,
+                category: normalizeValue(remote.component.category, normalizeValue(local?.component.category, legacy.category)),
+                path: local?.manifestPath
+                    ? componentWorkspacePath(cwd, local.manifestPath)
+                    : legacy.path || componentTargetPath(cwd, remote.component),
+                remoteVersion: legacy.remoteVersion,
+                remoteHash: portableBaselineHash,
+                sourceHash: local?.hash || portableBaselineHash,
+                pulledAt: legacy.pulledAt,
+            };
+        }
+    }
+    const migrated = {
+        schemaVersion: 2,
+        componentIdentity: identity,
+        components: migratedComponents,
+        groups: lock.groups,
+        roleGroups: lock.roleGroups,
+        jobTemplates: lock.jobTemplates,
+        schedules: lock.schedules,
+        events: lock.events,
+        endpoints: lock.endpoints,
+        databaseSchemas: lock.databaseSchemas,
+        databaseViews: lock.databaseViews,
+    };
+    writeComponentLock(projectRoot, migrated);
+    return migrated;
+}
+function findLocalEntryForRemote(remote, localCatalog) {
+    const identityKey = readComponentIdentityValue(remote, localCatalog.identity);
+    if (!identityKey) {
+        return null;
+    }
+    const identityMatch = localCatalog.byIdentity.get(identityKey);
+    if (identityMatch) {
+        return identityMatch;
+    }
+    if (localCatalog.identity.mode !== 'stableKey') {
+        return null;
+    }
+    const remoteComponentId = componentIdOf(remote);
+    const idMatch = remoteComponentId
+        ? localCatalog.byComponentId.get(remoteComponentId)
+        : null;
+    if (!idMatch) {
+        return null;
+    }
+    const localIdentityKey = readComponentIdentityValue(idMatch.component, localCatalog.identity);
+    if (localIdentityKey && localIdentityKey !== identityKey) {
+        throw new Error(`Cannot match component ${remoteComponentId}: local ${identityDescription(localCatalog.identity)} "${localIdentityKey}" does not match remote "${identityKey}".`);
+    }
+    return idMatch;
+}
+function upsertLockFromRemote(cwd, remote, targetPath, local, environmentName) {
+    const identity = resolveComponentIdentity(cwd);
+    const remoteComponentId = componentIdOf(remote);
+    const localComponentId = componentIdOf(local || remote);
+    const identityKey = readComponentIdentityValue(remote, identity);
+    if (!remoteComponentId || !localComponentId || !identityKey) {
+        return;
+    }
+    const remoteHash = componentSourceHash(remote, identity);
     upsertComponentLockEntry(getProjectRoot(cwd), {
-        componentId,
-        componentName: remote.name || '',
-        category: normalizeValue(remote.category),
-        path: targetPath || componentTargetPath(cwd, remote),
+        identityMode: identity.mode,
+        ...(identity.mode === 'stableKey'
+            ? {
+                metadataProperty: identity.metadataProperty,
+                stableKey: identityKey,
+            }
+            : {}),
+        componentId: localComponentId,
+        remoteComponentId,
+        componentName: remote.name || local?.name || '',
+        category: normalizeValue(remote.category, normalizeValue(local?.category)),
+        path: targetPath || componentTargetPath(cwd, local || remote),
         remoteVersion: componentVersion(remote),
         remoteHash,
-        sourceHash: remoteHash,
+        sourceHash: local ? componentSourceHash(local, identity) : remoteHash,
         pulledAt: new Date().toISOString(),
-    });
+    }, identity, environmentName);
 }
-function buildPullDecision(cwd, remote) {
+function buildPullDecision(cwd, remote, localCatalog = buildLocalComponentCatalog(cwd, resolveComponentIdentity(cwd)), environmentName) {
+    const identity = localCatalog.identity;
     const remoteTargetPath = componentTargetPath(cwd, remote);
-    const componentId = componentIdOf(remote);
-    const localInfo = componentId ? findLocalManifestInfo(cwd, componentId) : null;
-    if (!localInfo?.manifestPath) {
+    const identityKey = readComponentIdentityValue(remote, identity);
+    if (!identityKey) {
+        return {
+            kind: 'skip',
+            targetPath: remoteTargetPath,
+            reason: `missing ${identityDescription(identity)}; unmanaged`,
+        };
+    }
+    const local = findLocalEntryForRemote(remote, localCatalog);
+    if (!local?.manifestPath) {
         return {
             kind: 'pull',
             targetPath: remoteTargetPath,
         };
     }
-    const localComponent = readWorkspaceComponentSafe(localInfo.manifestPath);
-    if (!localComponent) {
+    const targetPath = componentWorkspacePath(cwd, local.manifestPath);
+    const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(cwd)), identity, remote, environmentName);
+    const localHash = local.hash;
+    const remoteHash = componentSourceHash(remote, identity);
+    const base = {
+        targetPath,
+        manifestPath: local.manifestPath,
+        localComponent: local.component,
+    };
+    if (localHash === remoteHash) {
         return {
             kind: 'skip',
-            targetPath: localInfo.targetPath || remoteTargetPath,
-            reason: 'changed',
+            ...base,
+            reason: 'no changes',
         };
     }
-    const lockEntry = readComponentLock(getProjectRoot(cwd)).components[componentId];
-    const localHash = hashComponentSource(localComponent);
-    const remoteHash = hashComponentSource(remote);
     if (!lockEntry) {
-        if (localHash === remoteHash) {
-            return {
-                kind: 'skip',
-                targetPath: localInfo.targetPath || remoteTargetPath,
-                reason: 'no changes',
-            };
-        }
         return {
             kind: 'skip',
-            targetPath: localInfo.targetPath || remoteTargetPath,
+            ...base,
             reason: 'missing lock',
         };
     }
     if (localHash === lockEntry.remoteHash && remoteHash !== lockEntry.remoteHash) {
         return {
             kind: 'pull',
-            targetPath: localInfo.targetPath || remoteTargetPath,
+            ...base,
             reason: 'remote changed',
         };
     }
     if (localHash !== lockEntry.remoteHash && remoteHash === lockEntry.remoteHash) {
         return {
             kind: 'skip',
-            targetPath: localInfo.targetPath || remoteTargetPath,
+            ...base,
             reason: 'local changes',
         };
     }
     if (localHash !== lockEntry.remoteHash && remoteHash !== lockEntry.remoteHash && localHash !== remoteHash) {
         return {
             kind: 'skip',
-            targetPath: localInfo.targetPath || remoteTargetPath,
+            ...base,
             reason: 'conflict',
         };
     }
-    if (isSameComponentContract(localComponent, remote)) {
+    if (identity.mode === 'componentId' && isSameComponentContract(local.component, remote)) {
         return {
             kind: 'skip',
-            targetPath: localInfo.targetPath || remoteTargetPath,
+            ...base,
             reason: 'no changes',
         };
     }
     return {
         kind: 'skip',
-        targetPath: localInfo.targetPath || remoteTargetPath,
+        ...base,
         reason: 'changed',
     };
 }
+function syncLocalIdentityMetadata(manifestPath, remote, identity) {
+    if (identity.mode !== 'stableKey' || !manifestPath) {
+        return false;
+    }
+    const remoteStableKey = readComponentIdentityValue(remote, identity);
+    if (!remoteStableKey) {
+        return false;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const localStableKey = readComponentIdentityValue(manifest, identity);
+    if (localStableKey) {
+        if (localStableKey !== remoteStableKey) {
+            throw new Error(`Cannot pull ${componentIdOf(remote)}: local ${identityDescription(identity)} "${localStableKey}" does not match remote "${remoteStableKey}".`);
+        }
+        return false;
+    }
+    const metadata = isRecord(manifest.metadata) ? deepClone(manifest.metadata) : {};
+    manifest.metadata = {
+        ...metadata,
+        [identity.metadataProperty]: remoteStableKey,
+    };
+    writeJsonFile(manifestPath, manifest);
+    return true;
+}
+function buildPulledManifest(remote, local, identity) {
+    const manifest = stripDetails(remote);
+    if (identity.mode !== 'stableKey' || !local) {
+        return manifest;
+    }
+    const localComponentId = componentIdOf(local);
+    if (localComponentId) {
+        manifest.componentId = localComponentId;
+        delete manifest.id;
+    }
+    const localElementsByKey = new Map((local.elements || []).map((element) => [element.key, element]));
+    manifest.elements = (manifest.elements || []).map((element) => {
+        const localElementId = localElementsByKey.get(element.key)?.componentElementId;
+        return {
+            ...element,
+            ...(localElementId ? { componentElementId: localElementId } : {}),
+        };
+    });
+    return manifest;
+}
 async function confirmSingleStalePull(context, targetPath) {
     if (!isInteractiveTerminal()) {
         throw new Error(`Local component is stale at ${targetPath}. Re-run with --stale or --force, or use an interactive terminal to confirm overwrite.`);
     }
-    printNotice(context.println, `Local component is stale at ${targetPath}.`);
+    printSyncNotice(context.println, `Local component is stale at ${targetPath}.`);
     return promptConfirm('Overwrite local component with the remote version?', false);
 }
-async function pullSingleComponent(context, componentId, mode = { force: false, stale: false }) {
-    const { client, cwd, println } = context;
-    let component = null;
-    try {
-        component = unwrapComponent(await client.getComponent(componentId));
+async function resolveRemoteComponentForTarget(context, target, identity, remoteCatalog) {
+    const localManifestPath = findComponentManifestsById(context.cwd, target)[0];
+    const local = localManifestPath ? readWorkspaceComponentSafe(localManifestPath) : null;
+    const localIdentityKey = local ? readComponentIdentityValue(local, identity) : null;
+    let mismatchedDirectIdentity = null;
+    if (identity.mode === 'componentId' && !remoteCatalog) {
+        try {
+            return unwrapComponent(await context.client.getComponent(target));
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                return null;
+            }
+            rethrowComponentAccessError(error, 'pull');
+        }
     }
-    catch (error) {
-        rethrowComponentAccessError(error, 'pull');
+    if (!remoteCatalog) {
+        try {
+            const direct = unwrapComponent(await context.client.getComponent(target));
+            const directIdentityKey = direct ? readComponentIdentityValue(direct, identity) : null;
+            if (directIdentityKey && (!localIdentityKey || localIdentityKey === directIdentityKey)) {
+                return direct;
+            }
+            if (directIdentityKey && localIdentityKey && localIdentityKey !== directIdentityKey) {
+                mismatchedDirectIdentity = directIdentityKey;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ApiError && error.status === 404)) {
+                rethrowComponentAccessError(error, 'pull');
+            }
+        }
     }
-    if (!component) {
+    const catalog = remoteCatalog || await buildRemoteComponentCatalog(context, identity);
+    const resolved = localIdentityKey
+        ? catalog.byIdentity.get(localIdentityKey)?.component || null
+        : catalog.byIdentity.get(target)?.component
+            || catalog.byComponentId.get(target)?.component
+            || null;
+    if (!resolved && mismatchedDirectIdentity && localIdentityKey) {
+        throw new Error(`Cannot match component ${target}: local ${identityDescription(identity)} "${localIdentityKey}" does not match remote "${mismatchedDirectIdentity}".`);
+    }
+    return resolved;
+}
+async function pullResolvedComponent(context, component, mode, localCatalog) {
+    const { cwd, println } = context;
+    const identity = resolveComponentIdentity(cwd);
+    const componentId = componentIdOf(component);
+    const decision = buildPullDecision(cwd, component, localCatalog || buildLocalComponentCatalog(cwd, identity), context.componentEnvironment);
+    if (decision.kind === 'skip' && decision.reason.includes('; unmanaged')) {
         const result = {
             status: 'skipped',
-            targetPath: componentId,
-            reason: 'component not found',
+            targetPath: decision.targetPath,
+            reason: decision.reason,
         };
         printSyncStatus(println, {
             status: 'Skipped',
@@ -624,7 +792,6 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
         });
         return result;
     }
-    const decision = buildPullDecision(cwd, component);
     if (decision.kind === 'skip' && !mode.force) {
         if (decision.reason === 'stale version') {
             if (mode.stale) {
@@ -666,16 +833,21 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
             if (decision.reason === 'conflict' || decision.reason === 'missing lock') {
                 throw new Error(`Cannot pull ${componentId}: ${decision.reason} at ${decision.targetPath}. Re-run with --force only if you want to overwrite local files.`);
             }
+            let metadataUpdated = false;
             if (decision.reason === 'no changes') {
-                upsertLockFromRemote(cwd, component, decision.targetPath);
+                metadataUpdated = syncLocalIdentityMetadata(decision.manifestPath, component, identity);
+                const localComponent = decision.manifestPath
+                    ? readWorkspaceComponentSafe(decision.manifestPath) || decision.localComponent
+                    : decision.localComponent;
+                upsertLockFromRemote(cwd, component, decision.targetPath, localComponent, context.componentEnvironment);
             }
             const result = {
-                status: 'skipped',
+                status: metadataUpdated ? 'pulled' : 'skipped',
                 targetPath: decision.targetPath,
-                reason: decision.reason,
+                reason: metadataUpdated ? 'stable-key metadata' : decision.reason,
             };
             printSyncStatus(println, {
-                status: 'Skipped',
+                status: metadataUpdated ? 'Pulled' : 'Skipped',
                 direction: 'pull',
                 targetPath: result.targetPath,
                 reason: result.reason,
@@ -684,18 +856,30 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
         }
     }
     const root = getWorkspaceRoot(cwd);
-    const folder = path.join(root, getComponentFolder(component));
+    const folder = decision.manifestPath
+        ? path.dirname(decision.manifestPath)
+        : path.join(root, getComponentFolder(component));
     const targetPath = path.relative(cwd, folder);
-    const elementsDir = path.join(folder, 'elements');
-    fs.mkdirSync(elementsDir, { recursive: true });
-    const extension = getDetailsExtension(component);
-    for (const element of component.elements || []) {
-        const content = element.details ?? element.logic ?? '';
-        const filePath = path.join(elementsDir, `${element.order}_${element.key}.${extension}`);
-        fs.writeFileSync(filePath, content);
-    }
-    writeJsonFile(path.join(folder, 'component.json'), stripDetails(component));
-    upsertLockFromRemote(cwd, component, targetPath);
+    const populate = (directory) => {
+        const elementsDir = path.join(directory, 'elements');
+        fs.mkdirSync(elementsDir, { recursive: true });
+        const extension = getDetailsExtension(component);
+        for (const element of component.elements || []) {
+            const content = element.details ?? element.logic ?? '';
+            const filePath = path.join(elementsDir, `${element.order}_${element.key}.${extension}`);
+            fs.writeFileSync(filePath, content);
+        }
+        writeJsonFile(path.join(directory, 'component.json'), buildPulledManifest(component, decision.localComponent, identity));
+    };
+    if (mode.force) {
+        replaceWorkspaceResourceDirectory(root, folder, populate);
+    }
+    else {
+        populate(folder);
+    }
+    const manifestPath = path.join(folder, 'component.json');
+    const localComponent = readWorkspaceComponentSafe(manifestPath) || decision.localComponent;
+    upsertLockFromRemote(cwd, component, targetPath, localComponent, context.componentEnvironment);
     const result = {
         status: 'pulled',
         targetPath,
@@ -711,58 +895,40 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
     });
     return result;
 }
+async function pullSingleComponent(context, target, mode = { force: false, stale: false }) {
+    const identity = resolveComponentIdentity(context.cwd);
+    let remoteCatalog;
+    let localCatalog;
+    if (identity.mode === 'stableKey'
+        && !componentLockMatchesIdentity(readComponentLock(getProjectRoot(context.cwd)), identity)) {
+        remoteCatalog = await buildRemoteComponentCatalog(context, identity);
+        localCatalog = buildLocalComponentCatalog(context.cwd, identity);
+        migrateComponentLockIdentity(context.cwd, identity, localCatalog, remoteCatalog);
+    }
+    const component = await resolveRemoteComponentForTarget(context, target, identity, remoteCatalog);
+    if (!component) {
+        const result = {
+            status: 'skipped',
+            targetPath: target,
+            reason: 'component not found',
+        };
+        printSyncStatus(context.println, {
+            status: 'Skipped',
+            direction: 'pull',
+            targetPath: result.targetPath,
+            reason: result.reason,
+        });
+        return result;
+    }
+    return pullResolvedComponent(context, component, mode, localCatalog);
+}
 async function fetchAllComponentSummaries(context) {
-    const { client, cwd } = context;
-    const components = [];
-    const seenRequests = new Set();
-    let nextRequest = {
-        query: buildActiveComponentListQuery(0),
-    };
-    let discoveredTotal = null;
-    while (nextRequest) {
-        const requestKey = JSON.stringify(nextRequest);
-        if (seenRequests.has(requestKey)) {
-            throw new Error('Component list pagination loop detected while pulling all components.');
-        }
-        seenRequests.add(requestKey);
-        let pageValue;
-        try {
-            pageValue = await client.listComponents(nextRequest);
-        }
-        catch (error) {
-            rethrowComponentAccessError(error, 'list');
-        }
-        const page = unwrapComponentListPage(pageValue);
-        if (page.total !== null) {
-            discoveredTotal = page.total;
-        }
-        for (const item of page.items) {
-            if (isRecord(item)) {
-                components.push(item);
-            }
-        }
-        if (page.total !== null && components.length >= page.total) {
-            nextRequest = null;
-            continue;
-        }
-        if (page.nextRequest) {
-            nextRequest = withActiveComponentListFilter(page.nextRequest);
-            continue;
-        }
-        if (nextRequest.query
-            && typeof nextRequest.query.take === 'number'
-            && page.items.length === nextRequest.query.take) {
-            nextRequest = {
-                query: buildActiveComponentListQuery(components.length, nextRequest.query.take),
-            };
-            continue;
-        }
-        nextRequest = null;
+    try {
+        return await context.client.listAllComponents();
     }
-    if (components.length === 0) {
-        return { components, discoveredTotal };
+    catch (error) {
+        rethrowComponentAccessError(error, 'list');
     }
-    return { components, discoveredTotal };
 }
 async function pullAllComponents(context, options) {
     const { components, discoveredTotal } = await fetchAllComponentSummaries(context);
@@ -770,79 +936,212 @@ async function pullAllComponents(context, options) {
         context.println('No components found.');
         return [];
     }
-    await confirmBulkAction(context, 'pull', discoveredTotal ?? (components.length >= COMPONENT_LIST_PAGE_SIZE ? `at least ${components.length} components` : components.length), options.force || options.yes);
+    const identity = resolveComponentIdentity(context.cwd);
+    const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
+    const managedCount = remoteCatalog.byIdentity.size;
+    if (managedCount === 0) {
+        context.println(`No components managed by ${identityDescription(identity)} were found.`);
+        return [];
+    }
+    await confirmBulkAction(context, 'pull', identity.mode === 'componentId'
+        ? discoveredTotal ?? (components.length >= COMPONENT_LIST_PAGE_SIZE ? `at least ${components.length} components` : components.length)
+        : managedCount, options.force || options.yes);
     const startedAt = Date.now();
     const results = [];
-    for (const item of components) {
-        const componentId = item.componentId || item.id;
-        if (!componentId) {
-            continue;
-        }
-        const result = await pullSingleComponent(context, String(componentId), {
+    const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
+    migrateComponentLockIdentity(context.cwd, identity, localCatalog, remoteCatalog);
+    for (const entry of remoteCatalog.byComponentId.values()) {
+        const result = await pullResolvedComponent(context, entry.component, {
             force: options.force,
             stale: options.stale,
             promptOnStale: false,
-        });
+        }, localCatalog);
         if (result) {
             results.push(result);
         }
     }
-    printSummary(context.println, 'Pulled', results, Date.now() - startedAt);
+    printSyncSummary(context.println, 'Pulled', results, Date.now() - startedAt);
     return results;
 }
-async function pushSingleComponent(context, manifestPath) {
+async function resolveRemoteComponentForLocal(context, component, identity, remoteCatalog) {
+    const localComponentId = componentIdOf(component);
+    if (identity.mode === 'componentId') {
+        if (!localComponentId) {
+            return null;
+        }
+        if (typeof context.client.getComponent !== 'function') {
+            return component;
+        }
+        try {
+            return unwrapComponent(await context.client.getComponent(localComponentId));
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                return null;
+            }
+            rethrowComponentAccessError(error, 'push');
+        }
+    }
+    const identityKey = readComponentIdentityValue(component, identity);
+    if (!identityKey) {
+        return null;
+    }
+    const catalog = remoteCatalog || await buildRemoteComponentCatalog(context, identity);
+    return catalog.byIdentity.get(identityKey)?.component || null;
+}
+function buildPushElements(component, remote, identity) {
+    const remoteElementsByKey = new Map((remote.elements || []).map((element) => [element.key, element]));
+    return (component.elements || []).map((element) => {
+        const targetElementId = identity.mode === 'stableKey'
+            ? remoteElementsByKey.get(element.key)?.componentElementId
+            : element.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 buildComponentCreatePayload(component, identity) {
+    return {
+        name: component.name || '',
+        category: component.category ?? null,
+        desc: component.desc ?? null,
+        type: normalizeComponentType(component),
+        compiler: compilerFromType(component.type, component.compiler),
+        active: component.active ?? true,
+        async: Boolean(component.async),
+        metadata: sanitizeUserMetadata(component.metadata),
+        elements: buildPushElements(component, { elements: [] }, identity),
+    };
+}
+async function pushSingleComponent(context, manifestPath, remoteCatalog) {
     const { client, println } = context;
     const component = readWorkspaceComponent(manifestPath);
-    const componentId = component.componentId || component.id;
+    const localComponentId = componentIdOf(component);
     const targetPath = componentWorkspacePath(context.cwd, manifestPath);
-    if (!componentId) {
+    const identity = resolveComponentIdentity(context.cwd);
+    const identityKey = readComponentIdentityValue(component, identity);
+    if (!localComponentId) {
         throw new Error(`Missing componentId in ${manifestPath}.`);
     }
     if (!component.name) {
         throw new Error(`Missing component name in ${manifestPath}.`);
     }
-    const elements = (component.elements || []).map((element) => ({
-        ...(typeof element.componentElementId === 'string' && element.componentElementId
-            ? { componentElementId: element.componentElementId }
-            : {}),
-        key: element.key,
-        desc: element.desc,
-        details: element.details || '',
-        hidden: Boolean(element.hidden),
-        order: element.order,
-    }));
+    if (!identityKey) {
+        const result = {
+            status: 'skipped',
+            targetPath,
+            reason: `missing ${identityDescription(identity)}; unmanaged`,
+        };
+        printSyncStatus(println, {
+            status: 'Skipped',
+            direction: 'push',
+            targetPath,
+            reason: result.reason,
+        });
+        return result;
+    }
+    let resolvedRemoteCatalog = remoteCatalog;
+    if (identity.mode === 'stableKey'
+        && !componentLockMatchesIdentity(readComponentLock(getProjectRoot(context.cwd)), identity)) {
+        resolvedRemoteCatalog = resolvedRemoteCatalog || await buildRemoteComponentCatalog(context, identity);
+        migrateComponentLockIdentity(context.cwd, identity, buildLocalComponentCatalog(context.cwd, identity), resolvedRemoteCatalog);
+    }
     try {
-        if (!readBoolFlag(context.args, ['force', 'f'])) {
-            let remote = null;
-            try {
-                remote = unwrapComponent(await client.getComponent(componentId));
+        const remote = await resolveRemoteComponentForLocal(context, component, identity, resolvedRemoteCatalog);
+        if (!remote) {
+            if (context.componentEnvironment) {
+                const created = unwrapComponent(await client.createComponent(buildComponentCreatePayload(component, identity)));
+                const createdComponentId = componentIdOf(created);
+                if (!createdComponentId) {
+                    throw new Error(`Cannot push ${targetPath}: create response did not include componentId.`);
+                }
+                await client.saveComponentElements(createdComponentId, buildPushElements(component, { elements: [] }, identity));
+                const refreshedRemote = unwrapComponent(await client.getComponent(createdComponentId));
+                if (componentSourceHash(refreshedRemote, identity) !== componentSourceHash(component, identity)) {
+                    const logPath = writeComponentPushVerificationLog({
+                        cwd: context.cwd,
+                        targetPath,
+                        environment: context.componentEnvironment,
+                        identity,
+                        desired: component,
+                        actual: refreshedRemote,
+                    });
+                    throw new Error(`Cannot push ${targetPath}: created component did not verify against local source. Diagnostic: ${logPath}`);
+                }
+                upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component, context.componentEnvironment);
+                const result = { status: 'deployed', targetPath };
+                printSyncStatus(println, { status: 'Deployed', direction: 'push', targetPath });
+                return result;
             }
-            catch (error) {
-                if (error instanceof ApiError && error.status === 404) {
+            const result = {
+                status: 'skipped',
+                targetPath,
+                reason: "doesn't exist remotely",
+            };
+            printSyncStatus(println, {
+                status: 'Skipped',
+                direction: 'push',
+                targetPath,
+                reason: result.reason,
+            });
+            return result;
+        }
+        const remoteComponentId = componentIdOf(remote);
+        if (!remoteComponentId) {
+            throw new Error(`Remote component matched by ${identityDescription(identity)} "${identityKey}" has no componentId.`);
+        }
+        if (!readBoolFlag(context.args, ['force', 'f'])) {
+            const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(context.cwd)), identity, component, context.componentEnvironment);
+            if (!lockEntry) {
+                const remoteHash = componentSourceHash(remote, identity);
+                const localHash = componentSourceHash(component, identity);
+                if (context.componentEnvironment && localHash === remoteHash) {
+                    upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
                     const result = {
                         status: 'skipped',
                         targetPath,
-                        reason: "doesn't exist remotely",
+                        reason: 'local matches remote; target baseline adopted',
                     };
                     printSyncStatus(println, {
                         status: 'Skipped',
                         direction: 'push',
-                        targetPath,
+                        targetPath: result.targetPath,
                         reason: result.reason,
                     });
                     return result;
                 }
-                rethrowComponentAccessError(error, 'push');
+                throw new Error(`Cannot push ${targetPath}: missing lock entry. Run \`revo component pull ${identityKey} --force\` to establish a remote baseline.`);
             }
-            const lockEntry = readComponentLock(getProjectRoot(context.cwd)).components[componentId];
-            if (!lockEntry) {
-                throw new Error(`Cannot push ${targetPath}: missing lock entry. Run \`revo component pull ${componentId} --force\` to establish a remote baseline.`);
+            if (lockEntry.remoteComponentId !== remoteComponentId) {
+                throw new Error(`Cannot push ${targetPath}: ${identityDescription(identity)} "${identityKey}" now resolves to remote component ${remoteComponentId}, but the lock references ${lockEntry.remoteComponentId}. Pull/reconcile first.`);
             }
-            const remoteHash = hashComponentSource(remote);
+            const remoteHash = componentSourceHash(remote, identity);
+            const localHash = componentSourceHash(component, identity);
             if (remoteHash !== lockEntry.remoteHash) {
+                if (localHash === remoteHash) {
+                    upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
+                    const result = {
+                        status: 'skipped',
+                        targetPath,
+                        reason: 'local matches remote; lock refreshed',
+                    };
+                    printSyncStatus(println, {
+                        status: 'Skipped',
+                        direction: 'push',
+                        targetPath,
+                        reason: result.reason,
+                    });
+                    return result;
+                }
                 throw new Error(`Cannot push ${targetPath}: remote changed since the last lock baseline. Run \`revo component plan --all\` and pull/reconcile first.`);
             }
-            const localHash = hashComponentSource(component);
             if (localHash === lockEntry.remoteHash) {
                 const result = {
                     status: 'skipped',
@@ -858,20 +1157,98 @@ async function pushSingleComponent(context, manifestPath) {
                 return result;
             }
         }
-        const response = await client.saveComponentElements(componentId, elements);
-        if (response.status === 304) {
+        const hasLiveRemote = typeof client.getComponent === 'function';
+        const portableDiff = hasLiveRemote
+            ? diffPortableComponentSource(component, remote)
+            : { configurationFields: [], elementsChanged: true, changedFields: ['elements'] };
+        if (portableDiff.changedFields.length === 0) {
             const result = {
                 status: 'skipped',
                 targetPath,
                 reason: 'no changes',
             };
+            upsertLockFromRemote(context.cwd, remote, targetPath, component, context.componentEnvironment);
+            printSyncStatus(println, {
+                status: 'Skipped',
+                direction: 'push',
+                targetPath,
+                reason: result.reason,
+            });
+            return result;
+        }
+        let configurationChanged = false;
+        const operations = {};
+        let errorOperationId;
+        if (portableDiff.configurationFields.length > 0) {
             try {
-                const remote = unwrapComponent(await client.getComponent(componentId));
-                upsertLockFromRemote(context.cwd, remote, targetPath);
+                await client.updateComponent(remoteComponentId, buildPortableComponentUpdatePayload(component, remote, portableDiff.configurationFields));
+                configurationChanged = true;
+                operations.configurationUpdate = { outcome: 'accepted' };
             }
-            catch {
-                upsertLockFromRemote(context.cwd, component, targetPath);
+            catch (error) {
+                operations.configurationUpdate = describeComponentPushOperationError(error);
+                if (error instanceof ApiError) {
+                    errorOperationId = readRevoOperationId(error.headers) || errorOperationId;
+                }
+                if (!isNotModifiedError(error)) {
+                    throw error;
+                }
             }
+        }
+        let elementsChanged = false;
+        if (portableDiff.elementsChanged) {
+            try {
+                const elements = buildPushElements(component, remote, identity);
+                const response = await client.saveComponentElements(remoteComponentId, elements);
+                elementsChanged = response.status !== 304;
+                const operationId = readRevoOperationId(response.headers);
+                errorOperationId = operationId || errorOperationId;
+                operations.elementsSave = {
+                    outcome: 'accepted',
+                    status: response.status,
+                    ok: response.ok,
+                    response: response.data,
+                    ...(operationId ? { errorOperationId: operationId } : {}),
+                };
+            }
+            catch (error) {
+                operations.elementsSave = describeComponentPushOperationError(error);
+                if (error instanceof ApiError) {
+                    errorOperationId = readRevoOperationId(error.headers) || errorOperationId;
+                }
+                if (!isNotModifiedError(error)) {
+                    throw error;
+                }
+            }
+        }
+        const refreshedRemote = hasLiveRemote
+            ? unwrapComponent(await client.getComponent(remoteComponentId))
+            : {
+                ...component,
+                componentId: remoteComponentId,
+                ...(componentVersion(remote) != null ? { version: componentVersion(remote) } : {}),
+            };
+        if (hasLiveRemote
+            && componentSourceHash(refreshedRemote, identity) !== componentSourceHash(component, identity)) {
+            const logPath = writeComponentPushVerificationLog({
+                cwd: context.cwd,
+                targetPath,
+                environment: context.componentEnvironment,
+                identity,
+                desired: component,
+                actual: refreshedRemote,
+                operations,
+                errorOperationId,
+            });
+            throw new Error(`Cannot push ${targetPath}: updated component did not verify against local source. Diagnostic: ${logPath}`);
+        }
+        upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component, context.componentEnvironment);
+        if (!configurationChanged && !elementsChanged) {
+            const result = {
+                status: 'skipped',
+                targetPath,
+                reason: 'no changes',
+            };
             printSyncStatus(println, {
                 status: 'Skipped',
                 direction: 'push',
@@ -884,13 +1261,6 @@ async function pushSingleComponent(context, manifestPath) {
             status: 'deployed',
             targetPath,
         };
-        try {
-            const remote = unwrapComponent(await client.getComponent(componentId));
-            upsertLockFromRemote(context.cwd, remote, targetPath);
-        }
-        catch {
-            upsertLockFromRemote(context.cwd, component, targetPath);
-        }
         printSyncStatus(println, {
             status: 'Deployed',
             direction: 'push',
@@ -911,7 +1281,6 @@ async function pushSingleComponent(context, manifestPath) {
                 targetPath,
                 reason: result.reason,
             });
-            upsertLockFromRemote(context.cwd, component, targetPath);
             return result;
         }
         if (error instanceof PermissionDeniedError) {
@@ -937,6 +1306,7 @@ async function pushSingleComponent(context, manifestPath) {
 async function pushAllComponents(context, options) {
     const { cwd, println } = context;
     const root = getWorkspaceRoot(cwd);
+    const identity = resolveComponentIdentity(cwd);
     let manifests = getComponentManifestPaths(root);
     if (manifests.length === 0) {
         println(`No component.json files found in ${path.relative(cwd, root) || 'Components'}.`);
@@ -954,67 +1324,64 @@ async function pushAllComponents(context, options) {
         }
     }
     await confirmBulkAction(context, 'push', manifests.length, options.force || options.yes);
+    const remoteCatalog = identity.mode === 'stableKey'
+        ? await buildRemoteComponentCatalog(context, identity)
+        : undefined;
+    if (remoteCatalog) {
+        migrateComponentLockIdentity(cwd, identity, buildLocalComponentCatalog(cwd, identity), remoteCatalog);
+    }
     const startedAt = Date.now();
     const results = [];
     for (const manifestPath of manifests) {
-        const result = await pushSingleComponent(context, manifestPath);
+        const result = await pushSingleComponent(context, manifestPath, remoteCatalog);
         if (result) {
             results.push(result);
         }
     }
-    printSummary(context.println, 'Deployed', results, Date.now() - startedAt);
+    printSyncSummary(context.println, 'Deployed', results, Date.now() - startedAt);
     return results;
 }
 async function buildComponentPlan(context, scope = { enabled: false, base: '', componentIds: new Set() }) {
     const projectRoot = getProjectRoot(context.cwd);
     const lock = readComponentLock(projectRoot);
     const root = getWorkspaceRoot(context.cwd);
-    const localManifests = getComponentManifestPaths(root);
-    const localById = new Map();
-    for (const manifestPath of localManifests) {
-        const component = readWorkspaceComponentSafe(manifestPath);
-        const componentId = component ? componentIdOf(component) : '';
-        if (component && componentId) {
-            localById.set(componentId, {
-                manifestPath,
-                component,
-                hash: hashComponentSource(component),
-            });
-        }
-    }
+    const identity = resolveComponentIdentity(context.cwd);
+    const localCatalog = buildLocalComponentCatalog(context.cwd, identity);
     const { components } = await fetchAllComponentSummaries(context);
-    const remoteIds = components.map((item) => String(item.componentId || item.id || '')).filter(Boolean);
-    const remoteById = new Map();
-    for (const componentId of remoteIds) {
-        const remote = unwrapComponent(await context.client.getComponent(componentId));
-        remoteById.set(componentId, {
-            component: remote,
-            hash: hashComponentSource(remote),
-        });
-    }
-    const allIds = [...new Set([
-            ...localById.keys(),
-            ...remoteById.keys(),
-            ...Object.keys(lock.components),
+    const remoteCatalog = await buildRemoteComponentCatalog(context, identity, components);
+    const lockEntries = getComponentLockEntries(lock, identity, context.componentEnvironment);
+    const allIdentityKeys = [...new Set([
+            ...localCatalog.byIdentity.keys(),
+            ...remoteCatalog.byIdentity.keys(),
+            ...Object.keys(lockEntries),
         ])].sort();
-    const items = allIds.map((componentId) => {
-        const local = localById.get(componentId) || null;
-        const remote = remoteById.get(componentId) || null;
-        const lockEntry = lock.components[componentId] || null;
+    const items = allIdentityKeys.map((identityKey) => {
+        const local = localCatalog.byIdentity.get(identityKey) || null;
+        const remote = remoteCatalog.byIdentity.get(identityKey) || null;
+        const lockEntry = lockEntries[identityKey] || null;
         const component = local?.component || remote?.component;
-        const componentName = component?.name || lockEntry?.componentName || componentId;
+        const localComponentId = local ? componentIdOf(local.component) : '';
+        const remoteComponentId = remote ? componentIdOf(remote.component) : lockEntry?.remoteComponentId || '';
+        const componentId = localComponentId || remoteComponentId || lockEntry?.componentId || identityKey;
+        const componentName = component?.name || lockEntry?.componentName || identityKey;
         const category = normalizeValue(component?.category, lockEntry?.category ?? null);
-        const targetPath = local
+        const targetPath = local?.manifestPath
             ? componentWorkspacePath(context.cwd, local.manifestPath)
             : remote
                 ? componentTargetPath(context.cwd, remote.component)
-                : lockEntry?.path || componentId;
+                : lockEntry?.path || identityKey;
         const localHash = local?.hash || null;
         const remoteHash = remote?.hash || null;
         const lockHash = lockEntry?.remoteHash || null;
+        const changedFields = local && remote
+            ? diffPortableComponentSource(local.component, remote.component).changedFields
+            : [];
         let status = 'clean';
         let reason = 'local, lock, and remote match';
-        if (!local && remote) {
+        if (!local && !remote) {
+            reason = 'lock entry has no matching local or remote component';
+        }
+        else if (!local && remote) {
             status = 'safe-update';
             reason = 'remote component is missing locally';
         }
@@ -1045,9 +1412,14 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
             status = 'conflict';
             reason = 'local and remote changed since lock';
         }
-        const inScope = !scope.enabled || scope.componentIds.has(componentId);
+        const inScope = !scope.enabled
+            || scope.componentIds.has(localComponentId)
+            || scope.componentIds.has(remoteComponentId);
         return {
             componentId,
+            identityKey,
+            ...(identity.mode === 'stableKey' ? { stableKey: identityKey } : {}),
+            ...(remoteComponentId ? { remoteComponentId } : {}),
             componentName,
             category,
             path: targetPath,
@@ -1057,6 +1429,7 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
             remoteHash,
             remoteVersion: remote ? componentVersion(remote.component) : lockEntry?.remoteVersion ?? null,
             reason,
+            ...(changedFields.length > 0 ? { changedFields } : {}),
             ...(scope.enabled ? { inScope } : {}),
         };
     });
@@ -1065,6 +1438,11 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
         schemaVersion: 1,
         generatedAt: new Date().toISOString(),
         workspaceRoot: path.relative(context.cwd, root) || 'Components',
+        componentIdentity: identity,
+        unmanaged: {
+            local: localCatalog.unmanaged.length,
+            remote: remoteCatalog.unmanaged.length,
+        },
         ...(scope.enabled ? {
             scope: {
                 mode: 'changed',
@@ -1087,12 +1465,6 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
         items: scopedItems,
     };
 }
-function printPlan(context, plan) {
-    for (const item of plan.items) {
-        context.println(`${item.status.padEnd(14)} ${item.path} ${item.reason ? `(${item.reason})` : ''}`.trimEnd());
-    }
-    context.println(`Plan: ${plan.items.length} components, ${plan.counts.conflict} conflicts, ${plan.counts['local-changed']} local changes, ${plan.counts['remote-changed']} remote changes.`);
-}
 function parseTargets(args, names) {
     const values = readValues(args, names);
     if (values.length > 0) {
@@ -1140,21 +1512,45 @@ function buildDebugElements(component) {
     if (!componentName) {
         throw new Error('Missing component name in local manifest.');
     }
-    return [...(component.elements || [])].sort((left, right) => left.order - right.order).map((element) => {
+    return sortDebugElements(component.elements || [], componentName).map((element) => {
+        const key = readDebugElementKey(element, componentName);
+        const order = readDebugElementOrder(element, key, componentName);
         const details = element.details || '';
         return {
-            key: element.key,
+            key,
             desc: element.desc ?? null,
             initValue: details,
             details,
             componentId,
             componentName,
-            order: element.order,
+            order,
             hidden: Boolean(element.hidden),
             uuid: typeof element.uuid === 'string' ? element.uuid : undefined,
         };
     });
 }
+function readDebugElementKey(element, componentName) {
+    if (typeof element.key === 'string' && element.key.trim()) {
+        return element.key;
+    }
+    const order = Number.isFinite(Number(element.order)) ? Number(element.order) : 'unknown';
+    throw new Error(`Debug element at order ${order} in "${componentName}" is missing a valid key.`);
+}
+function readDebugElementOrder(element, key, componentName) {
+    const order = Number(element.order);
+    if (Number.isFinite(order)) {
+        return order;
+    }
+    throw new Error(`Debug element "${key}" in "${componentName}" is missing a valid numeric order.`);
+}
+function sortDebugElements(elements, componentName) {
+    return [...elements].sort((left, right) => {
+        const leftOrder = readDebugElementOrder(left, readDebugElementKey(left, componentName), componentName);
+        const rightOrder = readDebugElementOrder(right, readDebugElementKey(right, componentName), componentName);
+        return leftOrder - rightOrder
+            || readDebugElementKey(left, componentName).localeCompare(readDebugElementKey(right, componentName));
+    });
+}
 function resolveElementSourcePath(manifestPath, component, element) {
     const componentDir = path.dirname(manifestPath);
     const detailDirs = [
@@ -1184,12 +1580,14 @@ function buildDebugSourceComponent(role, manifestPath, component) {
         componentName: component.name || '',
         type: normalizeComponentType(component),
         manifestPath,
-        elements: [...(component.elements || [])].sort((left, right) => left.order - right.order).map((element) => {
+        elements: sortDebugElements(component.elements || [], component.name || component.componentId || component.id || 'component').map((element) => {
+            const key = readDebugElementKey(element, component.name || component.componentId || component.id || 'component');
+            const order = readDebugElementOrder(element, key, component.name || component.componentId || component.id || 'component');
             const sourcePath = resolveElementSourcePath(manifestPath, component, element);
             const details = element.details || '';
             return {
-                key: element.key,
-                order: element.order,
+                key,
+                order,
                 sourcePath,
                 bytes: Buffer.byteLength(details, 'utf8'),
             };
@@ -1243,19 +1641,31 @@ function collectDebugExtraLibs(cwd, currentComponentId) {
         .filter(({ component }) => {
         const type = normalizeComponentType(component);
         const componentId = component.componentId || component.id || '';
-        return isDebugLibraryType(type) && componentId !== currentComponentId && Boolean(component.name);
+        return isDebugLibraryType(type) && Boolean(componentId) && componentId !== currentComponentId && Boolean(component.name);
     })
         .map(({ manifestPath, component }) => ({
         payload: {
+            componentId: component.componentId || component.id || '',
             name: component.name,
             type: normalizeComponentType(component),
+            ...(typeof component.version === 'number' ? { version: component.version } : {}),
             elements: buildDebugElements(component),
         },
         source: buildDebugSourceComponent('extraLib', manifestPath, component),
     }));
 }
 function writeRawDebugRequestDump(options) {
-    process.stderr.write(`[debug-request] ${JSON.stringify(options, null, 2)}\n`);
+    const directory = path.join(getConfigDir(), 'debug-requests');
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    try {
+        fs.chmodSync(directory, 0o700);
+    }
+    catch {
+        // Some platforms do not support Unix-style permissions.
+    }
+    const filePath = path.join(directory, `debug-request-${randomUUID()}.json`);
+    writeJsonFile(filePath, options);
+    process.stderr.write(`[debug-request] Saved private payload to ${filePath}\n`);
 }
 function formatProcessLog(log) {
     if (!log || typeof log !== 'object' || Array.isArray(log)) {
@@ -1315,7 +1725,8 @@ async function debugSingleComponent(context, componentId) {
     const timeout = parseDebugNumber(context.args, ['timeout', 't'], 10, 600, 'Timeout');
     const memory = parseDebugNumber(context.args, ['memory', 'm'], 128, 1024, 'Memory');
     const stream = readBoolFlag(context.args, ['stream']);
-    const includeExtraLibs = !readBoolFlag(context.args, ['no-extra-libs']);
+    const includeExtraLibs = context.args['extra-libs'] !== false
+        && !readBoolFlag(context.args, ['no-extra-libs']);
     const rawDebug = readBoolFlag(context.args, ['raw-debug', 'debug-raw', 'debug-payload']);
     const profile = await context.client.me();
     const sandboxEndpoint = extractSandboxEndpoint(profile);
@@ -1379,6 +1790,12 @@ export async function handleComponentCommand(context) {
     const json = readBoolFlag(args, ['json']);
     const strict = readBoolFlag(args, ['strict']);
     const changedScope = resolveChangedComponentScope(context);
+    if (context.componentEnvironment && ['pull', 'plan', 'push'].includes(subcommand)) {
+        const identity = resolveComponentIdentity(context.cwd);
+        if (identity.mode !== 'stableKey') {
+            throw new Error('Component sync with a named project requires componentIdentity.mode "stableKey". Configure it in .revoengine/revo.json before pulling from a named project.');
+        }
+    }
     if (subcommand === 'pull-all') {
         await pullAllComponents(context, { force, stale, yes });
         return;
@@ -1393,7 +1810,17 @@ export async function handleComponentCommand(context) {
             context.print(plan);
         }
         else {
-            printPlan(context, plan);
+            printSyncPlan(context.println, {
+                title: 'Component',
+                environment: context.componentEnvironment || 'default',
+                counts: plan.counts,
+                items: plan.items.map((item) => ({
+                    status: item.status,
+                    target: item.path,
+                    reason: item.reason,
+                    changedFields: item.changedFields,
+                })),
+            });
         }
         if (strict) {
             const blocking = plan.items.filter((item) => ((!changedScope.enabled || item.inScope)
@@ -1436,7 +1863,7 @@ export async function handleComponentCommand(context) {
             await pushAllComponents(context, { force, yes, scope: changedScope });
             return;
         }
-        const manifests = targets.flatMap((componentId) => findComponentManifestsById(context.cwd, componentId));
+        const manifests = targets.flatMap((target) => findComponentManifestsByTarget(context.cwd, target));
         if (manifests.length === 0) {
             throw new Error(`Unable to find local component for ${targets.join(', ')}.`);
         }