@revoengine/cli 1.0.9 → 1.0.10

package/README.md

@@ -54,11 +54,39 @@ Initialize a project for ambient low-code editor globals:
 ```bash
 revo project
 revo project init ./app
+revo project init ./app --identity-mode stableKey --stable-key-name resourceKey --resources component
+revo project init ./app --identity-mode componentId
 revo project update ./app
 ```
 
 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.
 
+When compiler options are missing, project initialization sets `target: ES2022`, `module: ESNext`, and `moduleDetection: force`. Revo TypeScript elements are runtime-wrapped snippets, so module detection is required for top-level `await`; existing explicit compiler options are preserved.
+
+`--identity-mode stableKey|componentId` stores the component matching strategy in `.revoengine/revo.json`. New projects default to `stableKey`; existing projects without this setting retain legacy `componentId` matching. In stable-key mode, `--stable-key-name <name>` selects the metadata property and defaults to `stableKey`.
+
+```json
+{
+  "componentIdentity": {
+    "mode": "stableKey",
+    "metadataProperty": "resourceKey"
+  }
+}
+```
+
+Stable-key mode manages only components that contain the configured metadata property. Component UUIDs remain in API requests and lock diagnostics, but they are not used as durable identity. Duplicate stable-key values block plan, pull, and push. Use `--identity-mode componentId` only for a workspace that intentionally remains bound to one RevoEngine instance.
+
+During interactive init, the CLI asks for the stable key metadata name and which resource families it should track. Press Enter to use `stableKey` and track `all` resources. For non-interactive runs, `--resources <list>` accepts `all` or comma-separated resource names such as `component`; when omitted it defaults to `all`. Project initialization also backfills missing stable-key metadata for every tracked component while preserving existing keys. Pass `--no-metadata-backfill` only when initialization must not write remote component metadata.
+
+Backfill stable-key metadata for tracked resources with an explicit plan/apply flow:
+
+```bash
+revo metadata plan --env test
+revo metadata apply --env test --yes
+```
+
+Backfill only writes resources missing the configured stable-key metadata unless `--force` is passed. Generated component keys use `category/name#<random-hex>`.
+
 ## Common commands
 
 ```bash
@@ -135,12 +163,12 @@ 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.
+Remote sync state is stored separately in `.revoengine/revo.lock.json`. Lock schema v2 records the configured identity strategy and, in stable-key mode, keys each entry by the configured metadata value while retaining both the repository-local and current remote UUID. The lock 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 `--yes` or `--force` is passed.
-- `--yes` only confirms the bulk operation. `--force` is the destructive escape hatch that bypasses lock safety.
+- `--yes` only confirms the bulk operation. `--force` bypasses lock-content safety, but never bypasses stable-key ownership: missing or duplicate configured identities are still blocked or ignored.
 - `revo component pull --all` requests only active remote components where `deletedAt` is empty.
 - 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.
@@ -148,6 +176,7 @@ Bulk sync behavior:
 - 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.
+- In stable-key mode, push resolves the target remote UUID from metadata and remaps element IDs by element key before saving. Source-instance UUIDs are never sent as target identity.
 - 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.
@@ -158,13 +187,161 @@ Bulk sync behavior:
 - 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`.
 
