@revoengine/cli 1.0.4 → 1.0.6

package/README.md

@@ -57,7 +57,7 @@ revo project init ./app
 revo project update ./app
 ```
 
-This writes or refreshes `.revoengine/types/revo.editor.d.ts`, `.revoengine/revo.json`, patches `tsconfig.json` or `jsconfig.json`, and updates `.gitignore` so the generated type bundle stays local by default. Pass a path such as `./backend` when the RevoEngine workspace is nested.
+This writes or refreshes root `.revoengine/types/revo.editor.d.ts`, `.revoengine/types/revo.editor.definitions.json`, and `.revoengine/revo.json`, patches the workspace `tsconfig.json` or `jsconfig.json`, and updates root `.gitignore` so the generated editor bundle stays local by default. Pass a path such as `./backend` when the RevoEngine workspace is nested; the path is saved as `.revoengine/revo.json.workspace` while root `.revoengine/` remains the single state directory.
 
 ## Common commands
 
@@ -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
 ```
 
@@ -117,6 +117,7 @@ Debug one local component in sandbox:
 revo component debug 6dfb536a-1111-4222-8333-123456789abc
 revo component debug 6dfb536a-1111-4222-8333-123456789abc -d '{"filters":{}}'
 revo component debug 6dfb536a-1111-4222-8333-123456789abc --timeout 30 --memory 256
