@revoengine/cli 1.0.5 → 1.0.7

package/README.md

@@ -90,17 +90,16 @@ Pull every available component:
 
 ```bash
 revo component pull --all
+revo component pull --all --yes
 revo component pull --all --force
 ```
 
-Pull one or more remote components:
+Preview sync status before changing local or remote state:
 
 ```bash
-revo component pull 6dfb536a-1111-4222-8333-123456789abc
-revo component pull 6dfb536a-1111-4222-8333-123456789abc --stale
-revo component pull --all
-revo component pull --all --stale
-revo component pull --all --force
+revo component plan --all
+revo component plan --all --json
+revo component plan --all --strict
 ```
 
 Push one or more local components:
@@ -108,6 +107,7 @@ Push one or more local components:
 ```bash
 revo component push 6dfb536a-1111-4222-8333-123456789abc
 revo component push --all
+revo component push --all --yes
 revo component push --all --force
 ```
 
@@ -135,14 +135,20 @@ Components/
 Each component folder keeps its `component.json` manifest alongside an `elements/` directory with the source payload for every element.
 Components with `category: null` are stored under `Components/__no_category__/...` while the manifest keeps `"category": null`.
 
+Remote sync state is stored separately in `.revoengine/revo.lock.json`. The lock file records the last remote component hash/version that this workspace was pulled from or successfully pushed to. It is a baseline, not the deployed source of truth; the server remains authoritative for deployed state and local component files remain the desired source.
+
 Bulk sync behavior:
 
-- `revo component pull --all` and `revo component push --all` require terminal confirmation unless `--force` is passed.
+- `revo component pull --all` and `revo component push --all` require terminal confirmation unless `--yes` or `--force` is passed.
+- `--yes` only confirms the bulk operation. `--force` is the destructive escape hatch that bypasses lock safety.
 - `revo component pull --all` requests only active remote components where `deletedAt` is empty.
-- Pull compares the full local workspace contract before overwriting anything.
-- Pull skips with `no changes` when the local workspace already matches the remote component.
-- Pull skips with `changed` when local files differ from the remote contract.
-- Pull skips with `stale version` when the local version is older than the remote version, unless `--stale` or `--force` is passed.
+- Pull compares local files, `.revoengine/revo.lock.json`, and the current remote component before overwriting anything.
+- Pull fast-forwards clean local files when the remote moved and the local copy still matches the lock.
+- Pull rejects conflicts when both local files and the remote changed since the lock baseline.
+- Pull writes stable source manifests and keeps remote version churn out of `Components/**/component.json`.
+- `revo component plan --all --strict` exits with an error when conflicts or missing lock entries are present.
+- Push checks the current remote component against the lock before saving local changes.
+- Push rejects stale remote state instead of trusting the version inside local component JSON.
 - Push treats backend `Not modified` responses as skipped instead of failing the whole run.
 - Push treats backend `404` responses as skipped with `doesn't exist remotely`; restore the component in RevoEngine before pushing local changes to it.
 - Debug posts the local `component.json` plus `elements/{order}_{key}.{js|ts}` source files to the authenticated sandbox `debug` endpoint.

package/dist/src/commands/component.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ApiError, PermissionDeniedError } from "../client.js";
-import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, resolveProjectWorkspace } from "../project.js";
+import { hashComponentSource, hashStable, readComponentLock, sanitizeComponentSource, upsertComponentLockEntry, } from "../component-lock.js";
+import { buildSandboxDebugStreamUrl, buildSandboxDebugUrl, extractSandboxEndpoint, resolveProjectRoot, resolveProjectWorkspace, } from "../project.js";
 import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
 import { deepClone, readBoolFlag, readFlag, readValues, sanitizeSegment, writeJsonFile } from "../utils.js";
 const NULL_CATEGORY_FOLDER = '__no_category__';
@@ -195,6 +196,9 @@ function getWorkspaceRoot(cwd) {
     const projectWorkspace = resolveProjectWorkspace(cwd);
     return path.join(projectWorkspace || cwd, 'Components');
 }