+## Environments
+
+Save named environment profiles once, then compare and mirror components between environments terraform-style:
+
+```bash
+revo env add develop --url https://api.dev.revong.com
+revo env add e2e --url https://api.e2e.revong.com
+revo env list
+revo env remove e2e
+```
+
+`revo env add` prompts for the API key, validates it against `/api/v1/me`, and stores the profile (with the inferred instance) next to your default login in the OS config directory. Use `--offline` to skip validation. `revo auth logout` clears only the default login and keeps named environment profiles.
+
+Compare two environments:
+
+```bash
+revo env diff --from develop --to e2e
+revo env diff --from develop --to e2e --json
+revo env diff --from develop --to e2e --strict        # CI drift gate: non-zero exit on any difference
+revo env diff --from develop --to e2e --prune         # classify target-only components as deletes
+revo env diff --from develop --to e2e --key Forms/Card --category Shared
+```
+
+The special name `default` refers to your normal login (`revo auth login` / `REVO_TOKEN`), so `--from default --to e2e` works without saving a profile for the default.
+
+Components are matched across environments by a **stable key** stored in resource metadata by the platform. The metadata property defaults to `stableKey`; initialize a workspace with `revo project init --stable-key-name <name>` or pass `--stable-key-name <name>` to env commands to use a different property. `revo metadata apply` writes this value to `metadata` for components. Env sync reads `metadata`, `metaData`, and `resourceMetadata` for compatibility, but it does not generate stable keys while creating resources. Project metadata also stores `trackedResources`, defaulting to `all`; env commands read it or accept `--resources <list>` directly. For older components that do not have metadata yet, the CLI falls back to normalized `category/name`, because component ids and element ids are instance-local. Content comparison uses a portable hash that ignores ids, versions, and timestamps. Two components in one environment that share the same stable key are reported as a `collision` and block `apply` until resolved or scoped out with `--key`/`--category`.
+
+Mirror components from a source environment into a target:
+
+```bash
+revo env apply --from develop --to e2e                # prints the plan, then asks for confirmation
+revo env apply --from develop --to e2e --dry-run      # plan only, never writes
+revo env apply --from develop --to e2e --yes          # confirm creates/updates non-interactively
+revo env apply --from develop --to e2e --yes --prune --force   # full mirror including deletes
+```
+
+Apply semantics:
+
+- Creates run first, then updates, then deletes; failures are reported per component and the run continues.
+- `--yes` only confirms the bulk apply. Deletes additionally require `--force` (non-interactive) or a second dedicated confirmation (interactive), matching the component sync semantics.
+- Deletes only happen with `--prune`; without it, target-only components are reported as `orphan` and left alone.
+- Element identity is preserved on update: source elements are matched to the target's elements by key, so the target keeps its own element ids.
+- After every create/update the CLI re-fetches the target component and verifies its content hash against the source; mismatches are flagged as `verification mismatch`.
+
+## Environment sync runbook
+
+Use this flow when preparing one environment to track and mirror resources with the CLI. The examples use `test` as the source and `dev` as the target.
+
+1. Initialize the local project metadata:
+
+```bash
+revo project init
+```
+
+For CI or non-interactive setup:
+
+```bash
+revo project init --identity-mode stableKey --stable-key-name stableKey --resources all
+```
+
+This writes `.revoengine/revo.json` with:
+
+- `componentIdentity.mode`: `stableKey` for portable identity or `componentId` for legacy instance-bound identity.
+- `componentIdentity.metadataProperty`: the component metadata property used in stable-key mode. Default: `stableKey`.
+- `trackedResources`: resource families the CLI should track. Default: `all`; this CLI currently tracks components.
+
+2. Save environment profiles:
+
+```bash
+revo env add test --url https://api.test.revong.com
+revo env add dev --url https://api.dev.revong.com
+revo env list
+```
+
+For one-off commands without a saved profile, use `default` plus environment variables:
+
+```bash
+REVO_URL="https://api.dev.revong.com" REVO_TOKEN="$REVO_DEV_TOKEN" revo metadata plan --env default
+```
+
+3. Plan metadata backfill before writing anything:
+
+```bash
+revo metadata plan --env test
+revo metadata plan --env dev
+```
+
+Use JSON when reviewing exact resources:
+
+```bash
+revo metadata plan --env test --json
+```
+
+4. Apply metadata backfill:
+
+```bash
+revo metadata apply --env test --yes
+revo metadata apply --env dev --yes
+```
+
+Important: if the same resources already exist in multiple environments, do not treat independently generated random suffixes as interchangeable. `category/name#aaaa1111` and `category/name#bbbb2222` are different stable keys, even when the readable prefix matches. Pick a source of truth and make the target environment use the exact same metadata value, including casing, before running destructive sync.
+
+5. Verify metadata backfill:
+
+```bash
+revo metadata plan --env test
+revo metadata plan --env dev
+```
+
+Expected after a successful backfill:
+
+```text
+Plan: 0 to update, N already populated.
+```
+
+6. Preview environment drift:
+
+```bash
+revo env diff --from test --to dev
+revo env diff --from test --to dev --json
+```
+
+Use `--strict` in CI:
+
+```bash
+revo env diff --from test --to dev --strict
+```
+
+7. Apply non-destructive sync:
+
+```bash
+revo env apply --from test --to dev --dry-run
+revo env apply --from test --to dev --yes
+```
+
+Without `--prune`, target-only resources are reported as `orphan` and left untouched.
+
+8. Apply full mirror with orphan removal:
+
+```bash
+revo env diff --from test --to dev --prune
+revo env apply --from test --to dev --prune --dry-run
+revo env apply --from test --to dev --prune --yes --force
+```
+
+Only use `--prune --force` after reviewing the plan. It deletes target resources that are missing from the source.
+
 ## Configuration
 
 The CLI reads configuration in this order:
 
 1. CLI flags such as `--url` and `--token`
-2. Environment variables such as `REVO_URL` and `REVO_TOKEN`
-3. Stored config in the OS config directory
+2. A named environment profile when a command is invoked with `--from`/`--to` (profiles resolve exclusively and are not mixed with environment variables or the stored default login)
+3. Environment variables such as `REVO_URL` and `REVO_TOKEN`
+4. Stored config in the OS config directory
 
 This means environment variables override the locally stored config, which is the intended setup for CI and non-interactive automation.
 

package/dist/src/cli.js

@@ -2,7 +2,7 @@ import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { RevoClient } from "./client.js";
 import { resolveRuntimeConfig } from "./config.js";
