@revoengine/cli 1.0.8 → 1.0.10

package/dist/src/project.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJsonFile } from "./utils.js";
+import { COMPONENT_IDENTITY_BY_ID, DEFAULT_COMPONENT_IDENTITY, DEFAULT_STABLE_KEY_NAME, normalizeComponentIdentityConfig, normalizeComponentIdentityMode, normalizeStableKeyName, } from "./resource-metadata.js";
+import { TRACK_ALL_RESOURCES, normalizeTrackedResources, } from "./tracked-resources.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');
@@ -180,6 +182,22 @@ function appendUnique(list, value) {
     }
     return list;
 }
+function readResourceSelectionArgs(args) {
+    const values = [];
+    for (const name of ['resources', 'resource', 'tracked-resources', 'trackedResources']) {
+        const value = args[name];
+        if (typeof value === 'string') {
+            values.push(value);
+        }
+        else if (Array.isArray(value)) {
+            values.push(...value);
+        }
+        else if (value === true) {
+            throw new Error(`--${name} requires a value such as "all" or "component".`);
+        }
+    }
+    return values.length > 0 ? values : undefined;
+}
 function writeJsonFile(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
@@ -187,10 +205,27 @@ function writeJsonFile(filePath, value) {
 export function resolveProjectInvocation(args) {
     const projectArgs = args._.slice(1);
     const [first, second, ...rest] = projectArgs;
+    const explicitStableKeyName = readString(args.stableKeyName)
+        || readString(args['stable-key-name']);
+    const stableKeyName = explicitStableKeyName
+        ? normalizeStableKeyName(explicitStableKeyName)
+        : undefined;
+    const explicitIdentityMode = readString(args.identityMode)
+        || readString(args['identity-mode']);
+    const identityMode = explicitIdentityMode
+        ? normalizeComponentIdentityMode(explicitIdentityMode)
+        : stableKeyName
+            ? 'stableKey'
+            : undefined;
+    const trackedResourceArgs = readResourceSelectionArgs(args);
+    const trackedResources = trackedResourceArgs ? normalizeTrackedResources(trackedResourceArgs) : undefined;
     if (!first) {
         return {
             action: 'init',
             extraArgs: [],
+            identityMode,
+            stableKeyName,
+            ...(trackedResources ? { trackedResources } : {}),
         };
     }
     if (first === 'init' || first === 'update') {
@@ -198,6 +233,9 @@ export function resolveProjectInvocation(args) {
             action: first,
             targetArg: second,
             extraArgs: rest,
+            identityMode,
+            stableKeyName,
+            ...(trackedResources ? { trackedResources } : {}),
         };
     }
     if (first === 'switch') {
@@ -207,6 +245,9 @@ export function resolveProjectInvocation(args) {
         action: 'init',
         targetArg: first,
         extraArgs: second ? [second, ...rest] : rest,
+        identityMode,
+        stableKeyName,
+        ...(trackedResources ? { trackedResources } : {}),
     };
 }
 function normalizeWorkspaceDirectory(projectRoot, workspaceRoot) {
@@ -363,6 +404,40 @@ export function readProjectMetadata(startDir = process.cwd()) {
     }
     return raw;
 }
+export function readProjectStableKeyName(startDir = process.cwd()) {
+    const metadata = readProjectMetadata(startDir);
+    const identity = readProjectComponentIdentity(startDir);
+    return normalizeStableKeyName(identity.mode === 'stableKey'
+        ? identity.metadataProperty
+        : metadata?.stableKeyName || DEFAULT_STABLE_KEY_NAME);
+}
+export function readProjectComponentIdentity(startDir = process.cwd()) {
+    const metadata = readProjectMetadata(startDir);
+    if (!metadata) {
+        return COMPONENT_IDENTITY_BY_ID;
+    }
+    if (metadata.componentIdentity && isRecord(metadata.componentIdentity)) {
+        const mode = readString(metadata.componentIdentity.mode);
+        const metadataProperty = readString(metadata.componentIdentity.metadataProperty);
+        if (mode) {
+            return normalizeComponentIdentityConfig({
+                mode: normalizeComponentIdentityMode(mode),
+                ...(metadataProperty ? { metadataProperty } : {}),
+            });
+        }
+    }
+    if (metadata.stableKeyName) {
+        return normalizeComponentIdentityConfig({
+            mode: 'stableKey',
+            metadataProperty: metadata.stableKeyName,
+        }, DEFAULT_COMPONENT_IDENTITY);
+    }
+    return COMPONENT_IDENTITY_BY_ID;
+}
+export function readProjectTrackedResources(startDir = process.cwd()) {
+    const metadata = readProjectMetadata(startDir);
+    return normalizeTrackedResources(metadata?.trackedResources || TRACK_ALL_RESOURCES);
+}
 export function resolveProjectRoot(startDir = process.cwd()) {
     const metadataFile = findProjectMetadataFile(startDir);
     return metadataFile ? path.dirname(path.dirname(metadataFile)) : '';
@@ -440,6 +515,8 @@ export function syncProjectFiles(layoutOrTargetDir, input) {
         libVersion: input.libVersion,
         hash: input.hash,
         lastSyncAt: input.lastSyncAt,
+        componentIdentity: normalizeComponentIdentityConfig(input.componentIdentity, DEFAULT_COMPONENT_IDENTITY),
+        trackedResources: normalizeTrackedResources(input.trackedResources || TRACK_ALL_RESOURCES),
         ...(workspaceDirectory !== '.' ? { workspace: workspaceDirectory } : {}),
     });
     const configResult = ensureProjectConfig(workspaceRoot, toPosixRelative(workspaceRoot, typesFile));
@@ -480,6 +557,9 @@ export function ensureProjectConfig(rootDir, typesInclude = REVO_TYPES_FILE) {
     if (!fs.existsSync(tsconfigPath) && !fs.existsSync(jsconfigPath)) {
         writeJsonFile(tsconfigPath, {
             compilerOptions: {
+                target: 'ES2022',
+                module: 'ESNext',
+                moduleDetection: 'force',
                 allowJs: true,
                 checkJs: false,
                 noEmit: true,
@@ -499,6 +579,15 @@ export function ensureProjectConfig(rootDir, typesInclude = REVO_TYPES_FILE) {
     const filePath = fs.existsSync(tsconfigPath) ? tsconfigPath : jsconfigPath;
     const parsed = parseConfigFile(filePath);
     const compilerOptions = ensureObjectField(parsed, 'compilerOptions', filePath);
+    if (compilerOptions.target === undefined) {
+        compilerOptions.target = 'ES2022';
+    }
+    if (compilerOptions.module === undefined) {
+        compilerOptions.module = 'ESNext';
+    }
+    if (compilerOptions.moduleDetection === undefined) {
+        compilerOptions.moduleDetection = 'force';
+    }
     if (compilerOptions.allowJs === undefined) {
         compilerOptions.allowJs = true;
     }

package/dist/src/resource-metadata.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentRecord } from './types.ts';
+export declare const DEFAULT_STABLE_KEY_NAME = "stableKey";
+export declare const NULL_CATEGORY_KEY = "__no_category__";
+export type ComponentIdentityMode = 'componentId' | 'stableKey';
+export type ComponentIdentityConfig = {
+    mode: ComponentIdentityMode;
+    metadataProperty?: string;
+};
+export declare const COMPONENT_IDENTITY_BY_ID: ComponentIdentityConfig;
+export declare const DEFAULT_COMPONENT_IDENTITY: ComponentIdentityConfig;
+export declare function normalizeStableKeyName(value: string | null | undefined): string;
+export declare function normalizeComponentIdentityMode(value: string | null | undefined): ComponentIdentityMode;
+export declare function normalizeComponentIdentityConfig(value: Partial<ComponentIdentityConfig> | null | undefined, fallback?: ComponentIdentityConfig): ComponentIdentityConfig;
+export declare function sameComponentIdentityConfig(left: ComponentIdentityConfig, right: ComponentIdentityConfig): boolean;
+export declare function readConfiguredResourceMetadataStableKey(component: ComponentRecord, stableKeyName?: string): string | null;
+export declare function readComponentIdentityValue(component: ComponentRecord, identity: ComponentIdentityConfig): string | null;
+export declare function readResourceMetadataStableKey(component: ComponentRecord, stableKeyName?: string): string | null;
+export declare function buildStableKey(component: ComponentRecord, stableKeyName?: string): string;
+export declare function buildStableKeyValue(component: ComponentRecord, stableKeyName?: string): string;
+export declare function buildResourceIdentityStableKeyValue(component: ComponentRecord): string;
+export declare function buildResourceMetadataWithStableKey(component: ComponentRecord, stableKeyName?: string): {
+    [x: string]: unknown;
+};
+export declare function sanitizeUserMetadata(value: unknown): Record<string, unknown>;

package/dist/src/resource-metadata.js

@@ -0,0 +1,129 @@
+export const DEFAULT_STABLE_KEY_NAME = 'stableKey';
+export const NULL_CATEGORY_KEY = '__no_category__';
+export const COMPONENT_IDENTITY_BY_ID = {
+    mode: 'componentId',
+};
+export const DEFAULT_COMPONENT_IDENTITY = {
+    mode: 'stableKey',
+    metadataProperty: DEFAULT_STABLE_KEY_NAME,
+};
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function normalizeKeyPart(value) {
+    return (value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+export function normalizeStableKeyName(value) {
+    const normalized = (value || DEFAULT_STABLE_KEY_NAME).trim();
+    if (!normalized) {
+        return DEFAULT_STABLE_KEY_NAME;
+    }
+    if (!/^[A-Za-z_$][A-Za-z0-9_$-]*$/.test(normalized)) {
+        throw new Error('Stable key metadata name must start with a letter, "_", or "$" and contain only letters, digits, "_", "$", or "-".');
+    }
+    return normalized;
+}
+export function normalizeComponentIdentityMode(value) {
+    const normalized = (value || '').trim().toLowerCase().replace(/[-_\s]/g, '');
+    if (normalized === 'stablekey' || normalized === 'metadata') {
+        return 'stableKey';
+    }
+    if (normalized === 'componentid' || normalized === 'id' || normalized === 'uuid') {
+        return 'componentId';
+    }
+    throw new Error('Component identity mode must be "stableKey" or "componentId".');
+}
+export function normalizeComponentIdentityConfig(value, fallback = COMPONENT_IDENTITY_BY_ID) {
+    const mode = value?.mode
+        ? normalizeComponentIdentityMode(value.mode)
+        : fallback.mode;
+    if (mode === 'componentId') {
+        return { mode };
+    }
+    return {
+        mode,
+        metadataProperty: normalizeStableKeyName(value?.metadataProperty || fallback.metadataProperty),
+    };
+}
+export function sameComponentIdentityConfig(left, right) {
+    const normalizedLeft = normalizeComponentIdentityConfig(left);
+    const normalizedRight = normalizeComponentIdentityConfig(right);
+    return normalizedLeft.mode === normalizedRight.mode
+        && normalizedLeft.metadataProperty === normalizedRight.metadataProperty;
+}
+function readConfiguredStableKeyFromRecord(value, stableKeyName) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    return readString(value[stableKeyName])
+        ?? (isRecord(value.details) ? readString(value.details[stableKeyName]) : null);
+}
+function readAnyStableKeyFromRecord(value, stableKeyName) {
+    return readConfiguredStableKeyFromRecord(value, stableKeyName)
+        ?? (stableKeyName === DEFAULT_STABLE_KEY_NAME ? null : readConfiguredStableKeyFromRecord(value, DEFAULT_STABLE_KEY_NAME));
+}
+export function readConfiguredResourceMetadataStableKey(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    const fieldName = normalizeStableKeyName(stableKeyName);
+    return readConfiguredStableKeyFromRecord(component.metadata, fieldName)
+        ?? readConfiguredStableKeyFromRecord(component.metaData, fieldName)
+        ?? readConfiguredStableKeyFromRecord(component.resourceMetadata, fieldName);
+}
+export function readComponentIdentityValue(component, identity) {
+    const normalized = normalizeComponentIdentityConfig(identity);
+    if (normalized.mode === 'componentId') {
+        return readString(component.componentId) ?? readString(component.id);
+    }
+    return readConfiguredResourceMetadataStableKey(component, normalized.metadataProperty);
+}
+export function readResourceMetadataStableKey(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    const fieldName = normalizeStableKeyName(stableKeyName);
+    return readAnyStableKeyFromRecord(component.metadata, fieldName)
+        ?? readAnyStableKeyFromRecord(component.metaData, fieldName)
+        ?? readAnyStableKeyFromRecord(component.resourceMetadata, fieldName);
+}
+export function buildStableKey(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    const metadataStableKey = readResourceMetadataStableKey(component, stableKeyName);
+    if (metadataStableKey) {
+        return normalizeKeyPart(metadataStableKey);
+    }
+    const category = normalizeKeyPart(component.category) || NULL_CATEGORY_KEY;
+    const name = normalizeKeyPart(component.name);
+    return `${category}/${name}`;
+}
+export function buildStableKeyValue(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    const metadataStableKey = readResourceMetadataStableKey(component, stableKeyName);
+    if (metadataStableKey) {
+        return metadataStableKey;
+    }
+    return buildResourceIdentityStableKeyValue(component);
+}
+export function buildResourceIdentityStableKeyValue(component) {
+    const category = typeof component.category === 'string' && component.category.trim()
+        ? component.category.trim()
+        : NULL_CATEGORY_KEY;
+    const name = typeof component.name === 'string' ? component.name.trim() : '';
+    return `${category}/${name}`;
+}
+export function buildResourceMetadataWithStableKey(component, stableKeyName = DEFAULT_STABLE_KEY_NAME) {
+    const fieldName = normalizeStableKeyName(stableKeyName);
+    return {
+        ...sanitizeUserMetadata(component.metadata),
+        [fieldName]: buildStableKeyValue(component, fieldName),
+    };
+}
+export function sanitizeUserMetadata(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const sanitized = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key.startsWith('__')) {
+            continue;
+        }
+        sanitized[key] = entry;
+    }
+    return sanitized;
+}

package/dist/src/tracked-resources.d.ts

@@ -0,0 +1,7 @@
+export declare const TRACK_ALL_RESOURCES = "all";
+export declare const TRACKABLE_RESOURCE_TYPES: readonly ["component"];
+export type TrackableResourceType = typeof TRACKABLE_RESOURCE_TYPES[number];
+export type TrackedResource = typeof TRACK_ALL_RESOURCES | TrackableResourceType;
+export declare function normalizeTrackedResources(value: string | string[] | null | undefined): TrackedResource[];
+export declare function formatTrackedResources(resources: readonly TrackedResource[]): string;
+export declare function shouldTrackResource(resources: readonly TrackedResource[], resource: TrackableResourceType): boolean;

package/dist/src/tracked-resources.js

@@ -0,0 +1,37 @@
+export const TRACK_ALL_RESOURCES = 'all';
+export const TRACKABLE_RESOURCE_TYPES = ['component'];
+const RESOURCE_ALIASES = {
+    all: TRACK_ALL_RESOURCES,
+    '*': TRACK_ALL_RESOURCES,
+    component: 'component',
+    components: 'component',
+};
+export function normalizeTrackedResources(value) {
+    const rawValues = Array.isArray(value) ? value : value ? [value] : [TRACK_ALL_RESOURCES];
+    const normalized = [];
+    for (const rawValue of rawValues) {
+        for (const part of rawValue.split(',')) {
+            const key = part.trim().toLowerCase();
+            if (!key) {
+                continue;
+            }
+            const resource = RESOURCE_ALIASES[key];
+            if (!resource) {
+                throw new Error(`Unsupported tracked resource "${part.trim()}". Supported values: all, component.`);
+            }
+            if (!normalized.includes(resource)) {
+                normalized.push(resource);
+            }
+        }
+    }
+    if (normalized.length === 0 || normalized.includes(TRACK_ALL_RESOURCES)) {
+        return [TRACK_ALL_RESOURCES];
+    }
+    return normalized;
+}
+export function formatTrackedResources(resources) {
+    return resources.join(',');
+}
+export function shouldTrackResource(resources, resource) {
+    return resources.includes(TRACK_ALL_RESOURCES) || resources.includes(resource);
+}

package/dist/src/types.d.ts

@@ -32,6 +32,9 @@ export type ComponentRecord = {
     active?: boolean;
     async?: boolean;
     version?: number;
+    metadata?: Record<string, unknown>;
+    metaData?: Record<string, unknown>;
+    resourceMetadata?: Record<string, unknown>;
     elements?: ComponentElementRecord[];
     [key: string]: unknown;
 };

package/dist/src/ui.js

@@ -103,18 +103,27 @@ function renderCommandCatalog() {
         commandRow('revo auth login', 'Paste API key in the terminal'),
         commandRow('revo auth status', 'Show the current authentication status'),
         commandRow('revo auth logout', 'Remove stored credentials'),
-        commandRow('revo project [path]', 'Initialize ambient editor types for JS and TS'),
+        commandRow('revo project [path] [--identity-mode <stableKey|componentId>] [--stable-key-name <name>] [--resources <list>]', 'Initialize editor types and component identity'),
         commandRow('revo project update [path]', 'Refresh editor types and project metadata'),
         commandRow('revo endpoints', 'List available API endpoints'),
         '',
         paintHeader('Components'),
         commandRow('revo component plan --all [--json] [--strict] [--changed --base <ref>]', 'Preview local/remote sync status'),
-        commandRow('revo component pull <componentId...> [--force]', 'Pull one or more components safely'),
+        commandRow('revo component pull <identity...> [--force]', 'Pull by configured stable key or component ID'),
         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 <identity...>', 'Push by configured stable key or component ID'),
         commandRow('revo component push --all [--yes] [--force] [--changed --base <ref>]', 'Push local components with lock checks'),
         commandRow('revo component debug <componentId> [BODY] [--stream] [--raw-debug]', 'Debug one local component against sandbox'),
         '',
+        paintHeader('Environments'),
+        commandRow('revo env add <name> [--url <url>] [--token <apiKey>]', 'Save a named environment profile'),
+        commandRow('revo env list [--json]', 'List saved environment profiles'),
+        commandRow('revo env remove <name>', 'Remove a saved environment profile'),
+        commandRow('revo env diff --from <env> --to <env> [--prune] [--json] [--strict]', 'Compare components across two environments'),
+        commandRow('revo env apply --from <env> --to <env> [--yes] [--prune] [--force]', 'Mirror components from one environment into another'),
+        commandRow('revo metadata plan --env <env> [--json]', 'Preview stable-key metadata backfill'),
+        commandRow('revo metadata apply --env <env> --yes', 'Populate missing stable-key metadata'),
+        '',
         paintHeader('Low-Level'),
         commandRow('revo search <CODE|SIMPLE> <term>', 'Search code references or all platform content'),
         commandRow('revo request <METHOD> <PATH> [BODY]', 'Make a raw API request with optional JSON body'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revoengine/cli",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "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/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')\"",
+    "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/resource-metadata.ts'); await import('./src/tracked-resources.ts'); await import('./src/metadata-backfill.ts'); await import('./src/ui.ts'); await import('./src/update-notifier.ts'); await import('./src/env-sync.ts'); await import('./src/commands/auth.ts'); await import('./src/commands/component.ts'); await import('./src/commands/endpoints.ts'); await import('./src/commands/env.ts'); await import('./src/commands/info.ts'); await import('./src/commands/metadata.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"