@revoengine/cli 1.0.8 → 1.0.10

package/dist/src/commands/component.js

@@ -1,17 +1,13 @@
 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 { ApiError, COMPONENT_LIST_PAGE_SIZE, PermissionDeniedError } from "../client.js";
+import { REVO_LOCK_FILE, componentLockMatchesIdentity, getComponentLockEntry, 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, } from "../resource-metadata.js";
 import { deepClone, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.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',
@@ -120,27 +116,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 +173,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 === '') {
@@ -298,6 +294,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 +400,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 +413,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,92 +444,317 @@ 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 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 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,
+    };
+    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) {
+    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 = hashComponentSource(remote);
+    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);
 }
-function buildPullDecision(cwd, remote) {
+function buildPullDecision(cwd, remote, localCatalog = buildLocalComponentCatalog(cwd, resolveComponentIdentity(cwd))) {
+    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);
+    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.`);
@@ -601,20 +762,60 @@ async function confirmSingleStalePull(context, targetPath) {
     printNotice(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));
+    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 +825,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 +866,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);
             }
             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,7 +889,9 @@ 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 });
@@ -694,8 +901,10 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
         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 manifestPath = path.join(folder, 'component.json');
+    writeJsonFile(manifestPath, buildPulledManifest(component, decision.localComponent, identity));
+    const localComponent = readWorkspaceComponentSafe(manifestPath) || decision.localComponent;
+    upsertLockFromRemote(cwd, component, targetPath, localComponent);
     const result = {
         status: 'pulled',
         targetPath,
@@ -711,58 +920,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,19 +961,26 @@ 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);
         }
@@ -790,39 +988,120 @@ async function pullAllComponents(context, options) {
     printSummary(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,
+        };
+    });
+}
+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 {
+        const remote = await resolveRemoteComponentForLocal(context, component, identity, resolvedRemoteCatalog);
+        if (!remote) {
+            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'])) {
-            let remote = null;
-            try {
-                remote = unwrapComponent(await client.getComponent(componentId));
+            const lockEntry = getComponentLockEntry(readComponentLock(getProjectRoot(context.cwd)), identity, component);
+            if (!lockEntry) {
+                throw new Error(`Cannot push ${targetPath}: missing lock entry. Run \`revo component pull ${identityKey} --force\` to establish a remote baseline.`);
             }
-            catch (error) {
-                if (error instanceof ApiError && error.status === 404) {
+            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 = componentSourceHash(remote, identity);
+            const localHash = componentSourceHash(component, identity);
+            if (remoteHash !== lockEntry.remoteHash) {
+                if (localHash === remoteHash) {
+                    upsertLockFromRemote(context.cwd, remote, targetPath, component);
                     const result = {
                         status: 'skipped',
                         targetPath,
-                        reason: "doesn't exist remotely",
+                        reason: 'local matches remote; lock refreshed',
                     };
                     printSyncStatus(println, {
                         status: 'Skipped',
@@ -832,17 +1111,8 @@ async function pushSingleComponent(context, manifestPath) {
                     });
                     return result;
                 }
-                rethrowComponentAccessError(error, 'push');
-            }
-            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.`);
-            }
-            const remoteHash = hashComponentSource(remote);
-            if (remoteHash !== lockEntry.remoteHash) {
                 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,7 +1128,8 @@ async function pushSingleComponent(context, manifestPath) {
                 return result;
             }
         }
-        const response = await client.saveComponentElements(componentId, elements);
+        const elements = buildPushElements(component, remote, identity);
+        const response = await client.saveComponentElements(remoteComponentId, elements);
         if (response.status === 304) {
             const result = {
                 status: 'skipped',
@@ -866,11 +1137,11 @@ async function pushSingleComponent(context, manifestPath) {
                 reason: 'no changes',
             };
             try {
-                const remote = unwrapComponent(await client.getComponent(componentId));
-                upsertLockFromRemote(context.cwd, remote, targetPath);
+                const refreshedRemote = unwrapComponent(await client.getComponent(remoteComponentId));
+                upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component);
             }
             catch {
-                upsertLockFromRemote(context.cwd, component, targetPath);
+                upsertLockFromRemote(context.cwd, remote, targetPath, component);
             }
             printSyncStatus(println, {
                 status: 'Skipped',
@@ -885,11 +1156,15 @@ async function pushSingleComponent(context, manifestPath) {
             targetPath,
         };
         try {
-            const remote = unwrapComponent(await client.getComponent(componentId));
-            upsertLockFromRemote(context.cwd, remote, targetPath);
+            const refreshedRemote = unwrapComponent(await client.getComponent(remoteComponentId));
+            upsertLockFromRemote(context.cwd, refreshedRemote, targetPath, component);
         }
         catch {
-            upsertLockFromRemote(context.cwd, component, targetPath);
+            upsertLockFromRemote(context.cwd, {
+                ...component,
+                componentId: remoteComponentId,
+                ...(componentVersion(remote) != null ? { version: componentVersion(remote) } : {}),
+            }, targetPath, component);
         }
         printSyncStatus(println, {
             status: 'Deployed',
@@ -911,7 +1186,6 @@ async function pushSingleComponent(context, manifestPath) {
                 targetPath,
                 reason: result.reason,
             });
-            upsertLockFromRemote(context.cwd, component, targetPath);
             return result;
         }
         if (error instanceof PermissionDeniedError) {
@@ -937,6 +1211,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,10 +1229,16 @@ 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);
         }
@@ -969,52 +1250,40 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
     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 = componentLockMatchesIdentity(lock, identity) ? lock.components : {};
+    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;
         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 +1314,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,
@@ -1060,10 +1334,16 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
             ...(scope.enabled ? { inScope } : {}),
         };
     });
+    const scopedItems = scope.enabled ? items.filter((item) => item.inScope) : items;
     return {
         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',
@@ -1071,7 +1351,7 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
                 componentIds: [...scope.componentIds].sort(),
             },
         } : {}),
-        counts: items.reduce((counts, item) => {
+        counts: scopedItems.reduce((counts, item) => {
             counts[item.status] += 1;
             return counts;
         }, {
@@ -1083,7 +1363,7 @@ async function buildComponentPlan(context, scope = { enabled: false, base: '', c
             create: 0,
             'missing-lock': 0,
         }),
-        items,
+        items: scopedItems,
     };
 }
 function printPlan(context, plan) {
@@ -1139,21 +1419,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 = [
@@ -1183,12 +1487,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'),
             };
@@ -1242,12 +1548,14 @@ 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),
@@ -1314,7 +1622,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);
@@ -1435,7 +1744,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(', ')}.`);
         }