+function getProjectRoot(cwd) {
+    return resolveProjectRoot(cwd) || cwd;
+}
 function getCategoryFolder(component) {
     if (component.category == null || component.category === '') {
         return NULL_CATEGORY_FOLDER;
@@ -211,7 +215,7 @@ function getDetailsExtension(component) {
     return componentTypeToExtension(normalizeComponentType(component));
 }
 function stripDetails(component) {
-    const clone = deepClone(component);
+    const clone = sanitizeComponentSource(deepClone(component));
     clone.elements = (clone.elements || []).map((element) => {
         const next = deepClone(element);
         delete next.details;
@@ -406,28 +410,47 @@ function normalizeElementContract(element) {
     };
 }
 function normalizeComponentContract(component) {
-    const componentId = component.componentId || component.id || '';
-    return {
-        componentId,
-        name: component.name || '',
-        category: normalizeValue(component.category),
-        desc: normalizeValue(component.desc),
-        active: component.active ?? true,
+    return hashStable({
+        ...sanitizeComponentSource(component),
         type: normalizeComponentType(component),
         compiler: compilerFromType(component.type, component.compiler),
-        version: typeof component.version === 'number' ? component.version : null,
         elements: [...(component.elements || [])]
             .map((element) => normalizeElementContract(element))
             .sort((left, right) => left.order - right.order || left.key.localeCompare(right.key)),
-    };
+    });
 }
 function isSameComponentContract(left, right) {
-    return JSON.stringify(normalizeComponentContract(left)) === JSON.stringify(normalizeComponentContract(right));
+    return normalizeComponentContract(left) === normalizeComponentContract(right);
+}
+function componentVersion(component) {
+    return typeof component.version === 'number' ? component.version : null;
+}
+function componentIdOf(component) {
+    return component.componentId || component.id || '';
+}
+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) {
+        return;
+    }
+    const remoteHash = hashComponentSource(remote);
+    upsertComponentLockEntry(getProjectRoot(cwd), {
+        componentId,
+        componentName: remote.name || '',
+        category: normalizeValue(remote.category),
+        path: targetPath || componentTargetPath(cwd, remote),
+        remoteVersion: componentVersion(remote),
+        remoteHash,
+        sourceHash: remoteHash,
+        pulledAt: new Date().toISOString(),
+    });
 }
 function buildPullDecision(cwd, remote) {
-    const remoteFolder = path.join(getWorkspaceRoot(cwd), getComponentFolder(remote));
-    const remoteTargetPath = path.relative(cwd, remoteFolder);
-    const componentId = remote.componentId || remote.id || '';
+    const remoteTargetPath = componentTargetPath(cwd, remote);
+    const componentId = componentIdOf(remote);
     const localInfo = componentId ? findLocalManifestInfo(cwd, componentId) : null;
     if (!localInfo?.manifestPath) {
         return {
@@ -443,13 +466,42 @@ function buildPullDecision(cwd, remote) {
             reason: 'changed',
         };
     }
-    const localVersion = typeof localComponent.version === 'number' ? localComponent.version : null;
-    const remoteVersion = typeof remote.version === 'number' ? remote.version : null;
-    if (localVersion !== null && remoteVersion !== null && localVersion < remoteVersion) {
+    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,
-            reason: 'stale version',
+            reason: 'missing lock',
+        };
+    }
+    if (localHash === lockEntry.remoteHash && remoteHash !== lockEntry.remoteHash) {
+        return {
+            kind: 'pull',
+            targetPath: localInfo.targetPath || remoteTargetPath,
+            reason: 'remote changed',
+        };
+    }
+    if (localHash !== lockEntry.remoteHash && remoteHash === lockEntry.remoteHash) {
+        return {
+            kind: 'skip',
+            targetPath: localInfo.targetPath || remoteTargetPath,
+            reason: 'local changes',
+        };
+    }
+    if (localHash !== lockEntry.remoteHash && remoteHash !== lockEntry.remoteHash && localHash !== remoteHash) {
+        return {
+            kind: 'skip',
+            targetPath: localInfo.targetPath || remoteTargetPath,
+            reason: 'conflict',
         };
     }
     if (isSameComponentContract(localComponent, remote)) {
@@ -534,6 +586,12 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
             }
         }
         else {
+            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.`);
+            }
+            if (decision.reason === 'no changes') {
+                upsertLockFromRemote(cwd, component, decision.targetPath);
+            }
             const result = {
                 status: 'skipped',
                 targetPath: decision.targetPath,
@@ -560,6 +618,7 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
         fs.writeFileSync(filePath, content);
     }
     writeJsonFile(path.join(folder, 'component.json'), stripDetails(component));
+    upsertLockFromRemote(cwd, component, targetPath);
     const result = {
         status: 'pulled',
         targetPath,
@@ -575,7 +634,7 @@ async function pullSingleComponent(context, componentId, mode = { force: false,
     });
     return result;
 }
-async function pullAllComponents(context, options) {
+async function fetchAllComponentSummaries(context) {
     const { client, cwd } = context;
     const components = [];
     const seenRequests = new Set();
@@ -623,11 +682,18 @@ async function pullAllComponents(context, options) {
         }
         nextRequest = null;
     }
+    if (components.length === 0) {
+        return { components, discoveredTotal };
+    }
+    return { components, discoveredTotal };
+}
+async function pullAllComponents(context, options) {
+    const { components, discoveredTotal } = await fetchAllComponentSummaries(context);
     if (components.length === 0) {
         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);
+    await confirmBulkAction(context, 'pull', discoveredTotal ?? (components.length >= COMPONENT_LIST_PAGE_SIZE ? `at least ${components.length} components` : components.length), options.force || options.yes);
     const startedAt = Date.now();
     const results = [];
     for (const item of components) {
@@ -659,6 +725,9 @@ async function pushSingleComponent(context, manifestPath) {
         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 || '',
@@ -666,6 +735,52 @@ async function pushSingleComponent(context, manifestPath) {
         order: element.order,
     }));
     try {
+        if (!readBoolFlag(context.args, ['force', 'f'])) {
+            let remote = null;
+            try {
+                remote = unwrapComponent(await client.getComponent(componentId));
+            }
+            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;
+                }
+                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',
+                    targetPath,
+                    reason: 'no local changes',
+                };
+                printSyncStatus(println, {
+                    status: 'Skipped',
+                    direction: 'push',
+                    targetPath,
+                    reason: result.reason,
+                });
+                return result;
+            }
+        }
         const response = await client.saveComponentElements(componentId, elements);
         if (response.status === 304) {
             const result = {
@@ -673,6 +788,13 @@ async function pushSingleComponent(context, manifestPath) {
                 targetPath,
                 reason: 'no changes',
             };
+            try {
+                const remote = unwrapComponent(await client.getComponent(componentId));
+                upsertLockFromRemote(context.cwd, remote, targetPath);
+            }
+            catch {
+                upsertLockFromRemote(context.cwd, component, targetPath);
+            }
             printSyncStatus(println, {
                 status: 'Skipped',
                 direction: 'push',
@@ -685,6 +807,13 @@ 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',
@@ -705,6 +834,7 @@ async function pushSingleComponent(context, manifestPath) {
                 targetPath,
                 reason: result.reason,
             });
+            upsertLockFromRemote(context.cwd, component, targetPath);
             return result;
         }
         if (error instanceof PermissionDeniedError) {
@@ -735,7 +865,7 @@ async function pushAllComponents(context, options) {
         println(`No component.json files found in ${path.relative(cwd, root) || 'Components'}.`);
         return [];
     }
-    await confirmBulkAction(context, 'push', manifests.length, options.force);
+    await confirmBulkAction(context, 'push', manifests.length, options.force || options.yes);
     const startedAt = Date.now();
     const results = [];
     for (const manifestPath of manifests) {
@@ -747,6 +877,124 @@ async function pushAllComponents(context, options) {
     printSummary(context.println, 'Deployed', results, Date.now() - startedAt);
     return results;
 }
+async function buildComponentPlan(context) {
+    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 { 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),
+        ])].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 component = local?.component || remote?.component;
+        const componentName = component?.name || lockEntry?.componentName || componentId;
+        const category = normalizeValue(component?.category, lockEntry?.category ?? null);
+        const targetPath = local
+            ? componentWorkspacePath(context.cwd, local.manifestPath)
+            : remote
+                ? componentTargetPath(context.cwd, remote.component)
+                : lockEntry?.path || componentId;
+        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) {
+            status = 'safe-update';
+            reason = 'remote component is missing locally';
+        }
+        else if (local && !remote) {
+            status = 'create';
+            reason = 'local component does not exist remotely';
+        }
+        else if (!lockEntry) {
+            status = localHash === remoteHash ? 'clean' : 'missing-lock';
+            reason = localHash === remoteHash ? 'local matches remote; lock can be adopted' : 'no lock baseline exists';
+        }
+        else if (localHash === lockHash && remoteHash === lockHash) {
+            status = 'clean';
+        }
+        else if (localHash !== lockHash && remoteHash === lockHash) {
+            status = 'local-changed';
+            reason = 'local source changed and remote still matches lock';
+        }
+        else if (localHash === lockHash && remoteHash !== lockHash) {
+            status = 'remote-changed';
+            reason = 'remote changed and local is clean';
+        }
+        else if (localHash === remoteHash) {
+            status = 'clean';
+            reason = 'local matches remote; lock is stale';
+        }
+        else {
+            status = 'conflict';
+            reason = 'local and remote changed since lock';
+        }
+        return {
+            componentId,
+            componentName,
+            category,
+            path: targetPath,
+            status,
+            localHash,
+            lockHash,
+            remoteHash,
+            remoteVersion: remote ? componentVersion(remote.component) : lockEntry?.remoteVersion ?? null,
+            reason,
+        };
+    });
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        workspaceRoot: path.relative(context.cwd, root) || 'Components',
+        counts: items.reduce((counts, item) => {
+            counts[item.status] += 1;
+            return counts;
+        }, {
+            clean: 0,
+            'local-changed': 0,
+            'remote-changed': 0,
+            'safe-update': 0,
+            conflict: 0,
+            create: 0,
+            'missing-lock': 0,
+        }),
+        items,
+    };
+}
+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) {
@@ -965,13 +1213,35 @@ export async function handleComponentCommand(context) {
     const targets = parseTargets(args, ['id', 'i']);
     const all = readFlag(args, ['all', 'a']) === 'true' || args.all === true || args.a === true;
     const force = readBoolFlag(args, ['force', 'f']);
+    const yes = readBoolFlag(args, ['yes', 'y']);
     const stale = readBoolFlag(args, ['stale', 's']);
+    const json = readBoolFlag(args, ['json']);
+    const strict = readBoolFlag(args, ['strict']);
     if (subcommand === 'pull-all') {
-        await pullAllComponents(context, { force, stale });
+        await pullAllComponents(context, { force, stale, yes });
         return;
     }
     if (subcommand === 'push-all') {
-        await pushAllComponents(context, { force });
+        await pushAllComponents(context, { force, yes });
+        return;
+    }
+    if (subcommand === 'plan') {
+        const plan = await buildComponentPlan(context);
+        if (json) {
+            context.print(plan);
+        }
+        else {
+            printPlan(context, plan);
+        }
+        if (strict) {
+            const blocking = plan.items.filter((item) => (item.status === 'conflict'
+                || item.status === 'missing-lock'
+                || item.status === 'remote-changed'
+                || item.status === 'safe-update'));
+            if (blocking.length > 0) {
+                throw new Error(`Component plan is not safe: ${blocking.length} blocking item(s).`);
+            }
+        }
         return;
     }
     if (subcommand === 'debug') {
@@ -987,7 +1257,7 @@ export async function handleComponentCommand(context) {
             throw new Error('Provide --id <componentId> or --all.');
         }
         if (all) {
-            await pullAllComponents(context, { force, stale });
+            await pullAllComponents(context, { force, stale, yes });
             return;
         }
         for (const componentId of targets) {
@@ -1000,7 +1270,7 @@ export async function handleComponentCommand(context) {
             throw new Error('Provide --id <componentId> or --all.');
         }
         if (all) {
-            await pushAllComponents(context, { force });
+            await pushAllComponents(context, { force, yes });
             return;
         }
         const manifests = targets.flatMap((componentId) => findComponentManifestsById(context.cwd, componentId));

package/dist/src/component-lock.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentRecord } from './types.ts';
+export declare const REVO_LOCK_FILE: string;
+export type ComponentLockEntry = {
+    componentId: string;
+    componentName: string;
+    category: string | null;
+    path: string;
+    remoteVersion: number | null;
+    remoteHash: string;
+    sourceHash: string;
+    pulledAt: string;
+};
+export type RevoLockFile = {
+    schemaVersion: 1;
+    components: Record<string, ComponentLockEntry>;
+};
+export declare function hashStable(value: unknown): string;
+export declare function sanitizeComponentSource<T extends ComponentRecord>(component: T): T;
+export declare function normalizeComponentSource(component: ComponentRecord): {
+    componentId: string;
+    name: string;
+    category: string | null;
+    desc: string | null;
+    active: boolean;
+    type: string;
+    compiler: string;
+    async: boolean;
+    elements: {
+        key: string;
+        desc: string | null;
+        hidden: boolean;
+        order: number;
+        details: string;
+    }[];
+};
+export declare function hashComponentSource(component: ComponentRecord): string;
+export declare function getLockPath(projectRoot: string): string;
+export declare function readComponentLock(projectRoot: string): RevoLockFile;
+export declare function writeComponentLock(projectRoot: string, lock: RevoLockFile): void;
+export declare function upsertComponentLockEntry(projectRoot: string, entry: ComponentLockEntry): void;

package/dist/src/component-lock.js

@@ -0,0 +1,107 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { REVO_PROJECT_DIR } from "./project.js";
+import { readJsonFile, writeJsonFile } from "./utils.js";
+export const REVO_LOCK_FILE = path.join(REVO_PROJECT_DIR, 'revo.lock.json');
+const VOLATILE_COMPONENT_FIELDS = new Set([
+    'version',
+    'revision',
+    'deployedAt',
+    'lastDeployedAt',
+    'lastSyncAt',
+    'lastUpdateAt',
+    'lastUpdateBy',
+    'createdAt',
+    'createdBy',
+    'updatedAt',
+    'updatedBy',
+    'deletedAt',
+    'deletedBy',
+    'hash',
+    'remoteHash',
+]);
+function normalizeValue(value, fallback = null) {
+    return value ?? fallback;
+}
+function stableObject(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => stableObject(item));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    const output = {};
+    for (const key of Object.keys(value).sort()) {
+        output[key] = stableObject(value[key]);
+    }
+    return output;
+}
+export function hashStable(value) {
+    return crypto
+        .createHash('sha256')
+        .update(JSON.stringify(stableObject(value)))
+        .digest('hex');
+}
+export function sanitizeComponentSource(component) {
+    const clone = JSON.parse(JSON.stringify(component));
+    for (const field of VOLATILE_COMPONENT_FIELDS) {
+        delete clone[field];
+    }
+    return clone;
+}
+export function normalizeComponentSource(component) {
+    const source = sanitizeComponentSource(component);
+    const componentId = source.componentId || source.id || '';
+    return {
+        componentId,
+        name: source.name || '',
+        category: normalizeValue(source.category),
+        desc: normalizeValue(source.desc),
+        active: source.active ?? true,
+        type: source.type || '',
+        compiler: source.compiler || '',
+        async: Boolean(source.async),
+        elements: [...(source.elements || [])]
+            .map((element) => ({
+            key: element.key,
+            desc: normalizeValue(element.desc),
+            hidden: Boolean(element.hidden),
+            order: element.order,
+            details: element.details ?? '',
+        }))
+            .sort((left, right) => left.order - right.order || left.key.localeCompare(right.key)),
+    };
+}
+export function hashComponentSource(component) {
+    return hashStable(normalizeComponentSource(component));
+}
+export function getLockPath(projectRoot) {
+    return path.join(projectRoot, REVO_LOCK_FILE);
+}
+export function readComponentLock(projectRoot) {
+    const lockPath = getLockPath(projectRoot);
+    if (!fs.existsSync(lockPath)) {
+        return {
+            schemaVersion: 1,
+            components: {},
+        };
+    }
+    const raw = readJsonFile(lockPath);
+    return {
+        schemaVersion: 1,
+        components: raw.components && typeof raw.components === 'object' ? raw.components : {},
+    };
+}
+export function writeComponentLock(projectRoot, lock) {
+    const sortedComponents = Object.fromEntries(Object.entries(lock.components).sort(([left], [right]) => left.localeCompare(right)));
+    writeJsonFile(getLockPath(projectRoot), {
+        schemaVersion: 1,
+        components: sortedComponents,
+    });
+}
+export function upsertComponentLockEntry(projectRoot, entry) {
+    const lock = readComponentLock(projectRoot);
+    lock.components[entry.componentId] = entry;
+    writeComponentLock(projectRoot, lock);
+}

package/dist/src/types.d.ts

@@ -13,6 +13,7 @@ export type CommandContext = {
     error: (message: string) => void;
 };
 export type ComponentElementRecord = {
+    componentElementId?: string;
     key: string;
     desc?: string;
     details?: string;

package/dist/src/ui.js

@@ -108,10 +108,11 @@ function renderCommandCatalog() {
         commandRow('revo endpoints', 'List available API endpoints'),
         '',
         paintHeader('Components'),
-        commandRow('revo component pull <componentId...> [--force] [--stale]', 'Pull one or more components safely'),
-        commandRow('revo component pull --all [--force] [--stale]', 'Pull every available component with confirmation'),
+        commandRow('revo component plan --all [--json] [--strict]', 'Preview local/remote sync status'),
+        commandRow('revo component pull <componentId...> [--force]', 'Pull one or more components safely'),
+        commandRow('revo component pull --all [--yes] [--force]', 'Pull every available component safely'),
         commandRow('revo component push <componentId...>', 'Push one or more local components'),
-        commandRow('revo component push --all [--force]', 'Push every local component.json with confirmation'),
+        commandRow('revo component push --all [--yes] [--force]', 'Push every local component with lock checks'),
         commandRow('revo component debug <componentId> [BODY] [--stream]', 'Debug one local component against sandbox'),
         '',
         paintHeader('Low-Level'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revoengine/cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "CLI package for the RevoEngine Platform API",
   "type": "module",
   "main": "dist/src/index.js",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "check": "node --input-type=module -e \"await import('./src/config.ts'); await import('./src/legacy.ts'); await import('./src/client.ts'); await import('./src/ui.ts'); await import('./src/update-notifier.ts'); await import('./src/commands/auth.ts'); await import('./src/commands/component.ts'); await import('./src/commands/endpoints.ts'); await import('./src/commands/info.ts'); await import('./src/commands/request.ts'); await import('./src/commands/search.ts'); await import('./src/cli.ts'); await import('./src/index.ts'); await import('./bin/revo.ts'); await import('./scripts/dev.ts')\"",
+    "check": "node --input-type=module -e \"await import('./src/config.ts'); await import('./src/legacy.ts'); await import('./src/client.ts'); await import('./src/component-lock.ts'); await import('./src/ui.ts'); await import('./src/update-notifier.ts'); await import('./src/commands/auth.ts'); await import('./src/commands/component.ts'); await import('./src/commands/endpoints.ts'); await import('./src/commands/info.ts'); await import('./src/commands/request.ts'); await import('./src/commands/search.ts'); await import('./src/cli.ts'); await import('./src/index.ts'); await import('./bin/revo.ts'); await import('./scripts/dev.ts')\"",
     "dev": "node ./scripts/dev.ts",
     "prepack": "npm run build",
     "test": "node --test ./test/*.test.ts"