+revo component debug 6dfb536a-1111-4222-8333-123456789abc --stream
 ```
 
 Pulled components are stored as a tree:
@@ -134,17 +135,26 @@ 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.
+- `revo component debug --stream` posts to `debug/stream`, writes live `api.log()` frames to stderr, and writes the final raw result payload to stdout.
+- Debug responses are saved under `.revoengine/output/debug_<timestamp>.json`.
+- Debug includes local `CODE_TS_LIB` and `CODE_JS_LIB` components as temporary `extraLibs` overrides by default. Use `--no-extra-libs` when you want backend-saved libraries only.
 - Sync logs show direction explicitly: `RevoEngine -> path` for pull and `RevoEngine <- path` for push.
 - Bulk runs print a summary such as `Deployed 54/67, Skipped 13/67 in 13s`.
 

package/dist/src/client.d.ts

@@ -9,6 +9,10 @@ export type ComponentListRequest = {
     path?: string;
     query?: Record<string, unknown>;
 };
+export type DebugStreamEvent = {
+    event: string;
+    data: unknown;
+};
 export type ClientOptions = {
     baseUrl?: string;
     instance?: string;
@@ -64,6 +68,7 @@ export declare class RevoClient {
     listEndpoints(): Promise<unknown>;
     getEditorTypes(requestPath?: string): Promise<unknown>;
     debugComponent(requestPath: string, body: unknown): Promise<unknown>;
+    debugComponentStream(requestPath: string, body: unknown): AsyncGenerator<DebugStreamEvent>;
     search(params: Record<string, unknown>): Promise<unknown>;
     listComponents(options?: ComponentListRequest): Promise<unknown>;
     getComponent(componentId: string): Promise<unknown>;

package/dist/src/client.js

@@ -125,6 +125,73 @@ async function readResponseData(response) {
     }
     return text;
 }
+function parseSseFrame(frame) {
+    let event = 'message';
+    const dataLines = [];
+    for (const line of frame.split(/\r?\n/g)) {
+        if (!line || line.startsWith(':')) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(':');
+        const field = separatorIndex >= 0 ? line.slice(0, separatorIndex) : line;
+        const rawValue = separatorIndex >= 0 ? line.slice(separatorIndex + 1) : '';
+        const value = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue;
+        if (field === 'event') {
+            event = value || event;
+        }
+        else if (field === 'data') {
+            dataLines.push(value);
+        }
+    }
+    if (dataLines.length === 0) {
+        return null;
+    }
+    const rawData = dataLines.join('\n');
+    let data = rawData;
+    try {
+        data = JSON.parse(rawData);
+    }
+    catch {
+        // Keep non-JSON SSE payloads readable instead of dropping them.
+    }
+    return {
+        event,
+        data,
+    };
+}
+async function* readSseEvents(response) {
+    if (!response.body) {
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+            break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        let separatorMatch = buffer.match(/\r?\n\r?\n/);
+        while (separatorMatch?.index !== undefined) {
+            const frame = buffer.slice(0, separatorMatch.index);
+            buffer = buffer.slice(separatorMatch.index + separatorMatch[0].length);
+            const event = parseSseFrame(frame);
+            if (event) {
+                yield event;
+            }
+            separatorMatch = buffer.match(/\r?\n\r?\n/);
+        }
+    }
+    buffer += decoder.decode();
+    const trailing = buffer.trim();
+    if (trailing) {
+        const event = parseSseFrame(trailing);
+        if (event) {
+            yield event;
+        }
+    }
+}
 function readProfileInstanceId(profile) {
     if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
         return '';
@@ -316,6 +383,43 @@ export class RevoClient {
             spinnerLabel: 'Debugging component',
         });
     }
+    async *debugComponentStream(requestPath, body) {
+        this.assertReady();
+        await this.validateSession();
+        const url = buildUrl(this.baseUrl, requestPath);
+        const headers = new Headers();
+        headers.set('Accept', 'text/event-stream');
+        headers.set('Content-Type', 'application/json');
+        headers.set('Authorization', this.authHeader);
+        headers.set('x-api-key', this.token);
+        if (this.instance) {
+            headers.set('instance', this.instance);
+            headers.set('x-api-instance', this.instance);
+        }
+        const response = await this.fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const data = await readResponseData(response);
+            if (response.status === 401) {
+                saveAuthValidationState({
+                    key: this.authValidationKey,
+                    status: 'not_authenticated',
+                    checkedAt: Date.now(),
+                });
+                throw new AuthenticationError(401, 'Not authenticated. Run `revo auth login`.', data);
+            }
+            if (response.status === 403) {
+                throw new PermissionDeniedError(requestPath, `Access denied for ${requestPath}.`, data);
+            }
+            throw new ApiError(response.status, toErrorMessage(typeof data === 'string' ? data : JSON.stringify(data), response.status), data);
+        }
+        for await (const event of readSseEvents(response)) {
+            yield event;
+        }
+    }
     async search(params) {
         return this.requestData('GET', '/api/v1/search', { query: params });
     }

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 { 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: '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: 'stale version',
+            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) {
@@ -666,6 +732,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 = {
@@ -685,6 +797,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 +824,7 @@ async function pushSingleComponent(context, manifestPath) {
                 targetPath,
                 reason: result.reason,
             });
+            upsertLockFromRemote(context.cwd, component, targetPath);
             return result;
         }
         if (error instanceof PermissionDeniedError) {
@@ -735,7 +855,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 +867,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) {
@@ -794,7 +1032,7 @@ function buildDebugElements(component) {
     if (!componentName) {
         throw new Error('Missing component name in local manifest.');
     }
-    return (component.elements || []).map((element) => {
+    return [...(component.elements || [])].sort((left, right) => left.order - right.order).map((element) => {
         const details = element.details || '';
         return {
             key: element.key,
@@ -809,6 +1047,101 @@ function buildDebugElements(component) {
         };
     });
 }
+function isDebugLibraryType(type) {
+    return type === 'CODE_TS_LIB' || type === 'CODE_JS_LIB';
+}
+function readLibraryDebugCode(cwd, type) {
+    const fileName = type === 'CODE_TS_LIB' ? 'debug_code.ts' : 'debug_code.js';
+    const filePath = path.join(cwd, '.revoengine', fileName);
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+}
+function buildDebugPayload(cwd, component, input) {
+    const type = normalizeComponentType(component);
+    const base = {
+        type,
+        inputs: input.inputs,
+        timeout: input.timeout,
+        memory: input.memory,
+        ...(input.extraLibs?.length ? { extraLibs: input.extraLibs } : {}),
+    };
+    if (!isDebugLibraryType(type)) {
+        return {
+            ...base,
+            elements: buildDebugElements(component),
+        };
+    }
+    return {
+        ...base,
+        libName: component.name || '',
+        libElements: buildDebugElements(component),
+        elements: [
+            {
+                key: 'Code',
+                order: 0,
+                details: readLibraryDebugCode(cwd, type),
+                hidden: false,
+            },
+        ],
+    };
+}
+function collectDebugExtraLibs(cwd, currentComponentId) {
+    return getComponentManifestPaths(getWorkspaceRoot(cwd))
+        .map((manifestPath) => readWorkspaceComponentSafe(manifestPath))
+        .filter((component) => Boolean(component))
+        .filter((component) => {
+        const type = normalizeComponentType(component);
+        const componentId = component.componentId || component.id || '';
+        return isDebugLibraryType(type) && componentId !== currentComponentId && Boolean(component.name);
+    })
+        .map((component) => ({
+        name: component.name,
+        type: normalizeComponentType(component),
+        elements: buildDebugElements(component),
+    }));
+}
+function formatProcessLog(log) {
+    if (!log || typeof log !== 'object' || Array.isArray(log)) {
+        return String(log ?? '');
+    }
+    const record = log;
+    const parts = [
+        typeof record.time === 'string' ? record.time : '',
+        typeof record.type === 'string' ? record.type : 'INFO',
+        typeof record.context === 'string' && record.context ? `[${record.context}]` : '',
+        typeof record.details?.message === 'string' ? record.details.message : '',
+    ].filter(Boolean);
+    const args = record.details?.args === undefined ? '' : ` ${JSON.stringify(record.details.args)}`;
+    return `${parts.join(' ')}${args}`;
+}
+function writeDebugOutputFile(cwd, response) {
+    if (response === undefined || response === null || response === '') {
+        return '';
+    }
+    const outputDir = path.join(cwd, '.revoengine', 'output');
+    fs.mkdirSync(outputDir, { recursive: true });
+    const timestamp = Math.floor(Date.now() / 1000);
+    let outputFile = path.join(outputDir, `debug_${timestamp}.json`);
+    let suffix = 1;
+    while (fs.existsSync(outputFile)) {
+        outputFile = path.join(outputDir, `debug_${timestamp}_${suffix}.json`);
+        suffix += 1;
+    }
+    fs.writeFileSync(outputFile, `${JSON.stringify(response, null, 2)}\n`);
+    return outputFile;
+}
+function extractResultPayload(response) {
+    if (!response || typeof response !== 'object' || Array.isArray(response)) {
+        return response;
+    }
+    const record = response;
+    if (Object.prototype.hasOwnProperty.call(record, 'result')) {
+        return record.result;
+    }
+    if (Object.prototype.hasOwnProperty.call(record, 'results')) {
+        return record.results;
+    }
+    return response;
+}
 async function debugSingleComponent(context, componentId) {
     const manifests = findComponentManifestsById(context.cwd, componentId);
     if (manifests.length === 0) {
@@ -819,23 +1152,50 @@ async function debugSingleComponent(context, componentId) {
     }
     const manifestPath = manifests[0];
     const component = readWorkspaceComponent(manifestPath);
-    const type = normalizeComponentType(component);
+    const componentKey = component.componentId || component.id || componentId;
     const inputs = parseDebugInputs(context.args);
     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 profile = await context.client.me();
     const sandboxEndpoint = extractSandboxEndpoint(profile);
     if (!sandboxEndpoint) {
         throw new Error('Authenticated profile did not include `endpoints.sandbox`, so component debug cannot run.');
     }
-    const response = await context.client.debugComponent(buildSandboxDebugUrl(sandboxEndpoint), {
-        elements: buildDebugElements(component),
-        type,
+    const payload = buildDebugPayload(context.cwd, component, {
         inputs,
         timeout,
         memory,
+        extraLibs: includeExtraLibs ? collectDebugExtraLibs(context.cwd, componentKey) : [],
     });
-    context.print(response);
+    if (stream) {
+        let result;
+        let done = false;
+        for await (const event of context.client.debugComponentStream(buildSandboxDebugStreamUrl(sandboxEndpoint), payload)) {
+            if (event.event === 'log') {
+                process.stderr.write(`${formatProcessLog(event.data)}\n`);
+            }
+            else if (event.event === 'result') {
+                result = event.data;
+            }
+            else if (event.event === 'error') {
+                throw new Error(`Debug stream failed: ${JSON.stringify(event.data)}`);
+            }
+            else if (event.event === 'done') {
+                done = true;
+            }
+        }
+        if (!done) {
+            throw new Error('Debug stream ended before the done event.');
+        }
+        writeDebugOutputFile(context.cwd, result);
+        context.print(extractResultPayload(result));
+        return;
+    }
+    const response = await context.client.debugComponent(buildSandboxDebugUrl(sandboxEndpoint), payload);
+    writeDebugOutputFile(context.cwd, response);
+    context.print(extractResultPayload(response));
 }
 export async function handleComponentCommand(context) {
     const { args } = context;
@@ -843,19 +1203,41 @@ 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') {
         const componentId = args._[2] || readFlag(args, ['id', 'i']) || '';
         if (!componentId) {
-            throw new Error('Missing component ID. Usage: `revo component debug <componentId> [-d <json>] [--timeout <seconds>] [--memory <mb>]`.');
+            throw new Error('Missing component ID. Usage: `revo component debug <componentId> [-d <json>] [--timeout <seconds>] [--memory <mb>] [--stream]`.');
         }
         await debugSingleComponent(context, componentId);
         return;
@@ -865,7 +1247,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) {
@@ -878,7 +1260,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/commands/project.js

@@ -1,10 +1,14 @@
 import path from 'node:path';
 import { buildProjectSyncState, buildEditorTypesUrl, extractSandboxEndpoint, extractEditorTypesBundle, resolveProjectInvocation, resolveProjectTarget, syncProjectFiles, } from "../project.js";
-function printSyncSummary(println, targetDir, result, prefix) {
-    println(`${prefix} ${targetDir}`);
-    println(`Wrote ${path.relative(targetDir, result.typesFile)}`);
-    println(`Wrote ${path.relative(targetDir, result.metadataFile)}`);
-    println(`${result.configResult.action === 'created' ? 'Created' : 'Patched'} ${path.basename(result.configResult.filePath)}`);
+function printSyncSummary(println, projectRoot, workspaceRoot, result, prefix) {
+    const workspaceDirectory = path.relative(projectRoot, workspaceRoot) || '.';
+    println(`${prefix} ${projectRoot}`);
+    if (workspaceDirectory !== '.') {
+        println(`Workspace ${workspaceDirectory}`);
+    }
+    println(`Wrote ${path.relative(projectRoot, result.typesFile)}`);
+    println(`Wrote ${path.relative(projectRoot, result.metadataFile)}`);
+    println(`${result.configResult.action === 'created' ? 'Created' : 'Patched'} ${path.relative(projectRoot, result.configResult.filePath)}`);
     if (result.gitignoreResult.action === 'created') {
         println('Created .gitignore');
     }
@@ -33,8 +37,8 @@ export async function handleProjectCommand(context) {
     if (invocation.extraArgs.length > 0) {
         throw new Error(`Project ${invocation.action} accepts at most one path argument.`);
     }
-    const targetDir = resolveProjectTarget(cwd, invocation.targetArg);
+    const layout = resolveProjectTarget(cwd, invocation.targetArg);
     const syncInput = await resolveProjectSyncInput(context);
-    const result = syncProjectFiles(targetDir, syncInput);
-    printSyncSummary(println, targetDir, result, invocation.action === 'update' ? 'Updated Revo project in' : 'Initialized Revo project in');
+    const result = syncProjectFiles(layout, syncInput);
+    printSyncSummary(println, layout.projectRoot, layout.workspaceRoot, result, invocation.action === 'update' ? 'Updated Revo project in' : 'Initialized Revo project in');
 }

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/project.d.ts

@@ -2,6 +2,7 @@ import type { ParsedArgs } from './types.ts';
 export declare const REVO_PROJECT_DIR = ".revoengine";
 export declare const REVO_TYPES_DIR: string;
 export declare const REVO_TYPES_FILE: string;
+export declare const REVO_TYPES_DEFINITIONS_FILE: string;
 export declare const REVO_METADATA_FILE: string;
 export declare const REVO_TYPES_GITIGNORE_ENTRY = ".revoengine/types/";
 export declare const REVO_DEBUG_JS_FILE: string;
@@ -17,6 +18,7 @@ export type ProjectInvocation = {
 };
 export type EditorTypesBundle = {
     code: string;
+    definitions?: unknown[];
     endpoint?: string;
     apiVersion?: string;
     libVersion?: string;
@@ -36,6 +38,7 @@ export type RevoProjectMetadata = {
 export type ProjectSyncInput = {
     endpoint: string;
     code: string;
+    definitions: unknown[];
     apiVersion: string;
     libVersion: string;
     hash: string;
@@ -49,12 +52,18 @@ export type GitignorePatchResult = {
     filePath: string;
     action: 'created' | 'patched' | 'unchanged';
 };
+export type ProjectTargetLayout = {
+    projectRoot: string;
+    workspaceRoot: string;
+    workspaceDirectory: string;
+};
 export declare function resolveProjectInvocation(args: ParsedArgs): ProjectInvocation;
-export declare function resolveProjectTarget(cwd: string, targetArg?: string): string;
+export declare function resolveProjectTarget(cwd: string, targetArg?: string): ProjectTargetLayout;
 export declare function extractEditorTypesBundle(payload: unknown): EditorTypesBundle;
 export declare function buildEditorEndpoint(baseUrl: string): string;
 export declare function buildEditorTypesUrl(endpoint: string): string;
 export declare function buildSandboxDebugUrl(endpoint: string): string;
+export declare function buildSandboxDebugStreamUrl(endpoint: string): string;
 export declare function extractSandboxEndpoint(profile: unknown): string | null;
 export declare function buildProjectMetadata(input: {
     baseUrl: string;
@@ -80,18 +89,20 @@ export declare function buildProjectSyncState(input: {
 }): {
     endpoint: string;
     code: string;
+    definitions: unknown[];
     apiVersion: string;
     libVersion: string;
     hash: string;
     lastSyncAt: string;
 };
-export declare function syncProjectFiles(targetDir: string, input: ProjectSyncInput): {
+export declare function syncProjectFiles(layoutOrTargetDir: ProjectTargetLayout | string, input: ProjectSyncInput): {
     projectDir: string;
     typesFile: string;
+    definitionsFile: string;
     metadataFile: string;
     configResult: ProjectConfigResult;
     gitignoreResult: GitignorePatchResult;
 };
 export declare function ensureProjectDebugScaffolding(rootDir: string): void;
-export declare function ensureProjectConfig(rootDir: string): ProjectConfigResult;
+export declare function ensureProjectConfig(rootDir: string, typesInclude?: string): ProjectConfigResult;
 export declare function ensureProjectGitignore(rootDir: string): GitignorePatchResult;

package/dist/src/project.js

@@ -4,6 +4,7 @@ import { readJsonFile } from "./utils.js";
 export const REVO_PROJECT_DIR = '.revoengine';
 export const REVO_TYPES_DIR = path.join(REVO_PROJECT_DIR, 'types');
 export const REVO_TYPES_FILE = path.join(REVO_TYPES_DIR, 'revo.editor.d.ts');
+export const REVO_TYPES_DEFINITIONS_FILE = path.join(REVO_TYPES_DIR, 'revo.editor.definitions.json');
 export const REVO_METADATA_FILE = path.join(REVO_PROJECT_DIR, 'revo.json');
 export const REVO_TYPES_GITIGNORE_ENTRY = '.revoengine/types/';
 export const REVO_DEBUG_JS_FILE = path.join(REVO_PROJECT_DIR, 'debug_code.js');
@@ -208,8 +209,29 @@ export function resolveProjectInvocation(args) {
         extraArgs: second ? [second, ...rest] : rest,
     };
 }
+function normalizeWorkspaceDirectory(projectRoot, workspaceRoot) {
+    const relative = path.relative(projectRoot, workspaceRoot).split(path.sep).join('/');
+    if (relative === '') {
+        return '.';
+    }
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('Project workspace directory must stay inside the Revo project root.');
+    }
+    return relative;
+}
 export function resolveProjectTarget(cwd, targetArg) {
-    return path.resolve(cwd, targetArg || '.');
+    const existingProjectRoot = resolveProjectRoot(cwd);
+    const projectRoot = existingProjectRoot || path.resolve(cwd);
+    const existingMetadata = existingProjectRoot ? readProjectMetadata(projectRoot) : null;
+    const workspaceRoot = targetArg
+        ? path.resolve(cwd, targetArg)
+        : resolveProjectWorkspaceRoot(projectRoot, existingMetadata?.workspace || '.');
+    const workspaceDirectory = normalizeWorkspaceDirectory(projectRoot, workspaceRoot);
+    return {
+        projectRoot,
+        workspaceRoot,
+        workspaceDirectory,
+    };
 }
 export function extractEditorTypesBundle(payload) {
     const root = isRecord(payload) && isRecord(payload.data) ? payload.data : payload;
@@ -223,6 +245,7 @@ export function extractEditorTypesBundle(payload) {
     }
     return {
         code,
+        definitions: Array.isArray(root.definitions) ? root.definitions : [],
         endpoint: readString(root.endpoint) || readString(meta?.endpoint),
         apiVersion: readString(root.apiVersion) || readString(meta?.apiVersion),
         libVersion: readString(root.libVersion) || readString(meta?.libVersion),
@@ -256,6 +279,15 @@ export function buildSandboxDebugUrl(endpoint) {
     url.hash = '';
     return url.toString();
 }
+export function buildSandboxDebugStreamUrl(endpoint) {
+    const url = new URL(endpoint);
+    const basePath = normalizeEndpoint(url.pathname);
+    const versionedPath = /\/v\d+$/i.test(basePath) ? basePath : `${basePath || ''}/v1`;
+    url.pathname = `${versionedPath}/debug/stream`.replace(/\/{2,}/g, '/');
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
 export function extractSandboxEndpoint(profile) {
     if (!profile || typeof profile !== 'object') {
         return null;
@@ -368,20 +400,38 @@ export function buildProjectSyncState(input) {
     return {
         endpoint: metadata.endpoint,
         code: input.bundle.code,
+        definitions: input.bundle.definitions ?? [],
         apiVersion: metadata.apiVersion,
         libVersion: metadata.libVersion,
         hash: metadata.hash,
         lastSyncAt: metadata.lastSyncAt,
     };
 }
-export function syncProjectFiles(targetDir, input) {
-    const projectDir = path.join(targetDir, REVO_PROJECT_DIR);
-    const typesDir = path.join(targetDir, REVO_TYPES_DIR);
+function toPosixRelative(fromDir, toPath) {
+    const relative = path.relative(fromDir, toPath).split(path.sep).join('/');
+    return relative || path.basename(toPath);
+}
+export function syncProjectFiles(layoutOrTargetDir, input) {
+    const layout = typeof layoutOrTargetDir === 'string'
+        ? {
+            projectRoot: layoutOrTargetDir,
+            workspaceRoot: layoutOrTargetDir,
+            workspaceDirectory: '.',
+        }
+        : layoutOrTargetDir;
+    const { projectRoot, workspaceRoot, workspaceDirectory } = layout;
+    const projectDir = path.join(projectRoot, REVO_PROJECT_DIR);
+    const typesDir = path.join(projectRoot, REVO_TYPES_DIR);
     fs.mkdirSync(projectDir, { recursive: true });
     fs.mkdirSync(typesDir, { recursive: true });
-    const typesFile = path.join(targetDir, REVO_TYPES_FILE);
-    const metadataFile = path.join(targetDir, REVO_METADATA_FILE);
+    const typesFile = path.join(projectRoot, REVO_TYPES_FILE);
+    const definitionsFile = path.join(projectRoot, REVO_TYPES_DEFINITIONS_FILE);
+    const metadataFile = path.join(projectRoot, REVO_METADATA_FILE);
     fs.writeFileSync(typesFile, input.code);
+    writeJsonFile(definitionsFile, {
+        schemaVersion: 1,
+        definitions: input.definitions,
+    });
     writeJsonFile(metadataFile, {
         schemaVersion: 1,
         endpoint: input.endpoint,
@@ -390,13 +440,15 @@ export function syncProjectFiles(targetDir, input) {
         libVersion: input.libVersion,
         hash: input.hash,
         lastSyncAt: input.lastSyncAt,
+        ...(workspaceDirectory !== '.' ? { workspace: workspaceDirectory } : {}),
     });
-    const configResult = ensureProjectConfig(targetDir);
-    const gitignoreResult = ensureProjectGitignore(targetDir);
-    ensureProjectDebugScaffolding(targetDir);
+    const configResult = ensureProjectConfig(workspaceRoot, toPosixRelative(workspaceRoot, typesFile));
+    const gitignoreResult = ensureProjectGitignore(projectRoot);
+    ensureProjectDebugScaffolding(projectRoot);
     return {
         projectDir,
         typesFile,
+        definitionsFile,
         metadataFile,
         configResult,
         gitignoreResult,
@@ -422,7 +474,7 @@ export function ensureProjectDebugScaffolding(rootDir) {
         fs.writeFileSync(filePath, contents);
     }
 }
-export function ensureProjectConfig(rootDir) {
+export function ensureProjectConfig(rootDir, typesInclude = REVO_TYPES_FILE) {
     const tsconfigPath = path.join(rootDir, 'tsconfig.json');
     const jsconfigPath = path.join(rootDir, 'jsconfig.json');
     if (!fs.existsSync(tsconfigPath) && !fs.existsSync(jsconfigPath)) {
@@ -433,7 +485,10 @@ export function ensureProjectConfig(rootDir) {
                 noEmit: true,
                 skipLibCheck: true,
             },
-            include: DEFAULT_PROJECT_INCLUDE,
+            include: [
+                ...DEFAULT_PROJECT_INCLUDE.filter((entry) => entry !== REVO_TYPES_FILE),
+                typesInclude,
+            ],
             exclude: DEFAULT_PROJECT_EXCLUDE,
         });
         return {
@@ -456,13 +511,16 @@ export function ensureProjectConfig(rootDir) {
     const files = ensureStringArray(parsed.files, 'files', filePath);
     const include = ensureStringArray(parsed.include, 'include', filePath);
     if (files) {
-        parsed.files = appendUnique(files, REVO_TYPES_FILE);
+        parsed.files = appendUnique(files, typesInclude);
     }
     else if (include) {
-        parsed.include = appendUnique(include, REVO_TYPES_FILE);
+        parsed.include = appendUnique(include, typesInclude);
     }
     else {
-        parsed.include = DEFAULT_PROJECT_INCLUDE;
+        parsed.include = [
+            ...DEFAULT_PROJECT_INCLUDE.filter((entry) => entry !== REVO_TYPES_FILE),
+            typesInclude,
+        ];
     }
     writeJsonFile(filePath, parsed);
     return {

package/dist/src/ui.js

@@ -108,11 +108,12 @@ 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 debug <componentId> [BODY]', 'Debug one local component against sandbox'),
+        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'),
         commandRow('revo search <CODE|SIMPLE> <term>', 'Search code references or all platform content'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revoengine/cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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"