-import { handleAuthCommand, handleComponentCommand, handleEndpointsCommand, handleInfoCommand, handleProjectCommand, handleRequestCommand, handleSearchCommand, } from "./commands/index.js";
+import { handleAuthCommand, handleComponentCommand, handleEndpointsCommand, handleEnvCommand, handleInfoCommand, handleMetadataCommand, handleProjectCommand, handleRequestCommand, handleSearchCommand, } from "./commands/index.js";
 import { buildRuntimeViewModel } from "./runtime-view.js";
 import { renderHelp, renderOverview } from "./ui.js";
 import { maybeNotifyUpdateAvailable } from "./update-notifier.js";
@@ -196,6 +196,14 @@ export async function main(argv = process.argv.slice(2)) {
         await handleEndpointsCommand(context);
         return;
     }
+    if (command === 'env') {
+        await handleEnvCommand(context);
+        return;
+    }
+    if (command === 'metadata') {
+        await handleMetadataCommand(context);
+        return;
+    }
     if (command === 'project') {
         await handleProjectCommand(context);
         return;

package/dist/src/client.d.ts

@@ -17,6 +17,7 @@ export type ClientOptions = {
     baseUrl?: string;
     instance?: string;
     token?: string;
+    envName?: string;
     fetch?: typeof fetch;
 };
 export type ApiResponse<T = unknown> = {
@@ -37,6 +38,7 @@ export declare class PermissionDeniedError extends ApiError {
     path: string;
     constructor(path: string, message: string, data: unknown);
 }
+declare const COMPONENT_LIST_PAGE_SIZE = 200;
 declare function buildUrl(baseUrl: string, requestPath: string, query?: Record<string, unknown>): URL;
 declare function normalizeToken(token?: string): string;
 export declare function extractProfileInstanceId(profile: unknown): string;
@@ -71,7 +73,15 @@ export declare class RevoClient {
     debugComponentStream(requestPath: string, body: unknown): AsyncGenerator<DebugStreamEvent>;
     search(params: Record<string, unknown>): Promise<unknown>;
     listComponents(options?: ComponentListRequest): Promise<unknown>;
+    listAllComponents(): Promise<{
+        components: Record<string, unknown>[];
+        discoveredTotal: number | null;
+    }>;
     getComponent(componentId: string): Promise<unknown>;
+    createComponent(body: unknown): Promise<unknown>;
+    updateComponent(componentId: string, body: unknown): Promise<unknown>;
+    deleteComponent(componentId: string): Promise<ApiResponse<unknown>>;
     saveComponentElements(componentId: string, body: unknown): Promise<ApiResponse<unknown>>;
 }
+export { COMPONENT_LIST_PAGE_SIZE };
 export { buildUrl, normalizeToken };

package/dist/src/client.js

@@ -25,6 +25,102 @@ export class PermissionDeniedError extends ApiError {
     }
 }
 const REQUEST_DELAY_MS = 50;
+const COMPONENT_LIST_PAGE_SIZE = 200;
+const ACTIVE_COMPONENT_LIST_FILTER = {
+    'filter[and][0][field]': 'deletedAt',
+    'filter[and][0][op]': 'isNull',
+};
+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 unwrapList(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (value && typeof value === 'object') {
+        const candidate = value;
+        if (Array.isArray(candidate.data)) {
+            return candidate.data;
+        }
+        if (Array.isArray(candidate.items)) {
+            return candidate.items;
+        }
+    }
+    return [];
+}
+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 normalizeBaseUrl(baseUrl) {
     const url = new URL(baseUrl || DEFAULT_BASE_URL);
     url.pathname = url.pathname.replace(/\/+$/, '');
@@ -428,11 +524,72 @@ export class RevoClient {
             query: options.query,
         });
     }
+    async listAllComponents() {
+        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 listing all components.');
+            }
+            seenRequests.add(requestKey);
+            const pageValue = await this.listComponents(nextRequest);
+            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;
+        }
+        return { components, discoveredTotal };
+    }
     async getComponent(componentId) {
         return this.requestData('GET', `/api/v1/component/${componentId}`);
     }
+    async createComponent(body) {
+        return this.requestData('POST', '/api/v1/component', {
+            body,
+            spinnerLabel: 'Creating component',
+        });
+    }
+    async updateComponent(componentId, body) {
+        return this.requestData('PUT', `/api/v1/component/${componentId}`, {
+            body,
+            spinnerLabel: 'Updating component',
+        });
+    }
+    async deleteComponent(componentId) {
+        return this.request('DELETE', `/api/v1/component/${componentId}`, {
+            spinnerLabel: 'Deleting component',
+        });
+    }
     async saveComponentElements(componentId, body) {
         return this.request('POST', `/api/v1/component/${componentId}/save`, { body });
     }
 }
+export { COMPONENT_LIST_PAGE_SIZE };
 export { buildUrl, normalizeToken };